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.