Rivalwin API — Análisis 360 Commercial

Descripción general

La API de Análisis 360 permite generar informes de publicidad comercial cross-channel de forma programática. Crea un informe Análisis 360 que analiza Meta, Google, TikTok, LinkedIn, Newsletter, perfiles sociales, informe IA y PDF descargable, igual que el módulo web.

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

Autenticación

Todas las peticiones requieren una API Key válida enviada en el header X-API-Key.

X-API-Key: tu_api_key_aqui

Rate Limiting

La API aplica dos tipos de limitación:

Rate limit por hora

Cada API Key tiene un límite de peticiones por hora configurado. Los headers de respuesta indican el estado:

X-RateLimit-Limit-Hour: 600
X-RateLimit-Remaining-Hour: 598

Si se excede el límite: 429 Too Many Requests con header Retry-After.

Cooldown entre informes

Existe un tiempo mínimo de espera entre la creación de informes consecutivos (por defecto 10 segundos, configurable por plan/empresa). Si intentas crear un informe antes de que transcurra este tiempo:

{
    "error": "cooldown_active",
    "message": "Please wait 7 seconds before creating another report.",
    "cooldown_seconds": 10,
    "retry_after": 7
}

Requisitos de la cuenta

Su cuenta de Rivalwin debe estar activa.
El plan contratado debe estar activo y no vencido (contrato o trial).
El plan debe incluir acceso a la API.

Si alguna de estas condiciones no se cumple, recibirás un error 403 Forbidden con el motivo específico.

Recepción de resultados

Existen dos formas de recibir los datos de un informe completado:

Polling

Consulta el endpoint report_status periódicamente (cada 15-30 segundos) hasta que el estado sea DONE. Es el método más simple y no requiere configuración adicional.

Webhook

Configura una URL de webhook en el módulo Integraciones & API Keys del sistema. Cuando un informe pase al estado DONE, la API enviará automáticamente un POST a la URL configurada con el payload completo del informe (mismo contenido que devuelve report_status en estado DONE).

De esta forma no necesitas hacer polling: simplemente esperas a recibir la notificación en tu servidor.

Endpoints

1. Crear un nuevo informe Análisis 360 (new_report)

Crea un informe Análisis 360 de forma asíncrona. Devuelve inmediatamente un hash identificador.

POST /api/v1/analysis360/companies/new_report

Headers

Header	Tipo	Requerido	Descripción
X-API-Key	string	Sí	Tu API Key
Idempotency-Key	string	No	Clave de idempotencia para evitar informes duplicados
Content-Type	string	Sí	`application/json`

Body (JSON)

Parámetro	Tipo	Requerido	Descripción
`rival_ref`	string	Sí	Referencia del rival (`rvl_…`) se encuentra en el buscador del módulo integraciones & API Keys del sistema
`date_from`	string	Sí	`YYYY-MM-DD`
`date_to`	string	Sí	`YYYY-MM-DD`
`country`	string	Sí	ISO-2 (ES, AR, EU, etc.)

Ejemplo de petición

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

Validaciones y restricciones

Reglas de fechas: igual que otros informes comerciales (máx. 60 días, date_to no futura, etc.).

Respuesta exitosa (202 Accepted)

{
    "hash": "...",
    "status": "PENDING",
    "created_at": "..."
}

Créditos

La cantidad de créditos que consume es la misma que al generarlo desde el sistema. Los créditos se descuentan al finalizar el proceso solo si hubo anuncios, igual que en el flujo web.

Idempotencia

Si envías el header Idempotency-Key con un valor previamente usado, la API devuelve el informe existente sin crear uno nuevo ni descontar créditos adicionales.

2. Consultar estado del informe (report_status)

Consulta el estado de un informe y obtiene los datos del reporte cuando está completo.

POST /api/v1/analysis360/companies/report_status

Headers requeridos

Header	Tipo	Requerido	Descripción
X-API-Key	string	Sí	Tu API Key
Content-Type	string	Sí	`application/json`

Body (JSON)

Parámetro	Tipo	Requerido	Descripción
`hash`	string	Sí	Hash del informe (obtenido de `new_report`)

Ejemplo de petición

curl -X POST https://rivalwin.com/api/v1/analysis360/companies/report_status \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"hash": "..."}'

Estados

PENDING / PROCESSING: el informe se está generando (puede tardar varios minutos).
DONE: incluye report con el payload completo.
ERROR: incluye error_message.

Informe completado (`report`)

Objeto raíz devuelto dentro de report cuando status es DONE.

Metadatos (raíz)

Campo	Tipo	Descripción
`platform`	string	Plataforma principal del registro de informe.
`inform_status`	string	Estado del informe en sistema.
`sector`	string \| null	Nombre del sector.
`country`	string \| null	País / alcance.
`campaign_start`	string \| null	Inicio de campaña (fecha según BD).
`campaign_end`	string \| null	Fin de campaña.
`inform_created`	string \| null	Alta del informe.
`pdf_url`	string \| null	URL del PDF si existe.

`rival`

Campo	Descripción
`ref`	Referencia pública del rival (`rvl_…`).
`name`, `logo`, `web`, `description`	Datos de ficha.
`social_links`	`facebook`, `instagram`, `tiktok`, `youtube` (URLs o `null`).

`kpis`

Campo	Descripción
`total_ads_all_platforms`	Suma de `int_cant_ads` en `informs_360`.
`meta_is_non_ue`	`true` si el bloque Meta del informe indica fuera de UE (`no_ue`).
`total_activations`	Total de activaciones (inicios) en el período analizado.
`peak_active_ads`	Suma de los picos de anuncios activos por plataforma (coherente con el módulo).
`platforms`	Objeto con claves en minúsculas: `google`, `meta`, `tiktok`, `linkedin` → `{ "max_simultaneous_active", "activations" }`; `newsletter` → `{ "sends" }` (envíos / activaciones del canal).

`charts`

platform_activity_by_day: array ordenado por día. Cada elemento:
- date: YYYY-MM-DD.
- Por canal: meta_activations, google_activations, tiktok_activations, linkedin_activations, newsletter_activations (enteros).
- Por canal: meta_active, google_active, tiktok_active, linkedin_active (anuncios activos ese día; newsletter suele ir en 0 si no aplica línea de activos).
platform_share: array de { "platform": "<minúsculas>", "value": <entero> } (participación en activaciones del gráfico de barras del resumen).
age_gender_distribution: array de { "age_range", "male", "female", "unknown" } (agregado Meta UE con desglose por edad; vacío si no aplica o sin datos).

`ads_by_platform`

Objeto con claves meta, google, tiktok, linkedin, newsletter.

Para meta, google, tiktok, linkedin:
- total_analyzed: cantidad total de creatividades agregadas en el informe (no solo las del top).
- top_ads: como máximo 4 elementos, mismos criterios que la vista web: Meta más recientes, Google más días activos, TikTok mayor rango de alcance, LinkedIn mayor rango de impresiones.

Cada ítem de top_ads (salvo newsletter) incluye de forma normalizada: id, creative_url, copy, format, objective, reach_min, reach_max, date_start, date_end, active (cuando se puede deducir).

newsletter:
- total_sends: total de registros de newsletter en el informe.
- items: hasta 4 últimos por date_added; campos típicos: id, subject, date_added, url.

`insights`

Campo	Descripción
`gpt_resume_html`	Resumen en HTML generado por IA.

`social_presence`

Campo	Descripción
`rival`	`name`, `logo_url`, `links` (`facebook`, `instagram`, `tiktok`, `youtube`).
`cards`	Una entrada por red configurada en el rival; cada tarjeta incluye `platform`, `platform_display_name`, `rival_configured_link`, `has_profile_data`, `display` (nombre, bio, URLs, badges, rating, etc.), `metrics`, y opcionalmente `informs_360_social_data` (fila de perfil sin `id_social_data`, `id_inform`, `id_rival`, `txt_json`).

Errores parciales

Si falla la ejecución del controlador al calcular métricas, kpis, charts, ads_by_platform y/o social_presence pueden ir vacíos o incompletos. Los metadatos de filas (rival, fechas, pdf_url) suelen seguir presentes.

Notas importantes

Los informes se generan de forma asíncrona. La creación devuelve un hash inmediatamente y el informe se procesa en segundo plano.
El tiempo de generación puede ser de varios minutos, ya que analiza múltiples plataformas simultáneamente.
Cada informe consume créditos equivalentes a los del módulo web. Los créditos se descuentan al finalizar el proceso solo si hubo anuncios.

Descripción general​

Autenticación​

Rate Limiting​

Rate limit por hora​

Cooldown entre informes​

Requisitos de la cuenta​

Recepción de resultados​

Polling​

Webhook​

Endpoints​

1. Crear un nuevo informe Análisis 360 (new_report)​

Headers​

Body (JSON)​

Ejemplo de petición​

Validaciones y restricciones​

Respuesta exitosa (202 Accepted)​

Créditos​

Idempotencia​

2. Consultar estado del informe (report_status)​

Headers requeridos​

Body (JSON)​

Ejemplo de petición​

Estados​

Informe completado (report)​

Metadatos (raíz)​

rival​

kpis​

charts​

ads_by_platform​

insights​

social_presence​

Errores parciales​

Notas importantes​

Descripción general

Autenticación

Rate Limiting

Rate limit por hora

Cooldown entre informes

Requisitos de la cuenta

Recepción de resultados

Polling

Webhook

Endpoints

1. Crear un nuevo informe Análisis 360 (new_report)

Headers

Body (JSON)

Ejemplo de petición

Validaciones y restricciones

Respuesta exitosa (202 Accepted)

Créditos

Idempotencia

2. Consultar estado del informe (report_status)

Headers requeridos

Body (JSON)

Ejemplo de petición

Estados

Informe completado (`report`)

Metadatos (raíz)

`rival`

`kpis`

`charts`

`ads_by_platform`

`insights`

`social_presence`

Errores parciales

Notas importantes