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://lora-api.agiletelecom.com/api

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

https://lora-api.agiletelecom.com/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://lora-api.agiletelecom.com/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://lora-api.agiletelecom.com/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.

Parametro	Tipo	Default	Descrizione
page	integer	0	Indice della pagina. La prima pagina è la 0.
limit	integer	10 o 20, a seconda dell'endpoint	Dimensione della pagina. Dove è imposto un massimo, è 1000. Verifica il riferimento dell'endpoint.

Richiesta di esempio

curl -X GET "https://lora-api.agiletelecom.com/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"}, e un 429 dagli endpoint di messaggistica non ha corpo.

Codici di stato HTTP

Codice	Significato	Descrizione
400	Bad Request	Il corpo della richiesta o i parametri della query non sono validi. data indica il parametro e, per date ed enumerazioni, i valori accettati.
401	Unauthorized	X-Api-Key mancante o non valida, oppure una chiave che non include l'operazione chiamata.
403	Forbidden	La richiesta non è consentita per il tuo account, ad esempio un mittente che la tua azienda non possiede.
404	Not Found	L'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.
409	Conflict	La risorsa esiste già, ad esempio un webhook già configurato.
429	Too Many Requests	Solo endpoint di messaggistica: superato il limite di richieste al secondo per account. Rispetta Retry-After.
500	Internal Server Error	Errore imprevisto dalla nostra parte. Riprova con backoff esponenziale e, se persiste, cita l'X-Request-Id al supporto.
502	Bad Gateway	Il 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 o 404. Questi indicano un problema con la tua richiesta che deve essere corretto prima di riprovare.

Formato delle Risposte

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

Header di risposta comuni

Header	Valore	Descrizione
Content-Type	application/json;charset=UTF-8	Formato del corpo della risposta
X-Request-Id	16d9b2a9ca97da0d8c4c4ea2ae689017	Identificativo di traccia della richiesta, da citare al supporto
Cache-Control	no-cache, no-store, must-revalidate	Le 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:

Dove	Formato	Esempio
Stato di consegna e storico messaggi (sendDate, deliveryDate, readDate)	ISO 8601 con offset	2026-09-03T08:28:52Z
Contatti, liste, campagne, esportazioni, inbox (createdAt, lastMessageDate, ...) e scheduledDate negli invii	yyyy-MM-dd HH:mm:ss.SSSZ	2026-09-01 10:17:53.200+0000

Parametri data nella query

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

Forma	Esempio	Interpretazione
Solo data	2026-08-27	L'intera giornata UTC: 00:00:00Z come from, 23:59:59Z come to
Data-ora senza offset	2026-08-27T10:30:00	UTC
ISO 8601 con offset	2026-08-27T00:00:00%2B01:00, 2026-08-27T23:59:59Z	Così 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.

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

• Quick Start -- Invia il tuo primo messaggio in 3 minuti.
• Guida all'autenticazione -- Configurazione dettagliata dell'autenticazione con whitelist IP.
• Riferimento API -- Documentazione completa degli endpoint.
• Collezioni Postman -- Collezioni di richieste pronte all'uso.