Listings APIListings API
Iniciar sesión

Haz tu primera llamada a la API

Autentícate, enumera tus ubicaciones, interpreta la estructura de la respuesta, recorre los resultados paginados y aprende cómo funcionan los ID.

Esta guía presupone que tienes una cuenta y una clave de API obtenidas siguiendo Primeros pasos. Todas las solicitudes se ejecutan contra la API activa en https://listingsapi.com, por lo que una llamada de escritura con una clave de API normal modifica datos reales. Para probar la API sin afectar a plataformas de publicación reales, usa el pase de un día gratuito para el entorno de pruebas.

1. Configura tu clave de API

Copia la clave de Claves de API en el panel y expórtala una vez en tu intérprete de comandos:

bash
export LISTINGSAPI_KEY="your-api-key"

Las claves tienen un nivel de acceso. Una clave Read (lectura) permite realizar todas las consultas y generar todos los informes de estas guías. Para crear o actualizar cualquier elemento, responder a una reseña o publicar una publicación, necesitas una clave Write (escritura). Si envías una clave Read a un endpoint de escritura, este devuelve el estado HTTP 400 con el código de error SY90016.

2. Enumera tus ubicaciones

Otros endpoints hacen referencia a una ubicación mediante su ID, así que empieza por enumerar las que tienes. La cabecera Authorization de REST usa el esquema API, seguido de un espacio y tu clave de API: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Lee la respuesta

La API REST devuelve una respuesta anidada en lugar de un array sin más. El nombre de la operación se encuentra en data, los resultados de la lista se devuelven como una conexión de edges y cada arista contiene un node:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

El Python SDK devuelve una página iterable de objetos. El Node SDK devuelve locations y pageInfo. Cuando llames directamente a la API REST, lee data.allLocations.edges[].node.

4. Recorre las páginas de resultados

Los endpoints que enumeran ubicaciones y reseñas usan paginación por cursor. Solicita una página con first y luego pasa pageInfo.endCursor como after para obtener la siguiente página. Los SDK pueden leer todas las páginas por ti.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

No todos los endpoints usan este tipo de paginación. Las cuentas conectadas, los resúmenes de duplicados y las publicaciones usan page y perPage con un array records. Cada guía indica qué formato de paginación usan sus endpoints.

5. Dos tipos de ID

Cada registro tiene dos identificadores. id es una cadena en base64, como TG9jYXRpb246MTgwMDI4OQ==, que al decodificarse da Location:1800289. databaseId es el número sin codificar, 1800289.

Guarda el id en base64. Todos los endpoints de escritura requieren identificadores codificados en base64, y esos son los valores que se devuelven en los datos de los webhooks. Muchos endpoints de lectura que reciben una ubicación en la ruta también aceptan el número sin codificar, y ambos SDK aceptan cualquiera de los dos formatos y realizan la codificación por ti.

6. Errores y límites de solicitudes

Las respuestas de error devuelven el estado HTTP correspondiente con un array errors. El mensaje lleva como prefijo un código de error SY, incluido en Códigos de error:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

Los límites de solicitudes dependen del plan y se contabilizan por minuto, hora y día. Launch permite 10 solicitudes por minuto. Cuando superas un límite, la API devuelve 429 con una cabecera Retry-After; espera esa cantidad de segundos antes de volver a intentarlo. Los SDK lanzan RateLimitError y proporcionan ese mismo valor. Encontrarás todos los detalles en Límites de solicitudes.

Siguientes pasos