Archiver les établissements que vous ne gérez plus

Recherchez par mot-clé, codes et ID par lots. Planifiez ou annulez l’archivage des établissements fermés en fin de cycle de facturation.

Trois endpoints de lecture permettent de rechercher des établissements selon différentes clés : une recherche en texte libre, une recherche par code magasin et une recherche par identifiant. L’archivage est une opération d’écriture planifiée : l’établissement reste actif jusqu’à la fin du cycle de facturation en cours, puis sa synchronisation et sa facturation cessent. Jusqu’à ce moment, vous pouvez l’annuler.

1. Rechercher par mot-clé

GET /locations/search?query= recherche le terme dans le nom, l’adresse postale, la ville et l’identifiant du magasin, et renvoie une connexion paginée par curseur : edges[].node avec pageInfo.endCursor, paginée à l’aide de first et after. Omettez query pour parcourir l’ensemble du compte par pages.

curl "https://listingsapi.com/api/v4/locations/search?query=Acme&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Acme Kitchen",            "storeId": "ACME-NYC-001",            "approved": "APPROVED",            "archived": false,            "archivalScheduledAt": null          }        }      ],      "pageInfo": { "endCursor": "TG9jYXRpb246MTgwMDI4OQ==", "hasNextPage": false, "total": 1 }    }  }}

Un tableau edges vide signifie qu’aucune correspondance n’a été trouvée ; c’est la vérification à effectuer avant une création si vous ne savez pas si un magasin existe déjà. Les deux SDK acceptent fields pour limiter la recherche de correspondances à name ou à store_id uniquement.

2. Rechercher par code magasin

Si vos systèmes identifient les établissements à l’aide de vos propres codes magasin, retrouvez-les directement avec GET /locations-by-store-codes. Le paramètre storeCodes est un tableau JSON encodé pour les URL. Les codes sans correspondance sont absents du résultat.

curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME-NYC-001","ACME-NYC-002"]' \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "getLocationsByStoreCodes": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "archived": false      }    ]  }}

3. Récupérer les enregistrements complets d’un lot d’identifiants

Lorsque vous disposez déjà d’identifiants base64, provenant de votre propre stockage ou du contenu d’un webhook, GET /locations-by-ids renvoie l’enregistrement complet de chacun en un seul appel. Les établissements archivés sont également renvoyés ; consultez donc archived et archivedAt pour les distinguer. Les identifiants inconnus sont ignorés sans avertissement ; comparez les nombres d’éléments.

curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "getLocationsByIds": [      { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "name": "Acme Kitchen", "archived": false, "archivedAt": null },      { "id": "TG9jYXRpb246MTgwMDI5MA==", "databaseId": 1800290, "name": "Acme Kitchen Brooklyn", "archived": false, "archivedAt": null }    ]  }}

Pour obtenir un sous-ensemble de l’ensemble du compte filtré côté serveur, GET /locations accepte également un paramètre filter encodé en JSON, par exemple pour filtrer par statut d’approbation. Consultez Répertorier tous les établissements.

4. Archiver les établissements que vous ne gérez plus

POST /locations/archive accepte input.locationIds et renvoie une entrée result par établissement. L’archivage est planifié, et non immédiat : chaque établissement passe à l’état ARCHIVE_SCHEDULED, continue à se synchroniser jusqu’à la fin du cycle de facturation en cours et est archivé lors de la génération de la facture suivante. À partir de ce moment, sa synchronisation avec les plateformes de publication et sa facturation cessent.

curl -X POST https://listingsapi.com/api/v4/locations/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="]  }}'

{  "data": {    "archiveLocations": {      "errors": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null },        { "locationId": "TG9jYXRpb246MTgwMDI5MA==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null }      ]    }  }}

Consultez success pour chaque entrée : un identifiant incorrect ne bloque pas le reste du lot. Tant que l’archivage est planifié, le champ archivalScheduledAt de l’établissement est renseigné dans les résultats de liste et de recherche. Un établissement archivé ne peut pas être mis à jour tant qu’il n’a pas été réactivé. Si des webhooks sont configurés, un événement profile.deleted est déclenché ; il s’agit d’une suppression logique, et aucune suppression définitive n’est possible.

5. Annuler un archivage planifié

Avant la clôture du cycle, POST /locations/cancel_archive avec les mêmes identifiants remet les établissements à l’état ACTIVE et leur facturation se poursuit. Une fois l’établissement entièrement archivé, cet appel renvoie 404 pour celui-ci. L’annulation n’émet aucun événement webhook.

curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'

{  "data": {    "cancelLocationsArchive": {      "errors": null,      "result": [        { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null }      ]    }  }}

Les deux SDK nécessitent deux arguments positionnels supplémentaires, un type de sélection et un identifiant changedBy, qu’ils envoient avec locationIds. Le corps de la requête REST ne nécessite que les identifiants.

Étapes suivantes

• Ajouter un établissement : l’appel de création et pourquoi y définir storeId rend l’étape 2 possible.
• Mettre à jour un établissement : corrigez les informations des établissements que vous avez trouvés au lieu de les archiver.
• Rechercher des établissements, Obtenir des établissements par code de magasin, Obtenir des établissements par ID, Archiver des établissements et Annuler l’archivage planifié : les pages de référence.