> ## Documentation Index
> Fetch the complete documentation index at: https://help.eazybe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Transmissão

> Aprenda a usar a API de Transmissão Pública da Eazybe para operações de transmissão relacionadas ao Meta WABA, incluindo geração de chaves API, transmissões de modelo únicas e em massa, verificações de saúde e tratamento de erros.

## 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

<Warning>
  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.
</Warning>

<Tip>
  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.
</Tip>

***

## Fluxo de Autenticação

<Steps>
  <Step>
    <h3>Gerar Chave API</h3>
    <p>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.</p>

    <h4>Ponto Final</h4>
    <code>POST /broadcast/public/generate-key</code>

    <h4>Corpo da Solicitação</h4>

    <table>
      <thead>
        <tr>
          <th>Campo</th>
          <th>Tipo</th>
          <th>Obrigatório</th>
          <th>Descrição</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>phoneNumber</code></td>
          <td>string</td>
          <td>Sim</td>
          <td>Número de telefone do remetente com código de país, sem espaços ou <code>+</code></td>
        </tr>
      </tbody>
    </table>

    <h4>Solicitação de Exemplo</h4>

    ```bash theme={null}

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

    <h4>Resposta de Sucesso</h4>

    ```json theme={null}

    {
    "status": true,
    "message": "API key generated successfully",
    "data": {
    "apiKey": "9548e0f4ea0ab360ac9eeaf69f9754d72c6b606353037125d21842b9364ca8"
    }
    }
    ```

    <h4>Exemplo de Falha</h4>

    ```json theme={null}

    {
    "statusCode": 400,
    "timestamp": "2026-04-14T07:13:33.289Z",
    "path": "/broadcast/public/generate-key",
    "method": "POST",
    "requestId": "9c57a355c364f07060335e348902c9b8",
    "message": "Failed to generate API key",
    "status": false,
    "status_code": 400,
    "data": {
    "error": {
    "message": "Phone number not found or not connected to WABA."
    }
    }
    }
    ```
  </Step>

  <Step>
    <h3>Usar Chave API nos Cabeçalhos de Solicitação</h3>
    <p>Todos os pontos finais de transmissão requerem a chave API gerada no cabeçalho <code>x-api-key</code>.</p>

    ```http theme={null}

    x-api-key: YOUR_API_KEY
    ```

    <Note>
      Armazene sua chave API com segurança. Evite regenerá-la desnecessariamente.
    </Note>
  </Step>
</Steps>

***

## Enviar Transmissão Única

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

### Ponto Final

```http theme={null}
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, por exemplo `en`                                                    |
| `templateType`     | string    | Sim         | Categoria do modelo: `MARKETING`, `UTILITY`                                                     |
| `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 - Necessário apenas para modelos baseados em variáveis |
| `broadcastName`    | string    | Não         | Rótulo opcional para este envio                                                                 |

### Solicitação de Exemplo

```bash theme={null}
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

```json theme={null}
{
  "status": true,
  "message": "Broadcast sent successfully",
  "data": {
    "status": true,
    "message": "Broadcast is being processed",
    "data": {
      "total_contacts": 1,
      "failed_contacts": 0,
      "estimated_cost": 0.94937,
      "oldBalance": 1860.0995179999998,
      "newEstimatedBalance": 1859.1501479999997
    }
  }
}
```

### Respostas Comuns de Falha

<Accordion>
  <AccordionItem title="Chave API inválida ou número não registrado">
    A solicitação falha quando a chave API não corresponde a um remetente
    registrado válido.
  </AccordionItem>

  <AccordionItem title="Créditos insuficientes">
    A solicitação falha quando os créditos da carteira não são suficientes para
    o envio.
  </AccordionItem>

  <AccordionItem title="Modelo inválido ou não aprovado">
    A solicitação falha se o modelo não existir ou não estiver aprovado.
  </AccordionItem>
</Accordion>

***

## 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

```http theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "status": true,
  "message": "Bulk broadcast queued successfully",
  "data": {
    "status": true,
    "message": "Broadcast is being processed",
    "data": {
      "total_contacts": 2,
      "failed_contacts": 0,
      "estimated_cost": 1.89874,
      "oldBalance": 1851.5995179999998,
      "newEstimatedBalance": 1849.7007779999997
    }
  }
}
```

### Notas Operacionais

<Warning>
  <ul>
    <li>Uma solicitação em massa não pode exceder 1000 destinatários.</li>

    <li>
      Os nomes de transmissão devem ser exclusivos; caso contrário, a
      solicitação falha.
    </li>
  </ul>
</Warning>

<Note>
  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{" "}
  <code>failure\_reason\_code: "INVALID\_PHONE\_NUMBER"</code> para rastreamento
  downstream.
</Note>

***

## 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

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

***

## 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

```http theme={null}
GET /broadcast/public/health
```

### Solicitação de Exemplo

```bash theme={null}
curl -X GET https://cerberus.eazybe.com/prod/api/v2/broadcast/public/health
```

### Resposta de Amostra

```json theme={null}
{
  "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

<Warning>
  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 <code>429</code>, <code>80007</code> e{" "}
  <code>130429</code>.
</Warning>

<Tip>
  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.
</Tip>

***

## Fluxo de Trabalho Recomendado para Clientes

<Steps>
  <Step>
    <h3>Integrar e Verificar</h3>

    <p>
      Integre e verifique o número do remetente na Eazybe antes de qualquer uso
      da API.
    </p>
  </Step>

  <Step>
    <h3>Gerar Chave API</h3>
    <p>Gere a chave API uma vez e armazene-a com segurança.</p>
  </Step>

  <Step>
    <h3>Verificar Modelos</h3>

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

  <Step>
    <h3>Validar Dados</h3>

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

  <Step>
    <h3>Enviar Transmissão</h3>

    <p>
      Use o ponto final único para testes únicos e o ponto final em massa para
      campanhas.
    </p>
  </Step>

  <Step>
    <h3>Monitorar Resposta</h3>

    <p>
      Monitore a resposta para <code>failed\_contacts</code>, alterações de saldo
      e status da fila.
    </p>
  </Step>

  <Step>
    <h3>Usar Nomes Exclusivos</h3>
    <p>Use nomes de transmissão exclusivos para cada campanha.</p>
  </Step>
</Steps>

***

## Melhores Práticas para Clientes

* 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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