Carrier Detection API: Hinzufügen von Kontext zu Netzbetreiber und Leitungstyp in einem Registrierungs-Backend

Ein Leitfaden für die Backend-Integration zum Aufruf einer Carrier Detection API nach der Telefonregistrierung, zum Speichern des ursprünglichen Netzbetreibers und Leitungstyps als Kontext für die Überprüfung sowie zum sicheren Umgang mit Fehlern.

Eine Carrier Detection API ist in einem Registrierungsablauf per Telefon ein serverseitiger Aufruf, der die übermittelte Nummer entgegennimmt und den Netzbetreiber, dem der Nummernblock ursprünglich zugewiesen wurde, den Leitungstyp sowie die geografische Zuordnung zurückgibt. Mit CarrierLookup normalisiert das Backend die Nummer in das E.164-Format, sendet sie an POST /api/v1/check mit einem auf dem Server gespeicherten API-Schlüssel und speichert das Ergebnis neben dem Konto als Kontext für die Überprüfung. Die beste Platzierung ist nach der Annahme des Formulars und vor jeglicher Weiterleitung oder Entscheidung zur manuellen Überprüfung, damit eine langsame oder unbestimmte Abfrage den Benutzer niemals am Abschluss der Registrierung hindert.

Telefonnummernabfrage vs. IP-basierte Netzbetreibererkennung

Suchen nach einer Carrier Detection API führen zu zwei verschiedenen Arten von Diensten, und die Wahl des falschen Dienstes verschwendet einen Integrationssprint.

Ein Registrierungs-Backend, das die von einer Person eingegebene Telefonnummer verstehen möchte, benötigt die zweite Art. Eine IP-Abfrage sagt nichts über die Nummer aus, und eine Nummernsuche sagt nichts über die Browsing-Sitzung aus. Einige Teams speichern beides, aber sie beantworten unterschiedliche Fragen und sollten in separaten Feldern mit separaten Namen abgelegt werden.

Wo der Aufruf der Carrier Detection API bei der Registrierung hingehört

Platzieren Sie die Abfrage im Backend, nach Ihrer eigenen Formularvalidierung und vor jeder Entscheidung, die deren Ausgabe verwendet. Eine Abfolge, die für die meisten Produkte funktioniert:

1. Formular akzeptieren. Prüfen Sie, ob das Telefonfeld vorhanden und plausibel formatiert ist.
2. Normalisierung auf E.164. Konvertieren Sie die Eingabe in ein Pluszeichen, Ländercode und Teilnehmerziffern ohne Leerzeichen, wie in ITU-T E.164 definiert. Synchrone Prüfungen benötigen keine separate Länderauswahl, da der Ländercode innerhalb der Nummer diese Information enthält.
3. Konto im Status "ausstehender Kontext" erstellen. Halten Sie die HTTP-Antwort nicht offen, während Sie auf die Abfrage warten, wenn Ihre Registrierungsseite ein enges Latenzbudget hat.
4. Aufruf von POST /api/v1/check von einem Job oder Worker mit einer Nummer.
5. Ergebnis speichern mit der Abfragezeit und einem Status wie abgeschlossen, leer oder Unbestimmt.
6. Eigene Regeln anwenden. Leiten Sie das Konto weiter, fügen Sie es einer manuellen Prüfschlange hinzu oder unternehmen Sie nichts.

Das Ausführen des Aufrufs in einer Warteschlange hält die Registrierung reaktionsfähig und bietet Wiederholungsversuchen einen natürlichen Platz.

Was von jeder Abfrage zu speichern ist

Eine abgeschlossene Prüfung beschreibt die Zuweisung der Nummer in einfachen Begriffen: den ursprünglichen Netzbetreiber, den zugrunde liegenden Netzbetreiber, wenn eine Marke in einem anderen Netz betrieben wird, den Leitungstyp wie Mobilfunk oder Festnetz, den Ländercode sowie die Region und Stadt, die mit dem Nummernblock verknüpft sind. Speichern Sie diese in Feldern, deren Namen aussagekräftig sind, zum Beispiel original_carrier anstelle von carrier und allocation_region anstelle von location. Region und Stadt beschreiben, wo der Nummernblock zugewiesen wurde, was nicht dem Ort entspricht, an dem sich die registrierende Person befindet.

Speichern Sie drei weitere Werte daneben:

• Abfrage-Zeitstempel, damit Prüfer wissen, wie alt der Kontext ist.
• Ergebnis: abgeschlossen mit Werten, abgeschlossen mit leeren Werten oder Unbestimmt.
• Gesendete Eingabe, die exakte E.164-Zeichenfolge, was spätere Audits und erneute Prüfungen vereinfacht.

Ein abgeschlossenes Ergebnis kann legitimerweise mit leeren Netzbetreiberfeldern zurückgegeben werden. Speichern Sie es als abgeschlossen-leer, nicht als Fehler und nicht als Beweis für irgendetwas bezüglich des Kontos. Diese Unterscheidung ist wichtig, wenn später jemand ein Dashboard auf Basis dieser Felder erstellt.

Umgang mit Timeouts, unbestimmten Ergebnissen und abgelehnten Eingaben

Drei Fehlerarten erfordern unterschiedliche Codepfade, und deren Zusammenführung ist der häufigste Integrationsfehler.

Die öffentliche API dokumentiert Timeout-Obergrenzen für Einzel- und Mehrfachanfragen sowie eine begrenzte Anzahl gemeinsam genutzter synchroner Slots pro Konto. Halten Sie Ihre Worker-Parallelität unter diesem gemeinsamen Budget, anstatt bei Traffic-Spitzen pro Registrierung parallel einen Request abzufeuern. Fehlgeschlagene oder unbestimmte Abfragen werden nicht berechnet, daher muss sich eine Wiederholungsrichtlinie nicht um doppelte Abrechnungen sorgen, sollte aber die Versuche begrenzen, zum Beispiel drei Versuche über eine Stunde verteilt, und das Konto dann für einen Prüfer mit einem unbestimmten Status belassen.

Den API-Schlüssel auf dem Server behalten

Die REST-API authentifiziert sich mit einem X-API-Key-Header, der ausschließlich von einem vertrauenswürdigen Server gesendet werden darf. Rufen Sie die Abfrage niemals aus Browser-JavaScript oder einem Mobile-App-Bundle auf; jeder kann einen an einen Client ausgelieferten Schlüssel extrahieren und Ihr Guthaben damit verbrauchen.

Praktische Kontrollen gemäß dem OWASP Secrets Management Cheat Sheet:

• Laden Sie den Schlüssel aus einem Secrets-Manager oder dem Secret-Speicher der Deployment-Plattform, nicht aus dem Quellcode.
• Geben Sie nur dem Abfrage-Worker Lesezugriff darauf.
• Rotieren Sie ihn nach Zeitplan und sofort nach einem vermuteten Leck.
• Schreiben Sie niemals den Schlüssel oder vollständige Request-Header in Anwendungsprotokolle.
• Überwachen Sie das Kontoguthaben mit GET /api/v1/balance, das das Guthaben ohne Berechnung liest, und lassen Sie sich bei plötzlichen Abfällen benachrichtigen, die nicht dem Registrierungsvolumen entsprechen.

Schützen Sie auch den Auslöser selbst. Begrenzen Sie die Rate Ihres eigenen Registrierungs-Endpunkts, damit automatisierte Formularübermittlungen nicht zu einem Strom kostenpflichtiger Abfragen werden können.

Verwendung des Ergebnisses bei Routing und Überprüfung

Betrachten Sie Netzbetreiber und Leitungstyp als Eingaben für Regeln, die in Ihrem Verantwortungsbereich liegen, nicht als Urteile. Einige Beispiele, die Teams verwenden:

• Routing-Tests. Gruppieren Sie neue Konten nach ursprünglichem Netzbetreiber und vergleichen Sie in Ihren eigenen Metriken, wie verschiedene Messaging-Anbieter für jede Gruppe abschneiden.
• Prüfschlangen. Senden Sie Konten, deren Leitungstyp nicht den Erwartungen des Produkts entspricht, wie etwa eine Festnetznummer bei einer Mobile-First-App, mit dem angehängten Kontext an einen Prüfer.
• Datenqualität. Markieren Sie Registrierungen, bei denen der Ländercode der Nummer und das im Formular gewählte Land nicht übereinstimmen, damit der Support um eine Korrektur bitten kann.

Schreiben Sie die Regeln auf und halten Sie sie umkehrbar. Ein Prüfer, der ein markiertes Konto betrachtet, sollte die Abfragewerte, die Abfragezeit und die ausgelöste Regel sehen. Da der Netzbetreiber die ursprüngliche Zuweisung widerspiegelt, steht ein Ergebnis niemals allein als Beweis dafür, dass ein Telefon einen Code empfangen kann oder der Person gehört, die sich registriert; kombinieren Sie es mit Ihrem bestehenden Verifizierungsschritt.

FAQ

Wie können Teams viele bestehende Konten prüfen, die sich vor der Integration registriert haben?

Verwenden Sie POST /api/v1/batch-check für den Bestand in Gruppen von bis zu 100 E.164-Nummern pro Request. Die Ergebnisse werden in der Reihenfolge der Eingabe zurückgegeben, und jede Zeile gibt an, ob ein normales Ergebnis existiert. Zeilen ohne normales Ergebnis sollten für einen späteren erneuten Versuch markiert werden, anstatt als leer aufgezeichnet zu werden. Sehr große historische Listen werden besser als asynchrone Bulk-Datei-Aufgabe pro Land übermittelt.

Wie kann ein Backend vermeiden, für dieselbe Nummer zweimal zu bezahlen?

Führen Sie einen Cache, der mit der normalisierten E.164-Zeichenfolge und der Abfragezeit als Schlüssel versehen ist. Wenn eine Nummer bereits ein abgeschlossenes Ergebnis einer kürzlichen Prüfung hat, verwenden Sie dieses wieder, anstatt die API erneut aufzurufen. Der Zuweisungskontext ändert sich langsam, daher aktualisieren viele Teams nur, wenn ein Datensatz bearbeitet wird oder wenn das gespeicherte Ergebnis älter als ein von ihnen gewählter Zeitraum ist, zum Beispiel mehrere Monate.

Wie können Entwickler die Integration vor dem Livegang testen?

Richten Sie den Worker auf eine Staging-Konfiguration mit eigenem API-Schlüssel und kleinem Guthaben aus und führen Sie dann eine skriptgesteuerte Reihe von Fällen aus: eine gültige Mobilfunknummer, eine Festnetznummer, eine Eingabe, die bei der E.164-Normalisierung fehlschlägt, und ein erzwungener Timeout. Bestätigen Sie, dass jeder Pfad den erwarteten Ergebnisstatus schreibt und dass kein Schlüssel oder Header in den Protokollen erscheint, bevor Sie den Produktionstraffic einschalten.

Mehr erfahren

Wählen Sie die Produktinformationen, die zum nächsten Schritt in Ihrem Workflow passen.

• Produktdokumentation ansehen →
• Mit dem Team sprechen →