Referencia de la API

Primeros pasos

Tres cosas separan una cuenta nueva de un mensaje entregado: un token, algo de saldo y una clave. Ninguna de ellas involucra a una persona.

1. Crea una cuenta: su navegador genera el token, y ese token es la cuenta.
2. Recárguela. $40 mínimo, en cualquiera de las monedas en la página de pagos.
3. Cree una clave de API en el panel. Se muestra una sola vez; solo almacenamos su hash, igual que el token.

Autenticación

Token portador en cada solicitud. La clave identifica la cuenta; no hay segundo factor, no hay firma en la solicitud y no hay lista blanca de IP — la clave es toda la credencial, así que trátela como tal.

Authorization: Bearer ws_live_9f2c…

Enviar mensajes

POST/v1/messages

Una llamada, uno o varios destinatarios, destinos mixtos. Cada destinatario se factura a la tarifa de su propio destino y se cobra por segmento. La llamada se acepta o se rechaza en conjunto; nunca le cobra parcialmente.

Cuerpo de la solicitud

Ejemplo

# one call, many recipients, mixed destinations
curl -X POST https://api.worldsms.io/v1/messages \
  -H "Authorization: Bearer $WORLDSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "ACME",
    "to":   ["+447700900123", "+33612345678"],
    "text": "Your code is 480913"
  }'

{
  "batch_id": "b_7Kq2xR9wLm",
  "accepted": 2,
  "rejected": 0,
  "segments": 1,
  "cost_usd": 0.0353
}

Agrupación

Un lote se acepta de inmediato y se procesa a 200 mensajes por minuto por cuenta, así que 50.000 destinatarios tardan aprox. 4 h 10 min. El tráfico urgente no debería hacer cola detrás de un envío de marketing: use una clave distinta para eso.

Estado del mensaje

GET/v1/messages/{batch_id}

El sondeo (polling) es compatible y tiene límite de tasa; los webhooks son la vía prevista. La respuesta consolida el lote y lista el estado por destinatario.

{
  "batch_id":    "b_7Kq2xR9wLm",
  "status":      "done",
  "sending":     0,
  "delivered":   1,
  "undelivered": 1,
  "refund_usd":  0.0216
}

refund_usd se liquida una sola vez, cuando el lote termina. Ya está de vuelta en su saldo para cuando puede leerlo.

Saldo disponible

GET/v1/balance

Compruébelo antes de un envío grande. Los saldos disponibles se mantienen internamente en microdólares enteros — las tarifas llegan a cuatro decimales, y un número de coma flotante no tiene cabida en un registro de movimientos — y se devuelven aquí redondeados a seis.

{ "balance_usd": 412.905400, "currency": "USD" }

Confirmaciones de entrega

Se emite un recibo por destinatario a medida que el operador lo reporta. Estos son los únicos cuatro estados; no existe un cajón de “desconocido” que signifique en silencio “lo perdimos”.

Los números que nunca resuelven a un destino con precio se rechazan en el envío y jamás entran en este ciclo de vida: no se facturan para luego reembolsarse, simplemente no se facturan.

Webhooks

Configure un endpoint en el panel o por lote con callback_url. Enviamos JSON por POST y esperamos un 2xx en 5 segundos. Los que no sean 2xx se reintentan seis veces con retroceso exponencial durante aproximadamente una hora, y después se descartan.

Carga útil

{
  "event":     "message.delivered",
  "batch_id":  "b_7Kq2xR9wLm",
  "to":        "+447700900123",
  "destination": "gb",
  "segments":  1,
  "cost_usd":  0.0137,
  "reference": "order-4471",
  "ts":        1785312041
}

Verificando la firma

Cada entrega lleva X-WorldSMS-Signature y X-WorldSMS-Timestamp. La firma es HMAC-SHA256(timestamp + "." + body) usando su secreto de webhook. Compare en tiempo constante, y rechace una marca de tiempo con más de cinco minutos de antigüedad, para que una entrega capturada no pueda repetirse contra usted más tarde.

// $secret is the webhook secret from the dashboard
$raw  = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_WORLDSMS_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_WORLDSMS_SIGNATURE'] ?? '';

// A stale timestamp is a replay, however well it is signed.
if (abs(time() - (int) $ts) > 300) { http_response_code(408); exit; }

$mine = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($mine, $sig)) { http_response_code(401); exit; }

http_response_code(204);

Errores

Cada error devuelve un cuerpo JSON con un slug error estable. Compare con el slug, nunca con el texto — el texto puede mejorar.

{
  "error":       "insufficient_credit",
  "message":     "Batch costs $84.20, balance is $12.05.",
  "required_usd": 84.20,
  "balance_usd":  12.05
}

Límites

Los límites de tasa se aplican a las llamadas a la API, no a los mensajes: una llamada con 5.000 destinatarios cuenta como una sola solicitud contra el límite.