Nicht mehr verwaltete Standorte finden und archivieren

Suchen Sie per Stichwort, lösen Sie Filialcodes/IDs gebündelt auf, planen oder widerrufen Sie die Archivierung geschlossener Filialen zum Abrechnungsende.

Drei Leseendpunkte finden Standorte anhand verschiedener Schlüssel: über eine Freitextsuche, eine Filialcode-Abfrage und eine ID-Abfrage. Die Archivierung ist ein geplanter Schreibvorgang: Der Standort bleibt bis zum Ende des aktuellen Abrechnungszeitraums aktiv, danach werden die Synchronisierung und die Abrechnung eingestellt. Bis zu diesem Zeitpunkt können Sie die Archivierung abbrechen.

1. Nach Stichwort suchen

GET /locations/search?query= gleicht den Suchbegriff mit Name, Straßenadresse, Stadt und Filial-ID ab und gibt eine Cursor-Connection zurück: edges[].node mit pageInfo.endCursor, paginiert über first und after. Lassen Sie query weg, um das gesamte Konto seitenweise abzurufen.

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 }    }  }}

Ein leeres edges-Array bedeutet, dass keine Übereinstimmung gefunden wurde. Dies sollten Sie vor dem Erstellen prüfen, wenn Sie unsicher sind, ob eine Filiale bereits existiert. Beide SDKs akzeptieren fields, um den Abgleich ausschließlich auf name oder store_id zu beschränken.

2. Anhand des Filialcodes abfragen

Wenn Ihre Systeme Standorte anhand Ihrer eigenen Filialcodes identifizieren, lösen Sie diese direkt mit GET /locations-by-store-codes auf. Der Parameter storeCodes ist ein URL-kodiertes JSON-Array. Codes ohne Übereinstimmung fehlen im Ergebnis.

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. Vollständige Datensätze für mehrere IDs abrufen

Wenn Ihnen bereits base64-IDs aus Ihrem eigenen Datenspeicher oder einer Webhook-Payload vorliegen, gibt GET /locations-by-ids für alle diese IDs den vollständigen Datensatz in einem einzigen Aufruf zurück. Auch archivierte Standorte werden aufgelöst; lesen Sie daher archived und archivedAt, um sie zu unterscheiden. Unbekannte IDs werden ohne Hinweis ausgelassen; vergleichen Sie die Anzahlen.

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 }    ]  }}

Für eine serverseitig gefilterte Teilmenge des gesamten Kontos akzeptiert GET /locations auch einen JSON-kodierten Parameter filter, beispielsweise zur Filterung nach Genehmigungsstatus. Siehe Alle Standorte auflisten.

4. Standorte archivieren, die Sie nicht mehr verwalten

POST /locations/archive nimmt input.locationIds entgegen und gibt pro Standort einen result-Eintrag zurück. Die Archivierung wird geplant und erfolgt nicht sofort: Jeder Standort wechselt in den Status ARCHIVE_SCHEDULED, wird bis zum Ende des aktuellen Abrechnungszeitraums weiter synchronisiert und beim Erstellen der nächsten Rechnung archiviert. Ab diesem Zeitpunkt wird er nicht mehr mit Plattformen synchronisiert und nicht mehr abgerechnet.

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 }      ]    }  }}

Lesen Sie success in jedem Eintrag: Eine fehlerhafte ID blockiert nicht den Rest der Stapelverarbeitung. Solange die Archivierung geplant ist, ist das Feld archivalScheduledAt des Standorts in Listen- und Suchergebnissen gesetzt. Ein archivierter Standort kann erst nach seiner Reaktivierung aktualisiert werden. Wenn Webhooks konfiguriert sind, wird ein profile.deleted-Ereignis ausgelöst; es handelt sich um eine logische Löschung, und eine endgültige Löschung ist nicht vorgesehen.

5. Eine geplante Archivierung abbrechen

Vor dem Ende des Abrechnungszeitraums versetzt POST /locations/cancel_archive mit denselben IDs die betreffenden Standorte zurück in den Status ACTIVE, und die Abrechnung wird fortgesetzt. Sobald der Standort vollständig archiviert ist, gibt dieser Aufruf für ihn 404 zurück. Beim Abbrechen wird kein Webhook-Ereignis ausgelöst.

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 }      ]    }  }}

Beide SDKs erfordern zwei zusätzliche Positionsargumente, einen Auswahltyp und einen changedBy-Bezeichner, die sie zusammen mit locationIds senden. Der REST-Body benötigt nur die IDs.

Nächste Schritte

• Standort hinzufügen: der Aufruf zum Erstellen und warum das Festlegen von storeId in diesem Aufruf Schritt 2 ermöglicht.
• Standort aktualisieren: Korrigieren Sie die Angaben zu den gefundenen Standorten, statt sie zu archivieren.
• Standorte suchen, Standorte anhand von Filialcodes abrufen, Standorte anhand von IDs abrufen, Standorte archivieren und Geplante Archivierung abbrechen: die Referenzseiten.