Obtén reseñas de una ubicación o de toda tu cuenta

Lista reseñas recientes de una ubicación, filtra puntuaciones bajas sin respuesta, pagina con cursores, recorre la cuenta y recibe avisos por webhook.

Las reseñas se denominan interactions en la API. Todas las reseñas de Google, Facebook o Yelp se devuelven en una lista por ubicación y en un resumen consolidado de la cuenta, de modo que una sola integración cubre todas las fuentes que conectes.

1. Enumera las reseñas más recientes de una ubicación

GET /locations/{locationId}/reviews es una conexión basada en cursores en data.interactions. Los resultados se devuelven del más reciente al más antiguo, y el valor predeterminado de first es 20, por lo que una sola llamada nunca devuelve el historial completo. La ruta acepta el id en base64 o el número sin codificar.

Latest reviews

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

JSON

{  "data": {    "interactions": {      "pageInfo": { "hasNextPage": true, "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0..." },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "nice place for family together",            "authorName": "vaibhav nakate",            "rating": 5,            "date": "2019-04-02T22:11:13.036997+00:00",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

Lee data.interactions.edges[].node. El valor de id es un UUID sin codificar, no un id de Relay en base64, y es lo que debes pasar al responder. totalCount es el número de coincidencias en todo el conjunto de resultados, no en esta página. canRespond indica si esa fuente acepta respuestas del propietario a través de la API.

2. Filtra las reseñas de puntuación baja sin respuesta

Los filtros de tipo array son cadenas JSON en la cadena de consulta: ratingFilters=[1,2] conserva las reseñas de una y dos estrellas, y responseStatus=["PENDING"] conserva las reseñas sin respuesta del propietario. Los corchetes y las comillas deben estar codificados para URL, por lo que el ejemplo de cURL usa -G con --data-urlencode, que codifica cada valor y lo añade a la URL por ti. La cadena de consulta literal equivalente es ratingFilters=%5B1%2C2%5D&responseStatus=%5B%22PENDING%22%5D.

Unanswered 1-2 stars

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

Los filtros que puedes combinar:

Parámetro	Valores	Notas
`siteUrls`	`["maps.google.com"]`, `["facebook.com"]`, `["yelp.com"]`	Nombres de host de Enumera las fuentes de reseñas de una cuenta.
`ratingFilters`	`[1,2]`, etc.	Puntuaciones en estrellas que se deben conservar.
`responseStatus`	`["PENDING"]` o `["RESPONDED"]`	Si existe una respuesta del propietario.
`sortOrder`	`["NEWEST_FIRST"]`, `["OLDEST_FIRST"]`, `["LAST_RESPONDED"]`	De forma predeterminada, se muestran primero las más recientes.
`startDate`, `endDate`	`YYYY-MM-DD`	Cadenas simples, no JSON.
`searchString`	texto libre	Búsqueda de texto completo en el cuerpo de la reseña.

3. Recorre las páginas con cursores

Vuelve a pasar pageInfo.endCursor como after. Detente cuando hasNextPage sea false o una página devuelva un array edges vacío; si el límite de una página coincide con la reseña más antigua, le sigue una página vacía. Ambos SDK pueden leer las páginas por ti.

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

Cada solicitud cuenta para tu límite de solicitudes, y obtener las reseñas de una ubicación con 425 reseñas usando first=50 requiere nueve llamadas. Si recibes 429, espera el tiempo indicado por Retry-After antes de solicitar la siguiente página. Para una sincronización programada, acota la ejecución con startDate y endDate en lugar de volver a leer el historial. Consulta Límites de solicitudes.

4. Recorre toda la cuenta con el resumen consolidado

GET /rollup_interactions devuelve los mismos nodos de todas las ubicaciones a las que la clave tiene acceso, en data.rollupInteractions, con un locationId en cada nodo. Acepta los mismos filtros, además de tag, cuyo valor predeterminado es all. No hay ningún filtro de ubicación; agrupa los resultados por locationId por tu cuenta. Ninguno de los SDK ofrece todavía un método para este endpoint, por lo que los ejemplos de los SDK lo llaman con requests y fetch.

Account-wide pending

curl -G "https://listingsapi.com/api/v4/rollup_interactions" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

Cada nodo tiene la misma estructura que en el paso 1, más un locationId numérico, el databaseId del establecimiento. El pageInfo del resumen consolidado puede omitir endCursor, así que usa el cursor de la última arista como after; los dos valores son equivalentes.

5. Obtén todos los detalles por id

Si tienes ids almacenados, GET /reviewDetails devuelve copias actualizadas sin paginación. interactionIds es un array JSON, codificado para URL como los demás filtros. La respuesta es un array simple en data.interactionDetails.interactions, y cada interacción incluye su responses.

Details by id

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'

JSON

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",          "responded": true,          "responseCount": 1,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED"            }          ]        }      ]    }  }}

Si proporcionas un id de otra cuenta, el endpoint devuelve 200 con interactionDetails: null y un error SY90001, así que comprueba si hay null antes de acceder por índice.

6. Recibe eventos de webhook en lugar de realizar consultas periódicas

Con una URL de webhooks configurada, se dispara un evento interaction.review cuando se incorpora o cambia una reseña. Los campos de la reseña se encuentran en data.interaction, no directamente en data, y data.interaction.id es el mismo UUID que devuelve la lista.

Dos precauciones. location_id se transmite sin normalizar en este evento: puede ser una cadena numérica o null, así que conviértelo tú en lugar de confiar en el tipo. Además, el mismo id vuelve a llegar cada vez que cambia la reseña, así que trata el evento como una señal para volver a leer la reseña, no como una inserción única. La entrega se realiza en un único intento, sin reintentos, así que mantén la comprobación periódica del paso 4 como medida de respaldo. La configuración se explica en Reacciona a eventos con webhooks.

Próximos pasos

Responde a las reseñas: responde a las reseñas pendientes que acabas de encontrar y, después, edita o archiva la respuesta.
Análisis de reseñas: valoración, volumen y tasa de respuesta de la misma ubicación.
Referencia: Lista las interacciones, Obtén interacciones agregadas, Obtén interacciones por sus ID, Atributos de las interacciones.
SDKs: Reseñas en Python, Reseñas en Node.