Authenticatie en API-antwoorden

Gebruik API-referenties

Verzend v3-verzoeken via HTTPS naar https://api.multitel.net. Elk eindpunt in deze handleiding vereist authenticatie. Bewaar referenties op uw server en plaats ze nooit in browser-JavaScript, openbare pagina’s, schermafbeeldingen of versiebeheer.

Gebruik een van deze referentievormen:

• HTTP Basic met de gebruikersnaam en het wachtwoord van API die voor uw MultiTEL-account zijn geconfigureerd.
• Bearer-token in de header Authorization: Bearer YOUR_API_TOKEN, voor een ingeschakeld API-account dat voor tokenauthenticatie is geconfigureerd. Tokenverzoeken worden alleen geaccepteerd vanaf adressen die voor dat API-account zijn toegestaan.

Als een IP-toegestanelijst voor uw API-account is geconfigureerd, verzendt u alle verzoeken vanaf toegestane 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'

De variabelen in deze voorbeelden zijn tijdelijke aanduidingen voor referenties die u privé in uw omgeving opslaat.

Authenticatiefouten afhandelen

Authenticatiefouten worden verzonden met HTTP-status 401. De inhoud gebruikt de standaardenvelop, met status.code ingesteld op 401 en een lege tekenreeks als response.

• Geen referenties: status.msg luidt Username and password are required, en het antwoord bevat een Basic-authenticatie-uitdaging.
• Bearer-token geweigerd: als de header Authorization het schema Bearer gebruikt en het token onbekend, uitgeschakeld of niet vanaf uw adres toegestaan is, heeft status.msg de waarde Invalid bearer token. Er worden geen andere referenties geprobeerd wanneer een Bearer-header aanwezig is.
• Ongeldige Basic-referenties: status.msg begint met A valid username and password pair are required., en het antwoord bevat een Basic-authenticatie-uitdaging. Het bericht kan meer diagnostische tekst bevatten, dus ontleed het niet.

Probeer het niet automatisch opnieuw met dezelfde referenties. Veel mislukte pogingen vanaf een adres binnen korte tijd kunnen ertoe leiden dat verdere verzoeken vanaf dat adres worden geblokkeerd.

Lees de antwoordinhoud

De meeste v3-eindpunten, waaronder getcountries, getstates, getareas en other, retourneren JSON in deze envelop:

{
  "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"
    }
  ]
}

Dit is een illustratief antwoord met een landenlijst, geen verklaring over de actuele voorraad of mogelijkheden.

Een foutantwoord ziet er zo uit:

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

Als een antwoord niet kan worden gecodeerd, bevat de inhoud status.code 500, status.msg Response encoding error, en een leeg object als response.

Het verouderde eindpunt GET /v3/countries retourneert {"code": 200, "data": [...]} in plaats daarvan. Controleer het gedocumenteerde antwoord van elk eindpunt. Als een inhoud geen geldige JSON is, bijvoorbeeld na een onverwachte serverfout, beschouw het verzoek dan als mislukt en probeer het later opnieuw.

API-resultaatcodes en HTTP-status

status.code is de API-resultaatcode. Het is niet de HTTP-status. Authenticatiefouten worden verzonden met HTTP 401. Anders melden de detectie-eindpunten uitkomsten zoals 404 en 500 alleen in status.code en stellen geen overeenkomende HTTP-status in. Een niet-gevonden- of ontbrekende-parameterresultaat kan daarom met een succesvolle HTTP-status aankomen. Controleer altijd status.code voor gebruik van response.

Resultaatcode 500 met het bericht ISO Code parameter is required betekent dat een vereiste parameter ontbreekt. Corrigeer het verzoek in plaats van het als een serverstoring te behandelen.

Volg next_function

Detectieresultaten bevatten next_function. Het is een relatief pad zonder voorloopslash, soms met een queryreeks, zoals v3/getareas/US of v3/getareas/US?state=NY. Plaats ervoor https://api.multitel.net/ om het volgende verzoek op te bouwen, en authenticeer dat verzoek op dezelfde manier. Optionele filters die u hebt verzonden, zoals pid, worden niet meegenomen in next_function. Voeg ze opnieuw toe als u ze nodig hebt.

Optionele voorraadkiezer (pid)

getcountries, getstates en getareas accepteren een optionele queryparameter pid die resultaten tot een voorraadbron beperkt. Gebruik deze alleen met een waarde die door MultiTEL is verstrekt, in de numerieke vorm of in de 32-teken hexadecimale vorm. Laat deze weg voor normaal gebruik. Verzend pid in de queryreeks. Als het eindpunt de waarde niet herkent of niet accepteert, negeert het deze zonder fout, en gedraagt het verzoek zich alsof pid was weggelaten.

Scheid detectie van bestellingen

Zoekopdrachten voor landen, staten en gebieden wijzigen uw account niet. De catalogus voor speciale nummers (other) ververst catalogusdetails en bewaart prijsoffertes voor uw account, maar plaatst geen bestelling. Geen enkel detectieverzoek reserveert een nummer, en de voorraad kan tussen verzoeken veranderen. Controleer de vereisten en de prijs voor een nummer voordat u een besteleindpunt gebruikt.

Volg voor aankopen, toewijzingen, berichten, faxverzendingen en andere acties de eigen regels voor opnieuw proberen van dat eindpunt. Als een actie na indiening een time-out krijgt, controleer dan de status ervan of uw accountgegevens voordat u deze herhaalt. Een verloren antwoord bewijst niet dat de actie is mislukt.