Documentación API REST

Guía de integración para desarrolladores. Nuestra API robusta le permite enviar y gestionar SMS de forma sencilla y eficiente.

1) Transporte y Formato

Base URL: https://sms.402tlabs.com/api/v1

Protocolo: HTTPS únicamente (Seguridad TLS 1.2+)
Content-Type: application/json; charset=utf-8
Codificación: UTF-8 (con normalización automática GSM)

2) Autenticación

Autentique sus solicitudes utilizando API Keys. Incluya su clave en el encabezado Authorization como un token Bearer.

Authorization Header

Authorization: Bearer <su_api_key>

3) Convenciones

3.1 Idempotencia

Para evitar duplicados en reintentos de red, use el encabezado:

Idempotency-Key: <uuid_unico>

3.2 Respuesta Estándar

Todas las respuestas siguen este envoltorio JSON:

JSON Response

{
  "status": 0,
  "message": "OK",
  "data": {}
}

4) Endpoints

POST /sms/send

Envía un mensaje SMS de forma inmediata.

Parámetros del Body

Campo	Tipo	Descripción
to Required	string	Número de destino en formato nacional o internacional (ej: 34600000000).
text Required	string	Contenido del mensaje (máx. 160 caracteres).
from	string	Remitente personalizado (3-11 caracteres alfanuméricos).

Ejemplo de Solicitud

{
  "to": "34600000000",
  "text": "Hola desde la API de 402T Labs",
  "from": "402TLabs"
}

POST /sms/schedule

Programa un envío de SMS para una fecha y hora futura.

Body Request

{
  "to": "34600000000",
  "text": "Este mensaje se enviará mañana",
  "send_at": "2023-12-31T10:00:00"
}

POST /sms/batch

Envía múltiples mensajes en una sola solicitud (máximo 100 mensajes).

Body Request

{
  "messages": [
    { "to": "34600000001", "text": "Mensaje 1" },
    { "to": "34600000002", "text": "Mensaje 2" }
  ]
}

GET /accounts/{login}/balance

Consulta el saldo actual de una cuenta específica.

Ejemplo de Respuesta

{
  "status": 0,
  "data": {
    "login": "usuario123",
    "balance": 524.50
  }
}

GET /sms/{guid}/status

Consulta el estado detallado de un mensaje mediante su Identificador Único (GUID).

Respuesta de Estado

{
  "guid": "a00f005b-51e6-477e-87fb-458d01c9740c",
  "state": "ENTREGADO",
  "updated_at": "2023-10-27T10:30:00"
}

POST /users

Crea una nueva subcuenta de usuario bajo su jerarquía.

Body Request

{
  "name": "Juan",
  "surname": "Pérez",
  "login": "juanp",
  "password": "********",
  "contact_email": "juan@example.com"
}

GET /users/{login}/costs

Consulta los costos configurados para un usuario específico.

POST /users/{login}/password

Cambia la contraseña de un usuario.

{
  "current_password": "old_pass",
  "new_password": "new_pass"
}

Apéndice A — Caracteres y Normalización

Nuestra plataforma soporta el alfabeto GSM estándar. Los caracteres fuera de este rango se normalizarán automáticamente o causarán un error si no pueden ser procesados.

€ @ $ Ç ç _ ! " # % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? ¡ A B C D E F G H I J K L M N Ñ O P Q R S T U V W X Y Z ¿ a b c d e f g h i j k l m n ñ o p q r s t u v w x y z Á á É é Í í Ó ó Ú ú À à È è Ì ì Ò ò Ù ù Ä ä Ë ë Ï ï Ö ö Ü ü Â â Ê ê Î î Ô ô Û û (espacio)

Apéndice B — Códigos de Error

Nuestra API utiliza códigos de error numéricos para facilitar el manejo programático de excepciones.

Código	Mensaje	Descripción
-1	Usuario/Password incorrectos	Credenciales inválidas.
-2	Sin permisos SMS	El usuario no tiene permisos de envío.
-7	Teléfono incorrecto	Formato MSISDN inválido.
-9	Faltan campos	Faltan parámetros obligatorios.
-11	Fecha en el pasado	La fecha programada ya ha pasado.
-12	Saldo insuficiente	No hay crédito suficiente.
-13	Remitente incorrecto	Remitente no válido o no autorizado.
-17	Usuario no existe	El login proporcionado no existe.
-19	SMS demasiado largo	Excede el límite de 160 caracteres.
-21	Caracteres inválidos	Detección de caracteres no permitidos.
-26	Login ya existe	El login ya está en uso.
-30	Petición no válida	Error genérico de solicitud mal formada.