Busca ubicaciones y archiva las que ya no gestionas

Busca por palabra clave, resuelve códigos e IDs de tienda en lote y programa o cancela el archivado de sucursales cerradas al fin del ciclo de facturación.

Tres endpoints de lectura permiten encontrar ubicaciones mediante distintas claves: una búsqueda de texto libre, una consulta por código de tienda y una consulta por id. El archivado es una operación de escritura programada: la ubicación permanece activa hasta el final del ciclo de facturación actual y, después, deja de sincronizarse y de facturarse. Hasta ese momento puedes cancelarlo.

1. Busca por palabra clave

GET /locations/search?query= busca coincidencias del término en el nombre, la dirección postal, la ciudad y el id de tienda, y devuelve una conexión con cursor: edges[].node con pageInfo.endCursor, paginada mediante first y after. Omite query para recorrer toda la cuenta mediante paginación.

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 vacío significa que no hubo coincidencias, que es la comprobación que debes realizar antes de crear una tienda cuando no sabes con certeza si ya existe. Ambos SDK aceptan fields para restringir la búsqueda de coincidencias únicamente a name o store_id.

2. Consulta por código de tienda

Si tus sistemas identifican las ubicaciones mediante tu propio código de tienda, consúltalas directamente con GET /locations-by-store-codes. El parámetro storeCodes es un array JSON con codificación URL. Los códigos sin coincidencias no aparecen en el 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. Obtén los datos completos de un lote de ids

Cuando ya tienes ids en base64, procedentes de tu propio almacenamiento o del contenido de un webhook, GET /locations-by-ids devuelve el registro completo de cada uno en una sola llamada. También se devuelven las ubicaciones archivadas, así que consulta archived y archivedAt para distinguirlas. Los ids desconocidos se omiten sin avisar; compara los recuentos.

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 obtener un subconjunto de toda la cuenta filtrado en el servidor, GET /locations también acepta un parámetro filter codificado en JSON, por ejemplo, para filtrar por estado de aprobación. Consulta Listar todas las ubicaciones.

4. Archiva las ubicaciones que ya no gestionas

POST /locations/archive recibe input.locationIds y devuelve una entrada result por ubicación. El archivado es programado, no inmediato: cada ubicación pasa a ARCHIVE_SCHEDULED, sigue sincronizándose hasta que termina el ciclo de facturación actual y se archiva cuando se genera la siguiente factura. A partir de ese momento, deja de sincronizarse con las plataformas de publicación y de facturarse.

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

Consulta el success de cada entrada: un id incorrecto no bloquea el resto del lote. Mientras el archivado está programado, el campo archivalScheduledAt de la ubicación aparece establecido en los resultados de las listas y las búsquedas. Una ubicación archivada no se puede actualizar hasta que se reactive. Si hay webhooks configurados, se emite un evento profile.deleted; se trata de una eliminación lógica y no existe la eliminación permanente.

5. Cancela un archivado programado

Antes de que se cierre el ciclo, POST /locations/cancel_archive con los mismos ids devuelve las ubicaciones a ACTIVE y la facturación continúa. Una vez que la ubicación está completamente archivada, esta operación devuelve 404 para ella. La cancelación no emite ningún 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 SDK requieren dos argumentos posicionales adicionales, un tipo de selección y un identificador changedBy, que envían junto con locationIds. El cuerpo de la solicitud REST solo necesita los ids.

Próximos pasos

• Añadir una ubicación: la llamada de creación y por qué establecer storeId en ella hace posible el paso 2.
• Actualizar una ubicación: corrige los datos de las ubicaciones que encontraste en lugar de archivarlas.
• Buscar ubicaciones, Obtener ubicaciones por códigos de tienda, Obtener ubicaciones por IDs, Archivar ubicaciones y Cancelar el archivado programado: las páginas de referencia.