Contratto dei dati operativi A2P SMS: campi e semantica

A cosa serve un contratto dei dati operativi

Nel traffico A2P SMS — messaggi inviati da un'applicazione o da un sistema a una persona — diverse organizzazioni possono registrare lo stesso messaggio in momenti diversi e con terminologie differenti. Un contratto dei dati operativi riduce le ambiguità specificando il significato di ogni campo, chi lo segnala e come si correlano gli eventi.

Non è uno standard universale né garantisce la consegna. È un accordo tra le parti per scambiare e riconciliare informazioni. Deve distinguere le decisioni proprie dell'accordo dai requisiti di un'interfaccia o di una specifica tecnica applicabile. I riferimenti normativi, come SMPP o HTTP, vanno consultati direttamente prima di attribuire loro requisiti specifici.

• Concordare lo schema prima di integrare o modificare lo scambio di dati.
• Documentare definizioni, formati, vocabolari e responsabilità insieme ai campi.
• Trattare l'interpretazione degli stati come un accordo esplicito, non come un'equivalenza presunta tra sistemi.

Attori e limiti delle responsabilità

Una catena può includere l'azienda che origina il traffico, una piattaforma di messaggistica, uno o più fornitori e un operatore mobile. Il percorso concreto e la partecipazione di ciascuna entità dipendono dall'accordo e dalla configurazione del servizio; è meglio non presupporre che la catena sia identica in tutti i casi.

Per ogni dato, indicate chi lo genera, chi lo trasmette, chi può trasformarlo e chi è responsabile della sua interpretazione. Per esempio, il mittente può dichiarare il tipo di traffico; una piattaforma può assegnare un identificativo interno; un fornitore può comunicare uno stato ricevuto da un altro sistema. Sono possibili assegnazioni progettuali, non responsabilità universali.

Separare le responsabilità aiuta a indagare sulle discrepanze: una parte può confermare di aver accettato una richiesta senza affermare che la rete l'abbia consegnata, mentre un'altra può segnalare un risultato successivo entro i limiti consentiti dalla propria fonte.

• Assegnare un responsabile a ciascun campo e a ogni transizione di stato.
• Dichiarare dove termina la responsabilità informativa di ciascuna parte.
• Indicare un contatto e una procedura per riconciliare le discrepanze, senza presumere che tutte le parti osservino gli stessi eventi.

Campi minimi e significato

L'insieme minimo dipende dall'obiettivo: operatività, assistenza, riconciliazione o analisi. È utile iniziare dai dati necessari per correlare una richiesta ai suoi eventi successivi e aggiungere solo i campi che le parti possono produrre e utilizzare secondo una definizione precisa.

Documentate almeno un identificativo del messaggio per ciascun sistema e, quando opportuno, gli identificativi di correlazione tra sistemi. Includete il destinatario nel formato concordato, il mittente, la classificazione dichiarata del traffico, per esempio OTP, transazionale o marketing, e il percorso dichiarato, se noto. Non presentate un percorso dichiarato come prova indipendente del percorso effettivamente seguito.

È inoltre utile includere lo stato, la fonte dello stato, la marcatura temporale dell'evento e il codice di errore, se presente. Se viene condiviso l'operatore di destinazione, indicate come è stato determinato e quando. Un campo relativo a un operatore sconosciuto non va compilato per inferenza. Definite anche la versione delle condizioni o dell'accordo operativo applicabile, con il relativo identificativo e la data o il periodo di validità concordato.

• Identificativi: identificativo del messaggio nel sistema mittente e riferimenti di correlazione disponibili.
• Contesto: destinatario, mittente, classificazione del traffico, percorso dichiarato e operatore, se noto.
• Evento: stato, fonte dello stato, data e ora, codice di errore e versione delle condizioni.
• Per ogni campo, specificare tipo, formato, obbligatorietà, vocabolario e significato.

Stati: accettazione, invio, DLR e risultato sconosciuto

Non riducete l'intero ciclo a un unico campo generico «stato». Definite le fasi che l'accordo deve distinguere: per esempio, richiesta accettata da un'interfaccia, tentativo di invio segnalato da una parte, rapporto di consegna ricevuto o risultato ancora sconosciuto. I nomi esatti e le transizioni vanno concordati per ogni integrazione.

Un DLR è un rapporto di stato ricevuto da una fonte specifica. Registrate chi lo ha emesso o trasmesso e che cosa significa in quel contesto. Di per sé, non va trattato come verifica indipendente del fatto che il messaggio sia apparso sul terminale o sia stato letto dalla persona.

Mantenete uno stato sconosciuto quando le informazioni non sono sufficienti per trarre una conclusione. Non convertite automaticamente l'assenza di un DLR in un errore, né uno stato favorevole segnalato in una garanzia di ricezione. Se due fonti sono in disaccordo, conservate entrambi gli eventi e documentate quale usa ogni processo e perché.

• Definire ogni stato tramite una descrizione, chi lo segnala e le transizioni consentite.
• Separare lo stato segnalato dalla valutazione interna che una parte fa del caso.
• Conservare gli eventi originali per ricostruire la sequenza e risolvere le discrepanze.

Marcature temporali e ordine degli eventi

Una marcatura temporale deve consentire di capire quando si è verificato o è stato registrato l'evento e in quale fuso orario. Concordate il formato, la precisione disponibile e se la data rappresenta il momento dell'evento, quello di ricezione del rapporto o quello di registrazione nel sistema.

Non deducete l'ordine soltanto dall'ora di arrivo su una piattaforma: gli eventi possono essere ricevuti in un ordine diverso da quello attribuito loro da ciascuna parte. Se disponibili, mantenete gli identificativi degli eventi o le sequenze e, quando serve per la riconciliazione, registrate separatamente le marcature temporali di origine e di ricezione.

Se una fonte non fornisce il fuso orario o una precisione sufficiente, dichiaratelo. Non completate questi dati come se fossero stati osservati.

• Concordare formato di data e ora, fuso orario e precisione.
• Distinguere l'ora dell'evento, l'ora di ricezione e l'ora di elaborazione.
• Definire come ordinare gli eventi quando le marcature temporali coincidono o sono incomplete.

Origine del dato e livello di evidenza

Lo stesso valore può avere un peso diverso a seconda di chi lo ha dichiarato e di come è stato ottenuto. Aggiungete metadati di provenienza quando aiutano a interpretare il record: sistema di origine, parte che lo trasmette, momento dell'osservazione e indicazione se si tratta di un dato dichiarato, di un evento ricevuto o di un'osservazione indipendente.

Per esempio, una piattaforma può dichiarare un percorso, mentre uno stato può arrivare nel rapporto di un fornitore. Il contratto deve evitare che la trasformazione o l'aggregazione cancelli questa distinzione. Se non esiste una verifica indipendente, indicatelo invece di lasciarla intendere.

Stabilite inoltre quali evidenze sono accettate per ciascun uso: assistenza, riconciliazione o analisi. Il valore utile per un'indagine potrebbe non essere sufficiente a risolvere una controversia commerciale.

• Indicare la provenienza del dato e la parte che lo ha comunicato.
• Distinguere tra osservazione diretta, dichiarazione ed evento ricevuto.
• Non trasformare uno stato trasmesso in un'affermazione più forte di quanto consenta la fonte disponibile.

Valori nulli, vocabolari e codici di errore

Un campo vuoto può significare che il valore è sconosciuto, non è stato raccolto, non è applicabile oppure non è stato ricevuto. Il contratto deve distinguere questi casi, invece di lasciare che ogni sistema li interpreti a modo proprio. Se il formato di scambio non consente di rappresentare tali differenze, documentate una convenzione comune e i suoi limiti.

Definite vocabolari controllati per categorie e stati e concordate come gestire i valori specifici di un fornitore. Se serve confrontare i dati tra le parti, conservate il codice originale insieme a una categoria normalizzata. La normalizzazione non dovrebbe cancellare il valore utile a indagare sull'evento nella sua fonte.

Prima di aggiungere codici, stati o mittenti a un elenco concordato, indicate chi può proporli, come vanno documentati e da quando si applicano. Non riutilizzate un valore precedente attribuendogli un significato nuovo.

• Distinguere esplicitamente tra sconosciuto, assente, non applicabile e non ricevuto.
• Mantenere il valore originale e, quando concordato, aggiungere un valore normalizzato.
• Pubblicare definizioni ed esempi per i codici specifici dei fornitori, senza presentarli come universali.

Versionamento e modifiche dello schema

Ogni scambio dovrebbe consentire di identificare la versione dello schema e quella delle condizioni operative applicate. Concordate come comunicare la versione e come associarla al periodo del traffico, senza presumere che il nome di un'interfaccia basti a identificare le regole.

Definite in anticipo una procedura di modifica: chi propone le modifiche, chi le approva, come vengono testate e quando entrano in vigore. Una modifica che aggiunge un campo facoltativo può essere più semplice da adottare rispetto a una che cambia il significato di uno stato o rende obbligatorio un dato; classificate l'impatto considerando i destinatari effettivi dei dati.

Durante una transizione, indicate quali versioni possono coesistere, come vengono identificati i record e per quanto tempo si mantiene la compatibilità, se le parti concordano una scadenza. Evitate di modificare la semantica senza cambiare la versione o comunicarlo in modo inequivocabile.

• Versionare lo schema e registrare la versione delle condizioni applicabili.
• Classificare le modifiche in base al loro impatto su produttori, destinatari e processi di riconciliazione.
• Concordare approvazione, test, data di entrata in vigore e gestione delle versioni precedenti.