Il primo SMS con curl e Node

Dalla chiave API al primo invio: la chiamata completa con curl, la stessa in Node 22 senza dipendenze, e come leggere stato, parti e prezzo nella risposta.

Prima di tutto: la chiave API

Le credenziali vivono dentro un'app: dalla sezione App della dashboard creane una (ad esempio "backend-produzione") e copia la chiave gsms_… al momento della creazione — viene mostrata una volta sola. Se la perdi, ne generi una nuova.

La chiave va nell'header Authorization come Bearer token, su ogni richiesta. Trattala come una password: mai nel codice client, mai in un repository.

La richiesta con curl

Per un SMS transazionale basta una POST con tre campi: il destinatario in formato internazionale (+39…), il testo e il tipo di mittente. L'header Idempotency-Key non è obbligatorio, ma conviene metterlo dal primo giorno: rende sicuri i retry (c'è una guida dedicata).

curl

curl -X POST https://sms-jet.com/api/v1/sms/transactional \
  -H "Authorization: Bearer gsms_…" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+393331234567",
    "text": "Your verification code is 123456",
    "sender_type": "system"
  }'

La stessa chiamata in Node

Node 22 ha fetch nativo: niente da installare. La chiamata è identica, cambia solo la sintassi:

Node 22

// Node 22 — native fetch, no dependencies
const response = await fetch('https://sms-jet.com/api/v1/sms/transactional', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gsms_…',
    'Idempotency-Key': 'order-1042',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+393331234567',
    text: 'Your verification code is 123456',
    sender_type: 'system',
  }),
})

const message = await response.json()
console.log(message.status, message.parts, message.price_eur)
// accepted 1 0.0298

Leggere la risposta

La risposta è sincrona: quando arriva, l'esito è già deciso e l'addebito già applicato. I campi da guardare: status ("accepted" = preso in carico per la consegna), parts (le parti fatturate), price_eur (il costo totale).

price_eur è una stringa con 4 decimali, non un numero: è denaro, e i float arrotondano. Confrontala e salvala come stringa o con un tipo decimale.

Un errore arriva come JSON con un campo code stabile su cui fare branching: saldo insufficiente è INSUFFICIENT_BALANCE (402), un corpo malformato VALIDATION_FAILED (400), una chiave sbagliata INVALID_API_KEY (401).

Risposta

200 OK

{
  "id": "0198f3c1-6b2a-7c41-9f0e-2d4a8b5c1e73",
  "status": "accepted",
  "encoding": "gsm7",
  "parts": 1,
  "price_eur": "0.0298"
}

Dove ritrovare il messaggio

Ogni invio compare nel registro messaggi della dashboard: destinatario, parti, prezzo e stato registrati al momento dell'invio. L'id nella risposta è lo stesso che vedi nel registro.

Per controllare lo stato via API, GET /api/v1/sms/:id restituisce lo stesso oggetto della risposta di invio, con lo stato aggiornato.