Integra el envío de SMS
en tu servicio.

Inicio rápido

1. Crea una clave API

   Tras registrarte, ser aprobado e iniciar sesión con OTP, ve a Gestionar claves API para crear una clave.

2. Prepara créditos

   La API usa el saldo y el precio de tu cuenta. El importe se descuenta cuando se acepta el envío.

3. Envía y consulta los resultados

   Guarda el ID del envío y consulta los resultados con la API de estado.

Cobertura

GET/api/v1/messages/countries

Consulta por API los países activos y el precio que se te aplica. Indica el país con country al enviar y usa números del mismo país en cada solicitud. No se aceptan envíos a países sin tarifa configurada.

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

Autentícate con una clave API

Incluye este encabezado en todas las solicitudes a la API. No necesitas cookies de sesión ni códigos OTP.

Authorization: Bearer hex_live_TU_CLAVE_API

La clave completa solo se muestra una vez al crearla. Guárdala en una variable de entorno del servidor y nunca en el código frontend. Las claves revocadas o de cuentas suspendidas no funcionan. Puedes crear hasta 5 claves.

Envía a 1.000 números de una vez

Envía el mismo mensaje a varios números. Validamos la solicitud, la ponemos en cola y respondemos al instante. Para enviar contenidos distintos a cada número, usa solicitudes separadas con un Idempotency-Key nuevo.

Si hay un solo número no válido o duplicado, se rechaza toda la solicitud sin enviar ni cobrar. Los duplicados se comprueban tras normalizar los números al formato internacional.

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

Cómo se calcula el importe

Números × segmentos (segments) × precio unitario de la cuenta. UCS-2 admite 70 caracteres en un segmento y después 67 por segmento. GSM-7 básico admite 160 y después 153 por segmento. Los caracteres de extensión cuentan doble y los emojis usan su longitud en UTF-16. unitPrice y cost se expresan en USDT. La respuesta incluye el precio aplicado; el 0,025 de arriba es solo un ejemplo.

Consulta el resultado de cada número

Usa el id que devuelve la API de envío. Solo puedes consultar los envíos hechos por API con la misma cuenta. Esta consulta devuelve los resultados guardados. Si necesitas los últimos resultados del operador, llama antes a la API de actualización.

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

limit va de 1 a 1.000 (100 por defecto) y offset de 0 a 1.000 (0 por defecto). Si nextOffset es null, es la última página. summary cuenta todos los números por estado. to usa el formato internacional sin +, y las horas se devuelven en milisegundos Unix. El orden puede diferir del de la solicitud original; identifica cada mensaje por su id.

Obtén el estado de entrega más reciente

Actualiza los resultados guardados a partir de los registros del operador. No hace falta cuerpo. Después, vuelve a leer los resultados con GET. Cada envío se puede actualizar una vez cada 30 segundos. Los registros del operador están disponibles durante 48 horas tras el envío. Si hay webhooks configurados, los resultados pueden actualizarse automáticamente.

curl -X POST 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{ "id": "35bed356-b84a-452a-8e94-98b538972ecd", "updated": 2 }

updated es el número de filas actualizadas. Puede ser 0 si los mensajes siguen en cola o no hay resultados nuevos. Recomendamos llamar a GET con intervalos de al menos 10 segundos y solicitar refresh solo cuando sea necesario.

Códigos de estado

state del envío

PREPARING: en preparación · RUNNING: en proceso · PAUSED: en pausa · DONE: cola procesada · CANCELED: cancelado

Los operadores pueden añadir códigos nuevos, así que gestiona también los valores de status desconocidos. Consulta el motivo del fallo en statusName, description y error.

Cómo gestionar los errores

{ "error": "Créditos insuficientes. Recarga y vuelve a intentarlo.", "code": "INSUFFICIENT_CREDITS" }

Cada clave API admite hasta 120 solicitudes por minuto entre envíos, consultas y actualizaciones. Si alcanzas el límite, revisa el encabezado Retry-After. La API está pensada para integraciones entre servidores y no admite llamadas CORS desde el navegador.

Conéctate con Node.js

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

Crea una clave de solicitud una vez por operación y reutilízala si reintentas por falta de respuesta. Si reenvías con una clave nueva una operación que ya tuvo éxito, se tratará como un envío distinto.