Passa al contenuto principale

Panoramica API

Questa pagina illustra le convenzioni principali dell'API REST del Qlara Platform: autenticazione, identificazione delle richieste, limiti di frequenza, paginazione, gestione degli errori e formato delle risposte.

Base URL​

Tutte le richieste API vengono effettuate verso il seguente base URL:

https://api.qlara.ai/api

Ogni percorso documentato in questo portale è relativo a questo base URL. Ad esempio, l'endpoint di invio SMS è:

https://api.qlara.ai/api/message-server/sms/send

Autenticazione​

Ogni richiesta deve includere credenziali valide. L'API supporta due metodi di autenticazione.

API Key (consigliato)​

Passa la tua API Key nell'header X-Api-Key:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Basic Auth​

Passa le credenziali come stringa username:password codificata in Base64 nell'header Authorization:

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts" \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Accept: application/json"
Suggerimento

L'autenticazione tramite API Key è consigliata per tutte le nuove integrazioni. È più semplice, più facile da ruotare e non espone la password del tuo account.

Attenzione

Non esporre mai la tua API Key o le credenziali in codice lato client, repository pubblici o URL. Inviale sempre tramite header su HTTPS.

Identificazione della Richiesta​

Ogni risposta include l'header X-Request-Id:

X-Request-Id: 16d9b2a9ca97da0d8c4c4ea2ae689017

Il valore è l'identificativo di traccia che la piattaforma ha assegnato alla richiesta, la stessa chiave che indicizza ogni riga di log prodotta dalla richiesta. Registralo dalla tua parte e citalo quando contatti il supporto per una chiamata specifica. È presente anche sulle risposte di errore, 401 e 500 inclusi, cioè quando serve di più.

Limiti di Frequenza​

Gli endpoint di messaggistica sotto /api/message-server/ applicano un limite di richieste al secondo per account, definito dal tuo piano di abbonamento. Quando lo superi, l'API risponde 429 Too Many Requests con corpo vuoto e l'header Retry-After: 1: attendi un secondo e riprova.

Gli endpoint Qlara Platform sotto /api/partner-gateway/v1/ al momento non applicano alcun limite di frequenza e non rispondono 429.

Nessuna delle due famiglie di endpoint restituisce header X-RateLimit-*. Per lo stato di consegna, preferisci i webhook a cicli di polling stretti: vedi la guida ai Webhook.

Paginazione​

Gli endpoint che restituiscono collezioni (contatti, liste contatti, campagne, esportazioni, media, agenti RCS, numeri WhatsApp, storico messaggi) sono paginati per pagina: page seleziona la pagina, contando da 0, e limit ne imposta la dimensione.

ParametroTipoDefaultDescrizione
pageinteger0Indice della pagina. La prima pagina è la 0.
limitinteger10 o 20, a seconda dell'endpointDimensione della pagina. Dove è imposto un massimo, è 1000. Verifica il riferimento dell'endpoint.

Richiesta di esempio​

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/contacts?page=2&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Risposta di esempio​

{
  "data": [
    {
      "id": 202365451,
      "fullName": "Marco Rossi",
      "phoneNumbers": ["+393401234567"],
      "createdAt": "2026-01-15 10:30:00.000+0000"
    },
    {
      "id": 202365452,
      "fullName": "Giulia Bianchi",
      "phoneNumbers": ["+393409876543"],
      "createdAt": "2026-01-16 14:20:00.000+0000"
    }
  ],
  "page": 2,
  "limit": 20,
  "totalCount": 1250,
  "totalPages": 63
}

Per iterare tutti i record, incrementa page da 0 a totalPages - 1.

Alcune collezioni hanno una forma diversa:

  • GET /partner-gateway/v1/campaigns avvolge lo stesso oggetto pagina in un involucro JSend: { "status": "success", "data": { "data": [...], "page": 0, "limit": 20, "totalCount": 12, "totalPages": 1 } }.
  • GET /partner-gateway/v1/messages/history e GET /partner-gateway/v1/messages/status restituiscono un array JSON semplice. Lo storico accetta comunque page e limit: sei sull'ultima pagina quando ne ricevi una con meno elementi di limit.
  • GET /partner-gateway/v1/inbox/conversations e GET /partner-gateway/v1/socials restituiscono un array JSON semplice senza paginazione. Restringi l'inbox con i suoi filtri (unreadOnly, channelIds, dateFrom, section) e ordinala con orderBy.

Gestione degli Errori​

L'API utilizza codici di stato HTTP standard. Gli endpoint Qlara Platform restituiscono un corpo JSend.

Formato della risposta di errore​

Una richiesta rifiutata (4xx) è un fail, e data ne spiega il motivo. Nella maggior parte dei casi è una stringa; è una lista di messaggi quando fallisce la validazione del corpo della richiesta:

{
  "status": "fail",
  "data": "Invalid 'from': '27/08/2026'. Accepted formats: yyyy-MM-dd (a whole day, UTC), yyyy-MM-ddTHH:mm:ss (UTC) or ISO-8601 with an offset such as 2025-01-15T00:00:00+01:00 or 2025-01-15T00:00:00Z"
}

Un errore dalla nostra parte (5xx) è un error:

{
  "status": "error",
  "message": "Something bad happened. Please try again!"
}

Due eccezioni a questa forma: una API Key mancante o non valida risponde 401 con {"error": "Invalid API Key"} sugli endpoint della Qlara Platform e con un corpo vuoto sugli endpoint di messaggistica, e un 429 dagli endpoint di messaggistica non ha corpo.

Codici di stato HTTP​

CodiceSignificatoDescrizione
400Bad RequestIl corpo della richiesta o i parametri della query non sono validi. data indica il parametro e, per date ed enumerazioni, i valori accettati.
401UnauthorizedX-Api-Key mancante o non valida, oppure una chiave che non include l'operazione chiamata.
403ForbiddenLa richiesta non è consentita per il tuo account, ad esempio un mittente che la tua azienda non possiede.
404Not FoundL'endpoint o la risorsa non esiste per il tuo account. Una lettura di stato risponde 404 quando l'id del messaggio è sconosciuto per il canale indicato.
409ConflictLa risorsa esiste già, ad esempio un webhook già configurato.
422Unprocessable ContentSolo endpoint di invio (POST /partner-gateway/v1/sms/messages, rcs/messages, whatsapp/messages): la piattaforma di messaggistica ha rifiutato il messaggio. Il corpo fail ne riporta i motivi. Se un canale di fallback ha accettato il messaggio, la risposta resta 202.
429Too Many RequestsSolo endpoint di messaggistica: superato il limite di richieste al secondo per account. Rispetta Retry-After.
500Internal Server ErrorErrore imprevisto dalla nostra parte. Riprova con backoff esponenziale e, se persiste, cita l'X-Request-Id al supporto.
502Bad GatewayIl provider del canale a monte ha restituito un errore.

Strategia di retry​

Per errori transienti (429 e 5xx), implementa un backoff esponenziale con jitter:

  1. Primo retry: attendi 1 secondo
  2. Secondo retry: attendi 2 secondi
  3. Terzo retry: attendi 4 secondi
  4. Massimo retry: 5 tentativi
  5. Aggiungi jitter: aggiungi un ritardo casuale di 0--500ms a ogni tempo di attesa per evitare il thundering herd

Non riprovare gli errori 400, 401, 403, 404 o 422. Questi indicano un problema con la tua richiesta che deve essere corretto prima di riprovare: un messaggio rifiutato con 422 viene rifiutato di nuovo se lo invii invariato.

Formato delle Risposte​

Tutte le risposte API utilizzano JSON con codifica UTF-8.

Header di risposta comuni​

HeaderValoreDescrizione
Content-Typeapplication/json;charset=UTF-8Formato del corpo della risposta
X-Request-Id16d9b2a9ca97da0d8c4c4ea2ae689017Identificativo di traccia della richiesta, da citare al supporto
Cache-Controlno-cache, no-store, must-revalidateLe risposte non devono essere messe in cache

Risposte con successo​

  • Singola risorsa: l'oggetto risorsa al livello principale.
  • Collezioni: l'oggetto pagina descritto in Paginazione, oppure un array semplice per gli endpoint lì elencati.
  • Creazione: 201 Created con la risorsa creata.
  • Aggiornamento: 200 OK con la risorsa aggiornata.
  • Eliminazione: 204 No Content per la maggior parte delle risorse. DELETE /partner-gateway/v1/contacts e DELETE /partner-gateway/v1/contacts/list rispondono 200 OK con true, e ricevono gli id da eliminare nel query parameter ids, separati da virgola, non nel corpo.
  • Operazioni asincrone (esportazioni): 202 Accepted con corpo vuoto. Interroga GET /partner-gateway/v1/exports finché l'esportazione mostra isAvailableForDownload: true, poi chiama GET /partner-gateway/v1/exports/{exportId} per l'URL di download.

Timestamp​

Sono in uso due formati, a seconda della risorsa:

DoveFormatoEsempio
Stato di consegna e storico messaggi (sendDate, deliveryDate, readDate)ISO 8601 con offset2026-09-03T08:28:52Z
Contatti, liste, campagne, esportazioni, inbox (createdAt, lastMessageDate, ...) e scheduledDate negli inviiyyyy-MM-dd HH:mm:ss.SSSZ2026-09-01 10:17:53.200+0000

Parametri data nella query​

from e to su GET /partner-gateway/v1/messages/history accettano:

FormaEsempioInterpretazione
Solo data2026-08-27L'intera giornata UTC: 00:00:00Z come from, 23:59:59Z come to
Data-ora senza offset2026-08-27T10:30:00UTC
ISO 8601 con offset2026-08-27T00:00:00%2B01:00, 2026-08-27T23:59:59ZCosì com'è

Codifica il + dell'offset come %2B: in una query string un + non codificato viene decodificato come spazio. Un valore in qualsiasi altra forma riceve 400 con l'elenco dei formati accettati.

Stati di consegna​

GET /partner-gateway/v1/messages/status e GET /partner-gateway/v1/messages/history riportano un deliveryStatus normalizzato (ACCEPTED, REJECTED, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ERROR, DISABLED, UNSUPPORTED, CONVERSATION_CLOSED o UNKNOWN) con una deliveryStatusDescription in minuscolo. Il webhook di stato consegna invia lo stesso stato come statusCode numerico. La tabella Delivery Statuses nel riferimento API associa ogni codice al suo stato ed elenca i canali che lo usano.

Versionamento​

La versione dell'API è inclusa nel percorso URL per gli endpoint di Qlara Platform:

/api/partner-gateway/v1/...

Gli endpoint specifici per canale (SMS, RCS, WhatsApp) utilizzano un percorso piatto senza versione esplicita:

/api/message-server/sms/send
/api/message-server/rcs/send
/api/message-server/whatsapp/send

Quando vengono introdotte modifiche non retrocompatibili, una nuova versione (es. v2) verrà pubblicata sotto un nuovo percorso. Le versioni esistenti rimangono disponibili per un periodo di deprecazione di almeno 6 mesi, durante il quale entrambe le versioni funzionano in parallelo.

Informazioni

Iscriviti al changelog dell'API e alle notifiche del tuo account per essere informato sulle prossime deprecazioni e nuove versioni.

Prossimi passi​