Contratto di integrazione DLR A2P SMS: campi, stati e modifiche
Una guida pratica per concordare il formato dei DLR tra provider SMS, conservare i codici originali, correlare gli eventi e testare le modifiche senza interpretare un report come prova automatica della ricezione sul telefono.
Perché la semantica di un DLR può variare
Un rapporto di consegna (DLR, dall’inglese Delivery Report) è un evento comunicato da un sistema della catena di messaggistica. Il suo significato operativo dipende da chi lo genera, dalla fase che rappresenta e da come il provider definisce i propri stati. Per questo, due sistemi possono usare etichette simili senza che i rispettivi report costituiscano prove equivalenti.
Prima dell’integrazione, individua ogni anello coinvolto, ad esempio la piattaforma di invio e il provider che restituisce il report, e richiedi la documentazione tecnica aggiornata. Non presumere che uno stato, un codice o un timestamp abbiano lo stesso significato in tutti i sistemi. Le informazioni disponibili qui non consentono di definire un elenco universale di stati né le relative equivalenze.
- Concorda quale evento comunica ciascun provider e quale fase del percorso intende rappresentare.
- Registra la definizione dello stato secondo la documentazione del provider, non soltanto la sua etichetta.
- Chiarisci cosa significano i timestamp e in quale fuso orario sono espressi.
Definisci uno schema comune prima di collegare i sistemi
Il contratto dati deve distinguere i campi obbligatori, facoltativi e subordinati alla disponibilità del provider. Per ogni campo, specifica nome, tipo, formato, significato, regole in caso di assenza ed esempi concordati. Non trasformare una convenzione locale in un requisito universale: verifica ogni punto con i partecipanti all’integrazione.
Come base per la negoziazione, considera un identificatore dell’evento, l’identificatore del messaggio noto al mittente, lo stato normalizzato, il codice e il testo originali, il sistema di origine e i timestamp disponibili. Aggiungi identificatori di correlazione quando avvengono traduzioni tra sistemi. Le informazioni disponibili non stabiliscono che tutti questi campi siano presenti o abbiano un formato standard in tutti i DLR.
- Indica come obbligatorio solo ciò che tutti i partecipanti possono produrre e convalidare.
- Definisci se un campo assente viene omesso, rappresentato come nullo o segnalato con un altro meccanismo.
- Specifica formato e fuso orario per ogni timestamp; non dedurre l’ora di ricezione da un altro timestamp senza una regola documentata.
- Includi nel contratto esempi validi e non validi.
Conserva lo stato normalizzato e la risposta originale
La normalizzazione semplifica l’elaborazione comune, ma può nascondere differenze importanti se sostituisce interamente la risposta del provider. Conserva separatamente lo stato interno normalizzato e lo stato, il codice e il testo ricevuti in origine. Memorizza anche il nome o l’identificatore del sistema di origine e la versione della mappatura applicata.
Mantieni una tabella di corrispondenze esplicita, verificata con ciascun provider. Se un codice non è documentato o non può essere mappato con sicurezza, classificalo come sconosciuto o da analizzare; non convertirlo automaticamente in esito positivo o negativo. Sul piano operativo, la normalizzazione deve essere reversibile: il team deve poter consultare il valore ricevuto e la regola che ha determinato la classificazione.
- Non eliminare il codice originale quando calcoli metriche o aggiorni gli stati interni.
- Documenta ogni equivalenza, indicandone la fonte, l’ambito e la data di revisione.
- Definisci una categoria per gli elementi sconosciuti e un percorso di revisione per i nuovi valori.
- Evita di raggruppare stati diversi, a meno che il provider non confermi che rappresentano la stessa condizione.
Correla ogni evento all’invio corretto
L’identificatore di un messaggio può variare da un sistema all’altro. Il contratto deve specificare quale identificatore genera ciascun partecipante, dove viene restituito e come viene collegato all’identificatore noto all’applicazione che ha inviato il messaggio. Se avviene una traduzione, registra la relazione tra i valori invece di presumere che siano intercambiabili.
Definisci la chiave, o la combinazione di chiavi, che l’integrazione userà per individuare l’invio associato. Specifica cosa accade se manca un identificatore, non si trova alcuna corrispondenza o ne vengono trovate più di una. Non attribuire un DLR sulla sola base di una somiglianza tra dati che non sia stata concordata come criterio valido.
- Documenta il percorso degli identificatori dall’invio al report.
- Verifica sia le corrispondenze valide sia gli identificatori assenti, sconosciuti e ripetuti.
- Conserva i valori di origine e di destinazione di ogni traduzione.
- Invia gli eventi senza corrispondenza a una coda o a un processo di analisi, senza assegnarli arbitrariamente.
Gestisci duplicati, ritardi ed eventi non riconosciuti
Concorda come identificare e gestire gli eventi ripetuti, tardivi o ricevuti in un ordine diverso da quello previsto. Le informazioni tecniche disponibili non definiscono una regola universale di deduplicazione o sequenziamento valida per tutti i provider. Il contratto deve quindi specificare quali dati permettono di riconoscere una ripetizione, per quanto tempo conservare le informazioni necessarie e come risolvere gli eventi contraddittori.
Non sovrascrivere uno stato precedente solo perché un altro evento è arrivato dopo: l’ordine di ricezione potrebbe non corrispondere all’ordine in cui gli eventi si sono verificati. Determina con ciascun provider quali timestamp siano rilevanti e quale precedenza, se prevista, sia documentata. Se manca una regola verificabile, conserva la cronologia e sottoponi i casi ambigui a revisione.
- Definisci il criterio per identificare un duplicato e cosa fare se viene ricevuto più di una volta.
- Registra separatamente il momento della ricezione locale e i timestamp comunicati, se disponibili.
- Stabilisci come gestire gli stati tardivi, sconosciuti, contraddittori e senza corrispondenza.
- Rendi tracciabile la logica di aggiornamento ed evita di eliminare la cronologia originale.
Testa il contratto con casi di accettazione concordati
Prepara test congiunti usando esempi approvati dai partecipanti. L’obiettivo è verificare il formato ricevuto, la convalida dei campi, la mappatura degli stati e la correlazione; non dimostrare, da solo, che un telefono abbia ricevuto il messaggio. L’elenco dei codici e dei risultati attesi deve basarsi sulla documentazione e sull’accordo tecnico dei provider coinvolti.
Esegui i test in un ambiente adeguato e registra input, risultato atteso, risultato osservato e decisione. Se il formato effettivo differisce dal contratto o uno stato non è documentato, sospendi l’accettazione di quella variante finché la discrepanza non viene risolta.
- Evento valido con tutti i campi concordati.
- Campo facoltativo assente e campo obbligatorio assente, ciascuno con il comportamento atteso documentato.
- Stato noto con codice originale conservato e mappatura attesa.
- Codice o stato sconosciuto, senza classificazione automatica come esito positivo.
- Evento ripetuto, tardivo, fuori sequenza e privo di un identificatore correlabile.
- Formato con campi aggiunti, omessi o rinominati, oppure con un tipo diverso, nei limiti definiti dal contratto.
Versiona il contratto e gestisci le modifiche
Tratta il formato e la mappatura come un contratto condiviso, non come un presupposto implicito nel codice. Identifica ogni versione, conserva lo storico delle modifiche e comunica quali sistemi la accettano. Prima di distribuire una modifica, determina se riguarda la struttura, il tipo di un campo, la semantica di uno stato o la correlazione.
Concorda con ogni partecipante una procedura di notifica, revisione e test. Non dichiarare compatibile una modifica solo perché il messaggio resta sintatticamente valido: un’etichetta invariata può assumere un significato diverso e un campo aggiunto può influire sui consumer che convalidano rigidamente il formato. La compatibilità va verificata rispetto alle regole specifiche dell’integrazione.
- Assegna una versione identificabile al contratto e alle tabelle di mappatura.
- Valuta separatamente le modifiche di formato e quelle semantiche.
- Esegui i casi di accettazione concordati prima di attivare una nuova versione.
- Definisci come comunicare, accettare o rifiutare le modifiche incompatibili.
Un DLR comunicato non dimostra da solo la ricezione sul terminale
Interpreta il DLR entro i limiti documentati dal suo emittente. Uno stato comunicato da un anello della catena indica ciò che quel sistema riporta; non va presentato automaticamente come conferma indipendente che il messaggio sia comparso o sia stato ricevuto dall’utente sul terminale. Le informazioni disponibili non consentono di affermare che uno stato specifico garantisca tale ricezione.
Nei report operativi, distingui gli eventi ricevuti da eventuali verifiche indipendenti e descrivine i limiti. Non usare il DLR come prova del consenso, dell’identità o della lettura del messaggio. Se una decisione aziendale dipende dalla ricezione effettiva, definisci in anticipo quale evidenza sia sufficiente e consulta le funzionalità documentate dei sistemi coinvolti.
- Descrivi lo stato come comunicato dalla sua fonte, senza attribuirgli una portata maggiore di quella supportata dalla documentazione.
- Distingui la ricezione del DLR, lo stato normalizzato e le eventuali prove indipendenti disponibili.
- Nei report e nelle metriche, evidenzia i casi sconosciuti o ambigui invece di forzarli in una categoria conclusiva.
Domande frequenti
Esiste un elenco universale di stati DLR che tutti i provider devono usare?
Le informazioni tecniche disponibili per questa guida non consentono di definire un elenco universale né equivalenze tra provider. Richiedi la documentazione di ciascun partecipante e concorda esplicitamente gli stati e i codici da mappare.
Devo sostituire il codice originale con uno stato normalizzato?
No. Conserva il codice, il testo e la fonte originali insieme allo stato normalizzato e alla regola di mappatura applicata. In questo modo puoi analizzare le discrepanze e rivedere la mappatura quando cambia la documentazione.
Cosa devo fare con un DLR duplicato o senza corrispondenza?
Definisci nel contratto come riconoscere e registrare i duplicati. Per un evento senza corrispondenza, conserva i dati ricevuti e avvia un’analisi; non associarlo a un invio sulla base di una corrispondenza non concordata.
Un DLR conferma che l’SMS è arrivato al telefono?
Non necessariamente. Il DLR comunica lo stato riportato da un sistema della catena e la sua portata dipende dalla definizione dell’emittente. Non presentarlo come prova indipendente della ricezione sul terminale senza evidenze documentate a supporto.
Cosa va testato prima di accettare una modifica del formato?
Verifica i campi obbligatori e facoltativi, i tipi e i formati concordati, la conservazione dei valori originali, la mappatura degli stati, la correlazione e la gestione dei valori sconosciuti, ripetuti e tardivi. I risultati attesi devono essere documentati dai partecipanti.
Fonti consultate
- SMPP v3.4 Issue 1.2SMPP Developers Forum
- HTTP Semantics (RFC 9110)IETF
- 3GPP specifications by series3GPP
- ITU-T Recommendation E.164International Telecommunication Union
- GSMA Networks resourcesGSMA