Documentación de la API

Autenticación

Todas las peticiones se autentican con un token personal enviado en la cabecera Authorization.

Authorization: Bearer TU_TOKEN
Accept: application/json

Cómo obtener tu token

1. Inicia sesión en tu cuenta de FastSMS.
2. Entra en la pantalla API Tokens.
3. Crea un token, ponle un nombre y cópialo en ese momento: solo se muestra una vez.

Ciclo de vida de un mensaje

Cada mensaje avanza por una máquina de estados. El campo status de las respuestas siempre contiene uno de estos seis valores.

programado --(llega la hora)--> por_enviar --(se asigna canal)--> en_cola --(el canal confirma)--> enviado
     |                             |                              |
     +-----------------------------+------------------------------+--> cancelado / error

Endpoints

Todas las rutas cuelgan de https://sms.51x.mx/api/v1 y requieren autenticación.

{
  "nombre": "Ana López",
  "numero": "5551234567",
  "mensaje": "Tu cita es mañana a las 10:00"
}

{
  "message": "Mensaje creado correctamente",
  "msg_id": "9b1c7d4e-...-3f2a",
  "status": "por_enviar"
}

{
  "fecha_envio": "2026-09-01",
  "hora_envio": "09:00",
  "mensajes": [
    {
      "nombre": "Ana",
      "numero": "5551234567",
      "mensaje": "Recordatorio de cita"
    },
    {
      "numero": "5559876543",
      "mensaje": "Tu paquete va en camino",
      "hora_envio": "18:30"
    }
  ]
}

{
  "message": "2 mensajes creados",
  "data": [
    {
      "msg_id": "9b1c7d4e-...-3f2a",
      "numero": "5551234567",
      "status": "programado"
    },
    {
      "msg_id": "7a2e9f10-...-b5c8",
      "numero": "5559876543",
      "status": "programado"
    }
  ]
}

GET /api/v1/messages?status=enviado&page=2

{
  "current_page": 1,
  "data": [ ... objetos mensaje ... ],
  "first_page_url": "...",
  "from": 1,
  "last_page": 3,
  "next_page_url": "...",
  "path": "...",
  "per_page": 50,
  "prev_page_url": null,
  "to": 50,
  "total": 118
}

{
  "msg_id": "9b1c7d4e-...-3f2a",
  "nombre": "Ana López",
  "numero": "5551234567",
  "mensaje": "Tu cita es mañana a las 10:00",
  "status": "enviado",
  "status_label": "Enviado",
  "fecha_envio": "2026-09-01",
  "hora_envio": "09:00:00",
  "sent_at": "2026-09-01 09:00:37",
  "error": null
}

{
  "message": "Mensaje cancelado",
  "status": "cancelado"
}

{
  "error": "No se puede cancelar un mensaje ya enviado o finalizado."
}

Programación de envíos

Para programar un mensaje, envía fecha_envio (AAAA-MM-DD) y hora_envio (HH:MM o HH:MM:SS). Si los omites, el mensaje entra en la cola de inmediato.

Longitud del mensaje y segmentos

La API no limita la longitud del campo mensaje, pero la red SMS sí: un mensaje largo se parte en varios segmentos y cada segmento se cobra por separado. Conviene que lo controles desde tu aplicación.

Un solo carácter acentuado o un emoji cambia todo el mensaje a Unicode y reduce la capacidad de 160 a 70 caracteres. Como referencia, el panel de FastSMS corta en 5 segmentos: 765 caracteres en GSM-7, 335 en Unicode.

Códigos de error

{
  "message": "The numero field is required.",
  "errors": {
    "numero": ["The numero field is required."]
  }
}

{
  "error": "Mensaje no encontrado"
}

Ejemplos de integración

El mismo envío, en tres lenguajes.

curl -X POST https://sms.51x.mx/api/v1/messages \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Ana",
    "numero": "5551234567",
    "mensaje": "Tu cita es manana a las 10:00"
  }'

<?php

$payload = json_encode([
    'nombre'  => 'Ana',
    'numero'  => '5551234567',
    'mensaje' => 'Tu cita es manana a las 10:00',
]);

$ch = curl_init('https://sms.51x.mx/api/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer TU_TOKEN',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
]);

$respuesta = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $respuesta['msg_id'];

const respuesta = await fetch('https://sms.51x.mx/api/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TU_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    nombre: 'Ana',
    numero: '5551234567',
    mensaje: 'Tu cita es manana a las 10:00',
  }),
});

const datos = await respuesta.json();
console.log(datos.msg_id);