Godkendelse og API-svar

Brug API-legitimationsoplysninger

Send v3-anmodninger over HTTPS til https://api.multitel.net. Alle slutpunkter i denne vejledning kræver godkendelse. Opbevar legitimationsoplysninger på din server, og læg dem aldrig i browser-JavaScript, offentlige sider, skærmbilleder eller kildekontrol.

Brug en af disse legitimationsformer:

• HTTP Basic med det API-brugernavn og den adgangskode, der er konfigureret til din MultiTEL-konto.
• Bearer-token i headeren Authorization: Bearer YOUR_API_TOKEN til en aktiveret API-konto, der er konfigureret til tokengodkendelse. Tokenanmodninger accepteres kun fra adresser, der er tilladt for den pågældende API-konto.

Hvis der er konfigureret en IP-tilladelsesliste til din API-konto, skal du sende alle anmodninger fra tilladte adresser.

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

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

Variablerne i disse eksempler er pladsholdere for legitimationsoplysninger, som du opbevarer privat i dit miljø.

Håndter godkendelsesfejl

Godkendelsesfejl sendes med HTTP-status 401. Brødteksten bruger standardkuverten, med status.code sat til 401 og en tom streng som response.

• Ingen legitimationsoplysninger: status.msg er Username and password are required, og svaret indeholder en Basic-godkendelsesudfordring.
• Bearer-token afvist: hvis headeren Authorization bruger skemaet Bearer og tokenet er ukendt, deaktiveret eller ikke tilladt fra din adresse, har status.msg værdien Invalid bearer token. Der forsøges ikke med andre legitimationsoplysninger, når der findes en Bearer-header.
• Ugyldige Basic-legitimationsoplysninger: status.msg starter med A valid username and password pair are required., og svaret indeholder en Basic-godkendelsesudfordring. Meddelelsen kan indeholde mere diagnostisk tekst, så du må ikke parse den i programkode.

Forsøg ikke automatisk igen med de samme legitimationsoplysninger. Mange mislykkede forsøg fra én adresse inden for en kort periode kan medføre, at yderligere anmodninger fra den pågældende adresse blokeres.

Læs svarteksten

De fleste v3-slutpunkter, herunder getcountries, getstates, getareas og other, returnerer JSON i denne kuvert:

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

Dette er et illustrativt landelistesvar, ikke en erklæring om aktuel beholdning eller funktioner.

Et fejlsvar ser sådan ud:

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

Hvis et svar ikke kan kodes, har brødteksten status.code 500, status.msg Response encoding error, og et tomt objekt som response.

Det ældre slutpunkt GET /v3/countries returnerer {"code": 200, "data": [...]} i stedet. Tjek hvert slutpunkts dokumenterede svar. Hvis en brødtekst ikke er gyldig JSON, f.eks. efter en uventet serverfejl, skal du behandle anmodningen som mislykket og prøve igen senere.

API-resultatkoder og HTTP-status

status.code er API-resultatkoden. Den er ikke HTTP-statusen. Godkendelsesfejl sendes med HTTP 401. Ellers rapporterer søgeslutpunkterne resultater som f.eks. 404 og 500 kun i status.code og angiver ikke en tilsvarende HTTP-status. Et resultat, der angiver, at noget ikke blev fundet, eller at en parameter mangler, kan derfor ankomme med en vellykket HTTP-status. Tjek altid status.code før du bruger response.

Resultatkode 500 med meddelelsen ISO Code parameter is required betyder, at en påkrævet parameter mangler. Ret anmodningen i stedet for at opfatte det som et servernedbrud.

Følg next_function

Søgeresultater indeholder next_function. Det er en relativ sti uden indledende skråstreg, nogle gange med en forespørgselsstreng, f.eks. v3/getareas/US eller v3/getareas/US?state=NY. Sæt https://api.multitel.net/ foran for at opbygge den næste anmodning, og godkend den anmodning på samme måde. Valgfrie filtre, du har sendt, f.eks. pid, overføres ikke til next_function. Tilføj dem igen, hvis du har brug for dem.

Valgfri beholdningsvælger (pid)

getcountries, getstates og getareas accepterer en valgfri forespørgselsparameter pid, der indsnævrer resultaterne til én beholdningskilde. Brug den kun med en værdi fra MultiTEL, enten i dens numeriske form eller i dens 32-tegns hexadecimale form. Udelad den ved normal brug. Send pid i forespørgselsstrengen. Hvis slutpunktet ikke genkender eller accepterer værdien, ignorerer det den uden fejl, og anmodningen opfører sig, som om pid var udeladt.

Adskil søgning fra ordrer

Opslag efter land, stat og område ændrer ikke din konto. Specialnummerkataloget (other) opdaterer katalogoplysninger og gemmer pristilbud for din konto, men afgiver ikke en ordre. Ingen søgeanmodning reserverer et nummer, og beholdningen kan ændre sig mellem anmodninger. Gennemgå kravene og prisen for et nummer, før du bruger et bestillingsslutpunkt.

Ved køb, tildelinger, beskeder, faxafsendelser og andre handlinger skal du følge det pågældende slutpunkts egne regler for nye forsøg. Hvis en handling overskrider tidsgrænsen efter indsendelse, skal du kontrollere dens status eller dine kontooplysninger, før du gentager den. Et mistet svar beviser ikke, at handlingen mislykkedes.