Listings APIListings API
Iniciar sesión

Añadir una ubicación

Crea una ubicación con los campos que necesitan las plataformas de publicación, gestiona errores de validación y confirma que esté en cola para envío.

Las fichas, las reseñas, las publicaciones y las analíticas se vinculan a un ID de ubicación. POST /api/v4/locations crea la ubicación y pone en cola una ficha por cada plataforma de publicación incluida en tu plan.

1. Recopila los campos obligatorios

Hay diez campos obligatorios. Un negocio con área de servicio también envía la dirección completa: con hideAddress: true, ListingsAPI almacena la dirección, pero no la envía a las plataformas de publicación. Las plataformas de publicación muestran en blanco los campos opcionales omitidos, así que envía toda la información que tengas.

CampoObligatorioNotas
nameSíDe 2 a 150 caracteres.
descriptionSíMínimo de 200 caracteres (SY10005).
countryIsoSíCódigo de dos letras de un país admitido (SY10036).
citySíObligatorio cuando hasCity del país es true (SY10126). Cuando es false, se descarta la ciudad que envíes.
subCategoryIdSídatabaseId numérico de la lista de subcategorías.
streetSíDe 5 a 100 caracteres (SY10011).
stateIsoSíEs obligatorio cuando stateRequired del país es true y debe ser uno de los states de ese país (SY10010). Omítelo cuando stateRequired sea false.
postalCodeNoEs opcional, pero envíalo siempre que hasPostalCode del país sea true. El valor que envíes debe ajustarse al formato del país (SY10014).
phoneSíSe valida según el país (SY10015).
bizUrlSíSe publica como sitio web. Algunas plataformas de publicación rechazan las fichas que no tienen uno.
storeIdNoTu propio código de tienda, único en toda la cuenta. Úsalo para volver a encontrar la ubicación sin almacenar nuestros ID.
businessHoursNoUna entrada por cada día de la semana. Consulta el formato en Actualizar una ubicación.

2. Crea la ubicación

POST /api/v4/locations recibe los campos en un objeto input en el cuerpo JSON de la solicitud. El método locations.add() del Python SDK recibe los mismos campos como argumentos con nombre y valida los obligatorios antes de enviar la solicitud. El método createLocation() del Node SDK recibe directamente el objeto camelCase.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. Lee la respuesta

Una creación correcta devuelve success: true y la nueva ubicación en data.createLocation.location. Guarda ambos identificadores: id es el valor base64 que recibe cada operación de escritura posterior, y databaseId es el valor numérico que se muestra en los paneles y en las cargas útiles de los webhooks.

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

status es PENDING mientras se valida la ubicación y se pone en cola. Avanza sin necesidad de otra llamada a la API.

4. Gestiona los errores de validación

Una creación puede fallar en dos puntos. Una solicitud mal formada o una clave incorrecta devuelve 4xx con un array errors en el nivel superior. Una solicitud bien formada con un campo que la API rechaza devuelve 200 con success: false y el problema dentro de data.createLocation.errors, así que comprueba el cuerpo de la respuesta de cada operación de escritura, no solo el código de estado.

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

Ambos SDK lanzan excepciones en caso de error. locations.add() de Python comprueba localmente los campos obligatorios y lanza ValidationError antes de enviar la solicitud. createLocation() de Node lanza ValidationError cuando la API rechaza los datos de entrada, por lo que el ejemplo anterior no comprueba ningún indicador de éxito.

Los códigos que encontrarás con más frecuencia:

CódigoCausaSolución
SY10005Falta la descripción o tiene menos de 200 caracteres.Escribe una descripción más completa.
SY10011Falta street o tiene menos de 5 caracteres.Envía street.
SY10010Falta stateIso o no es válido para el país.Envía un código de estado del endpoint de países.
SY10036countryIso no es un país admitido.Usa un código del endpoint de países.
SY10126Falta city para un país que lo exige.Envía city.
SY90016La clave es de solo lectura.Usa una clave de escritura.

5. Confirma que el envío ha comenzado

Al crear la ubicación, se pone en cola una ficha por cada plataforma de publicación de tu plan. Cada ficha comienza en AVAILABLE o IN_PROGRESS y pasa a SYNCED con un listingUrl una vez que la plataforma de publicación la acepta.

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

Con los webhooks configurados, no es necesario realizar consultas periódicas. Se emite un evento profile.created cuando el registro existe, y se emite un evento listing.submission para cada plataforma de publicación a medida que cambia su estado.

Próximos pasos