UC-001 — Invio SMS Singolo

Campo	Valore
ID	UC-001
Obiettivo	Inviare un SMS singolo e verificarne la consegna
Canale	SMS
Complessità	Base
Tempo stimato	10 minuti
API coinvolte	POST /api/message-server/sms/send, GET /api/partner-gateway/v1/messages/status/{customerMessageId}

Scenari reali

• E-commerce — Conferma ordine: TechStore invia un SMS al cliente per confermare la ricezione dell'ordine e comunicare il codice di tracking.
• Clinica — Promemoria appuntamento: Lo Studio Dentistico Bianchi ricorda al paziente l'appuntamento del giorno successivo.
• Marketing — Promo flash: FashionOutlet lancia una promozione lampo con scadenza a 24 ore, inviando un SMS personalizzato.

Flusso del messaggio

Il diagramma illustra il ciclo completo: il tuo server invia la richiesta, il gateway instrada il messaggio verso l'operatore, e lo stato di consegna torna a te tramite polling o webhook.

Step 1 — Invia l'SMS

Invoca l'endpoint di invio con destinatario, mittente e testo del messaggio.

curl -X POST https://api.qlara.ai/api/message-server/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "sender": "TechStore",
    "body": "Ciao Marco, il tuo ordine #ORD-20260409 e stato confermato! Consegna prevista: 11 aprile. Tracking: https://techstore.it/t/TRK789",
    "campaignId": "conferma-ordini-2026-04",
    "enableNotification": true
  }'

Response — Messaggio accettato

{
  "messageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "simulation": false,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1,
      "reasons": []
    }
  }
}

Salva il messageId

Il campo messageId e l'identificativo univoco che userai per verificare lo stato di consegna. Salvalo nel tuo database associato all'ordine.

Dietro le quinte — Cosa succede dopo l'invio

1. Validazione: Il gateway verifica API Key, formato del destinatario e lunghezza del messaggio.
2. Routing: Il Message Router identifica l'operatore del destinatario (+3934x = Vodafone IT) e seleziona la rotta con miglior rapporto qualita/costo.
3. Encoding: Il testo viene analizzato per determinare se usare GSM-7 (160 char/SMS) o UCS-2 Unicode (70 char/SMS). Caratteri come e (senza accento) rientrano in GSM-7.
4. Concatenazione: Se il messaggio supera la soglia, viene suddiviso in più parti (multipart SMS) con header UDH automatico.
5. Consegna: Il messaggio transita sulla rete SMSC dell'operatore fino al dispositivo.
6. DLR (Delivery Report): L'operatore restituisce il report di consegna che il gateway traduce in uno stato finale: DELIVERED (3) se l'SMS è arrivato al telefono, altrimenti REJECTED (2), EXPIRED (4), DELETED (5) o UNDELIVERABLE (6). Finché il report non arriva, il messaggio resta ACCEPTED (1).

Step 2 — Verifica stato di consegna (Polling)

Dopo qualche secondo, interroga lo stato di consegna usando il messageId ricevuto.

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/messages/status/f47ac10b-58cc-4372-a567-0e02b2c3d479?channel=SMS" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Consegnato

{
  "customerMessageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "channel": "SMS",
  "destination": "+393471234567",
  "deliveryStatus": "DELIVERED",
  "deliveryStatusDescription": "delivered",
  "sendDate": "2026-04-09T10:15:00+02:00",
  "deliveryDate": "2026-04-09T10:15:03+02:00",
  "readDate": null
}

Dietro le quinte — Tabella status codes

Status	Codice	Descrizione
ACCEPTED	1	Affidato all'operatore, in attesa del report di consegna. Non finale
REJECTED	2	L'operatore ha rifiutato il messaggio. Finale
DELIVERED	3	Messaggio consegnato al dispositivo. Finale
EXPIRED	4	Non consegnato entro il periodo di validità. Finale
DELETED	5	Annullato prima della consegna. Finale
UNDELIVERABLE	6	Il destinatario non può riceverlo (non raggiungibile o numero non valido). Finale
UNKNOWN	0	Nessuno stato disponibile per il messaggio

Il codice è lo statusCode numerico inviato dal webhook di consegna; l'API di polling restituisce il nome in deliveryStatus e la descrizione in minuscolo (delivered, undeliverable…) in deliveryStatusDescription.

Il polling e utile per verifiche puntuali. Per monitoraggio real-time su volumi elevati, usa i Webhook.

Step 3 — Ricevi il webhook di consegna

Se hai configurato un endpoint webhook (vedi guida Webhook), riceverai una notifica HTTP POST automatica:

{
  "eventType": "DELIVERY",
  "channel": "SMS",
  "messageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "destination": "+393471234567",
  "statusCode": 3,
  "description": "delivered",
  "eventDate": "2026-04-09T10:15:03+02:00",
  "price": 0.035,
  "totalParts": 1,
  "numPart": 1
}

messageId è l'identificativo che hai ricevuto al momento dell'invio. Per un SMS multipart ricevi un evento per ciascuna parte (numPart da 1 a totalParts).

Webhook vs Polling

Il webhook e il metodo consigliato per produzione: ricevi la notifica in tempo reale senza effettuare chiamate ripetute. Configura il tuo endpoint nella sezione Webhook della piattaforma.

Errori comuni

401 Unauthorized — API Key mancante o non valida

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e che la chiave sia attiva nel pannello della piattaforma.

accepted: false — Messaggio rifiutato

{
  "messageId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "simulation": false,
  "results": {
    "sms": {
      "accepted": false,
      "unicode": false,
      "parts": 0,
      "reasons": ["Invalid destination number format"]
    }
  }
}

Soluzione: Il numero deve essere in formato internazionale completo (es. +393471234567). Verifica di non aver omesso il prefisso +39.

Simulation mode attivo

{
  "messageId": "a2c4e6f8-1234-5678-9abc-def012345678",
  "simulation": true,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1,
      "reasons": []
    }
  }
}

Soluzione: Il campo simulation: true nella response indica che il messaggio non e stato realmente inviato. Rimuovi "simulation": true dal body della request per l'invio effettivo.

Risultato atteso

Step	Azione	Risultato
1	POST /sms/send	messageId restituito, accepted: true
2	GET /messages/status/{id}?channel=SMS	deliveryStatus: "DELIVERED"
3	Webhook ricevuto	statusCode: 3, eventType: "DELIVERY"

Esempio completo end-to-end

Ecco lo scenario TechStore completo, dall'invio alla verifica:

# 1. Invia l'SMS di conferma ordine
MESSAGE_ID=$(curl -s -X POST https://api.qlara.ai/api/message-server/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "sender": "TechStore",
    "body": "Ciao Marco, ordine #ORD-20260409 confermato! Tracking: https://techstore.it/t/TRK789",
    "enableNotification": true
  }' | jq -r '.messageId')

echo "Message ID: $MESSAGE_ID"

# 2. Attendi qualche secondo e verifica la consegna
sleep 5

curl -s -X GET "https://api.qlara.ai/api/partner-gateway/v1/messages/status/${MESSAGE_ID}?channel=SMS" \
  -H "X-Api-Key: YOUR_API_KEY" | jq .

Varianti

Invio con placeholder

Usa i placeholder per personalizzare il testo senza costruire stringhe lato server:

curl -X POST https://api.qlara.ai/api/message-server/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393481234567",
    "sender": "TechStore",
    "body": "Ciao {nome}, il tuo ordine {ordine} e pronto per il ritiro presso {negozio}.",
    "placeholders": {
      "nome": "Giulia",
      "ordine": "#ORD-20260410",
      "negozio": "TechStore Milano Centrale"
    },
    "enableNotification": true
  }'

Invio schedulato

Programma l'invio per una data e ora futura:

curl -X POST https://api.qlara.ai/api/message-server/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "sender": "StBianchi",
    "body": "Gentile Marco, le ricordiamo l appuntamento di domani 10 aprile alle ore 15:30. Studio Dentistico Bianchi - Tel. 02 1234567",
    "scheduledDate": "2026-04-10 08:00:00.000+0200"
  }'

Formato scheduledDate

Il formato richiesto e yyyy-MM-dd HH:mm:ss.SSSZ, ad esempio 2026-04-10 08:00:00.000+0200 per le 8:00 CEST.

Prossimi passi

• UC-002 — Invio RCS Rich Card: Invia messaggi ricchi con immagini e bottoni interattivi
• UC-003 — Invio WhatsApp Template: Usa template approvati da Meta per messaggi WhatsApp
• UC-004 — Verifica Delivery Status: Approfondisci il polling batch e il confronto con i webhook
• Guida SMS Universal: Documentazione completa del canale SMS
• Guida Autenticazione: Dettagli su API Key e Basic Auth