SAEM | Plataforma de SMS, Voz e IVR para Latinoamérica

Que hace

La API de SMS permite enviar SMS de forma:

Unitaria (un número por request).
Masiva (muchos números en un request) usando:
- JSON (hasta 200.000 registros).
- Parquet (hasta 500.000 registros y recomendado por performance).

Autenticación y headers requeridos

Todas las solicitudes deben incluir:

x-auth: api key entregada por Saem Colombia (si falta, rechaza la petición).
x-prefix: código del país como header (ej: 57).

Regla: sin estos headers, la API no procesa.

Modelo de datos (parámetros de entrada)

La guía lista estos campos (aplican según endpoint/formato):

from: identificador del remitente autorizado.
flash: obligatorio en todos los servicios; valores yes o no.
numbers: lista de mensajes a enviar; cada item incluye:
- to: número destino.
- content: texto del mensaje (incluye el shortname obligatorio, ver errores).
msg_id (opcional): id único del mensaje; si no lo envías, el sistema lo genera.

Nota importante: la guía menciona “content incluyendo el shortname” y existe error SHORTNAME_NOT_FOUND si no está.

Edpoint: Envío unitario

URL: https://apisms.saem.tel/v3/send

Metodo: GET

Headers: Headers: x-auth, x-prefix

Cómo funciona:

Envías los parámetros como query params (to, content, from, flash).
El sistema procesa un SMS a un destinatario.

Cuándo usar

Notificaciones puntuales (OTP, confirmaciones individuales, etc.).

Endpoint: Envío masivo en JSON

URL: https://apisms.saem.tel/v3/send

Método: POST

Headers: x-auth, x-prefix

Body: JSON

Límite:

Máximo 200.000 registros por envío en JSON.
Si excedes: error SMS_008.

Cómo funciona

Mandas un objeto con metadata (ej. from, flash) y la lista numbers.
Cada elemento de numbers representa un SMS a enviar.

Recomendación práctica

Si necesitas trazabilidad: envía msg_id tú (UUID) para correlacionar.
Si no lo envías, la API lo genera.

Endpoint: Envío masivo en Parquet

URL: https://apisms.saem.tel/v3/send/parquet

Método: POST

Headers: x-auth, x-prefix

Body: form-data (archivo .parquet + parámetros adicionales)

Límite

Máximo 500.000 registros.
Si excedes: error SMS_008.

Cómo funciona

En vez de pasar numbers en JSON, subes un archivo Parquet con los registros.
La guía recomienda Parquet por:
- carga más rápida,
- menor tamaño,
- mejor rendimiento general.

Parámetros de salida

Descripciones de campos en la respuesta (especialmente para campañas masivas):

request_id: id único de la campaña masiva.
total_credits: créditos consumidos.
records: total de mensajes procesados.
total_pdu_count: total de PDUs generados entre todos los mensajes (útil para entender segmentación de SMS largos).

Manejo de errores

Errores de Autenticación

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.
`COUNTRY_001`	400	El prefijo (`x-prefix`) no tiene un país asociado o no está configurado.

Errores de Envío / Validación

Código	HTTP Status	Descripción
`SMS_002`	402	Créditos insuficientes (cuentas prepago).
`SMS_008`	400	Se excedió el límite máximo de registros permitidos.
`SMS_009`	400	Archivo Parquet inválido o mal formado.
`DUPLICATED_MSG_ID`	400	El `msg_id` ya fue utilizado en una campaña previa.
`FORBIDDEN_TERMS`	400	El contenido contiene términos no permitidos.
`SHORTNAME_INACTIVE`	400	El shortname está inactivo.
`SHORTNAME_NOT_FOUND`	400	No se encontró el shortname en el contenido del mensaje.
`CONTENT_TOO_LONG`	400	El contenido del mensaje excede la longitud permitida.

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).

API SMS