Integrazioni
Integra ciò che hai già.
Capacità documentate della piattaforma per messaggistica, dati, finanza e account. Specifiche e percorsi delle chiamate vengono forniti con la documentazione di installazione.
Invio SMS via HTTP
Un’API JSON, accanto a SMPP.
I clienti inviano via SMPP o via HTTP(S): i due canali condividono instradamento, tariffazione, ricevute e fatturazione. Verso i fornitori la terminazione resta SMPP o SS7.
SMPPSMPP 3.4 e SMPP su TLS
HTTP(S)POST /v1/sms con JSON
Un solo ciclorouting, ricevuta, billing, fattura
FornitoriSMPP o SS7 su SIGTRAN
Le chiamate descritte qui appartengono alle API dell’installazione Auvia del cliente, non a questo sito. L’indirizzo di base dipende dall’installazione.
Invio: POST /v1/sms
- AutenticazioneHeader Authorization: Bearer con la chiave API di un account, abilitata al permesso sms.send. Per ogni chiave si può impostare una lista di IP ammessi, facoltativa.
- IdempotenzaCon l’header facoltativo Idempotency-Key, la stessa richiesta ricevuta due volte entro 24 ore restituisce la stessa risposta senza inviare di nuovo.
- Risposta 202Il messaggio è accettato, non consegnato. La consegna si conosce da ricevuta di consegna e consultazione.
- LottiFino a 1.000 destinatari per richiesta. Ogni destinatario ha il proprio esito: un numero non valido non fa fallire gli altri.
- Rifiuto totaleSe tutti i destinatari vengono rifiutati, la risposta è 400 o 402, con i motivi.
Campi della richiesta
- frommittente del messaggio
- toarray di destinatari, fino a 1.000 per richiesta
- texttesto del messaggio
- prioritypriorità; l’esempio documentato usa otp
- validity_minutesvalidità del messaggio, in minuti
- client_refriferimento del cliente, restituito nei webhook
- dlrrichiesta della ricevuta di consegna
- encodingfacoltativo: auto (predefinito), gsm7 o ucs2
- scheduled_atfacoltativo: invio programmato
POST /v1/sms
Authorization: Bearer <CHIAVE_API>
Idempotency-Key: <VALORE_UNIVOCO>
Content-Type: application/json
{
"from": "MITTENTE",
"to": ["<MSISDN_DESTINATARIO>"],
"text": "Il tuo codice è 482913",
"priority": "otp",
"validity_minutes": 60,
"client_ref": "ordine-8812",
"dlr": true
}HTTP 202
{
"accepted": 1,
"rejected": 0,
"messages": [
{
"to": "<MSISDN_DESTINATARIO>",
"message_id": "<ID_MESSAGGIO>",
"status": "accepted",
"parts": 1,
"encoding": "gsm7",
"price": 0.045,
"currency": "EUR"
}
]
}Chiave API, numero e identificativo sono segnaposto. Il prezzo è un valore illustrativo, non una tariffa.
Codici d’errore
| Codice | HTTP | Significato |
|---|---|---|
| invalid_number | 400, per destinatario | numero non valido o rete sconosciuta |
| missing_text | 400 | testo vuoto |
| text_too_long | 400 | testo di più di 10 parti |
| sender_not_allowed | 403, per destinatario | mittente non approvato |
| blocked | 403, per destinatario | firewall o regola di routing |
| insufficient_balance | 402 | saldo esaurito |
| rate_limited | 429 | limite TPS dell’account, con header Retry-After |
| unauthorized / forbidden | 401 / 403 | chiave mancante, revocata o IP non ammesso |
Codici stabili, documentati e uguali dove possibile a quelli SMPP. Il limite di 10 parti vale per questa API HTTP; non sostituisce le altre capacità della piattaforma.
Consultazione
- GET /v1/sms/{message_id}stato attuale del messaggio, con il dettaglio per parte
- GET /v1/balancesaldo e fido
Webhook per DLR e MO
- DestinazioniRicevuta di consegna (type dlr) e messaggio in ingresso (type mo, con from, to, text, received_at e incomplete) arrivano con POST all’URL configurato sull’account.
- FirmaHeader X-Signature: t=<timestamp>,v1=<HMAC-SHA256(secret, t + "." + body)>. Il cliente rifiuta le firme più vecchie di 5 minuti per limitare il riutilizzo di notifiche intercettate.
- ConfermaQualsiasi risposta 2xx conferma la ricezione della notifica webhook, non la consegna dell’SMS.
- Nuovi tentativiSe il cliente risponde con un errore o non risponde entro 10 secondi, si ritenta con attese crescenti fino a 8 volte in 6 ore. Esauriti i tentativi, l’invio della notifica viene interrotto e la mancata consegna viene registrata.
{
"type": "dlr",
"message_id": "<ID_MESSAGGIO>",
"client_ref": "ordine-8812",
"to": "<MSISDN_DESTINATARIO>",
"status": "delivered",
"parts": 2,
"parts_delivered": 2,
"error_code": null,
"done_at": "2026-10-05T02:27:11Z"
}API di messaggistica
- HTTP(S) SMS APIinvio SMS e ricezione dei delivery report su HTTP/HTTPS
- HTTP MNP APIinformazioni di portabilità per qualsiasi MSISDN
- Inbound SMS APIinoltro in tempo reale dei MO a sistemi di terze parti
API dati e finanza
- CDR Export APIesportazione dei call detail record
- Finance Document APIaccesso a fatture e documenti finanziari
- Traffic Report APIreport di traffico per qualsiasi periodo
REST API per sistemi esterni
- Saldosaldo corrente, fido, importo disponibile e valuta
- Consumimessaggi, consegnati, falliti, parti e importi per periodo
- CDRcall detail record per messaggio
- Fatturenumero, date, totale, importo pagato e stato
- Numeri virtualielenco, aggiunta e rimozione di numeri e range
- Autenticazionetoken con chiavi API
Protocolli
- ClientiSMPP 3.4, SMPP su TLS, API HTTP(S) e portale web
- FornitoriSMPP 3.4 e 5.0
- SS7SIGTRAN (M3UA), tramite il gateway SMPP-to-SIGTRAN integrato
- MNP/HLRDNS ENUM/NAPTR e HTTP(S) MNP API
SMPP 3.4SMPP su TLSSMPP 5.0 (fornitori)SIGTRAN M3UADNS ENUM/NAPTRHTTP(S) per l’invioSFTP (record e PCAP SS7)
Dal protocollo alla rotta.
Il catalogo descrive come il traffico in ingresso viene instradato, tariffato e monitorato.