API de Transmisión

Resumen

Este documento explica cómo los clientes pueden usar la API de Transmisión Pública de Eazybe para operaciones de transmisión relacionadas con Meta WABA. La API admite:

Generación de claves API
Transmisiones de plantillas para un solo destinatario
Transmisiones masivas de plantillas
Verificaciones de estado
Manejo operativo de errores

La API utiliza solicitudes JSON sobre HTTPS y se autentica a través del encabezado x-api-key. Está diseñada para mensajería saliente basada en plantillas de WhatsApp aprobadas a través de la plataforma Eazybe.

Configuración Base

Configuración	Valor
URL Base	`https://cerberus.eazybe.com/prod/api/v2`
Autenticación	Encabezado `x-api-key`
Content-Type	`application/json`
Operaciones Admitidas	Generar clave, enviar transmisión única, enviar transmisión masiva, verificación de estado

Antes de Comenzar

Asegúrese de que el número de teléfono remitente ya esté integrado en Eazybe y vinculado a una configuración WABA activa. La generación de la clave API fallará si no se encuentra una cuenta WABA para el número enviado.

Confirme que sus plantillas de WhatsApp requeridas estén aprobadas en Meta antes de intentar enviar. Las plantillas no aprobadas o faltantes devolverán fallos en la solicitud.

Flujo de Autenticación

Generar Clave API

Use este punto final una vez para un número de remitente registrado y almacene de forma segura la clave API devuelta para solicitudes futuras.

Punto Final

POST /broadcast/public/generate-key

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
`phoneNumber`	string	Sí	Número de teléfono del remitente con código de país, sin espacios o `+`

Solicitud de Ejemplo

curl -X POST https://cerberus.eazybe.com/prod/api/v2/broadcast/public/generate-key \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210"
  }'

Respuesta Exitosa

{
  "status": true,
  "status_code": 200,
  "message": "API key generated successfully",
  "data": {
    "apiKey": "15558044483"
  }
}

Ejemplo de Fallo

{
  "status": false,
  "status_code": 400,
  "message": "User is not signed up yet.",
  "data": {
    "error": {
      "message": "No WABA account found for this phone number"
    }
  }
}

Usar Clave API en Encabezados de Solicitud

Todos los puntos finales de transmisión requieren la clave API generada en el encabezado x-api-key.

x-api-key: YOUR_API_KEY

Almacene su clave API de forma segura. Evite regenerarla innecesariamente.

Enviar Transmisión Única

Use el punto final de transmisión única para enviar un mensaje de plantilla a un destinatario.

Punto Final

POST /broadcast/public/send-single

Estructura de Solicitud Requerida

Campo	Tipo	Requerido	Descripción
`templateName`	string	Sí	Nombre de plantilla de WhatsApp aprobada
`templateLanguage`	string	Sí	Código de idioma de plantilla (ej., `en`)
`templateType`	string	Sí	Categoría de plantilla: `MARKETING`, `UTILITY` o `AUTHENTICATION`
`countryCode`	string	Sí	Código de país del destinatario sin `+`
`toPhoneNumber`	string	Sí	Número móvil del destinatario
`templateId`	string	No	ID de plantilla de Meta
`templateParams`	string[]	No	Valores de variables de plantilla en orden
`broadcastName`	string	No	Etiqueta opcional para este envío

Solicitud de Ejemplo

curl -X POST https://cerberus.eazybe.com/prod/api/v2/broadcast/public/send-single \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "templateName": "christmas_template",
    "templateLanguage": "en",
    "templateType": "MARKETING",
    "templateId": "768465685803110",
    "countryCode": "91",
    "toPhoneNumber": "8077378155",
    "templateParams": ["John", "100"],
    "broadcastName": "Single Broadcast Test"
  }'

Respuesta Exitosa

{
  "status": true,
  "message": "Single broadcast queued successfully",
  "data": {
    "broadcastId": "6789abcdef123456",
    "campaign_id": "abc123xyz456",
    "status": "PENDING_SEND"
  }
}

Respuestas Comunes de Fallo

Enviar Transmisión Masiva

Use el punto final masivo para enviar la misma plantilla aprobada a múltiples destinatarios en una sola solicitud. Una sola solicitud puede incluir hasta 1000 destinatarios.

Punto Final

POST /broadcast/public/send-bulk

Estructura de Solicitud Requerida

Campo	Tipo	Requerido	Descripción
`broadcastName`	string	Sí	Nombre único de campaña
`templateName`	string	Sí	Nombre de plantilla de WhatsApp aprobada
`templateLanguage`	string	Sí	Código de idioma de plantilla
`templateType`	string	Sí	Categoría de plantilla
`data`	array	Sí	Lista de destinatarios, máximo 1000 por solicitud
`templateId`	string	No	ID de plantilla de Meta
`globalTemplateParams`	string[]	No	Variables predeterminadas usadas cuando no se proporcionan parámetros a nivel de destinatario

Objeto de Destinatario en `data`

Campo	Tipo	Requerido	Descripción
`countryCode`	string	Sí	Código de país del destinatario sin `+`
`toPhoneNumber`	string	Sí	Número móvil del destinatario
`templateParams`	string[]	No	Variables a nivel de destinatario que sobrescriben los valores globales

Solicitud de Ejemplo

curl -X POST https://cerberus.eazybe.com/prod/api/v2/broadcast/public/send-bulk \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "broadcastName": "Campaña Festival 2024",
    "templateName": "festive_offer_promo",
    "templateLanguage": "en",
    "templateType": "MARKETING",
    "templateId": "1172528374418691",
    "data": [
      {
        "countryCode": "91",
        "toPhoneNumber": "9897964421",
        "templateParams": ["John Doe", "212812790", "16-02-2026"]
      },
      {
        "countryCode": "91",
        "toPhoneNumber": "8077378155",
        "templateParams": ["Vineet", "122878278", "14-02-2026"]
      }
    ],
    "globalTemplateParams": ["Empresa Predeterminada", "Fecha de prueba"]
  }'

Respuesta Exitosa

{
  "status": true,
  "message": "Broadcast is being processed",
  "data": {
    "total_contacts": 2,
    "failed_contacts": 0,
    "estimated_cost": 0.15,
    "oldBalance": 100.5,
    "newEstimatedBalance": 100.35
  }
}

Notas Operativas

Una solicitud masiva no puede exceder 1000 destinatarios.
Los nombres de transmisión deben ser únicos; de lo contrario, la solicitud falla.

Los números no válidos pueden crear fallos parciales. Los contactos fallidos se cuentan por separado y no se deducen créditos para esos contactos no válidos. Los contactos fallidos pueden almacenarse con failure_reason_code: “INVALID_PHONE_NUMBER” para seguimiento descendente.

Manejo de Parámetros de Plantilla

La API admite parámetros tanto a nivel de destinatario como globales.

Parámetros a Nivel de Destinatario

Use templateParams dentro de cada objeto de destinatario cuando cada contacto deba recibir diferentes valores de variables. Casos de uso de ejemplo:

ID de pedido por cliente
Hora de cita por cliente
Nombre personalizado por destinatario

Parámetros Globales

Use globalTemplateParams cuando los mismos valores de variables se apliquen a todos los destinatarios en una campaña masiva. Esto reduce datos de carga repetidos y es útil para valores comunes de toda la campaña, como nombre de marca, código de cupón o porcentaje de oferta.

Regla de Precedencia

Cuando se proporcionan templateParams a nivel de destinatario, sobrescriben los valores globales para ese destinatario.

Verificación de Estado

Use el punto final de estado para verificar si el servicio de API de Transmisión Pública está operativo.

Punto Final

GET /broadcast/public/health

Solicitud de Ejemplo

curl -X GET https://cerberus.eazybe.com/prod/api/v2/broadcast/public/health

Respuesta de Muestra

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": "Public Broadcast API",
  "version": "1.0.0",
  "endpoints": {
    "single": "POST /broadcast/public/send-single",
    "bulk-standard": "POST /broadcast/public/send-bulk-standard",
    "health": "GET /broadcast/public/health"
  }
}

Referencia de Manejo de Errores

Código de Estado	Error	Significado
`400`	`User is not signed up yet`	La clave API no es válida o el número de teléfono no está registrado
`400`	`No subscriptions available`	No hay una suscripción activa disponible para transmisiones
`400`	`Insufficient credits`	El saldo del monedero no es suficiente
`400`	`Template does not exist`	La plantilla no existe o no está aprobada
`400`	`Invalid template language`	La variante de idioma de plantilla solicitada no está aprobada
`400`	`Invalid phone number format`	El formato del código de país o teléfono no es válido
`400`	`Pricing not available`	El envío no es compatible con el código de país de destino
`400`	`Recipient limit exceeded`	La solicitud masiva contiene más de 1000 destinatarios
`400`	`Broadcast with same name exists`	El nombre de la campaña debe ser único
`500`	`Internal Server Error`	Error inesperado del lado del servidor

Códigos de Razón de Fallo

Código	Significado	Notas
`INVALID_PHONE_NUMBER`	Número de destinatario no válido	Verifique el formato del código de país y número
`UNSUPPORTED_COUNTRY_CODE`	Precios de país no disponibles	Destino no admitido
`TEMPLATE_SEND_FAILED`	Fallo en el envío de plantilla	Revise la respuesta de error de API sin procesar
`131014`	Parámetro no válido	Problema con el parámetro de plantilla
`131051`	Límite de tasa excedido	Demasiadas solicitudes enviadas en un intervalo corto
`WORKER_ERROR`	Fallo de procesamiento de trabajador	Revise la respuesta de error de trabajador

Límites de Tasa y Restricciones de Plataforma

Meta tiene una tasa de envío aproximada de alrededor de 30 mensajes por segundo por WABA. La API incluye reintentos automáticos con retroceso exponencial para errores de límite de tasa como 429, 80007 y 130429.

Procese por lotes de manera responsable y divida cargas grandes en múltiples solicitudes una vez que se acerque al límite de 1000 destinatarios por solicitud.

Flujo de Trabajo Recomendado para Clientes

Integrar y Verificar

Integre y verifique el número de remitente en Eazybe antes de cualquier uso de la API.

Generar Clave API

Genere la clave API una vez y almacénela de forma segura.

Verificar Plantillas

Asegúrese de que la plantilla de WhatsApp esté aprobada en Meta y que la variante de idioma esté disponible.

Validar Datos

Valide códigos de país de destinatarios, números de teléfono y recuento de variables de plantilla antes de enviar.

Enviar Transmisión

Use el punto final único para pruebas únicas y el punto final masivo para campañas.

Monitorear Respuesta

Monitoree la respuesta para failed_contacts, cambios de saldo y estado de cola.

Usar Nombres Únicos

Use nombres de transmisión únicos para cada campaña.

Mejores Prácticas

Almacene la clave API de forma segura y evite regenerarla innecesariamente
Prevalide números para reducir fallos y limpieza operativa
Haga coincidir el número de variables de plantilla exactamente con los marcadores de posición de plantilla aprobados
Use globalTemplateParams para valores compartidos y parámetros a nivel de destinatario solo cuando se requiera personalización
Verifique créditos antes de solicitudes masivas grandes
Comience con un lote de prueba pequeño antes de enviar campañas de volumen completo

Patrones de Carga de Ejemplo

Envío Único con Variables

{
  "templateName": "order_shipped",
  "templateLanguage": "en",
  "templateType": "MARKETING",
  "countryCode": "91",
  "toPhoneNumber": "9876543210",
  "templateParams": ["John", "ORD12345", "17-02-2024"]
}

Envío Masivo con Variables a Nivel de Destinatario

{
  "broadcastName": "Recordatorios de Cita",
  "templateName": "appointment_reminder",
  "templateLanguage": "en",
  "templateType": "UTILITY",
  "data": [
    {
      "countryCode": "1",
      "toPhoneNumber": "5551234567",
      "templateParams": ["Alice", "2024-01-20", "10:00 AM"]
    },
    {
      "countryCode": "1",
      "toPhoneNumber": "5559876543",
      "templateParams": ["Bob", "2024-01-20", "2:30 PM"]
    }
  ]
}

Envío Masivo con Variables Globales

{
  "broadcastName": "Promo Global",
  "templateName": "promo_offer",
  "templateLanguage": "en",
  "templateType": "MARKETING",
  "data": [
    {
      "countryCode": "91",
      "toPhoneNumber": "9876543210"
    },
    {
      "countryCode": "91",
      "toPhoneNumber": "9876543211"
    }
  ],
  "globalTemplateParams": ["MiTienda", "SAVE20", "20"]
}

Overview

Endpoints

​Resumen

​Configuración Base

​Antes de Comenzar

​Flujo de Autenticación

​Generar Clave API

​Punto Final

​Cuerpo de la Solicitud

​Solicitud de Ejemplo

​Respuesta Exitosa

​Ejemplo de Fallo

​Usar Clave API en Encabezados de Solicitud

​Enviar Transmisión Única

​Punto Final

​Estructura de Solicitud Requerida

​Solicitud de Ejemplo

​Respuesta Exitosa

​Respuestas Comunes de Fallo

​Enviar Transmisión Masiva

​Punto Final

​Estructura de Solicitud Requerida

​Objeto de Destinatario en data

​Solicitud de Ejemplo

​Respuesta Exitosa

​Notas Operativas

​Manejo de Parámetros de Plantilla

​Parámetros a Nivel de Destinatario

​Parámetros Globales

​Regla de Precedencia

​Verificación de Estado

​Punto Final

​Solicitud de Ejemplo

​Respuesta de Muestra

​Referencia de Manejo de Errores

​Códigos de Razón de Fallo

​Límites de Tasa y Restricciones de Plataforma

​Flujo de Trabajo Recomendado para Clientes

​Integrar y Verificar

​Generar Clave API

​Verificar Plantillas

​Validar Datos

​Enviar Transmisión

​Monitorear Respuesta

​Usar Nombres Únicos

​Mejores Prácticas

​Patrones de Carga de Ejemplo

​Envío Único con Variables

​Envío Masivo con Variables a Nivel de Destinatario

​Envío Masivo con Variables Globales

Resumen

Configuración Base

Antes de Comenzar

Flujo de Autenticación

Generar Clave API

Punto Final

Cuerpo de la Solicitud

Solicitud de Ejemplo

Respuesta Exitosa

Ejemplo de Fallo

Usar Clave API en Encabezados de Solicitud

Enviar Transmisión Única

Punto Final

Estructura de Solicitud Requerida

Solicitud de Ejemplo

Respuesta Exitosa

Respuestas Comunes de Fallo

Enviar Transmisión Masiva

Punto Final

Estructura de Solicitud Requerida

Objeto de Destinatario en `data`

Solicitud de Ejemplo

Respuesta Exitosa

Notas Operativas

Manejo de Parámetros de Plantilla

Parámetros a Nivel de Destinatario

Parámetros Globales

Regla de Precedencia

Verificación de Estado

Punto Final

Solicitud de Ejemplo

Respuesta de Muestra

Referencia de Manejo de Errores

Códigos de Razón de Fallo

Límites de Tasa y Restricciones de Plataforma

Flujo de Trabajo Recomendado para Clientes

Integrar y Verificar

Generar Clave API

Verificar Plantillas

Validar Datos

Enviar Transmisión

Monitorear Respuesta

Usar Nombres Únicos

Mejores Prácticas

Patrones de Carga de Ejemplo

Envío Único con Variables

Envío Masivo con Variables a Nivel de Destinatario

Envío Masivo con Variables Globales