Rivalwin API

La API de Rivalwin permite generar informes de inteligencia publicitaria de forma programática. Analiza la actividad publicitaria de tus competidores en múltiples plataformas, obtén datos de creatividades, inversión estimada, alcance, segmentación y análisis de IA — todo desde tu propia infraestructura.

Base URL: https://rivalwin.com/api/v1/

---

Plataformas disponibles

Plataforma	Tipo	Base URL	Descripción
Meta Ads	Commercial	/meta/companies/	Anuncios comerciales en Facebook, Instagram y Messenger
Google Ads	Commercial	/google/companies/	Anuncios en Google Search, Display y YouTube
TikTok Ads	Commercial	/tiktok/companies/	Anuncios en TikTok (videos, imágenes, alcance estimado)
LinkedIn Ads	Commercial	/linkedin/companies/	Anuncios en LinkedIn (impresiones, segmentación geográfica)
Newsletter	Commercial	/newsletter/companies/	Análisis de newsletters competitivas
Análisis 360	Commercial	/analysis360/companies/	Informe cross-channel (Meta + Google + TikTok + LinkedIn + Newsletter + social + IA)

---

Cómo funciona

Todas las APIs siguen el mismo flujo asíncrono de dos pasos:

1. POST /new_report    →  Creas un informe y recibes un hash identificador
2. POST /report_status →  Consultas el estado con ese hash hasta obtener los datos

Los informes se procesan en segundo plano (típicamente entre 1 y 5 minutos). Puedes recibir los resultados de dos formas:

• Polling: consulta report_status cada 15-30 segundos hasta que el estado sea DONE.
• Webhook: configura una URL en el sistema y recibe automáticamente el payload completo cuando el informe esté listo.

---

Autenticación

Todas las peticiones requieren el header X-API-Key:

X-API-Key: tu_api_key_aqui

Las API Keys se generan y administran desde el módulo Integraciones & API Keys dentro del sistema de Rivalwin.

---

Rate Limiting

Limitación	Detalle
Por hora	Cada API Key tiene un límite de peticiones por hora (configurable por plan). Los headers X-RateLimit-Limit-Hour y X-RateLimit-Remaining-Hour indican el estado.
Cooldown	Tiempo mínimo de espera entre informes consecutivos (por defecto 10 segundos). Si se incumple, recibirás un error 429 con cooldown_active.

---

Requisitos de la cuenta

Para utilizar la API necesitas:

• Una cuenta activa en Rivalwin.
• Un plan contratado activo y no vencido (contrato o trial).
• Un plan que incluya acceso a la API.

---

Webhook

Como alternativa al polling, puedes configurar una URL de webhook en el módulo Integraciones & API Keys. Cuando un informe pase al estado DONE, la API enviará automáticamente un POST a tu URL con el mismo payload que devuelve report_status.

---

Créditos

Cada informe generado consume créditos de tu cuenta. La cantidad varía según la plataforma y la configuración de tu plan. Si no tienes créditos suficientes, recibirás un error 402 insufficient_credits.

---

Idempotencia

Todos los endpoints new_report soportan el header opcional Idempotency-Key. Si envías una clave previamente utilizada, la API devuelve el informe existente sin crear uno nuevo ni descontar créditos adicionales.

curl -X POST https://rivalwin.com/api/v1/{platform}/companies/new_report \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mi-clave-unica-123" \
  -d '{
    "rival_ref": "rvl_...",
    "date_from": "2026-03-01",
    "date_to": "2026-03-31",
    "country": "ES"
  }'

---

Códigos de error comunes

HTTP	Error	Descripción
400	missing_parameters	Faltan parámetros requeridos
400	invalid_date_range	Rango de fechas inválido (futuro, invertido o mayor a 60 días)
401	missing_api_key	No se envió el header X-API-Key
401	invalid_api_key	La API Key no es válida o está revocada
402	insufficient_credits	Créditos insuficientes
403	account_inactive	La cuenta está desactivada
403	api_not_in_plan	El plan no incluye acceso a la API
404	rival_not_found	El rival_ref no existe o está inactivo
429	rate_limit_exceeded	Se excedió el límite por hora
429	cooldown_active	Debe esperar antes de crear otro informe
500	internal_error	Error interno del servidor

---

Quick start

# 1. Crear un informe (ejemplo con Meta Commercial)
curl -X POST https://rivalwin.com/api/v1/meta/companies/new_report \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "rival_ref": "rvl_...",
    "date_from": "2026-03-01",
    "date_to": "2026-03-31",
    "country": "AR"
  }'

# Respuesta → { "hash": "abc123...", "status": "PENDING", ... }

# 2. Consultar estado (repetir cada 15-30 segundos)
curl -X POST https://rivalwin.com/api/v1/meta/companies/report_status \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"hash": "abc123..."}'

# Cuando status = "DONE", el campo "report" contiene todos los datos.

Consulta la documentación de cada plataforma en el menú lateral para ver los campos específicos de cada informe, los KPIs disponibles y ejemplos completos en PHP, Python y JavaScript.