Rivalwin API — Newsletter Commercial

Descripción general

La API de Newsletter Commercial permite generar informes de newsletters de forma programática. Siguiendo el mismo patrón que el resto de APIs, new_report crea un job asíncrono y report_status devuelve el informe cuando está completo. El pipeline incluye carga de envíos desde la base de datos, análisis GPT y generación de PDF.

Base URL: https://rivalwin.com/api/v1/newsletter/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 de Newsletter (new_report)

Crea un informe de newsletters competitivas de forma asíncrona. Devuelve inmediatamente un hash identificador.

POST /api/v1/newsletter/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 comercial
date_from	string	Sí	Fecha inicio del período (YYYY-MM-DD)
date_to	string	Sí	Fecha fin del período (YYYY-MM-DD)

Ejemplo de petición

curl -X POST https://rivalwin.com/api/v1/newsletter/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"
  }'

Validaciones y restricciones

Regla	Detalle
Rango máximo de fechas	60 días
Fecha fin máxima	Ayer (no se permite el día actual ni futuro)
Formato de fecha	YYYY-MM-DD estricto
Créditos	Se descuentan según inform_newsletter_credits (por defecto 10)

Respuesta exitosa (202 Accepted)

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

chr_report_type en api_jobs: newsletter_commercial.

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/newsletter/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/newsletter/companies/report_status \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"hash": "..."}'

Respuesta según estado

PENDING / PROCESSING — El informe está en cola, recogiendo newsletters o en PROCESSING_GPT:

{
    "hash": "...",
    "status": "PENDING",
    "created_at": "...",
    "message": "The report is queued and will start processing shortly."
}

DONE — El informe está completo con todos los datos:

Estructura alineada con informes Meta comerciales (report_id, rival, sector, campaign_*, kpis, insights, ads, pdf_url).

ERROR — Error durante la generación:

{
    "hash": "...",
    "status": "ERROR",
    "created_at": "...",
    "completed_at": "...",
    "error_message": "Report failed during processing."
}

---

Estructura completa del reporte

KPIs (kpis)

Campo	Descripción
newsletters_total / ads_total	Total de newsletters encontradas en el período
most_frequent_day	Día de la semana con más envíos
most_frequent_hour	Hora del día con más envíos
weekly_average	Promedio de envíos por semana
dates_sent	Fechas de envío
color_palette	Paleta de colores extraída del HTML

Insights (insights)

Campo	Descripción
gpt_analysis	HTML del análisis IA

Anuncios (ads[])

Cada elemento de ads representa un envío de newsletter:

Campo	Descripción
ad_id	newsletter_0, newsletter_1, …
format	email_newsletter
status	delivered
platforms	["email"]
copy.from	Remitente
copy.subject	Asunto
start_date / end_date	Fecha de envío (date_added del origen)
html	HTML completo del cuerpo del email

---

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.
• Si api_jobs.json_response ya está relleno en DONE, se devuelve esa copia hasta generar un informe nuevo.
• Cada informe consume créditos de tu cuenta según el sistema.