Trova le sedi e archivia quelle che non gestisci più

Cerca per parola chiave, risolvi codici negozio e ID in blocco, programma o annulla l'archiviazione di sedi chiuse a fine ciclo di fatturazione.

Tre endpoint di lettura trovano le sedi tramite chiavi diverse: una ricerca a testo libero, una ricerca per codice negozio e una ricerca per id. L'archiviazione è un'operazione di scrittura pianificata: la sede rimane attiva fino alla fine del ciclo di fatturazione corrente, poi la sincronizzazione e la fatturazione si interrompono. Fino a quel momento puoi annullarla.

1. Cerca per parola chiave

GET /locations/search?query= cerca il termine nel nome, nell'indirizzo, nella città e nell'id del negozio e restituisce una connessione basata su cursori: edges[].node con pageInfo.endCursor, paginata tramite first e after. Ometti query per scorrere le pagine dell'intero account.

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 array edges vuoto indica che non sono state trovate corrispondenze: questo è il controllo da eseguire prima di una creazione quando non sai con certezza se un negozio esiste già. Entrambi gli SDK accettano fields per limitare la ricerca delle corrispondenze solo a name o store_id.

2. Cerca per codice negozio

Se i tuoi sistemi identificano le sedi tramite un tuo codice negozio, risolvile direttamente con GET /locations-by-store-codes. Il parametro storeCodes è un array JSON con codifica URL. I codici senza corrispondenza non sono presenti nel risultato.

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. Recupera i record completi per un gruppo di id

Quando disponi già di id base64, provenienti dal tuo archivio o dal payload di un webhook, GET /locations-by-ids restituisce il record completo per ciascuno di essi in un'unica chiamata. Vengono risolte anche le sedi archiviate, quindi leggi archived e archivedAt per distinguerle. Gli id sconosciuti vengono ignorati senza segnalazioni; confronta i conteggi.

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

Per ottenere un sottoinsieme dell'intero account selezionato lato server, GET /locations accetta anche un parametro filter codificato in JSON, ad esempio per filtrare in base allo stato di approvazione. Consulta Elenca tutte le sedi.

4. Archivia le sedi che non gestisci più

POST /locations/archive accetta input.locationIds e restituisce una voce result per ogni sede. L'archiviazione è pianificata, non immediata: ogni sede passa a ARCHIVE_SCHEDULED, continua a sincronizzarsi fino alla fine del ciclo di fatturazione corrente e viene archiviata quando viene generata la fattura successiva. Da quel momento la sincronizzazione con le piattaforme di pubblicazione e la fatturazione si interrompono.

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

Leggi success di ogni voce: un id non valido non blocca il resto del gruppo. Mentre l'archiviazione è pianificata, il campo archivalScheduledAt della sede è impostato nei risultati degli elenchi e delle ricerche. Una sede archiviata non può essere aggiornata finché non viene riattivata. Se sono configurati webhook, viene emesso un evento profile.deleted; si tratta di un'eliminazione logica e non è prevista un'eliminazione definitiva.

5. Annulla un'archiviazione pianificata

Prima della chiusura del ciclo, POST /locations/cancel_archive con gli stessi id riporta le sedi a ACTIVE e la fatturazione continua. Una volta che la sede è stata completamente archiviata, questa operazione restituisce 404 per quella sede. L'annullamento non emette alcun evento 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 }      ]    }  }}

Entrambi gli SDK richiedono due argomenti posizionali aggiuntivi, un tipo di selezione e un identificatore changedBy, che inviano insieme a locationIds. Il corpo della richiesta REST richiede solo gli id.

Passaggi successivi

• Aggiungi una sede: la chiamata di creazione e perché impostare storeId in quella chiamata rende possibile il passaggio 2.
• Aggiorna una sede: correggi i dettagli delle sedi che hai trovato invece di archiviarle.
• Cerca sedi, Ottieni sedi tramite i codici negozio, Ottieni sedi tramite gli ID, Archivia sedi e Annulla l'archiviazione programmata: le pagine di riferimento.