Documentazione API

Per iniziare

Tre cose stanno tra un nuovo account e un messaggio consegnato: un token, un po' di credito, e una chiave. Nessuna di queste coinvolge un essere umano.

1. Crei un account: il Suo browser genera il token, e quel token è l'account.
2. Lo rifornisca. Minimo $40, in una qualsiasi delle criptovalute su la pagina dei pagamenti.
3. Crei una chiave API nel pannello. Viene mostrata una sola volta; conserviamo solo il suo hash, esattamente come per il token.

Autenticazione

Bearer token a ogni richiesta. La chiave identifica l'account; non c'è un secondo fattore, nessuna firma sulla richiesta e nessuna allowlist di IP — la chiave è l'intera credenziale, quindi la tratti come tale.

Authorization: Bearer ws_live_9f2c…

Invii messaggi

POST/v1/messages

Una chiamata, uno o più destinatari, destinazioni miste. Ogni destinatario viene tariffato al prezzo della propria destinazione ed è addebitato per segmento. La chiamata viene accettata o rifiutata nel suo complesso; non Le viene mai addebitato solo in parte.

Corpo della richiesta

Esempio

# 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
}

Raggruppamento

Un batch viene accettato immediatamente e defluisce a 200 messaggi al minuto per account, quindi 50.000 destinatari richiedono circa 4 h 10 min. Il traffico critico in termini di tempo non dovrebbe mettersi in coda dietro un invio di marketing: usi una chiave separata per quello.

Stato del messaggio

GET/v1/messages/{batch_id}

Il polling è supportato e sottoposto a limite di frequenza; i webhook sono il percorso previsto. La risposta aggrega il batch ed elenca lo stato per singolo destinatario.

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

refund_usd viene regolato una sola volta, al termine del batch. È già di nuovo nel Suo saldo nel momento in cui può leggerlo.

Saldo

GET/v1/balance

Verifichi prima di un invio consistente. I saldi sono conservati internamente in micro-dollari interi — le tariffe arrivano a quattro decimali, e un float non ha ragione d'esistere in un registro movimenti — e restituiti qui arrotondati a sei.

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

Ricevute di consegna

Una ricevuta viene emessa per ogni destinatario non appena l'operatore la riporta. Questi sono gli unici quattro stati; non esiste una categoria “sconosciuto” che significhi silenziosamente “l'abbiamo persa”.

I numeri che non corrispondono mai a una destinazione con prezzo sono rifiutati al momento dell'invio e non entrano affatto in questo ciclo di vita — non vengono addebitati e poi rimborsati, semplicemente non vengono addebitati.

Webhook

Imposti un endpoint nel pannello o per singolo batch con callback_url. Inviamo JSON via POST e ci aspettiamo un 2xx entro 5 secondi. Un codice non-2xx viene ritentato sei volte con backoff esponenziale nell'arco di circa un'ora, poi scartato.

Payload

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

Verifica della firma in corso

Ogni consegna porta X-WorldSMS-Signature e X-WorldSMS-Timestamp. La firma è HMAC-SHA256(timestamp + "." + body) utilizzando il Suo secret del webhook. Confronti in tempo costante, e rifiuti un timestamp più vecchio di cinque minuti, in modo che una consegna intercettata non possa esserLe ripresentata in seguito.

// $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);

Errori

Ogni errore restituisce un corpo JSON con uno slug error stabile. Si basi sullo slug, mai sul testo descrittivo — il testo può essere migliorato.

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

Limiti

I limiti di frequenza si applicano alle chiamate API, non ai messaggi: una chiamata che trasporta 5.000 destinatari costa una richiesta rispetto al limite.