Elige cómo integrar
Compara la API REST, los SDK de Python y Node, el servidor MCP y los webhooks según la arquitectura de tu aplicación y los requisitos de integración.
Todos los métodos de integración utilizan la misma clave de API y URL base: https://listingsapi.com/api/v4. Puedes usar la API REST o un SDK para las solicitudes a la API, los webhooks para las actualizaciones basadas en eventos y el servidor MCP para integrar con la ayuda de un agente de IA.
1. Elige cómo llamarás a la API
API REST. Usa la API REST para acceder a todos los endpoints directamente a través de HTTP. Tu aplicación debe analizar la respuesta, gestionar ambos métodos de paginación e inspeccionar el array errors[] para detectar errores de la API.
Python SDK. Instala el Python SDK con pip install listingsapi. El SDK proporciona clases de recursos a través de interfaces como client.locations y client.reviews. Gestiona la paginación por cursor con auto_paging_iter(), reintenta las solicitudes que devuelven respuestas 429 o 5xx y valida los cuerpos de datos de las ubicaciones en locations.add() antes de enviar la solicitud a la API. Lee Python SDK.
Node SDK. Instala el Node SDK con npm install listingsapi-js. Requiere Node.js 18 o posterior, incluye definiciones de tipos de TypeScript y no tiene dependencias en tiempo de ejecución. Los métodos del SDK se exponen directamente en la instancia del cliente, por ejemplo, client.fetchAllLocations(). Configura fetchAll: true para recuperar todos los resultados paginados en una sola respuesta. Los ID numéricos se codifican automáticamente en Base64 antes de enviar las solicitudes a la API. Lee Node SDK.
Servidor MCP. Conecta clientes de IA como Claude, ChatGPT, Cursor y Gemini al servidor MCP de ListingsAPI en https://listingsapi.com/mcp mediante Streamable HTTP. No es necesario instalar un servidor MCP local. El servidor expone herramientas para buscar en la documentación de ListingsAPI, descubrir endpoints REST y ejecutar operaciones compatibles de la API. La autenticación utiliza una clave de API u OAuth. Abre /dashboard/mcp para ver la configuración del cliente, las herramientas MCP disponibles y el nivel de permisos de la clave de API necesario para cada herramienta. Conecta un agente de IA con MCP.
Webhooks. Usa webhooks con la API REST, los SDK o el servidor MCP para recibir actualizaciones basadas en eventos. Cuando cambia una ubicación, ficha, reseña o publicación, ListingsAPI envía una solicitud HTTP POST a la URL del webhook configurada para tu cuenta. Esto permite que tu aplicación procese los cambios sin consultar periódicamente la API en busca de actualizaciones. Lee Introducción a los webhooks.
2. Comprende el modelo de autenticación
La API REST y los SDK autentican las solicitudes mediante una clave de API. Pasa la clave en la cabecera HTTP Authorization de la solicitud mediante el esquema de autenticación API:
Authorization: API <YOUR_API_KEY>
Las claves de API tienen acceso Read (lectura) o Write (escritura). Una clave Read permite acceder a operaciones de lectura, incluidas las consultas y los informes. Se requiere una clave Write para las operaciones que crean o actualizan recursos. Si envías una clave Read a un endpoint de escritura, el endpoint devuelve el estado HTTP 400 con el código de error SY90016.
El alcance de las claves de API se limita a una cuenta. Las solicitudes realizadas con claves de la misma cuenta consumen la misma cuota de límite de solicitudes de esa cuenta.
El servidor MCP también admite la autenticación con OAuth. Los clientes MCP pueden autenticarse a través del navegador mediante OAuth en lugar de proporcionar una clave de API. Las solicitudes de la API REST y los SDK se autentican mediante la cabecera Authorization. Consulta la documentación de Autenticación para obtener detalles sobre la configuración.
3. Comprende los modelos de paginación
Los endpoints REST que devuelven listas usan paginación basada en cursores o en desplazamientos. Los SDK abstraen estos modelos de paginación.
Los endpoints basados en cursores aceptan first y after. Los resultados se devuelven a través de edges[].node, y pageInfo.endCursor proporciona el cursor para la siguiente solicitud.
Los endpoints basados en desplazamientos aceptan page y perPage. Los resultados se devuelven en records[], y pageInfo.totalRecords indica el número total de registros disponibles.
Los siguientes ejemplos realizan la misma operación de enumeración de ubicaciones mediante tres métodos de integración. La implementación con cURL requiere que la aplicación analice directamente la estructura de la respuesta de la API.
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.En todos los métodos de integración, los errores de la API se devuelven en el array errors[], con un código de error SY como prefijo de cada mensaje de error. Las solicitudes de escritura pueden devolver HTTP 200 con success: false, por lo que debes comprobar el cuerpo de la respuesta antes de considerar que la operación se ha completado correctamente.
Cuando la cuenta supera su límite de solicitudes, la API devuelve HTTP 429 con una cabecera Retry-After. El plan Launch admite hasta 10 solicitudes por minuto. Consulta la documentación de Códigos de error y Límites de solicitudes para obtener más información.
4. Elige entre webhooks y consultas periódicas
Usa consultas periódicas cuando tu aplicación necesite conocer el estado de los recursos según un horario definido, como en una sincronización nocturna de todas las ubicaciones, o cuando el evento requerido no sea compatible con webhooks. Usa webhooks cuando tu aplicación necesite procesar cambios a medida que se producen, como la recepción de una nueva reseña, un cambio de estado de una ficha o el rechazo de una publicación en Google.
Configura una URL de webhook por cuenta en /dashboard/webhooks. Cada solicitud de webhook incluye una cabecera X-ListingsAPI-Signature con el siguiente formato:
X-ListingsAPI-Signature: sha256=<base64 HMAC>
El endpoint del webhook debe devolver una respuesta 2xx en un plazo de 5 segundos. Las entregas fallidas no se reintentan.
Usa el evento del webhook como desencadenante para obtener el estado actual del recurso desde la API. Dado que las entregas de webhooks no se reintentan, ejecuta un proceso de conciliación programado para detectar las actualizaciones que se hayan podido pasar por alto. Consulta Reacciona a eventos con webhooks para ver un ejemplo de implementación.
5. Compara de un vistazo
Siguientes pasos
- Añade una ubicación: tu primera llamada de escritura con la opción que hayas elegido.
- Reacciona a eventos con webhooks: pon en marcha un receptor que verifique las firmas.
- Python SDK y Node SDK: instala, configura y consulta las tablas de métodos.
- Autenticación, Límites de solicitudes y Códigos de error: las tres referencias que comparten todas las opciones.