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)

Guia de Uso da API de Envio de SMS

Abreviações

Abreviatura	Descrição
PARQUET	Formato de arquivo projetado para armazenar grandes quantidades de dados de maneira organizada e eficiente.
PDU	Unidade de Dados do Protocolo (Protocol Data Unit) que representa a quantidade de fragmentos nos quais um SMS é dividido para o seu envio.
UUID	Identificador Único Universal (código gerado aleatoriamente) utilizado para msg_id e request_id.

Introdução

A API de Envio de SMS permite realizar envios unitários e em massa de mensagens de texto utilizando os formatos JSON ou Parquet.

Através deste guia você poderá conhecer como se autenticar, quais serviços estão disponíveis e quais estruturas devem ser utilizadas para realizar os envios corretamente, quais métodos estão disponíveis e quais formatos devem ser usados para realizar as solicitações.

1. Autenticação e Segurança

Antes de usar a API de Envios em Massa, é necessário contar com uma chave de acesso segura ("api key"). Essa chave é entregue diretamente pela equipe da Saem Colombia e deve ser incluída em cada solicitação dentro do cabeçalho x-auth.

Sem essa autenticação, o sistema rejeitará a requisição.

Além da api key, deve-se incluir o cabeçalho x-prefix indicando o código do país em todas as solicitações.

Exemplo de aplicação (headers):

Key	Value
x-auth	api-key-00000000000000000000000000000000000000
x-prefix	57

Serviços Disponíveis na API SMS

Parâmetros de Entrada

Quote

Campo	Descrição
from	Identificador do remetente autorizado a enviar mensagens.
numbers	Lista de mensagens a enviar. Cada objeto deve incluir to, content e, opcionalmente, msg_id.
msg_id	ID único da mensagem. Se não for enviado, é gerado automaticamente.
to	Número de celular do destinatário.
content	Texto da mensagem incluindo o shortname.
flash	Define se o SMS será exibido imediatamente em uma janela pop-up (yes ou no). Este campo é obrigatório para todos os serviços.
unique-numbers	Se necessário, utilize este parâmetro para validar e rejeitar números duplicados no envio. Aceita yes ou no. Caso contrário, não é necessário incluí-lo.
x-prefix	Código do país, deve ser enviado como header.
x-auth	Token de autenticação, deve ser enviado como header.

2. Envio Unitário

• URL: https://apisms.saem.tel/v3/send
• Método: GET
• Headers: x-auth: api-key-XXX000X00000, x-prefix: 57 Exemplo de Params (query string):

Key	Value
to	573999999999
content	Prueba oficial SMS API V3 claro
from	saemcolombia
flash	no

Exemplo de solicitação completa:

GET https://apisms.saem.tel/v3/send?to=573999999999&content=Prueba oficial SMS API V3 claro&from=saemcolombia&flash=no

💡 IMPORTANTE Para todos os nossos serviços em formato JSON poderá ser carregado um máximo de 200.000 registros. Se for enviada uma quantidade superior, o sistema rejeitará a solicitação com o erro: SMS_008.

3. Envio em Massa — Formato JSON

• URL: https://apisms.saem.tel/v3/send
• Método: POST
• Headers: x-auth: api-key-XXX000X00000, x-prefix: 57 Exemplo de Body:

{
  "from": "SaemColombia",
  "coding": 0,
  "dlr": "no",
  "dlr-url": "",
  "dlr-level": "",
  "dlr-method": "",
  "flash": "no",
  "unique-numbers": "yes",
  "numbers": [
    { "to": "3000000000", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3123457891", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3999999999", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3999999999", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3999999999", "content": "Hola Saem, este es tu mensaje de prueba oficial" }
  ]
}

Para o formato a seguir devemos levar em conta que o corpo da solicitação (body) deve ser enviado no formato form-data, incluindo o arquivo .parquet e os demais parâmetros necessários.

💡 Recomendação: Sugere-se utilizar o formato .Parquet em vez de arquivos JSON, já que ele permite um carregamento muito mais rápido, reduz o tamanho do arquivo e melhora o desempenho geral do processo.

Para este formato poderá ser carregado um máximo de 500.000 registros. Se for enviada uma quantidade superior, o sistema rejeitará a solicitação com o erro SMS_008.

4. Envio em Massa — Formato Parquet

• URL: https://apisms.saem.tel/v3/send/parquet
• Método: POST
• Headers: x-auth: api-key-XXX000X00000, x-prefix: 57 Exemplo de Body (form-data):

Key	Tipo	Value
file	File	sms_prueba.parquet
from	Text	saemcolombia
coding	Text	0
dlr	Text	no
dlr-url	Text	(vazio)
dlr-level	Text	1
dlr-method	Text	POST
flash	Text	(vazio)

5. Erros Comuns e Respostas

Código	Status	Descrição
USER_NOT_FOUND	404	O usuário não é válido.
USER_INACTIVE	401	O usuário está inativo ou não tem permissões para realizar a ação.
AUTH.TOKEN_MISSING	400	Falta o token de autenticação.
API_KEY_NOT_FOUND	400	A chave API não foi encontrada ou foi revogada.
COUNTRY_001	400	Não foi encontrado um país associado ao prefixo.
SMS_002	402	Créditos insuficientes para usuários com plano pré-pago.
SMS_008	400	O número de registros enviados excede o limite permitido.
SMS_009	400	O arquivo Parquet enviado não é válido ou não cumpre o formato esperado.
DUPLICATED_MSG_ID	400	Um ou mais identificadores msg_id já existem em uma campanha anterior.
FORBIDDEN_TERMS	400	O conteúdo contém termos não permitidos.
SHORTNAME_INACTIVE	400	O shortname não se encontra ativo para o usuário.
SHORTNAME_NOT_FOUND	400	A mensagem não contém o shortname obrigatório.
CONTENT_TOO_LONG	400	O conteúdo ultrapassa o limite de comprimento permitido para um SMS.

Parâmetros de Saída

Campo	Descrição
request_id	ID único atribuído à campanha em massa.
total_credits	Total de créditos consumidos pelo envio.
records	Total de mensagens processadas da campanha.
total_pdu_count	Total de PDUs gerados entre todas as mensagens.