API complementarias

Cada endpoint de apoyo con cURL, Python y Node: países, estados admitidos, catálogo de subcategorías y plataformas de publicación incluidas en tu plan.

Los endpoints de apoyo ofrecen los tres catálogos de referencia que el resto de la API utiliza para validar los datos: qué países y estados se admiten, qué categorías de negocio existen y qué directorios de las plataformas de publicación cubre tu plan. Los tres son de solo lectura, no tienen paginación y devuelven el conjunto completo, por lo que basta con una clave Read (lectura) y el almacenamiento en caché importa más que la paginación.

Resumen de los endpoints

Listar los países y estados admitidos

GET /countries

Devuelve el catálogo completo en data.supportedCountries. Cada país incluye un código ISO, un id en base64, un databaseId numérico, un array states cuyas entradas tienen sus propios códigos ISO y tres indicadores de dirección: hasCity (ciudad obligatoria), stateRequired (estado obligatorio y validado con states) y hasPostalCode (el país utiliza códigos postales). Un país que no está subdividido devuelve un array states vacío.

Parámetros

Este endpoint no acepta ninguno. Siempre devuelve el conjunto completo.

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

Los dos campos iso contienen los valores que necesitas. El iso de un país se utiliza como countryIso al crear y actualizar, y el iso de un estado se utiliza como stateIso. Validar ambos con esta lista antes de una operación de escritura convierte un 400 del servidor en un mensaje claro en tu propio formulario.

Listar las subcategorías

GET /sub-categories

Devuelve unos 6,000 registros de categorías en data.subcategories en un único array sin paginación. Esta consulta convierte un tipo de negocio que conoces como texto libre en el id numérico que exige una operación de escritura de una ubicación.

Parámetros

Ninguno. Cada llamada devuelve el catálogo completo.

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

Cada registro contiene cinco campos, y el que uses depende de dónde vayas a utilizarlo.

Una ubicación admite una categoría principal en subCategoryId y hasta nueve más en additionalCategoryIds.

Listar los sitios del plan

GET /plan-sites

Devuelve todos los directorios de las plataformas de publicación incluidos en el plan de tu cuenta, en data.planSites. Esta es la lista de referencia de los ids numéricos de los sitios, y solo los ids que aparecen aquí son válidos en el resto de la API.

Parámetros

Ninguno. La respuesta se limita al plan de tu cuenta.

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

Los dos arrays de países responden a preguntas diferentes. supportedCountries indica en qué países el sitio acepta fichas, así que filtra por el countryIso de tu ubicación antes de ofrecer una plataforma de publicación. hideAddressSupportedCountries indica en qué países el sitio respeta la ocultación de la dirección, que es lo que necesita un negocio con área de servicio. Ambos arrays pueden contener cincuenta códigos o más; el ejemplo anterior está abreviado.

Los ids de los sitios son estables y conviene conocerlos: 1 corresponde a Google Maps y 184 a Facebook, las dos plataformas de publicación a las que se dirigen la mayoría de los flujos de conexión.

Enlaces de acción del lugar

No es un endpoint independiente. Los enlaces de acción del lugar son los botones de Google, como Order online (pedir online), Reserve a table (reservar una mesa) y Book an appointment (reservar una cita), y la plataforma los gestiona como un campo de la ubicación en lugar de como un recurso independiente. Los defines mediante el array placeActionLinks al crear y actualizar, y los consultas desde cualquier endpoint de lectura de ubicaciones.

Cada entrada requiere un placeActionType y un uri, admite un indicador opcional isPreferred con un máximo de un enlace preferido por tipo, y acepta un action de add o delete al actualizar. Los tipos válidos, las reglas de eliminación y el comportamiento de sincronización se detallan en Enlaces de acción del lugar.

Errores que verás

Ninguno de estos endpoints realiza escrituras, por lo que una clave Read nunca devuelve SY90016 aquí. La lista completa está en Códigos de error.

Próximos pasos

• Consultar países y categorías: la versión orientada a la tarea, que explica paso a paso cómo pasar a la creación de una ubicación.
• Añadir una ubicación: donde se utilizan countryIso y subCategoryId.
• Detectar y corregir errores de fichas: utiliza los sitios del plan para distinguir entre una plataforma de publicación que falta y una que falla.
• Referencia de las API auxiliares para consultar la lista completa de campos de los tres endpoints.