Eventi A2P SMS duplicati e fuori ordine: come riconciliarli senza perdere evidenze

Perché gli eventi possono duplicarsi, arrivare in ritardo o fuori ordine

In un’integrazione A2P, un invio può generare osservazioni in più fasi: la richiesta API, una risposta di accettazione o rifiuto, un’interazione SMPP e, se disponibile, un rapporto di consegna (DLR). Questi segnali non arrivano necessariamente insieme né nell’ordine in cui si sono verificati i fatti. Possono inoltre verificarsi nuovi tentativi di notifica o eventi ripetuti.

La semantica concreta dipende dall’interfaccia e dal fornitore. Non esiste una precedenza universale che consenta di concludere, per tutti i sistemi, che un evento API prevalga su uno SMPP o che qualsiasi DLR significhi la stessa cosa. Documenta che cosa rappresenta ciascun evento nella tua integrazione prima di usarlo per aggiornare uno stato.

• Distingui il momento in cui il sistema dichiara che si è verificato un evento da quello in cui la tua piattaforma lo ha ricevuto.
• Considera la ripetizione dei messaggi una possibilità operativa, non la prova che il fatto sottostante si sia verificato più volte.
• Non presumere che un evento mancante equivalga a un errore, a una consegna o a un annullamento.

Separa il registro originale dalla vista dello stato calcolata

Mantieni distinti due concetti. Il registro degli eventi conserva ciò che è stato ricevuto; la proiezione operativa riassume ciò che la piattaforma può affermare in quel momento. Se cambia una regola di riconciliazione, la proiezione può essere ricalcolata a partire dal registro, senza cancellare o riscrivere le evidenze che hanno prodotto il risultato.

Per ciascun evento conserva, quando disponibili, il contenuto ricevuto, la fonte o l’interfaccia, l’identificativo di correlazione, i tempi dichiarati e osservati e l’esito delle convalide. Evita di sostituire un evento precedente con uno successivo solo perché quest’ultimo sembra più conclusivo.

La conservazione, la protezione dalle alterazioni e i requisiti di audit devono essere adeguati agli obblighi della tua organizzazione e ai contratti applicabili. Qui non viene fornita alcuna garanzia universale di archiviazione immutabile.

• Salva l’osservazione originale e registra separatamente ogni normalizzazione.
• Gestisci le versioni delle regole usate per calcolare la proiezione.
• Consenti di ricostruire quali eventi e regole hanno prodotto lo stato visualizzato.

Definisci identità e deduplicazione senza presumere una chiave globale

Non dare per scontato che esista un identificativo univoco condiviso tra API, SMPP, aggregatori e operatori. Un identificativo può essere valido solo nell’ambito di un account, una connessione, un fornitore o un periodo. Definisci l’ambito di ciascun identificativo in base alla documentazione della specifica interfaccia.

Se non esiste una chiave affidabile, non unire gli eventi solo perché coincidono destinatario, testo e orario approssimativo: due messaggi legittimi possono condividere questi attributi. In tal caso, conserva entrambi e contrassegnali come possibili duplicati o come correlazione incerta, invece di scartare evidenze.

La normalizzazione del numero può facilitare le ricerche, ma da sola non dimostra che due record corrispondano allo stesso invio. E.164 è una raccomandazione di numerazione e non fornisce, di per sé, una regola per correlare i messaggi.

• Usa prima l’identificativo documentato dall’interfaccia e il relativo ambito: account, connessione o fornitore.
• Registra le regole di deduplicazione e il motivo di ogni corrispondenza.
• Se la correlazione è ambigua, conserva l’evento ed evita di unire automaticamente i messaggi.

Ordina con cautela: tempo dichiarato, tempo osservato e sequenza

Conserva separatamente il timestamp incluso dal mittente dell’evento e l’ora in cui il tuo sistema lo ha osservato. Un orario dichiarato può descrivere il momento di origine; l’ora osservata documenta quando l’evento è arrivato alla tua piattaforma. Nessuno dei due dovrebbe sostituire silenziosamente l’altro.

Se l’interfaccia fornisce una sequenza o una versione con semantica documentata, valuta di usarla nell’ambito per cui è valida. Se non esiste un segnale di ordinamento affidabile, non trasformare l’ordine di arrivo in una cronologia definitiva. Una regola di spareggio stabile può rendere ripetibile il calcolo, ma non prova quale evento sia avvenuto per primo.

Registra il fuso orario, la precisione e gli eventuali problemi dell’orologio quando questi dati sono disponibili. Se mancano, conserva tale limite nella valutazione dell’evento.

• Salva almeno il tempo dichiarato e quello di ricezione in campi distinti.
• Usa le sequenze solo se ne conosci l’ambito e il significato.
• Segnala come incerto l’ordine relativo quando le evidenze non consentono di determinarlo.

Definisci transizioni esplicite e non dedurre la consegna

Progetta una macchina a stati per il tuo sistema basandoti sui significati documentati per ciascuna interfaccia. Non esiste una precedenza universale tra accettazione, errore, stato intermedio e DLR che si possa applicare senza conoscere il fornitore e il contratto tecnico.

Un’accettazione dell’invio indica soltanto ciò che l’interfaccia documenta in merito alla richiesta. Un DLR va interpretato in base alla sua origine e alla sua semantica; la sua ricezione non equivale automaticamente a una verifica indipendente del fatto che la persona abbia visto l’SMS o che il messaggio sia arrivato al dispositivo in tutti i casi.

Quando le evidenze non bastano per decidere, mostra uno stato come «in attesa», «sconosciuto» o «in conflitto», secondo il tuo modello. Il nome deve chiarire che non si tratta di una consegna confermata.

• Documenta quali eventi consentono ciascuna transizione e che cosa significano in quella specifica integrazione.
• Definisci le condizioni per mantenere uno stato incerto e per segnalare una contraddizione.
• Non trasformare l’assenza di un DLR, un’accettazione o un codice non interpretato in una consegna confermata.

Gestisci le contraddizioni e i DLR tardivi senza perdere lo storico

Se un DLR arriva dopo che l’interfaccia ha segnalato un errore, o se due fonti sembrano contraddirsi, conserva entrambi gli eventi e valutane il significato secondo la documentazione applicabile. Non eliminare l’evento precedente né scegliere automaticamente quello più recente: l’ora di ricezione, da sola, non determina quale abbia maggiore autorità.

La proiezione può essere aggiornata quando una nuova osservazione fornisce evidenze rilevanti, ma deve restare traccia di che cosa è cambiato, quando è stato ricalcolato e quale regola è stata applicata. Se il conflitto non può essere risolto, è più preciso mantenerlo visibile che nasconderlo dietro un unico stato definitivo.

• Registra le contraddizioni come una condizione esplicita, non come una sovrascrittura silenziosa.
• Definisci quando una regola consente di risolvere un conflitto e quando è necessaria una revisione.
• Conserva gli eventi tardivi per l’audit e la rielaborazione.

Rendi la riconciliazione ripetibile e verificabile

Una rielaborazione dovrebbe produrre lo stesso risultato se viene eseguita con lo stesso insieme di eventi, le stesse regole e la stessa versione della configurazione. Per ottenere questa proprietà, separa l’ingestione dalla proiezione ed evita che il risultato dipenda da effetti collaterali non registrati.

L’idempotenza può essere applicata all’elaborazione di una notifica quando esistono un’identità affidabile e un ambito definito. In loro assenza, una deduplicazione aggressiva può eliminare evidenze valide. È preferibile registrare il criterio usato, conservare l’osservazione ricevuta e segnalare le corrispondenze incerte.

Monitora andamenti anomali, come l’aumento degli eventi ripetuti, ritardi insoliti tra tipi di evento o contraddizioni ricorrenti. Gli avvisi devono descrivere ciò che è stato osservato, senza attribuire una causa in assenza di evidenze.

• Gestisci le versioni delle regole di proiezione e registra quella applicata.
• Consenti di ricalcolare gli stati a partire dallo storico conservato.
• Misura duplicati, ritardi e conflitti per interfaccia e ambito, senza trasformare questi dati in garanzie di qualità.

Esempio: accettazione, errore temporaneo e DLR tardivo

Immagina che l’API risponda accettando la richiesta. In seguito arriva un segnale che la tua integrazione interpreta come errore temporaneo e, più tardi, compare un DLR. I nomi e i significati esatti devono provenire dalla documentazione del fornitore; questo esempio non stabilisce una sequenza normativa.

Per prima cosa conserva i tre eventi con i rispettivi tempi dichiarati e di ricezione, gli identificativi e l’ambito noto. Verifica se possono essere correlati con sufficiente sicurezza. Poi applica le regole documentate: l’accettazione non dimostra la consegna, l’errore temporaneo non deve essere cancellato dall’arrivo successivo di un altro evento e il DLR può giustificare solo le conclusioni consentite dalla sua semantica.

Se la documentazione stabilisce che quel DLR rappresenta un esito di consegna per il messaggio correlato, la proiezione può riportare tale esito indicandone chiaramente l’ambito. Se la semantica, l’identità o il legame con l’invio non sono confermati, conserva lo stato come incerto o in conflitto. In nessun caso l’esempio consente di affermare che l’utente abbia visto l’SMS o che vi sia stata una ricezione indipendente sul cellulare.

• Concludi che sono stati ricevuti un’accettazione, un segnale di errore e un DLR; correlazione e significato devono essere verificati.
• Non concludere senza documentazione che l’accettazione confermi la consegna o che il DLR provi l’effettiva ricezione da parte dell’utente.
• Lascia in sospeso qualsiasi conflitto di identità, ordine o semantica che le evidenze disponibili non risolvano.