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.

Qué hace esta API

Permite crear campañas de llamadas automáticas (masivas) en dos modos:

STANDARD: audio pregrabado (referenciado por audioId)
CUSTOM: texto a voz (TTS) por contacto (content), usando una voz (voice = “Juan” o “Maria”)

Autenticación

Todas las solicitudes deben incluir:

x-auth: api key entregada por Saem.

A diferencia de SMS, aquí prefix es un campo de body para campañas (no se describe como header en los endpoints de envío de CallB en la guía).

Conceptos clave de payload

campos usados en esta API:

subService: "standard" o "custom"
prefix: código país origen (ej 57)
gmt: zona horaria local en formato +/-HH:MM (afecta ventana de ejecución)
nameCampaign: nombre de campaña
mailbox: true/false (dejar mensaje en buzón si no contesta)
configProgramming: lista de programaciones de ejecución
- máximo 5 configuraciones (y si envías más de una, crea una campaña independiente por cada configuración)
- incluye:
  - dateStart, dateEnd
  - reviews: (reintentos)
  - configReview: condiciones para reintentar (máx 5 “repasos”)
numbers:
- STANDARD: lista de números (sin símbolos)
- CUSTOM: arreglo de objetos { number, content } Condiciones para reintentos (configReview) Valores permitidos: buzon, colgo, congestion, fallo, maquina, mcolgo, msatisfactorio, nocontesta, satisfactorio.

Límite de carga

Para servicios en JSON:

Máximo 200.000 registros
Si excedes: error CALLB_022.

Para Parquet:

Máximo 500.000 registros
Si excedes: CALLB_022

Flujo STANDARD: cómo se arma una campaña

Paso A: Obtener/crear audioId El campo audioId se obtiene:

Desde el módulo “Recursos” en la plataforma web (cada audio tiene un ID), o
Generándolo por API (siguiente sección).

Paso B: Generar audio por API (opcional, pero recomendado si automatizas)

URL: https://apicallb.saem.tel/audio/generate
Método: POST
Headers: x-auth
Body: incluye text, voice, resource_name (nombre base del archivo .wav)

Paso C: Crear campaña 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: [ ... ] (lista de teléfonos)
}

Flujo CUSTOM: campaña TTS (texto a voz)

Crear campaña 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 }, ...]
  misma lógica de prefix, gmt, configProgramming.
}

Plantillas (CUSTOM) Etiquetas que el sistema interpreta por contacto: {I} identificador, {N} nombre, {S} saldo/valor, {T} teléfono, {E} correo, {C} cuenta.

Campañas con Parquet

URL: https://apicallb.saem.tel/send/massive/parquet Método: POST Headers: x-auth Body: form-data (archivo .parquet + campos)

Reglas del archivo

STANDARD: Parquet con columna number.
CUSTOM: Parquet con columnas number y content.

configProgramming en form-data debe enviarse como string JSON (no como objeto): [{"dateStart":"...","dateEnd":"...","reviews":2,...}]

Respuesta dee creación de campaña

Al crear una campaña se retorna un resumen que contiene:

sends: conteo por operador (incluye "null" para “números errados encontrados”)
summary:
- total_records
- total_credits
- seconds_aprox (segundos aproximados totales)

Errores

Código	HTTP Status	Descripción
`AUTH.TOKEN_MISSING`	400	No se envió el header `x-auth`.
`API_KEY_NOT_FOUND`	400	La API Key enviada no existe o es inválida.
`USER_NOT_FOUND`	404	No se encontró el usuario asociado a la API Key.
`USER_INACTIVE`	401	El usuario está inactivo y no puede ejecutar campañas.

Código	HTTP Status	Descripción
`CALLB_015`	404	No se encontró el recurso multimedia (audioId inválido o inexistente).
`CALLB_016`	404	No existe configuración para el país o prefijo enviado.
`CALLB_018`	400	El horario configurado está fuera del rango permitido para el país.

Código	HTTP Status	Descripción
`CALLB_019`	400	Archivo Parquet inválido o mal estructurado.
`CALLB_021`	402	Créditos insuficientes para ejecutar la campaña.
`CALLB_022`	400	Se excedió el número máximo de registros permitidos.

Código	HTTP Status	Descripción
`CALLB_AUD_001`	400	`resource_name` inválido o con formato incorrecto.
`CALLB_AUD_002`	409	El recurso de audio ya existe (nombre duplicado).