SMS Legacy API

Cos'è SMS Legacy

SMS Legacy è il formato retrocompatibile per l'invio di messaggi SMS tramite la piattaforma Qlara. A differenza del formato Universal (un messaggio per richiesta), il formato Legacy consente di inviare più messaggi a più destinatari in una singola richiesta HTTP.

Questo formato è pensato per chi ha già un'integrazione esistente basata su questo schema o per chi necessita di inviare lo stesso messaggio a liste di destinatari in un'unica chiamata. Per le nuove integrazioni, si consiglia il formato SMS Universal.

---

Endpoint

Invio messaggi

POST https://lora-api.agiletelecom.com/api/services/sms/send

Verifica credito

GET https://lora-api.agiletelecom.com/api/services/sms/credit

Content-Type: application/json

Autenticazione: API Key (X-Api-Key) oppure Basic Auth (Authorization: Basic)

---

Campi della richiesta di invio

Campi globali

Campo	Tipo	Obbligatorio	Default	Descrizione
globalId	string	No	(auto)	Identificativo globale della richiesta per raggruppare tutti i messaggi inviati nella stessa chiamata. Se non fornito, viene generato automaticamente
enableConcatenated	boolean	No	true	Se true, i messaggi lunghi vengono automaticamente concatenati in più parti SMS. Se false, il testo viene troncato alla lunghezza massima di una singola parte
enableUnicode	boolean	No	true	Se true, i messaggi con caratteri non GSM-7 vengono inviati in codifica Unicode. Se false, i caratteri non supportati vengono rimossi o sostituiti
enableDelivery	boolean	No	true	Se true, abilita le notifiche di consegna (delivery notification) verso il tuo URL di callback
simulation	boolean	No	false	Se true, i messaggi vengono elaborati e validati ma non inviati fisicamente. Utile per test
skipRcsOverride	boolean	No	false	Se true, gli SMS vengono inviati direttamente senza passare per un eventuale override RCS configurato a livello di account
messages	array	Sì	–	Lista di messaggi da inviare. Ogni elemento descrive un messaggio con i propri destinatari (vedi sotto)

Campi dell'oggetto messages[]

Ogni elemento dell'array messages rappresenta un messaggio con il suo testo e la lista dei destinatari.

Campo	Tipo	Obbligatorio	Descrizione
destinations	array[string]	Sì	Lista di numeri destinatari in formato internazionale (es. ["+393401234567", "+393409876543"])
ids	array[string]	No	Lista di ID personalizzati per ogni destinatario, nello stesso ordine di destinations. Utile per tracciamento individuale
sender	string	Sì	Mittente del messaggio. Alfanumerico (max 11 caratteri) o numerico
body	string	Sì*	Testo del messaggio. *Mutuamente esclusivo con hexBody
hexBody	string	No*	Testo del messaggio in formato esadecimale. Usato per contenuti binari. *Mutuamente esclusivo con body
udhData	string	No	User Data Header in formato esadecimale. Usato per messaggi binari o concatenazione manuale
scheduling	string	No	Data e ora di invio programmato. Formato: yyyy-MM-dd HH:mm:ss.SSSZ (es. 2025-10-01 09:00:00.000+0000)

---

Risposta di invio

{
    "globalId": "d4f5e6a7-b8c9-0123-4567-890abcdef012",
    "processedMessages": 1,
    "processedSmsParts": 3,
    "credit": 1247.50
}

Campo	Tipo	Descrizione
globalId	string	ID globale della richiesta (quello fornito o generato automaticamente)
processedMessages	integer	Numero totale di messaggi processati (un messaggio per ogni destinatario)
processedSmsParts	integer	Numero totale di parti SMS generate (considera la concatenazione)
credit	number	Credito residuo dopo l'invio

---

Endpoint verifica credito

GET https://lora-api.agiletelecom.com/api/services/sms/credit

Non richiede body. Restituisce il saldo credito disponibile per l'account.

Risposta:

{
    "credit": 1247.50
}

Campo	Tipo	Descrizione
credit	number	Credito SMS disponibile per il tuo account

---

Confronto: Legacy vs Universal

Caratteristica	SMS Legacy	SMS Universal
Messaggi per richiesta	Multipli	Uno
Destinatari per messaggio	Multipli	Uno
Placeholder nel testo	No	Sì
Modalità simulazione	Sì	Sì
Invio programmato	Sì (scheduling)	Sì (scheduledDate)
Notifiche di consegna	Sì (enableDelivery)	Sì (enableNotification)
ID messaggio personalizzato	Sì (ids[])	Sì (messageId)
Controllo codifica Unicode	Sì (enableUnicode)	Automatica
Controllo concatenazione	Sì (enableConcatenated)	Automatica
Verifica credito	Sì (endpoint dedicato)	No
Formato consigliato	Per integrazioni esistenti	Per nuove integrazioni

---

Esempi

1. Invio multi-destinatario

Invio dello stesso messaggio a tre destinatari con ID personalizzati per il tracciamento:

{
    "globalId": "campagna-marzo-2025",
    "enableConcatenated": true,
    "enableUnicode": true,
    "enableDelivery": true,
    "simulation": false,
    "messages": [
        {
            "destinations": [
                "+393401234567",
                "+393409876543",
                "+393405551234"
            ],
            "ids": [
                "msg-001",
                "msg-002",
                "msg-003"
            ],
            "sender": "MyBrand",
            "body": "Ciao! Approfitta della promozione: 20% di sconto su tutto il catalogo fino al 31 marzo. Visita il nostro sito!"
        }
    ]
}

Risposta:

{
    "globalId": "campagna-marzo-2025",
    "processedMessages": 3,
    "processedSmsParts": 3,
    "credit": 1244.50
}

2. Verifica credito

Per controllare il credito SMS disponibile prima di un invio massivo:

GET /api/services/sms/credit HTTP/1.1
Host: lora-api.agiletelecom.com
X-Api-Key: YOUR_API_KEY

Risposta:

{
    "credit": 1244.50
}

---

Codici di errore

Codice HTTP	Significato	Cosa fare
200	Richiesta elaborata	Verifica processedMessages e processedSmsParts nella risposta
400	Richiesta non valida	Verifica i campi obbligatori e il formato dei dati
401	Non autenticato	Verifica la tua API Key o le credenziali Basic Auth
403	Accesso negato	IP non in whitelist o risorsa non autorizzata
422	Entità non processabile	Dati sintatticamente corretti ma semanticamente non validi
429	Troppe richieste	Hai superato il rate limit. Riprova dopo il periodo indicato
500	Errore interno del server	Riprova più tardi. Se il problema persiste, contatta il supporto