Ein Registrierungsprofil für eine Rufnummer einreichen

Gespeichertes Profil und Rufnummer vorbereiten

Mit diesem Ablauf verknüpfen Sie ein gespeichertes Registrierungsprofil mit einer gekauften Rufnummer und beantragen bei unterstützten, über einen Netzbetreiber bereitgestellten Rufnummern die Prüfung der Registrierung. Dies ist keine allgemeine Aktivierungs-API für sämtliche Rufnummernanbieter. Eine erfolgreiche Anfrage belegt weder, dass die Dokumente genehmigt wurden, noch, dass die Rufnummer aktiv ist.

Verwenden Sie ein freigeschaltetes MultiTEL-API-Konto über HTTPS mit den dafür konfigurierten Zugangsdaten und IP-Beschränkungen. Sowohl das nicht gelöschte Profil als auch die gekaufte, nicht annullierte Rufnummer müssen zu Ihrem Konto gehören.

Erstellen Sie ein Registrierungsprofil oder wählen Sie ein vorhandenes aus. Bewahren Sie die lokale Profilkennung uuid aus create_document auf; get_document gibt dieselbe lokale Referenz als id zurück.
Für eine Einreichung beim Netzbetreiber benötigt das Profil seine gespeicherten Identitäts- und Adressreferenzen. Fügen Sie die erforderlichen Nachweise und ergänzenden Dokumente vor der Einreichung über die jeweils vorgesehenen Abläufe hinzu.
Prüfen Sie, ob Rufnummer und Profil die geltenden Anforderungen für das Land und die Rufnummer erfüllen. Gehen Sie nicht davon aus, dass ein gespeichertes Profil für jede Rufnummer genehmigt ist.

Verknüpfung einreichen

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

Der Pfad enthält die gekaufte Telefonnummer, nicht deren UUID, eine Nebenstelle einer Telefonanlage oder eine Identitäts-ID. Der Anfragehandler entfernt alle Zeichen außer Ziffern aus der Rufnummer. Verwenden Sie die vollständige internationale Rufnummer mit Ländervorwahl. Das Beispiel ist fiktiv und muss durch Ihre eigene Rufnummer und die gespeicherte lokale Profilreferenz ersetzt werden.

Felder zur Einreichung der Registrierung
Feld	Erforderlich	Bedeutung
`document_uuid`	Ja	Die exakte gespeicherte lokale Profilkennung uuid. Verwenden Sie stattdessen weder die maskierte entfernte Kennung identity_id oder address_id noch eine Upload-ID oder einen zurückgegebenen Wert von registration_details_id.
`service_description`	Nein	Eine Beschreibung des vorgesehenen Dienstes, die zur Überprüfung durch den Netzbetreiber weitergeleitet wird. Führende und nachfolgende Leerzeichen werden entfernt.
`onetime_files`	Vom Ablauf abhängig	Ein Array für Dokumente, die einmalig beim Netzbetreiber einzureichen sind. Der aktuelle Anfragehandler entfernt führende und nachfolgende Leerzeichen aus den Zeichenfolgen und leitet sie weiter, ohne lokale Upload-Referenzen aufzulösen. Die Kompatibilität mit den von create_encrypt_files zurückgegebenen maskierten IDs ist nicht nachgewiesen; beachten Sie vor der Verwendung dieses Feldes die unten beschriebene Einschränkung für einmalig einzureichende Dokumente.

Bei Multipart-Anfragen wird ein Array durch wiederholte Felder onetime_files[] übergeben. Auch eine JSON-Anfrage mit Content-Type: application/json wird akzeptiert; ihre Eigenschaften werden mit den Formulardaten zusammengeführt. Das Feld number kann in den Nutzdaten angegeben werden, wenn die Rufnummer im Pfad fehlt. Verwenden Sie vorzugsweise den oben ausdrücklich angegebenen Pfad, um Mehrdeutigkeiten zu vermeiden.

Verknüpfung und Genehmigung unterscheiden

Prüfen Sie sowohl das HTTP-Ergebnis als auch status.code in der JSON-Antwort. JSON-Fehler können mit HTTP 200 zurückgegeben werden. Bei einer erfolgreichen Einreichung beim Netzbetreiber lautet die Meldung: Address verification task created; awaiting carrier review. Dieses Beispiel verwendet fiktive Referenzen.

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

Die anbieterbezogenen Kennungen sind maskierte Referenzen und keine austauschbaren lokalen Profil-IDs. document_uuid bleibt die von Ihnen eingereichte lokale Profilreferenz. Im Verarbeitungspfad dieses Anfragehandlers für Netzbetreiber ist registration_details_id ein weiterer Hashwert dieser lokalen Referenz; ersetzen Sie document_uuid bei späteren Profil- oder Einreichungsanfragen nicht durch diesen Wert.

Bei einigen zugeteilten Rufnummern wird die Identität lokal verknüpft, statt eine Überprüfung beim Netzbetreiber anzulegen. Das erfolgreiche Ergebnis lautet Identity associated. und enthält ein leeres Array response. Dadurch wird weder ein Prüfauftrag beim Netzbetreiber angelegt noch eine Genehmigung bestätigt. Das Portal bietet einen neueren Ablauf zur Verknüpfung, dessen Anbieterbehandlung und Prüfungen auf wiederholte Einreichungen sich von diesem Endpunkt unterscheiden.

Fehler behandeln, ohne doppelte Aufträge anzulegen

API-Code 400 steht für eine fehlende Rufnummer oder Profilreferenz. Code 404 steht für ein Profil oder eine Rufnummer, die für das Konto nicht verfügbar sind, oder für eine Rufnummer, die im Bestand des Netzbetreibers fehlt. Code 422 kann fehlende Identitäts- oder Adressreferenzen, Anforderungen des Verkäufers oder eine Ablehnung bei der Validierung durch den Netzbetreiber melden. Eine fehlende Callback-Konfiguration kann zu 503 führen, ein Übertragungsfehler beim Anlegen zu 502. Lesen Sie die Meldung und gegebenenfalls requirement_diagnostics, statt alle Fehler gleich zu behandeln.

Der Verarbeitungspfad für Netzbetreiber kann lokale Kennzeichen für ausstehende Registrierungen aktualisieren, bevor die Anforderungsvalidierung, die Prüfung der Callback-Konfiguration oder das Anlegen des Auftrags abgeschlossen sind. Ein Fehler bedeutet daher nicht, dass der lokale Zustand unverändert geblieben ist, und ein Kennzeichen für einen ausstehenden Vorgang allein belegt nicht, dass ein Auftrag existiert. Verwenden Sie diese Kennzeichen nicht als Bestätigung einer Genehmigung oder der Zustellung der Anfrage.

Der Anbieter kann einen Auftrag annehmen, selbst wenn ein späterer lokaler Datenbankvorgang fehlschlägt, und diese Hilfsfunktion prüft nicht das Ergebnis jedes lokalen Schreibvorgangs, bevor sie Erfolg meldet. Dieser Anfragehandler bietet weder einen clientseitigen Idempotenzparameter noch einen Schutz vor doppelten Einreichungen. Prüfen Sie nach einer Zeitüberschreitung, einem Fehler oder einem unklaren Ergebnis den Registrierungsverlauf der Rufnummer im Portal oder wenden Sie sich an den Support, bevor Sie die Anfrage erneut einreichen. Ein fehlender lokaler Datensatz allein belegt nicht, dass der Anbieter nichts erhalten hat.

Einschränkung bei einmalig einzureichenden Dokumenten

Der Anfragehandler akzeptiert onetime_files und leitet jede nicht leere Zeichenfolge in die Zuordnung verschlüsselter Dateien beim Netzbetreiber weiter. Er schlägt weder die Upload-Datensätze des zugehörigen Kontos nach noch wandelt er externe maskierte Upload-IDs in Datei-IDs des Anbieters um. Die Offline-Prüfung hat das Weiterleitungsverhalten bestätigt, nicht das erfolgreiche Anhängen beim Netzbetreiber.

Gehen Sie nicht davon aus, dass eine Datei-ID aus create_encrypt_files in dieses Feld kopiert werden kann, um einen Ablauf für eine einmalige Vereinbarung abzuschließen. Verwenden Sie das Portal oder klären Sie mit MultiTEL den unterstützten Ablauf für Kennungen, wenn eine Rufnummer diese Dokumente erfordert. Dieser Teil der API-Prüfung bleibt ungeklärt und ist kein durchgängig überprüftes Beispiel.

Registrierungsinformationen schützen

Reichen Sie nur Informationen und Dokumente ein, die Sie für die Rufnummer verwenden dürfen. Ordnen Sie Profil- und Überprüfungsreferenzen stets dem richtigen Konto zu und vermeiden Sie es, vollständige Registrierungsnutzdaten zu protokollieren. Diese Anfrage löscht oder ersetzt nicht sämtliche früheren Nachweise oder Überprüfungen. Die Prüfung durch den Netzbetreiber, die Aktivierung und die Aufbewahrung sind separate Prozesse.