Listings APIListings API
Accedi

Aggiungi una sede

Crea una sede con i campi richiesti dalle piattaforme di pubblicazione, gestisci gli errori di validazione e verifica che sia in coda per l'invio.

Schede, recensioni, post e dati analitici sono tutti associati all'ID di una sede. POST /api/v4/locations crea la sede e mette in coda una scheda per ogni piattaforma di pubblicazione inclusa nel tuo piano.

1. Raccogli i campi obbligatori

Dieci campi sono obbligatori. Anche un'attività che serve un'area geografica deve inviare l'indirizzo completo: con hideAddress: true, ListingsAPI memorizza l'indirizzo ma non lo invia alle piattaforme di pubblicazione. Le piattaforme di pubblicazione mostrano come vuoti i campi facoltativi omessi, quindi invia tutte le informazioni che hai.

CampoObbligatorioNote
nameSìDa 2 a 150 caratteri.
descriptionSìAlmeno 200 caratteri (SY10005).
countryIsoSìCodice di 2 lettere di un paese supportato (SY10036).
citySìObbligatorio quando il valore di hasCity del paese è true (SY10126). Quando è false, la città che invii viene scartata.
subCategoryIdSìdatabaseId numerico dall'elenco delle sottocategorie.
streetSìDa 5 a 100 caratteri (SY10011).
stateIsoSìObbligatorio quando il valore di stateRequired del paese è true e deve essere uno dei valori di states di quel paese (SY10010). Omettilo quando stateRequired è false.
postalCodeNoFacoltativo, ma invialo ogni volta che il valore di hasPostalCode del paese è true. Il valore che invii deve rispettare il formato del paese (SY10014).
phoneSìValidato in base al paese (SY10015).
bizUrlSìPubblicato come sito web. Alcune piattaforme di pubblicazione rifiutano una scheda che ne è priva.
storeIdNoIl tuo codice del punto vendita, univoco all'interno dell'account. Usalo per ritrovare la sede senza memorizzare i nostri ID.
businessHoursNoUna voce per ogni giorno della settimana. Per il formato, consulta Aggiorna una sede.

2. Crea la sede

POST /api/v4/locations accetta i campi in un oggetto input nel corpo JSON della richiesta. Il metodo locations.add() del Python SDK accetta gli stessi campi come argomenti con nome e valida quelli obbligatori prima di inviare la richiesta. Il metodo createLocation() del Node SDK accetta direttamente l'oggetto camelCase.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. Leggi la risposta

Una creazione riuscita restituisce success: true e la nuova sede in data.createLocation.location. Conserva entrambi gli identificatori: id è il valore base64 che ogni successiva operazione di scrittura accetta e databaseId è il valore numerico mostrato nelle dashboard e nei payload dei webhook.

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

status è PENDING mentre la sede viene validata e messa in coda. Passa allo stato successivo senza un'ulteriore chiamata API.

4. Gestisci gli errori di validazione

Una creazione può fallire in 2 punti. Una richiesta malformata o una chiave non valida restituisce 4xx con un array errors al livello principale. Una richiesta ben formata con un campo rifiutato dall'API restituisce 200 con success: false e il problema all'interno di data.createLocation.errors, quindi controlla il corpo della risposta di ogni operazione di scrittura, non solo il codice di stato.

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

Entrambi gli SDK sollevano un'eccezione in caso di errore. locations.add() di Python controlla localmente i campi obbligatori e solleva ValidationError prima di inviare la richiesta. createLocation() di Node solleva ValidationError quando l'API rifiuta i dati in ingresso, motivo per cui l'esempio precedente non controlla alcun flag di successo.

I codici che incontrerai più spesso:

CodiceCausaSoluzione
SY10005Descrizione mancante o inferiore a 200 caratteri.Scrivi una descrizione più completa.
SY10011street mancante o inferiore a 5 caratteri.Invia street.
SY10010stateIso mancante o non valido per il paese.Invia un codice di stato ottenuto dall'endpoint dei paesi.
SY10036countryIso non è un paese supportato.Usa un codice ottenuto dall'endpoint dei paesi.
SY10126city mancante per un paese che lo richiede.Invia city.
SY90016La chiave è di tipo Read, per la sola lettura.Usa una chiave Write.

5. Verifica che l'invio sia iniziato

La creazione della sede mette in coda una scheda per ogni piattaforma di pubblicazione inclusa nel tuo piano. Ogni scheda parte da AVAILABLE o IN_PROGRESS e passa a SYNCED con un listingUrl una volta che la piattaforma di pubblicazione l'ha accettata.

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

Con i webhook configurati, non è necessario effettuare polling. Un evento profile.created viene generato quando il record esiste e un evento listing.submission viene generato per ogni piattaforma di pubblicazione al variare del relativo stato.

Passaggi successivi