Qlara Platform API
Panoramica
La Qlara Platform API è un'interfaccia REST unificata che consente di:
- Monitorare la consegna dei messaggi inviati tramite SMS, RCS e WhatsApp - interrogando lo stato per messaggio o configurando un webhook
- Gestire contatti e liste utilizzati come destinatari delle campagne
- Creare e gestire campagne di invio massivo sui canali SMS, RCS e WhatsApp
- Consultare ed esportare lo storico completo dei messaggi inviati
- Gestire conversazioni bidirezionali tramite la casella di posta
- Caricare file multimediali (immagini, video) riutilizzabili nelle campagne e conversazioni
- Collegare profili social (Facebook, Instagram, LinkedIn, Google, TikTok)
Nota: L'invio dei messaggi (SMS, RCS, WhatsApp) è gestito da servizi upstream separati. Questa API fornisce il monitoraggio delle consegne, la gestione campagne, la gestione contatti e la gestione conversazioni.
Autenticazione
Ogni richiesta deve includere una chiave API valida nell'header HTTP X-API-Key:
X-API-Key: <la-tua-chiave-api>
Le chiavi API sono associate al tuo account. Usa la sezione Chiavi API per crearle e gestirle.
Identificazione della Richiesta
Ogni risposta include l'header X-Request-Id con l'identificativo che la piattaforma ha assegnato alla richiesta:
X-Request-Id: 16d9b2a9ca97da0d8c4c4ea2ae689017
Citalo quando contatti il supporto per una chiamata specifica: è la chiave con cui vengono cercati i nostri log.
Canali Supportati
| Canale | Chiave | Operazioni Disponibili |
|---|---|---|
| SMS | SMS | Monitoraggio consegna, storico, campagne |
| RCS | RCS | Monitoraggio consegna, storico, campagne |
WHATSAPP | Monitoraggio consegna, storico, campagne |
Stati di Consegna
Tutti gli endpoint di monitoraggio restituiscono lo stesso deliveryStatus normalizzato, e il
webhook di consegna invia il codice numerico corrispondente. Entrambi provengono da un'unica tabella:
| Codice | deliveryStatus | deliveryStatusDescription | Canali | Significato |
|---|---|---|---|---|
| 1 | ACCEPTED | accepted | SMS | Accettato e inoltrato all'operatore; nessuna notifica di consegna ancora ricevuta. Non definitivo. |
| 2 | REJECTED | rejected | SMS | L'operatore ha rifiutato il messaggio. Definitivo. |
| 3 | DELIVERED | delivered | SMS, RCS, WhatsApp | L'operatore ha confermato la consegna sul dispositivo. Definitivo. |
| 4 | EXPIRED | expired | SMS, RCS, WhatsApp | Non consegnato entro la finestra di validità; l'operatore lo ha scartato. Definitivo. |
| 5 | DELETED | deleted | SMS | Il messaggio è stato annullato prima della consegna. Definitivo. |
| 6 | UNDELIVERABLE | undeliverable | SMS | La destinazione non può ricevere il messaggio (numero irraggiungibile o non valido). Definitivo. |
| 9 | ERROR | general error | RCS, WhatsApp | Consegna fallita. Definitivo. |
| 10 | DISABLED | disabled | RCS, WhatsApp | Il destinatario ha il canale disattivato. Definitivo. |
| 11 | UNSUPPORTED | unsupported | RCS, WhatsApp | Il dispositivo o il numero del destinatario non supporta il canale. Definitivo. |
| 12 | CONVERSATION_CLOSED | conversation closed | La finestra di assistenza di 24 ore era chiusa. Definitivo. | |
| 0 | UNKNOWN | unknown | SMS, RCS, WhatsApp | La piattaforma non ha informazioni di stato per questo messaggio. |
Un messaggio inviato ma non ancora confermato risulta ACCEPTED su SMS e UNKNOWN su RCS e
WhatsApp, che non hanno un codice intermedio proprio. deliveryDate viene valorizzata solo quando
arriva la notifica di consegna, quindi un messaggio DELIVERED la riporta.
Il webhook di consegna trasporta gli stessi numeri, quindi un'unica tabella permette di leggere sia
l'API sia il callback. Il callback registrato con POST /partner-gateway/v1/webhooks/delivery-status
invia il codice come statusCode e la terza colonna come description; il callback di consegna
della piattaforma SMS invia lo stesso numero come DELIVERY_STATUS.
Flussi di Lavoro Principali
1 - Monitorare lo stato di consegna di un messaggio
GET /partner-gateway/v1/messages/status/{customerMessageId}?channel=SMS
-> 200 { deliveryStatus: "DELIVERED" }
Puoi anche consultare lo stato dei messaggi RCS e WhatsApp tramite i rispettivi endpoint dedicati.
2 - Ricevere eventi di consegna tramite webhook (senza polling)
POST /partner-gateway/v1/webhooks/delivery-status
{ "callbackUrl": "https://il-tuo-server.example.com/webhook" }
La piattaforma invierà automaticamente gli eventi di consegna a quell'URL.
3 - Eseguire una campagna massiva
POST /partner-gateway/v1/campaigns -> crea campagna (bozza)
PUT /partner-gateway/v1/campaigns/{id}/confirm -> pianifica e invia
GET /partner-gateway/v1/campaigns/stats -> statistiche di consegna
4 - Esportare lo storico messaggi
POST /partner-gateway/v1/messages/history/export -> 202 Accepted
GET /partner-gateway/v1/exports -> interroga fino a isAvailableForDownload = true
GET /partner-gateway/v1/exports/{exportId} -> recupera URL di download
Operazioni Asincrone
Le operazioni che possono richiedere molto tempo (invio campagne, esportazione dati) restituiscono
202 Accepted immediatamente e vengono elaborate in background.
Usa l'endpoint di lista o stato corrispondente per monitorare l'avanzamento.
Codici di Stato HTTP Comuni
| Codice | Significato |
|---|---|
| 200 | OK - richiesta completata con successo |
| 201 | Created - risorsa creata con successo |
| 202 | Accepted - operazione asincrona accodata |
| 204 | No Content - operazione riuscita senza corpo di risposta |
| 400 | Bad Request - errore di validazione; ispeziona il corpo della risposta per i dettagli |
| 401 | Non autorizzato - X-API-Key mancante o non valida |
| 404 | Not Found - la risorsa richiesta non esiste |
| 409 | Conflict - la risorsa esiste già (es. un webhook è già configurato) |
| 500 | Internal Server Error |
| 502 | Bad Gateway - il provider del canale a monte ha restituito un errore |
Authentication
- API Key: ApiKeyAuth
Autenticazione
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |