Guía de uso API de envíos SMS

Abreviaciones

Abreviatura	Descripción
PARQUET	Formato de archivo diseñado para almacenar grandes cantidades de datos de manera ordenada y eficiente.
PDU	Unidad de datos del protocolo (Protocol Data Unit) que representa la cantidad de fragmentos en los que se divide un SMS para su envío.
UUID	Identificador Único Universal (código generado aleatoriamente) utilizado para msg_id y request_id.
DLR	Acuse de entrega (Delivery Receipt). Notificación que confirma si un SMS fue entregado o falló.
SMPP	Protocolo de mensajería corta (Short Message Peer-to-Peer). Protocolo estándar para envío de SMS vía conexión TCP persistente.

Introducción

La API de Envío de SMS permite realizar envíos unitarios y masivos de mensajes de texto utilizando formatos JSON o Parquet.

A través de esta guía podrá conocer cómo autenticarse, qué servicios están disponibles, qué métodos se pueden usar y qué estructuras y formatos se deben utilizar para realizar las solicitudes de manera correcta.

---

1. Autenticación y seguridad

Antes de usar la API de Envíos Masivos, es necesario contar con una clave de acceso segura (api key). Esta clave es entregada directamente por el equipo de Saem Colombia y debe incluirse en cada solicitud dentro del encabezado x-auth.

Sin esta autenticación, el sistema rechazará la petición.

Además de la api key, se debe incluir el header x-prefix indicando el código del país en todas las solicitudes.

Ejemplo de aplicación (headers):

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

---

Servicios disponibles en la API SMS

Parámetros de entrada

Campo	Descripción
from	Identificador del remitente autorizado para enviar mensajes.
numbers	Lista de mensajes a enviar. Cada objeto debe incluir to, content y opcionalmente msg_id.
msg_id	ID único del mensaje. Si no se envía se genera automáticamente.
to	Número celular del destinatario.
content	Texto del mensaje incluyendo el shortname.
flash	Define si el SMS se mostrará de inmediato en una ventana emergente (yes o no). Este campo es obligatorio enviarlo para todos los servicios.
unique-numbers	Si lo requiere, utilice este parámetro para validar y rechazar números duplicados en el envío. Acepta yes o no. De lo contrario, no es necesario incluirlo.
x-prefix	Código del país, debe enviarse como header.
x-auth	Token de autenticación, debe enviarse como header.
dlr	Activa el acuse de entrega. Enviar yes para recibirlo. Aplica para envío unitario y masivo.
dlr-url	URL donde se enviará la notificación de entrega (callback HTTP). Requerido si dlr=yes.
dlr-level	Nivel de reporte del DLR: 1 = solo exitosos, 2 = solo fallidos, 3 = todos los estados.
dlr-method	Método HTTP del callback: GET o POST.

---

2. Envío unitario

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

Ejemplo de params:

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

GET https://apisms.saem.tel/v3/send?to=573999999999&content=Prueba%20oficial%20SMS%20API%20V3%20claro&from=saemcolombia&flash=no
x-auth: api-key-XXX000X00000
x-prefix: 57

💡 IMPORTANTE Para todos nuestros servicios en formato JSON se podrá subir un máximo de 200.000 registros. Si se envía una cantidad superior, el sistema rechazará la solicitud con el error SMS_008.

---

3. Envío masivo formato JSON

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

Ejemplo de body (raw / JSON):

{
  "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" }
  ]
}

---

4. Envío masivo formato Parquet

Para este formato se debe tener en cuenta que el cuerpo de la solicitud (body) debe enviarse en formato form-data, incluyendo el archivo .parquet y los demás parámetros necesarios.

💡 Recomendación Se sugiere utilizar el formato Parquet en lugar de archivos JSON, ya que permite una carga mucho más rápida, reduce el tamaño del archivo y mejora el rendimiento general del proceso.

Para este formato se podrá subir un máximo de 500.000 registros. Si se envía una cantidad superior, el sistema rechazará la solicitud con el error SMS_008.

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

Ejemplo de body (form-data):

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

---

5. Notificación de entrega (DLR)

El DLR permite recibir una notificación cuando un SMS ha sido entregado o ha fallado. Para activarlo, incluya los parámetros dlr, dlr-url, dlr-level y dlr-method en su solicitud de envío.

Ejemplo de solicitud con DLR (unitario GET)

Key	Value
to	57312345789
content	Hola saem oficial claro
from	SAEM
dlr	yes
dlr-url	https://miservidor.com/dlr
dlr-level	1
dlr-method	POST
flash	no

GET https://apisms.saem.tel/v3/send?to=57312345789&content=Hola%20saem%20oficial%20claro&from=SAEM&dlr=yes&dlr-url=https://miservidor.com/dlr&dlr-level=1&dlr-method=POST&flash=no

Campos que recibe su endpoint de callback

• id: Identificador único del mensaje (UUID).
• message_status: Estado del mensaje (DELIVRD = entregado, UNDELIV = fallido, EXPIRED = expirado).

NOTA: Su endpoint debe responder con HTTP 200 para confirmar la recepción del DLR.

Ejemplo de callback (form values)

Campo	Valor
connector	XXXXXXXXXXXXXXXXX
dlvrd	001
donedate	2501011200
err	000
id	00000000-0000-0000-0000-000000000000
id_smsc	XXXXXXXXXXXXXXXXX
level	2
message_status	DELIVRD
sub	001
subdate	2501011200
text	(vacío)

---

6. Protocolo SMPP

El protocolo SMPP permite enviar SMS y recibir acuses de entrega (DLR) mediante una conexión TCP persistente. Es el método recomendado para altos volúmenes de mensajes o cuando se requiere un canal bidireccional en tiempo real.

Datos de conexión

• Host: smpp.saem.tel
• Puerto: 2775
• Modo: bind_transceiver (envío y recepción en la misma sesión)

Credenciales

El system_id y la contraseña SMPP son asignados por el equipo de Saem Colombia. Son independientes de las credenciales HTTP (api key).

Envío de mensajes (submit_sm)

• source_addr: Shortname autorizado (remitente).
• destination_addr: Número del destinatario (con prefijo de país, ej: 573001234567).
• short_message: Contenido del SMS.
• registered_delivery: 1 para activar el acuse de entrega (DLR).

Recepción de acuses (deliver_sm)

Al activar registered_delivery=1, el servidor envía un deliver_sm a la sesión SMPP activa con el estado de entrega. Los estados posibles son: DELIVRD (entregado), UNDELIV (fallido), EXPIRED (expirado).

Ejemplo de sesión

1 · CONEXIÓN Y AUTENTICACIÓN (BIND)
  Host:       smpp.saem.tel
  Puerto:     2775
  System ID:  <su_system_id>
  Modo:       bind_transceiver
  ✔ Bind exitoso — sesión SMPP abierta

2 · ENVÍO DE MENSAJE (submit_sm)
  Remitente (source_addr):      <su_shortname>
  Destinatario (dest_addr):     573001234567
  Contenido (short_message):    Prueba SMPP SAEM
  registered_delivery:          1  (activar DLR)
  ✔ submit_sm enviado

Límites

• TPS máximo y número de sesiones simultáneas: definidos por el plan asignado.

---

7. Errores comunes y respuestas

Código	Status	Descripción
USER_NOT_FOUND	404	El usuario no es válido.
USER_INACTIVE	401	El usuario está inactivo o no tiene permisos para realizar la acción.
AUTH.TOKEN_MISSING	400	Falta el token de autenticación.
API_KEY_NOT_FOUND	400	No se encontró la clave API o ha sido revocada.
COUNTRY_001	400	No se encontró un país asociado al prefijo.
SMS_002	402	Créditos insuficientes para usuarios con plan prepago.
SMS_008	400	El número de registros enviados excede el límite permitido.
SMS_009	400	El archivo Parquet enviado no es válido o no cumple con el formato esperado.
DUPLICATED_MSG_ID	400	Uno o más identificadores msg_id ya existen en una campaña previa.
FORBIDDEN_TERMS	400	El contenido contiene términos no permitidos.
SHORTNAME_INACTIVE	400	El nombre corto no se encuentra activo para el usuario.
SHORTNAME_NOT_FOUND	400	El mensaje no contiene el shortname obligatorio.
CONTENT_TOO_LONG	400	El contenido supera el límite de longitud permitido para un SMS.

Parámetros de salida

Campo	Descripción
request_id	ID único asignado a la campaña masiva.
total_credits	Total de créditos consumidos por el envío.
records	Total de mensajes procesados de la campaña.
total_pdu_count	Total de PDUs generados entre todos los mensajes.