Listings APIListings API
Se connecter

Ajouter un établissement

Créez un établissement avec les champs requis des plateformes de publication, gérez les erreurs de validation et vérifiez sa soumission en file d’attente.

Les fiches, les avis, les publications et les données analytiques sont tous associés à un identifiant d'établissement. POST /api/v4/locations crée l'établissement et met en file d'attente une fiche par plateforme de publication incluse dans votre forfait.

1. Rassembler les champs obligatoires

Dix champs sont obligatoires. Une entreprise desservant une zone géographique doit également envoyer son adresse complète : avec hideAddress: true, ListingsAPI conserve l'adresse, mais ne la transmet pas aux plateformes de publication. Les plateformes de publication affichent les champs facultatifs omis comme vides ; envoyez donc toutes les informations dont vous disposez.

ChampObligatoireRemarques
nameOuiDe 2 à 150 caractères.
descriptionOuiAu moins 200 caractères (SY10005).
countryIsoOuiCode à deux lettres d'un pays pris en charge (SY10036).
cityOuiObligatoire lorsque hasCity du pays vaut true (SY10126). Lorsque cette valeur est false, toute ville que vous envoyez est ignorée.
subCategoryIdOuidatabaseId numérique provenant de la liste des sous-catégories.
streetOuiDe 5 à 100 caractères (SY10011).
stateIsoOuiObligatoire lorsque stateRequired du pays vaut true, et doit correspondre à l'une des valeurs de states de ce pays (SY10010). Omettez ce champ lorsque stateRequired vaut false.
postalCodeNonFacultatif, mais envoyez-le lorsque hasPostalCode du pays vaut true. Toute valeur envoyée doit respecter le format du pays (SY10014).
phoneOuiValidé en fonction du pays (SY10015).
bizUrlOuiPublié comme site web. Certaines plateformes de publication refusent une fiche sans site web.
storeIdNonVotre propre code de magasin, unique au sein du compte. Utilisez-le pour retrouver l'établissement sans conserver nos identifiants.
businessHoursNonUne entrée par jour de la semaine. Consultez Mettre à jour un établissement pour connaître le format.

2. Créer l'établissement

POST /api/v4/locations accepte les champs dans un objet input du corps JSON de la requête. La méthode locations.add() du Python SDK accepte les mêmes champs sous forme d'arguments nommés et valide les champs obligatoires avant d'envoyer la requête. La méthode createLocation() du Node SDK accepte directement l'objet 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. Lire la réponse

Une création réussie renvoie success: true et le nouvel établissement dans data.createLocation.location. Conservez les deux identifiants : id est la valeur en base64 utilisée par toutes les opérations d'écriture ultérieures, et databaseId est la valeur numérique affichée dans les tableaux de bord et les charges utiles des webhooks.

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 vaut PENDING pendant la validation et la mise en file d'attente de l'établissement. Ce statut évolue sans appel API supplémentaire.

4. Gérer les erreurs de validation

Une création peut échouer à deux niveaux. Une requête mal formée ou une clé incorrecte entraîne le renvoi de 4xx avec un tableau errors au premier niveau. Une requête bien formée contenant un champ rejeté par l'API entraîne le renvoi de 200 avec success: false et le problème dans data.createLocation.errors ; vérifiez donc le corps de la réponse à chaque opération d'écriture, et pas seulement le code de statut.

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

Les deux SDK lèvent une exception en cas d'échec. En Python, locations.add() vérifie les champs obligatoires localement et lève ValidationError avant d'envoyer la requête. En Node, createLocation() lève ValidationError lorsque l'API rejette les données d'entrée, ce qui explique pourquoi l'exemple ci-dessus ne teste aucun indicateur de réussite.

Les codes que vous rencontrerez le plus souvent :

CodeCauseCorrection
SY10005Description absente ou de moins de 200 caractères.Rédigez une description plus complète.
SY10011street absent ou de moins de 5 caractères.Envoyez street.
SY10010stateIso absent ou non valide pour le pays.Envoyez un code d'État provenant du point de terminaison des pays.
SY10036countryIso n'est pas un pays pris en charge.Utilisez un code provenant du point de terminaison des pays.
SY10126city absent pour un pays qui l'exige.Envoyez city.
SY90016La clé est en lecture seule.Utilisez une clé d'écriture.

5. Confirmez que la soumission a commencé

La création de l'établissement met en file d'attente une fiche par plateforme de publication incluse dans votre forfait. Chaque fiche commence à AVAILABLE ou IN_PROGRESS et passe à SYNCED avec un listingUrl une fois que la plateforme de publication l'accepte.

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

Lorsque les webhooks sont configurés, aucune interrogation périodique n'est nécessaire. Un événement profile.created est déclenché lorsque l'enregistrement existe, et un événement listing.submission est déclenché pour chaque plateforme de publication à chaque changement de statut.

Étapes suivantes