Cómo diseñamos una API unificada para 84 fuentes de reseñas: esquema, IDs y pruebas de contrato
Dirijo Prisma Reviews, una pequeña API que devuelve reseñas de clientes de 84 plataformas en un único formato JSON. Esta entrada no trata sobre el producto. Trata sobre tres problemas de ingeniería que nos ocuparon la mayor parte del tiempo: diseñar un esquema que se adapte a fuentes con formas muy distintas, mantener los IDs estables para que la misma reseña nunca aparezca dos veces, y probar el contrato para que un cambio aguas arriba no rompa silenciosamente los clientes aguas abajo.
Una cosa primero, porque condiciona todo lo demás: no todas las fuentes de reseñas son APIs. De nuestras 84 fuentes, 59 tienen una API oficial. Las otras 25 no, y en su lugar leemos sus páginas o feeds públicos.
No todas las fuentes son una API
Cada plataforma de nuestra configuración tiene tres propiedades: cómo se conecta un negocio, si podemos publicar una respuesta y cómo nos llegan las reseñas nuevas. Si ordenamos las 84 fuentes según cómo las leemos, obtenemos cuatro grupos:
| Grupo | Fuentes | Ejemplos |
|---|---|---|
| API oficial, credenciales propias del negocio u OAuth | 50 | Google Business Profile (acceso pendiente), App Store, Google Play, Trustpilot (acceso pendiente), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, gestores de propiedades como Hostaway y Guesty |
| API pública oficial, sin credenciales del negocio | 9 | Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator |
| Sin API: página o feed público | 3 | Shopify App Store (página HTML de reseñas), WordPress.org (feed RSS de reseñas), Apple Podcasts (feed público de reseñas) |
| Sin API: proveedor de datos de pago | 22 | Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable |
Los grupos difieren en aspectos que se filtran en el diseño de la API:
- Autenticación. El primer grupo necesita un flujo OAuth o una clave que el negocio pega. Los otros tres solo necesitan la URL pública de una ficha.
- Respuestas. Solo 25 de las 84 fuentes permiten a un tercero publicar una respuesta, y dos de ellas, Google Business Profile y Trustpilot, siguen esperando que la plataforma apruebe nuestro acceso. Tener una API no basta: el endpoint de respuestas de Atlassian ahora responde
410 API_DEPRECATED, y la API de respuestas de Microsoft Store está rota por parte de Microsoft, así que ambas son de solo lectura. - Coste y frecuencia. Las APIs oficiales no nos cuestan nada por llamada, así que las consultamos a menudo. Leer a través de un proveedor de datos se factura por reseña, y algunos proveedores cobran por ejecución todo lo que sea nuevo, así que esas fuentes se consultan una vez al día.
- Por qué no hay API. La API de socios de Expedia con respuestas solo está abierta a channel managers completos, y nos rechazó. La de Airbnb es solo por invitación. Shopify no tiene API de reseñas; los desarrolladores de apps responden desde su propio panel.
Algunas plataformas aparecen dos veces. Las reseñas de Airbnb y Booking.com pueden venir de una página pública (solo lectura), o a través de la API oficial de un gestor de propiedades, que sí permite respuestas. Esa es la razón de uno de los campos que veremos más abajo.
Un solo esquema para todas
Cada reseña, de cada fuente, tiene los mismos 14 campos, y todos están siempre presentes. Cuando una plataforma no nos da algo, el campo es null, nunca falta. Una clave ausente y un null significan lo mismo para una persona, pero no para un cliente tipado, y "siempre presente" es fácil de probar.
{ "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E", "platform": "google", "location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N", "rating": 4, "title": null, "text": "Great flat white, a bit slow at lunchtime.", "author": "Marta G.", "language": "en", "url": null, "source": null, "created_at": "2026-10-19T12:41:07.000Z", "updated_at": "2026-10-19T12:41:07.000Z", "deleted_at": null, "reply": null } rating es un entero del 1 al 5, o null. Booking.com puntúa sobre 10, así que dividimos entre dos, redondeamos y limitamos a 1-5. Steam no tiene estrellas, solo "recomendado" o "no recomendado", que mapeamos a 5 y 1. Algunas fuentes permiten una reseña sin calificación, y entonces el campo es null. Nunca escribimos un 0: parece una puntuación real y arrastra las medias hacia abajo.
text y title pueden ser null. Las reseñas de solo calificación son habituales en las tiendas de apps, y solo algunas plataformas tienen títulos. No inventamos uno a partir de la primera frase.
url significa algo concreto en plataformas de solo lectura. Cuando no podemos publicar una respuesta, url es donde el negocio puede responderla a mano. Si un cliente intenta responder de todos modos, el error lleva la misma URL.
source existe por culpa de los agregadores. Viator devuelve reseñas escritas en Viator y en Tripadvisor. Un gestor de propiedades devuelve reseñas de Airbnb, Booking.com y Vrbo a través de una sola conexión. platform indica a través de qué conexión llegó la reseña; source indica en qué sitio se escribió.
created_at y updated_at están separados porque la gente edita reseñas. Una reseña de una estrella editada que pasa a ser de cuatro estrellas debe ser una actualización, no una fila nueva.
reply es un objeto con un estado, no una cadena. El estado es published, queued, failed o unknown. El último necesita explicación. A veces la petición a la plataforma sale y no vuelve ninguna respuesta, y la plataforma no tiene forma de leer la respuesta de vuelta. Reintentarlo podría publicar la misma respuesta dos veces, con el nombre del negocio. Así que nos detenemos, la marcamos como unknown, y le indicamos al cliente que compruebe la plataforma antes de publicar de nuevo. Un estado que dice "no lo sabemos" es más útil que una suposición.
Los límites de longitud de las respuestas se comprueban por plataforma antes de encolar una respuesta: 4.096 bytes en Google Business Profile, 350 caracteres en Google Play, 80 en eBay. Un emoji es un carácter pero cuatro bytes, así que contamos puntos de código para los límites de caracteres y bytes para los límites de bytes.
IDs estables y deduplicación
Los duplicados son el error que los clientes notan primero. Nuestra regla es simple: cada conector debe devolver el ID propio de la plataforma para cada reseña, y la base de datos tiene un índice único en (location_id, external_id). Una segunda sincronización de la misma reseña es una actualización, nunca una inserción. Las ubicaciones funcionan igual, con un índice único en (connection_id, external_id).
Lo difícil es que "el ID propio de la plataforma" no siempre existe:
- Las reseñas de Etsy no tienen ID propio. Cada reseña pertenece exactamente a una transacción, así que el ID de la transacción es el ID de la reseña.
- WordPress.org no da ningún ID de reseña en su feed. Cada reseña es un tema de foro, así que usamos el slug del tema.
- La página del Shopify App Store lleva un ID de contenido de reseña en su HTML. Nos apoyamos en él, sabiendo que un rediseño de la página podría cambiarlo.
- Google Play tiene IDs reales, pero su API solo devuelve reseñas creadas o editadas en los últimos siete días. El historial almacenado es nuestro, y no podemos volver a leerlo.
Los clientes nunca ven los IDs de las plataformas como claves primarias. Reciben nuestros propios IDs con un prefijo de tipo y un cuerpo ordenado por tiempo (rev_01KJ…, loc_01KJ…, req_01KJ…). El prefijo hace evidente un ID mal colocado en los logs, y el orden ayuda con la paginación: el cursor codifica el timestamp y el ID del último elemento, así que un límite de página se mantiene fijo mientras llegan reseñas nuevas.
Reconexión. Un negocio desconecta una cuenta y la vuelve a conectar una semana después. Crear ubicaciones nuevas duplicaría cada reseña. En su lugar, una ubicación desconectada hace menos de 30 días con el mismo ID externo se reactiva: mismos IDs, sin reseñas duplicadas.
Eliminaciones. Una reseña eliminada de la plataforma simplemente deja de aparecer. Nada te lo avisa. Para 60 de las 84 fuentes podemos leer el historial completo, así que lo volvemos a leer periódicamente (cada 25 días para Google Business Profile, cuyos términos no nos permiten conservar contenido sin confirmar más de 30; semanalmente para la mayoría de las demás) y marcamos con deleted_at las reseñas que la plataforma ya no devuelve, además de un webhook review.deleted. La salvaguarda clave: si una lectura se detuvo antes de tiempo, por un timeout o un límite de páginas, no marcamos nada. Tratar "no lo vi" como "ya no existe" eliminaría reseñas reales. Google Play queda excluido por su ventana de siete días.
Pruebas de contrato contra la especificación OpenAPI
El contrato es un documento OpenAPI 3.1 con 18 paths, 30 esquemas y 9 eventos de webhook. Dos tipos de prueba lo mantienen honesto.
La primera es barata y se ejecuta en cada commit: los enums de la especificación deben coincidir exactamente con el código. Los IDs de plataforma de la especificación deben ser iguales a la lista de la configuración de plataformas, y los eventos de webhook de la especificación deben ser iguales a los tipos de evento que el código puede emitir. Los clientes generados rechazan los valores de enum que desconocen, así que una plataforma añadida al código pero no a la especificación rompería esos clientes en su primera sincronización.
La segunda es un modo de pruebas. Las claves de API son de dos tipos, pk_live_… y pk_test_…, contra el mismo servidor. Una clave de prueba dirige cada plataforma a un conector de pruebas: ubicaciones y reseñas de ejemplo deterministas con la forma de las reales (una cafetería en Google, una app en el App Store, un hotel en Booking.com), respuestas que se aceptan y nunca se publican en ningún sitio, y en las plataformas de solo lectura una url en cada reseña, porque la documentación promete una. Cualquiera puede ejecutar el contrato completo, incluidos los paths de escritura, sin tocar una cuenta real.
Los ejemplos siguientes son los de la especificación, con las URL reemplazadas por example.com. Una petición de lista:
GET /v1/reviews?platform=google&limit=1 Authorization: Bearer pk_test_… devuelve la reseña mostrada antes dentro de data, más un next_cursor. Una respuesta a una plataforma que admite respuestas se acepta con 202, y la reseña vuelve con su respuesta en la cola (se omiten otros campos):
POST /v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply Authorization: Bearer pk_test_… Content-Type: application/json { "text": "Thanks Marta! We have added a second barista at lunch." } { "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E", "platform": "google", "reply": { "text": "Thanks Marta! We have added a second barista at lunch.", "created_at": null, "status": "queued", "error": null } } Los casos interesantes son los fallos. Cada error tiene la misma forma (type, code, message, retryable, request_id, docs_url), y algunos códigos añaden campos sobre los que un cliente puede actuar. Responder a una reseña de Yelp devuelve 422:
{ "error": { "type": "invalid_request_error", "code": "reply_not_supported", "message": "Yelp has no reply API for third parties, so Prisma only reads its reviews. Answer this one on the platform: https://example.com/biz/example-cafe-madrid", "retryable": false, "request_id": "req_01KJ8T3C5D7E9F1G3H5J7K9M1N", "docs_url": "https://example.com/docs/errors#reply_not_supported", "platform": "yelp", "url": "https://example.com/biz/example-cafe-madrid" } } Una respuesta que supera el límite de la plataforma también devuelve 422, con code: "reply_too_long", platform: "google_play" y max_length: 350. Los clientes deberían ramificar según code, nunca según message: el mensaje es para personas y puede cambiar.
La misma forma se mantiene en tráfico real. Esta es una respuesta real de producción a una petición sin clave (cabeceras recortadas, URL de docs reemplazada):
HTTP/1.1 401 Unauthorized Content-Type: application/json Request-Id: req_01K6VVGDM8CFFJEQ3MNWWR582S {"error":{"type":"authentication_error","code":"missing_api_key","message":"Send your API key as \"Authorization: Bearer pk_live_…\".","retryable":false,"request_id":"req_01K6VVGDM8CFFJEQ3MNWWR582S","docs_url":"https://example.com/docs/errors#missing_api_key"}} El request_id del cuerpo coincide con la cabecera Request-Id. Para cada operación comprobamos el código de estado, que el cuerpo valida contra su esquema (los 14 campos de reseña presentes, tipos nullable donde están declarados), la forma del error en cada respuesta no 2xx, y las cabeceras Request-Id y de límite de peticiones en caso de éxito.
Ejecuta las mismas comprobaciones con Apidog CLI
Las mismas comprobaciones funcionan en cualquier API que incluya un archivo OpenAPI. Apidog CLI importa la especificación, y un agente de código como Claude Code escribe y ejecuta los casos de prueba. Configúralo una vez:
npm install -g apidog-cli@latest apidog login --with-token <YOUR_TOKEN> apidog skill install Luego dale al agente un único prompt:
Import ./openapi.json into Apidog project <projectId>. Create test cases for the list reviews and reply endpoints that assert the status code, that the body validates against its schema with all 14 review fields present, and that the Request-Id header is set. Add a case that replies to a Yelp review and expects 422 with code reply_not_supported. Run them against the test environment and summarize any failures. El agente importa la especificación, lee el esquema de casos de prueba, valida su payload, crea el caso y lo ejecuta:
apidog import --project <projectId> --format openapi --file ./openapi.json apidog cli-schema get test-case-create apidog cli-schema validate test-case-create --file case.json apidog test-case create --project <projectId> --file case.json apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,junit El reporter junit escribe un archivo que tu CI puede leer, así que la misma ejecución puede servir de puerta para cada pull request. La guía de CI/CD de Apidog CLI cubre la configuración del pipeline.
Lecciones
Modela "tiene API" y "puede responder" como propiedades separadas. Atlassian y Microsoft demuestran que una API puede existir y aun así no aceptar respuestas. Un solo flag para ambas prometería respuestas que no podemos entregar.
Planifica el estado de respuesta unknown antes de que salga la primera respuesta. Un estado que admite incertidumbre cuesta un valor de enum; una respuesta pública duplicada cuesta la confianza de un cliente.
No confíes en que un ID de plataforma exista o se mantenga estable. Anota, por conector, de dónde viene el ID y qué podría cambiarlo.
Prueba la especificación contra el código, no solo el código contra la especificación. La prueba de enums son unas diez líneas, y protege el fallo que más daña a los clientes generados.





