Encontre locais e arquive aqueles que você não gerencia mais

Pesquise por palavra-chave, consulte códigos de loja e IDs em lote e agende ou cancele o arquivamento de filiais fechadas no fim do ciclo de cobrança.

Três endpoints de leitura encontram locais por diferentes chaves: uma pesquisa de texto livre, uma consulta por código de loja e uma consulta por id. O arquivamento é uma operação de escrita agendada: o local permanece ativo até o fim do ciclo de faturamento atual e, então, deixa de ser sincronizado e cobrado. Até esse momento, você pode cancelar o arquivamento.

1. Pesquise por palavra-chave

GET /locations/search?query= busca correspondências para o termo no nome, no endereço, na cidade e no id da loja e retorna uma conexão com cursor: edges[].node com pageInfo.endCursor, paginada com first e after. Omita query para paginar toda a conta.

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

Um array edges vazio significa que nenhuma correspondência foi encontrada, e essa é a verificação que você deve fazer antes de criar uma loja quando não tiver certeza se ela já existe. Ambos os SDKs aceitam fields para restringir a correspondência apenas a name ou store_id.

2. Consulte por código de loja

Se os seus sistemas identificam os locais pelo seu próprio código de loja, consulte-os diretamente com GET /locations-by-store-codes. O parâmetro storeCodes é um array JSON codificado para URL. Códigos sem correspondência não aparecem no resultado.

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. Carregue os dados completos de um lote de ids

Quando você já tem ids em base64, provenientes do seu próprio armazenamento ou do payload de um webhook, GET /locations-by-ids retorna o registro completo de cada um deles em uma única chamada. Locais arquivados também são encontrados, então consulte archived e archivedAt para distingui-los. Ids desconhecidos são omitidos silenciosamente; compare as contagens.

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

Para obter um subconjunto de toda a conta filtrado no servidor, GET /locations também aceita um parâmetro filter codificado em JSON, por exemplo, para filtrar pelo status de aprovação. Consulte Liste todos os locais.

4. Arquive locais que você não gerencia mais

POST /locations/archive recebe input.locationIds e retorna uma entrada result por local. O arquivamento é agendado, não imediato: cada local entra em ARCHIVE_SCHEDULED, continua sendo sincronizado até o fim do ciclo de faturamento atual e é arquivado quando a próxima fatura é gerada. A partir daí, ele deixa de ser sincronizado com as plataformas de publicação e de ser cobrado.

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

Leia o success de cada entrada: um id inválido não bloqueia o restante do lote. Enquanto o arquivamento estiver agendado, o campo archivalScheduledAt do local fica definido nos resultados de listagem e pesquisa. Um local arquivado não pode ser atualizado até ser reativado. Se houver webhooks configurados, um evento profile.deleted é disparado; trata-se de uma exclusão lógica, e não há exclusão física.

5. Cancele um arquivamento agendado

Antes do encerramento do ciclo, POST /locations/cancel_archive com os mesmos ids retorna os locais a ACTIVE, e a cobrança continua. Depois que o local estiver totalmente arquivado, essa operação retorna 404 para ele. O cancelamento não emite nenhum evento de 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 }      ]    }  }}

Ambos os SDKs exigem dois argumentos posicionais adicionais, um tipo de seleção e um identificador changedBy, que são enviados junto com locationIds. O corpo da requisição REST precisa apenas dos ids.

Próximas etapas

• Adicionar um local: a chamada de criação e por que definir storeId nela torna a etapa 2 possível.
• Atualizar um local: corrija os detalhes dos locais que você encontrou em vez de arquivá-los.
• Pesquisar locais, Obter locais por códigos de loja, Obter locais por IDs, Arquivar locais e Cancelar o arquivamento agendado: as páginas de referência.