API

API de Review Sources

Registra fuentes de reviews (Google, Trustpilot, etc.), pull de reviews y lectura de tendencias.

Las review sources son plataformas de valoración externas (Google Business Profile, Trustpilot, Yelp, ProvenExpert, Trusted Shops, …) que Rankion sondea y consolida en pulls regulares. Por la API gestionas las sources, rotas auth keys y opcionalmente recibes updates en tiempo real por webhook — el único endpoint webhook outbound de toda la API de Rankion.

Contexto del módulo: Review Sources · ver también Webhooks.

Gestionar sources

Method	Endpoint	Descripción
GET	`/v1/review-sources`	Todas las sources activas (plataforma, status, last pull)
GET	`/v1/review-sources/{id}`	Detalle con lista de reviews actual
DELETE	`/v1/review-sources/{id}`	Eliminar source

curl "$BASE/review-sources" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, platform, source_url, status, avg_rating, total_reviews, last_pull_at}'

Control de auth

Por source existe una auth key (para plataformas key-based) o una OAuth connection (para Google).

Method	Endpoint	Descripción
POST	`/v1/review-sources/{id}/rotate-key`	Rotar auth key (la antigua queda inválida al instante)
POST	`/v1/review-sources/{id}/disconnect`	Pausar source sin eliminar
POST	`/v1/review-sources/{id}/reconnect`	Reactivar source pausada

curl -X POST "$BASE/review-sources/4/rotate-key" \
  -H "Authorization: Bearer $TOKEN"

La response entrega la nueva key una sola vez — luego solo enmascarada (xxxx-…-1234). Guárdala inmediatamente en tu config.

Onboarding de source

Las nuevas sources se crean por dos vías: registro activo de webhook (para plataformas con soporte push) o entrada en waitlist (para plataformas aún no habilitadas).

Method	Endpoint	Descripción
POST	`/v1/review-sources/webhook`	Registrar nueva source con setup de webhook
POST	`/v1/review-sources/waitlist`	Solicitud para una plataforma todavía no soportada

curl -X POST "$BASE/review-sources/webhook" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"platform": "trustpilot", "source_url": "https://trustpilot.com/review/example.com"}'

Public review webhook (inbound)

Las plataformas externas o Zapier/Make pueden empujar reviews directamente a Rankion — este es el único endpoint público autenticado por key de la API.

Method	Endpoint	Auth	Descripción
POST	`/v1/webhooks/reviews/{source}`	`X-Rankion-Key: <source_key>`	Empujar una review como JSON

{source} es el slug de una source de GET /review-sources (p. ej. trustpilot-example-com). La auth no corre por Authorization: Bearer, sino por la key específica de la source obtenida en rotate-key. Así puedes pasar la URL de webhook a sistemas terceros sin compartir el master token.

curl -X POST "https://rankion.ai/api/v1/webhooks/reviews/trustpilot-example-com" \
  -H "X-Rankion-Key: $SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "tp-987654",
    "rating": 5,
    "title": "Top Service",
    "body": "Schnelle Antwort, alles glatt.",
    "author": "Anna M.",
    "submitted_at": "2026-04-30T11:22:33Z",
    "url": "https://trustpilot.com/reviews/987654"
  }'

Response 200:

{"received": true, "review_id": 4521, "duplicate": false}

Con duplicate: true la review se ha deduplicado por external_id — sin nuevo insert, sin error.

Notas

Webhook key ≠ API token. La X-Rankion-Key autoriza solo pushes a esa única source — no puede leer nada, modificar nada ni invocar nada en otros sitios. Una compromisión queda limitada a reviews falsas para una source.
Rota de inmediato ante compromisión. POST /rotate-key invalida la key antigua atómicamente — los inflight requests con la key vieja reciben 401.
Disconnect en lugar de DELETE, si solo quieres pausar. DELETE además elimina todas las reviews ya pulled de la BD (cascada).
Los cron pulls corren automáticamente cada 6 h por source activa. El re-pull manual está (a fecha 2026-05) solo en la UI.
Google Reviews va por OAuth, no por source keys — ver API de Google Integrations.

Relacionado: Google Integrations · Webhooks · Review Sources.

Letzte Aktualisierung: 1 de mayo de 2026