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.