O que esta API faz

Permite criar campanhas de chamadas automáticas (massivas) em dois modos:

• STANDARD: áudio pré-gravado (referenciado por audioId)
• CUSTOM: texto para voz (TTS) por contato (content), utilizando uma voz (voice = "Juan" ou "Maria")

---

Autenticação

Todas as requisições devem incluir:

• x-auth: API key fornecida pela Saem.

Diferente da API de SMS, aqui prefix é um campo do body da campanha, não um header nos endpoints de envio do CallB segundo a documentação.

---

Conceitos principais do payload

Campos utilizados nesta API:

• subService: "standard" ou "custom"

• prefix: código do país de origem (exemplo 57)

• gmt: fuso horário local no formato +/-HH:MM (afeta a janela de execução)

• nameCampaign: nome da campanha

• mailbox: true/false (deixar mensagem na caixa postal caso não atenda)

• configProgramming: lista de programações de execução

  • máximo 5 configurações

  • se mais de uma configuração for enviada, será criada uma campanha separada para cada configuração

  • inclui:

    • dateStart, dateEnd
    • reviews (tentativas)
    • configReview: condições para novas tentativas (máx 5 revisões)

• numbers:

  • STANDARD: lista de números de telefone (sem símbolos)
  • CUSTOM: array de objetos { number, content }

Condições de reintento (configReview)

Valores permitidos:

buzon, colgo, congestion, fallo, maquina, mcolgo, msatisfactorio, nocontesta, satisfactorio.

---

Limite de carga

Para serviços em JSON:

• Máximo 200.000 registros
• Se exceder → erro CALLB_022

Para Parquet:

• Máximo 500.000 registros
• Se exceder → CALLB_022

---

Fluxo STANDARD: como montar uma campanha

Passo A: Obter ou criar audioId

O campo audioId pode ser obtido:

• No módulo “Recursos” da plataforma web (cada áudio possui um ID), ou
• Gerando via API (próximo passo).

---

Passo B: Gerar áudio via API (opcional)

Recomendado se você automatiza campanhas.

URL: https://apicallb.saem.tel/audio/generate Método: POST Headers: x-auth

Campos do body:

• text
• voice
• resource_name (nome base do arquivo .wav)

---

Passo C: Criar campanha STANDARD (JSON)

URL: https://apicallb.saem.tel/send/massive Método: POST Headers: x-auth

Body típico

{
  subService: "standard",
  prefix,
  gmt,
  nameCampaign,
  audioId,
  configProgramming: [...],
  numbers: [...]
}

(numbers é uma lista de telefones)

---

Fluxo CUSTOM: campanha TTS (texto para voz)

Criar campanha CUSTOM (JSON)

URL: https://apicallb.saem.tel/send/massive Método: POST Headers: x-auth

Body típico

{
  subService: "custom",
  voice: "Juan" | "Maria",
  numbers: [{ number, content }, ...],
  prefix,
  gmt,
  configProgramming
}

---

Templates (CUSTOM)

Tags interpretadas pelo sistema por contato:

• {I} identificador
• {N} nome
• {S} saldo/valor
• {T} telefone
• {E} email
• {C} conta

---

Campanhas com Parquet

URL: https://apicallb.saem.tel/send/massive/parquet Método: POST Headers: x-auth Body: form-data (arquivo .parquet + parâmetros)

Regras do arquivo

• STANDARD → Parquet com coluna number
• CUSTOM → Parquet com colunas number e content

configProgramming deve ser enviado no form-data como string JSON, não como objeto:

[{"dateStart":"...","dateEnd":"...","reviews":2}]

---

Resposta de criação da campanha

Ao criar uma campanha, retorna um resumo contendo:

• sends: contagem por operadora (inclui "null" para números inválidos encontrados)

• summary:

  • total_records
  • total_credits
  • seconds_aprox (segundos totais aproximados)

---

Erros

Erros de autenticação

Código	HTTP Status	Descrição
AUTH.TOKEN_MISSING	400	Header x-auth não enviado
API_KEY_NOT_FOUND	400	API key inexistente ou inválida
USER_NOT_FOUND	404	Usuário associado à API key não encontrado
USER_INACTIVE	401	Usuário inativo e não pode executar campanhas

---

Erros de configuração

Código	HTTP Status	Descrição
CALLB_015	404	Recurso multimídia não encontrado (audioId inválido)
CALLB_016	404	Não existe configuração para o país/prefixo enviado
CALLB_018	400	Horário configurado fora do intervalo permitido

---

Erros de processamento

Código	HTTP Status	Descrição
CALLB_019	400	Arquivo Parquet inválido ou mal estruturado
CALLB_021	402	Créditos insuficientes para executar a campanha
CALLB_022	400	Número máximo de registros excedido

---

Erros de geração de áudio

Código	HTTP Status	Descrição
CALLB_AUD_001	400	resource_name inválido ou com formato incorreto
CALLB_AUD_002	409	Recurso de áudio já existe (nome duplicado)