API de Transmissão

Visão Geral

Este documento explica como os clientes podem usar a API de Transmissão Pública da Eazybe para operações de transmissão relacionadas ao Meta WABA. A API suporta:

Geração de chaves API
Transmissões de modelo para único destinatário
Transmissões em massa de modelo
Verificações de saúde
Tratamento operacional de erros

A API usa solicitações JSON sobre HTTPS e autentica através do cabeçalho x-api-key. É destinada a mensagens outbound baseadas em modelos de WhatsApp aprovados através da plataforma Eazybe.

Configuração Base

Configuração	Valor
URL Base	`https://cerberus.eazybe.com/prod/api/v2`
Autenticação	Cabeçalho `x-api-key`
Content-Type	`application/json`
Operações Suportadas	Gerar chave, enviar transmissão única, enviar transmissão em massa, verificação de saúde

Antes de Começar

Certifique-se de que o número de telefone remetente já esteja integrado na Eazybe e vinculado a uma configuração WABA ativa. A geração da chave API falhará se nenhuma conta WABA for encontrada para o número enviado.

Confirme que os modelos de WhatsApp necessários estão aprovados no Meta antes de tentar enviar. Modelos não aprovados ou ausentes retornarão falhas na solicitação.

Fluxo de Autenticação

Gerar Chave API

Use este ponto final uma vez para um número de remetente registrado e armazene com segurança a chave API retornada para solicitações futuras.

Ponto Final

POST /broadcast/public/generate-key

Corpo da Solicitação

Campo	Tipo	Obrigatório	Descrição
`phoneNumber`	string	Sim	Número de telefone do remetente com código de país, sem espaços ou `+`

Solicitação de Exemplo

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

Resposta de Sucesso

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

Exemplo de Falha

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

Usar Chave API nos Cabeçalhos de Solicitação

Todos os pontos finais de transmissão requerem a chave API gerada no cabeçalho x-api-key.

x-api-key: YOUR_API_KEY

Armazene sua chave API com segurança. Evite regenerá-la desnecessariamente.

Enviar Transmissão Única

Use o ponto final de transmissão única para enviar uma mensagem de modelo para um destinatário.

Ponto Final

POST /broadcast/public/send-single

Estrutura de Solicitação Obrigatória

Campo	Tipo	Obrigatório	Descrição
`templateName`	string	Sim	Nome do modelo de WhatsApp aprovado
`templateLanguage`	string	Sim	Código de idioma do modelo (ex., `en`)
`templateType`	string	Sim	Categoria do modelo: `MARKETING`, `UTILITY` ou `AUTHENTICATION`
`countryCode`	string	Sim	Código de país do destinatário sem `+`
`toPhoneNumber`	string	Sim	Número móvel do destinatário
`templateId`	string	Não	ID do modelo Meta
`templateParams`	string[]	Não	Valores das variáveis do modelo em ordem
`broadcastName`	string	Não	Rótulo opcional para este envio

Solicitação de Exemplo

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"
  }'

Resposta de Sucesso

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

Respostas Comuns de Falha

Enviar Transmissão em Massa

Use o ponto final em massa para enviar o mesmo modelo aprovado para múltiplos destinatários em uma única solicitação. Uma única solicitação pode incluir até 1000 destinatários.

Ponto Final

POST /broadcast/public/send-bulk

Estrutura de Solicitação Obrigatória

Campo	Tipo	Obrigatório	Descrição
`broadcastName`	string	Sim	Nome exclusivo de campanha
`templateName`	string	Sim	Nome do modelo de WhatsApp aprovado
`templateLanguage`	string	Sim	Código de idioma do modelo
`templateType`	string	Sim	Categoria do modelo
`data`	array	Sim	Lista de destinatários, máximo 1000 por solicitação
`templateId`	string	Não	ID do modelo Meta
`globalTemplateParams`	string[]	Não	Variáveis padrão usadas quando parâmetros no nível do destinatário não são fornecidos

Objeto de Destinatário em `data`

Campo	Tipo	Obrigatório	Descrição
`countryCode`	string	Sim	Código de país do destinatário sem `+`
`toPhoneNumber`	string	Sim	Número móvel do destinatário
`templateParams`	string[]	Não	Variáveis no nível do destinatário que substituem valores globais

Solicitação de Exemplo

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": "Campanha 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 Padrão", "Data de teste"]
  }'

Resposta de Sucesso

{
  "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 Operacionais

Uma solicitação em massa não pode exceder 1000 destinatários.
Os nomes de transmissão devem ser exclusivos; caso contrário, a solicitação falha.

Números inválidos podem criar falhas parciais. Contatos com falha são contados separadamente e créditos não são deduzidos para esses contatos inválidos. Contatos com falha podem ser armazenados com failure_reason_code: “INVALID_PHONE_NUMBER” para rastreamento downstream.

Tratamento de Parâmetros de Modelo

A API suporta parâmetros tanto no nível do destinatário quanto globais.

Parâmetros no Nível do Destinatário

Use templateParams dentro de cada objeto de destinatário quando cada contato deve receber diferentes valores de variáveis. Casos de uso de exemplo:

ID do pedido por cliente
Horário de compromisso por cliente
Nome personalizado por destinatário

Parâmetros Globais

Use globalTemplateParams quando os mesmos valores de variáveis se aplicam a todos os destinatários em uma campanha em massa. Isso reduz dados de carga repetidos e é útil para valores comuns em toda a campanha, como nome da marca, código de cupom ou porcentagem de oferta.

Regra de Precedência

Quando templateParams no nível do destinatário são fornecidos, eles substituem os valores globais para aquele destinatário.

Verificação de Saúde

Use o ponto final de saúde para verificar se o serviço da API de Transmissão Pública está operacional.

Ponto Final

GET /broadcast/public/health

Solicitação de Exemplo

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

Resposta de Amostra

{
  "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"
  }
}

Referência de Tratamento de Erros

Código de Status	Erro	Significado
`400`	`User is not signed up yet`	A chave API é inválida ou o número de telefone não está registrado
`400`	`No subscriptions available`	Nenhuma assinatura ativa está disponível para transmissões
`400`	`Insufficient credits`	O saldo da carteira não é suficiente
`400`	`Template does not exist`	O modelo está ausente ou não aprovado
`400`	`Invalid template language`	A variante de idioma de modelo solicitada não está aprovada
`400`	`Invalid phone number format`	O formato do código de país ou telefone é inválido
`400`	`Pricing not available`	O envio não é suportado para o código de país de destino
`400`	`Recipient limit exceeded`	A solicitação em massa contém mais de 1000 destinatários
`400`	`Broadcast with same name exists`	O nome da campanha deve ser exclusivo
`500`	`Internal Server Error`	Erro inesperado do lado do servidor

Códigos de Razão de Falha

Código	Significado	Notas
`INVALID_PHONE_NUMBER`	Número de destinatário inválido	Verifique a formatação do código de país e número
`UNSUPPORTED_COUNTRY_CODE`	Preços de país indisponíveis	Destino não suportado
`TEMPLATE_SEND_FAILED`	Falha no envio do modelo	Revise a resposta de erro da API bruta
`131014`	Parâmetro inválido	Problema com o parâmetro do modelo
`131051`	Limite de taxa excedido	Muitas solicitações enviadas em um intervalo curto
`WORKER_ERROR`	Falha de processamento do trabalhador	Revise a resposta de erro do trabalhador

Limites de Taxa e Restrições da Plataforma

Meta tem uma taxa de envio aproximada de cerca de 30 mensagens por segundo por WABA. A API inclui novas tentativas automáticas com retrocesso exponencial para erros de limite de taxa como 429, 80007 e 130429.

Processe em lotes com responsabilidade e divida uploads grandes em múltiplas solicitações uma vez que se aproxime do limite de 1000 destinatários por solicitação.

Fluxo de Trabalho Recomendado para Clientes

Integrar e Verificar

Integre e verifique o número do remetente na Eazybe antes de qualquer uso da API.

Gerar Chave API

Gere a chave API uma vez e armazene-a com segurança.

Verificar Modelos

Certifique-se de que o modelo de WhatsApp esteja aprovado no Meta e que a variante de idioma esteja disponível.

Validar Dados

Valide códigos de país de destinatários, números de telefone e contagem de variáveis do modelo antes de enviar.

Enviar Transmissão

Use o ponto final único para testes únicos e o ponto final em massa para campanhas.

Monitorar Resposta

Monitore a resposta para failed_contacts, alterações de saldo e status da fila.

Usar Nomes Exclusivos

Use nomes de transmissão exclusivos para cada campanha.

Melhores Práticas

Armazene a chave API com segurança e evite regenerá-la desnecessariamente
Pré-valide números para reduzir falhas e limpeza operacional
Faça coincidir o número de variáveis do modelo exatamente com os espaços reservados do modelo aprovado
Use globalTemplateParams para valores compartilhados e parâmetros no nível do destinatário apenas quando personalização for necessária
Verifique créditos antes de grandes solicitações de transmissão
Comece com um pequeno lote de teste antes de enviar campanhas de volume completo

Padrões de Carga de Exemplo

Envio Único com Variáveis

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

Envio em Massa com Variáveis no Nível do Destinatário

{
  "broadcastName": "Lembretes de Compromisso",
  "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"]
    }
  ]
}

Envio em Massa com Variáveis Globais

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

Overview

Endpoints

​Visão Geral

​Configuração Base

​Antes de Começar

​Fluxo de Autenticação

​Gerar Chave API

​Ponto Final

​Corpo da Solicitação

​Solicitação de Exemplo

​Resposta de Sucesso

​Exemplo de Falha

​Usar Chave API nos Cabeçalhos de Solicitação

​Enviar Transmissão Única

​Ponto Final

​Estrutura de Solicitação Obrigatória

​Solicitação de Exemplo

​Resposta de Sucesso

​Respostas Comuns de Falha

​Enviar Transmissão em Massa

​Ponto Final

​Estrutura de Solicitação Obrigatória

​Objeto de Destinatário em data

​Solicitação de Exemplo

​Resposta de Sucesso

​Notas Operacionais

​Tratamento de Parâmetros de Modelo

​Parâmetros no Nível do Destinatário

​Parâmetros Globais

​Regra de Precedência

​Verificação de Saúde

​Ponto Final

​Solicitação de Exemplo

​Resposta de Amostra

​Referência de Tratamento de Erros

​Códigos de Razão de Falha

​Limites de Taxa e Restrições da Plataforma

​Fluxo de Trabalho Recomendado para Clientes

​Integrar e Verificar

​Gerar Chave API

​Verificar Modelos

​Validar Dados

​Enviar Transmissão

​Monitorar Resposta

​Usar Nomes Exclusivos

​Melhores Práticas

​Padrões de Carga de Exemplo

​Envio Único com Variáveis

​Envio em Massa com Variáveis no Nível do Destinatário

​Envio em Massa com Variáveis Globais

Visão Geral

Configuração Base

Antes de Começar

Fluxo de Autenticação

Gerar Chave API

Ponto Final

Corpo da Solicitação

Solicitação de Exemplo

Resposta de Sucesso

Exemplo de Falha

Usar Chave API nos Cabeçalhos de Solicitação

Enviar Transmissão Única

Ponto Final

Estrutura de Solicitação Obrigatória

Solicitação de Exemplo

Resposta de Sucesso

Respostas Comuns de Falha

Enviar Transmissão em Massa

Ponto Final

Estrutura de Solicitação Obrigatória

Objeto de Destinatário em `data`

Solicitação de Exemplo

Resposta de Sucesso

Notas Operacionais

Tratamento de Parâmetros de Modelo

Parâmetros no Nível do Destinatário

Parâmetros Globais

Regra de Precedência

Verificação de Saúde

Ponto Final

Solicitação de Exemplo

Resposta de Amostra

Referência de Tratamento de Erros

Códigos de Razão de Falha

Limites de Taxa e Restrições da Plataforma

Fluxo de Trabalho Recomendado para Clientes

Integrar e Verificar

Gerar Chave API

Verificar Modelos

Validar Dados

Enviar Transmissão

Monitorar Resposta

Usar Nomes Exclusivos

Melhores Práticas

Padrões de Carga de Exemplo

Envio Único com Variáveis

Envio em Massa com Variáveis no Nível do Destinatário

Envio em Massa com Variáveis Globais