Authentifizierung und API-Antworten

Verwenden Sie API-Anmeldedaten

Senden Sie v3-Anfragen über HTTPS an https://api.multitel.net. Jeder Endpunkt in dieser Anleitung erfordert eine Authentifizierung. Bewahren Sie Anmeldedaten auf Ihrem Server auf und geben Sie sie niemals in Browser-JavaScript, öffentliche Seiten, Screenshots oder die Quellcodeverwaltung ein.

Verwenden Sie eine dieser Anmeldedatenformen:

HTTP Basic mit dem API-Benutzernamen und dem Passwort, die für Ihr MultiTEL-Konto konfiguriert sind.
Bearer-Token in einem Header Authorization: Bearer YOUR_API_TOKEN, für ein aktiviertes API-Konto, das für die Token-Authentifizierung konfiguriert ist. Token-Anfragen werden nur von Adressen akzeptiert, die für dieses API-Konto zugelassen sind.

Wenn eine IP-Allowlist für Ihr API-Konto konfiguriert ist, senden Sie alle Anfragen von zugelassenen Adressen.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

Die Variablen in diesen Beispielen sind Platzhalter für Anmeldedaten, die Sie privat in Ihrer Umgebung speichern.

Behandeln Sie Authentifizierungsfehler

Authentifizierungsfehler werden mit HTTP-Status 401 gesendet. Der Antwortkörper verwendet die Standard-Hüllstruktur, wobei status.code auf den Wert 401 gesetzt ist und eine leere Zeichenkette als response verwendet wird.

Keine Anmeldedaten: status.msg lautet Username and password are required, und die Antwort enthält eine Basic-Authentifizierungsaufforderung.
Bearer-Token abgelehnt: wenn der Authorization-Header das Bearer-Schema verwendet und das Token unbekannt, deaktiviert oder von Ihrer Adresse aus nicht zugelassen ist, wird für status.msg folgender Wert zurückgegeben: Invalid bearer token. Es werden keine anderen Anmeldedaten versucht, wenn ein Bearer-Header vorhanden ist.
Ungültige Basic-Anmeldedaten: status.msg beginnt mit A valid username and password pair are required., und die Antwort enthält eine Basic-Authentifizierungsaufforderung. Die Meldung kann weiteren Diagnosetext enthalten, daher werten Sie sie nicht programmatisch aus.

Versuchen Sie es nicht automatisch mit denselben Anmeldedaten erneut. Viele fehlgeschlagene Versuche von einer Adresse innerhalb eines kurzen Zeitraums können dazu führen, dass weitere Anfragen von dieser Adresse blockiert werden.

Lesen Sie den Antwortkörper

Die meisten v3-Endpunkte, einschließlich getcountries, getstates, getareas und other, geben JSON in dieser Hüllstruktur zurück:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

Dies ist eine beispielhafte Länderlisten-Antwort, keine Aussage über den aktuellen Bestand oder die aktuellen Fähigkeiten.

Feld	Bedeutung
`status.code`	Der API-Ergebniscode, zum Beispiel `200`, `401`, `404` oder `500`.
`status.msg`	Eine menschenlesbare Meldung. Sie kann leer sein. Stützen Sie die Programmlogik auf `status.code`, nicht auf den Meldungstext.
`status.results`	Die Anzahl der Einträge. Für die hier dokumentierten Ermittlungs-Endpunkte ist sie vorhanden, wenn `response` eine JSON-Liste ist, einschließlich einer leeren Liste (`0`). Sie fehlt, wenn `response` eine leere Zeichenkette oder `null` ist. Andere Endpunkt-Nutzlasten können eine Anzahl anders melden; folgen Sie der jeweiligen Antwortdokumentation.
`response`	Die Endpunkt-Nutzlast. Ihr Typ hängt vom Endpunkt und vom Ergebnis ab. Bei Fehlern ist sie eine leere Zeichenkette.

Eine Fehlerantwort sieht so aus:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Wenn eine Antwort nicht kodiert werden kann, enthält der Körper status.code 500, status.msg Response encoding error, und ein leeres Objekt als response.

Der ältere Endpunkt GET /v3/countries gibt stattdessen {"code": 200, "data": [...]} zurück. Prüfen Sie die dokumentierte Antwort jedes Endpunkts. Wenn ein Körper kein gültiges JSON ist, zum Beispiel nach einem unerwarteten Serverfehler, behandeln Sie die Anfrage als fehlgeschlagen und versuchen Sie es später erneut.

API-Ergebniscodes und HTTP-Status

status.code ist der API-Ergebniscode. Es ist nicht der HTTP-Status. Authentifizierungsfehler werden mit HTTP 401 gesendet. Andernfalls melden die Ermittlungs-Endpunkte Ergebnisse wie 404 und 500 nur in status.code und legen keinen passenden HTTP-Status fest. Ein Nicht-gefunden- oder Fehlender-Parameter-Ergebnis kann daher mit einem erfolgreichen HTTP-Status eintreffen. Prüfen Sie immer status.code vor der Verwendung von response.

Ergebniscode 500 mit der Meldung ISO Code parameter is required bedeutet, dass ein erforderlicher Parameter fehlt. Korrigieren Sie die Anfrage, statt sie als Serverausfall zu behandeln.

Folgen Sie next_function

Ermittlungsergebnisse enthalten next_function. Es ist ein relativer Pfad ohne führenden Schrägstrich, manchmal mit einer Abfragezeichenkette, wie zum Beispiel v3/getareas/US oder v3/getareas/US?state=NY. Stellen Sie https://api.multitel.net/ voran, um die nächste Anfrage zu erstellen, und authentifizieren Sie diese Anfrage auf dieselbe Weise. Optionale Filter, die Sie gesendet haben, wie zum Beispiel pid, werden nicht in next_function übernommen. Fügen Sie sie erneut hinzu, wenn Sie sie benötigen.

Optionaler Bestandsselektor (pid)

getcountries, getstates und getareas akzeptieren einen optionalen pid-Abfrageparameter, der Ergebnisse auf eine Bestandsquelle eingrenzt. Verwenden Sie ihn nur mit einem von MultiTEL bereitgestellten Wert, entweder in seiner numerischen Form oder in seiner 32-stelligen hexadezimalen Form. Lassen Sie ihn bei normaler Verwendung weg. Senden Sie pid in der Abfragezeichenkette. Wenn der Endpunkt den Wert nicht erkennt oder akzeptiert, ignoriert er ihn ohne Fehler, und die Anfrage verhält sich so, als ob pid weggelassen worden wäre.

Trennen Sie Ermittlung und Bestellungen

Länder-, Bundesland- und Gebietsabfragen ändern Ihr Konto nicht. Der Katalog für Sondernummern (other) aktualisiert Katalogdetails und speichert Preisangebote für Ihr Konto, gibt aber keine Bestellung auf. Keine Ermittlungsanfrage reserviert eine Nummer, und der Bestand kann sich zwischen Anfragen ändern. Prüfen Sie die Anforderungen und den Preis für eine Nummer, bevor Sie einen Bestell-Endpunkt verwenden.

Befolgen Sie für Käufe, Zuweisungen, Nachrichten, Faxversand und andere Aktionen die jeweiligen Wiederholungsregeln dieses Endpunkts. Wenn eine Aktion nach dem Absenden eine Zeitüberschreitung aufweist, prüfen Sie ihren Status oder Ihre Kontodatensätze, bevor Sie sie wiederholen. Eine verlorene Antwort beweist nicht, dass die Aktion fehlgeschlagen ist.