Integrationsvertrag für A2P-SMS-DLR: Felder, Status und Änderungen
Ein praxisorientierter Leitfaden zur Abstimmung des DLR-Formats zwischen SMS-Anbietern: Originalcodes bewahren, Ereignisse korrelieren und Änderungen testen, ohne einen Bericht automatisch als Nachweis für den Empfang auf dem Mobiltelefon zu interpretieren.
Warum die Semantik eines DLR variieren kann
Ein Zustellbericht (DLR, kurz für Delivery Report) ist ein Ereignis, das von einem System innerhalb der Nachrichtenkette gemeldet wird. Seine operative Bedeutung hängt davon ab, wer ihn erzeugt, welche Phase er abbildet und wie der jeweilige Anbieter seine Statuswerte definiert. Deshalb können zwei Systeme ähnliche Bezeichnungen verwenden, ohne dass ihre Berichte gleichwertige Nachweise darstellen.
Ermitteln Sie vor der Integration alle beteiligten Glieder – zum Beispiel die Versandplattform und den Anbieter, der den Bericht zurückmeldet – und fordern Sie deren aktuelle technische Dokumentation an. Gehen Sie nicht davon aus, dass ein Status, Code oder Zeitstempel in allen Systemen dieselbe Bedeutung hat. Die hier verfügbaren Informationen reichen nicht aus, um eine universelle Liste von Statuswerten oder deren Entsprechungen festzulegen.
- Vereinbaren Sie, welches Ereignis jeder Anbieter meldet und welche Phase des Ablaufs es abbilden soll.
- Dokumentieren Sie die Statusdefinition anhand der Anbieterdokumentation und nicht nur anhand der Bezeichnung.
- Klären Sie, was die Zeitstempel bedeuten und in welcher Zeitzone sie angegeben werden.
Legen Sie vor der Verbindung der Systeme ein gemeinsames Schema fest
Der Datenvertrag muss zwischen erforderlichen, optionalen und von der Verfügbarkeit beim Anbieter abhängigen Feldern unterscheiden. Legen Sie für jedes Feld Name, Typ, Format, Bedeutung, Regeln für fehlende Werte und abgestimmte Beispiele fest. Machen Sie aus einer lokalen Konvention keine universelle Anforderung: Prüfen Sie jeden Punkt gemeinsam mit den Beteiligten der Integration.
Als Grundlage für die Abstimmung kommen eine Ereigniskennung, die dem Absender bekannte Nachrichtenkennung, der normalisierte Status, der ursprüngliche Code und Text, das Quellsystem sowie verfügbare Zeitstempel infrage. Fügen Sie Korrelationskennungen hinzu, wenn Werte zwischen Systemen übersetzt werden. Die verfügbaren Informationen belegen nicht, dass alle diese Felder in jedem DLR vorhanden sind oder einem Standardformat entsprechen.
- Kennzeichnen Sie nur Felder als verpflichtend, die alle Beteiligten erzeugen und validieren können.
- Legen Sie fest, ob ein fehlendes Feld ausgelassen, als null dargestellt oder auf andere Weise gemeldet wird.
- Definieren Sie Format und Zeitzone für jeden Zeitstempel. Leiten Sie die Empfangszeit nicht ohne dokumentierte Regel aus einem anderen Zeitstempel ab.
- Nehmen Sie gültige und ungültige Beispiele in den Vertrag auf.
Bewahren Sie den normalisierten Status und die ursprüngliche Antwort auf
Eine Normalisierung erleichtert die gemeinsame Verarbeitung, kann jedoch wichtige Unterschiede verbergen, wenn sie die Anbieterantwort vollständig ersetzt. Speichern Sie den internen normalisierten Status getrennt vom ursprünglich empfangenen Status, Code und Text. Bewahren Sie außerdem den Namen oder die Kennung des Quellsystems und die Version des angewandten Mappings auf.
Führen Sie eine explizite Zuordnungstabelle, die mit jedem Anbieter abgestimmt und regelmäßig überprüft wird. Ist ein Code nicht dokumentiert oder lässt er sich nicht sicher zuordnen, kennzeichnen Sie ihn als unbekannt oder noch zu prüfen. Wandeln Sie ihn nicht automatisch in Erfolg oder Fehler um. Die Normalisierung sollte operativ nachvollziehbar bleiben: Das Team muss prüfen können, welcher Wert eingegangen ist und welche Regel zur Einstufung geführt hat.
- Verwerfen Sie den Originalcode nicht, wenn Sie Kennzahlen berechnen oder interne Status aktualisieren.
- Dokumentieren Sie jede Zuordnung mit Quelle, Geltungsbereich und Prüfdatum.
- Definieren Sie eine Kategorie für unbekannte Werte und einen Prüfprozess für neue Werte.
- Fassen Sie unterschiedliche Statuswerte nicht zusammen, solange der Anbieter nicht bestätigt hat, dass sie dieselbe Bedingung abbilden.
Korrelieren Sie jedes Ereignis mit dem richtigen Versand
Eine Nachrichtenkennung kann sich zwischen verschiedenen Systemen unterscheiden. Der Vertrag muss erklären, welcher Beteiligte welche Kennung erzeugt, wo sie zurückgegeben wird und wie sie mit der der sendenden Anwendung bekannten Kennung verknüpft ist. Bei einer Übersetzung speichern Sie die Beziehung zwischen den Werten, statt anzunehmen, dass sie austauschbar sind.
Legen Sie fest, anhand welchen Schlüssels oder welcher Schlüsselkombination Ihre Integration den zugehörigen Versand sucht. Definieren Sie, was geschieht, wenn eine Kennung fehlt, kein Treffer gefunden wird oder mehrere Treffer vorliegen. Ordnen Sie einen DLR nicht allein aufgrund einer Datenähnlichkeit zu, die nicht als gültiges Kriterium vereinbart wurde.
- Dokumentieren Sie den Weg der Kennungen vom Versand bis zum Bericht.
- Testen Sie gültige Treffer ebenso wie fehlende, unbekannte und doppelte Kennungen.
- Bewahren Sie bei jeder Übersetzung die Quell- und Zielwerte auf.
- Leiten Sie nicht zugeordnete Ereignisse an eine Warteschlange oder einen Prüfprozess weiter, statt sie willkürlich zuzuweisen.
Behandeln Sie Duplikate, Verzögerungen und unbekannte Ereignisse
Vereinbaren Sie, wie wiederholte, verspätete oder entgegen der erwarteten Reihenfolge eingegangene Ereignisse erkannt und behandelt werden. Die verfügbaren technischen Informationen legen keine universelle Regel zur Deduplizierung oder Sequenzierung fest, die für alle Anbieter gilt. Der Vertrag muss daher bestimmen, anhand welcher Daten eine Wiederholung erkannt wird, wie lange die erforderlichen Informationen aufbewahrt werden und wie widersprüchliche Ereignisse behandelt werden.
Überschreiben Sie einen früheren Status nicht allein deshalb, weil ein anderes Ereignis später eingegangen ist: Die Empfangsreihenfolge muss nicht der Reihenfolge entsprechen, in der die Ereignisse aufgetreten sind. Klären Sie mit jedem Anbieter, welche Zeitstempel relevant sind und welche Vorrangregel gegebenenfalls dokumentiert ist. Gibt es keine überprüfbare Regel, bewahren Sie den Verlauf auf und leiten Sie mehrdeutige Fälle zur Prüfung weiter.
- Legen Sie fest, anhand welcher Kriterien ein Ereignis als Duplikat gilt und was bei seinem erneuten Eingang geschieht.
- Speichern Sie den lokalen Empfangszeitpunkt getrennt von gemeldeten Zeitstempeln, sofern diese verfügbar sind.
- Bestimmen Sie den Umgang mit verspäteten, unbekannten, widersprüchlichen und nicht zugeordneten Statuswerten.
- Sorgen Sie dafür, dass die Aktualisierungslogik nachvollziehbar ist, und löschen Sie nicht den ursprünglichen Verlauf.
Testen Sie den Vertrag anhand vereinbarter Abnahmekriterien
Bereiten Sie gemeinsame Tests mit Beispielen vor, die von den Beteiligten freigegeben wurden. Damit sollen das empfangene Format, die Feldvalidierung, die Statuszuordnung und die Korrelation geprüft werden – nicht der Empfang der Nachricht auf einem Mobiltelefon nachgewiesen werden. Die Liste der Codes und erwarteten Ergebnisse muss sich auf die Dokumentation und die technische Vereinbarung der beteiligten Anbieter stützen.
Führen Sie die Tests in einer geeigneten Umgebung aus und protokollieren Sie Eingabe, erwartetes Ergebnis, beobachtetes Ergebnis und Entscheidung. Weicht das tatsächliche Format vom Vertrag ab oder ist ein Status nicht dokumentiert, setzen Sie die Abnahme dieser Variante aus, bis die Abweichung geklärt ist.
- Gültiges Ereignis mit allen vereinbarten Feldern.
- Fehlendes optionales und fehlendes verpflichtendes Feld, jeweils mit dokumentiertem erwarteten Verhalten.
- Bekannter Status mit erhaltenem Originalcode und erwarteter Zuordnung.
- Unbekannter Code oder Status, ohne automatische Einstufung als Erfolg.
- Wiederholtes, verspätetes, außer Reihenfolge eingegangenes und nicht korrelierbares Ereignis.
- Format mit hinzugefügten, ausgelassenen oder umbenannten Feldern oder einem abweichenden Datentyp – im Rahmen der Vertragsgrenzen.
Versionieren Sie den Vertrag und steuern Sie Änderungen
Behandeln Sie Format und Zuordnung als gemeinsamen Vertrag und nicht als implizite Annahme im Code. Kennzeichnen Sie jede Version, bewahren Sie die Änderungshistorie auf und dokumentieren Sie, welche Systeme sie unterstützen. Ermitteln Sie vor der Bereitstellung einer Änderung, ob sie die Struktur, den Feldtyp, die Bedeutung eines Status oder die Korrelation betrifft.
Vereinbaren Sie mit jedem Beteiligten ein Verfahren für Benachrichtigung, Prüfung und Tests. Erklären Sie eine Änderung nicht allein deshalb für kompatibel, weil die Nachricht weiterhin syntaktisch gültig ist: Eine unveränderte Bezeichnung kann eine andere Bedeutung erhalten, und ein hinzugefügtes Feld kann Verbraucher beeinträchtigen, die das Format strikt validieren. Die Kompatibilität muss anhand der konkreten Integrationsregeln geprüft werden.
- Versehen Sie den Vertrag und die Zuordnungstabellen mit einer eindeutig erkennbaren Versionsnummer.
- Bewerten Sie Änderungen am Format und Änderungen an der Semantik getrennt.
- Führen Sie vor der Aktivierung einer neuen Version die vereinbarten Abnahmetests aus.
- Legen Sie fest, wie inkompatible Änderungen angekündigt, angenommen oder abgelehnt werden.
Ein gemeldeter DLR beweist für sich genommen nicht den Empfang auf dem Endgerät
Interpretieren Sie einen DLR nur im Rahmen dessen, was sein Absender dokumentiert. Ein von einem Glied der Kette gemeldeter Status zeigt, was dieses System berichtet; er darf nicht automatisch als unabhängige Bestätigung dafür dargestellt werden, dass die Nachricht auf dem Endgerät des Nutzers angezeigt oder von ihm empfangen wurde. Die verfügbaren Informationen erlauben nicht die Aussage, dass ein bestimmter Status diesen Empfang garantiert.
Unterscheiden Sie in Betriebsberichten zwischen eingegangenen Ereignissen und einer möglicherweise vorhandenen unabhängigen Überprüfung und beschreiben Sie deren Grenzen. Verwenden Sie einen DLR nicht als Nachweis für die Einwilligung, Identität oder das Lesen der Nachricht. Hängt eine Geschäftsentscheidung vom tatsächlichen Empfang ab, legen Sie vorab fest, welche Nachweise als ausreichend gelten, und prüfen Sie die dokumentierten Möglichkeiten der beteiligten Systeme.
- Beschreiben Sie einen Status als Meldung seines Ursprungs und gehen Sie mit der Aussage nicht über die Dokumentation hinaus.
- Trennen Sie den Empfang des DLR, den normalisierten Status und verfügbare unabhängige Nachweise voneinander.
- Weisen Sie unbekannte oder mehrdeutige Fälle in Kennzahlen und Berichten aus, statt sie in eine eindeutige Kategorie zu zwingen.
Häufige Fragen
Gibt es eine universelle Liste von DLR-Statuswerten, die alle Anbieter verwenden müssen?
Die für diesen Leitfaden verfügbaren technischen Informationen reichen nicht aus, um eine universelle Liste oder Entsprechungen zwischen Anbietern festzulegen. Fordern Sie die Dokumentation jedes Beteiligten an und vereinbaren Sie ausdrücklich, welche Statuswerte und Codes zugeordnet werden.
Sollte ich den Originalcode durch einen normalisierten Status ersetzen?
Nein. Bewahren Sie den ursprünglichen Code, Text und Ursprung zusammen mit dem normalisierten Status und der angewandten Zuordnungsregel auf. So können Sie Abweichungen untersuchen und die Zuordnung überprüfen, wenn sich die Dokumentation ändert.
Wie gehe ich mit einem doppelten oder nicht zugeordneten DLR um?
Legen Sie im Vertrag fest, wie Duplikate erkannt und protokolliert werden. Bewahren Sie bei einem nicht zugeordneten Ereignis die empfangenen Daten auf und leiten Sie den Fall zur Prüfung weiter. Weisen Sie ihn nicht aufgrund einer nicht vereinbarten Übereinstimmung einem Versand zu.
Bestätigt ein DLR, dass die SMS auf dem Telefon angekommen ist?
Nicht unbedingt. Ein DLR meldet den Status, den ein System der Nachrichtenkette angibt; die Bedeutung hängt von der Definition des Absenders ab. Stellen Sie ihn ohne dokumentierte Belege nicht als unabhängigen Nachweis für den Empfang auf dem Endgerät dar.
Was sollte vor der Abnahme einer Formatänderung getestet werden?
Prüfen Sie die vereinbarten erforderlichen und optionalen Felder, Typen und Formate, die Bewahrung der Originalwerte, die Statuszuordnung, die Korrelation sowie den Umgang mit unbekannten, wiederholten und verspäteten Werten. Die erwarteten Ergebnisse müssen von den Beteiligten dokumentiert sein.
Verwendete Quellen
- 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