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)

O que faz

A API de SMS permite enviar mensagens SMS de forma:

• Unitária (um número por requisição).

• Massiva (muitos números em uma requisição) usando:

  • JSON (até 200.000 registros).
  • Parquet (até 500.000 registros e recomendado por performance).

---

Autenticação e Headers Obrigatórios

Todas as requisições devem incluir:

• x-auth: API key fornecida pela Saem Colombia (se estiver ausente, a requisição será rejeitada).
• x-prefix: código do país enviado como header (exemplo: 57).

Regra: sem esses headers, a API não processa a requisição.

---

Modelo de Dados (Parâmetros de Entrada)

A documentação lista os seguintes campos (dependendo do endpoint/formato):

• from: identificador do remetente autorizado.

• flash: obrigatório em todos os serviços; valores yes ou no.

• numbers: lista de mensagens a serem enviadas; cada item inclui:

  • to: número de destino.
  • content: texto da mensagem (deve incluir o shortname obrigatório, ver seção de erros).

• msg_id (opcional): identificador único da mensagem; se não for enviado, o sistema o gera automaticamente.

Nota importante: a documentação menciona “content incluindo o shortname”, e existe o erro SHORTNAME_NOT_FOUND caso ele não esteja presente.

---

Endpoint: Envio Unitário

URL: https://apisms.saem.tel/v3/send

Método: GET

Headers: x-auth, x-prefix

Como funciona

• Os parâmetros são enviados como query params (to, content, from, flash).
• O sistema processa um SMS para um único destinatário.

Quando usar

• Notificações pontuais (OTP, confirmações individuais, alertas, etc.).

---

Endpoint: Envio Massivo em JSON

URL: https://apisms.saem.tel/v3/send

Método: POST

Headers: x-auth, x-prefix

Body: JSON

Limite

• Máximo de 200.000 registros por envio em JSON.
• Se exceder → erro SMS_008.

Como funciona

• Você envia um objeto com metadados (ex.: from, flash) e a lista numbers.
• Cada elemento dentro de numbers representa um SMS a ser enviado.

Recomendação prática

• Se precisar de rastreabilidade: envie o msg_id (UUID) para correlacionar mensagens.
• Caso contrário, a API irá gerá-lo automaticamente.

---

Endpoint: Envio Massivo em Parquet

URL: https://apisms.saem.tel/v3/send/parquet

Método: POST

Headers: x-auth, x-prefix

Body: form-data (arquivo .parquet + parâmetros adicionais)

Limite

• Máximo de 500.000 registros.
• Se exceder → erro SMS_008.

Como funciona

• Em vez de enviar numbers em JSON, você faz upload de um arquivo Parquet contendo os registros.

A documentação recomenda Parquet porque oferece:

• upload mais rápido,
• menor tamanho de arquivo,
• melhor desempenho geral.

---

Parâmetros de Saída

Campos retornados na resposta (especialmente para campanhas massivas):

• request_id: identificador único da campanha massiva.
• total_credits: créditos consumidos.
• records: total de mensagens processadas.
• total_pdu_count: total de PDUs gerados entre todas as mensagens (útil para entender a segmentação de SMS longos).

---

Tratamento de Erros

Erros de Autenticação

Código	HTTP Status	Descrição
AUTH.TOKEN_MISSING	400	O header x-auth não foi enviado.
API_KEY_NOT_FOUND	400	A API Key enviada não existe ou é inválida.
USER_NOT_FOUND	404	O usuário associado à API Key não foi encontrado.
USER_INACTIVE	401	O usuário está inativo.
COUNTRY_001	400	O prefixo (x-prefix) não está associado a nenhum país ou não está configurado.

---

Erros de Envio / Validação

Código	HTTP Status	Descrição
SMS_002	402	Créditos insuficientes (contas pré-pagas).
SMS_008	400	O limite máximo de registros permitidos foi excedido.
SMS_009	400	Arquivo Parquet inválido ou mal formatado.
DUPLICATED_MSG_ID	400	O msg_id já foi utilizado em uma campanha anterior.
FORBIDDEN_TERMS	400	O conteúdo da mensagem contém termos proibidos.
SHORTNAME_INACTIVE	400	O shortname está inativo.
SHORTNAME_NOT_FOUND	400	O shortname não foi encontrado no conteúdo da mensagem.
CONTENT_TOO_LONG	400	O conteúdo da mensagem excede o tamanho permitido.