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.