Autentisering og API-svar

Bruk API-legitimasjon

Send v3-forespørsler via HTTPS til https://api.multitel.net. Hvert endepunkt i denne veiledningen krever autentisering. Oppbevar legitimasjonen på serveren din, og legg den aldri i nettleserens JavaScript, på offentlige sider, i skjermbilder eller i kildekontroll.

Bruk én av disse legitimasjonsformene:

• HTTP Basic med API-brukernavnet og passordet som er konfigurert for MultiTEL-kontoen din.
• Bearer-token i headeren Authorization: Bearer YOUR_API_TOKEN, for en aktivert API-konto konfigurert for tokenautentisering. Tokenforespørsler godtas kun fra adresser som er tillatt for den API-kontoen.

Hvis en IP-tillatelsesliste er konfigurert for API-kontoen din, send alle forespørsler fra tillatte 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'

Variablene i disse eksemplene er plassholdere for legitimasjon du lagrer privat i miljøet ditt.

Håndter autentiseringsfeil

Autentiseringsfeil sendes med HTTP-status 401. Kroppen bruker standardkonvolutten, med status.code satt til 401 og en tom streng som response.

• Ingen legitimasjon: status.msg er Username and password are required, og svaret inkluderer en Basic-autentiseringsutfordring.
• Bearer-token avvist: hvis headeren Authorization bruker skjemaet Bearer og tokenet er ukjent, deaktivert eller ikke tillatt fra adressen din, har status.msg verdien Invalid bearer token. Ingen annen legitimasjon prøves når en Bearer-header er til stede.
• Ugyldig Basic-legitimasjon: status.msg begynner med A valid username and password pair are required., og svaret inkluderer en Basic-autentiseringsutfordring. Meldingen kan inneholde mer diagnostisk tekst, så ikke analyser den programmatisk.

Ikke prøv på nytt automatisk med samme legitimasjon. Mange mislykkede forsøk fra én adresse i løpet av kort tid kan føre til at videre forespørsler fra den adressen blokkeres.

Les svarkroppen

De fleste v3-endepunkter, inkludert getcountries, getstates, getareas og other, returnerer JSON i denne konvolutten:

{
  "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 illustrerende svar med en liste over land, ikke en uttalelse om gjeldende beholdning eller funksjoner.

En feilrespons ser slik ut:

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

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

Det gamle endepunktet GET /v3/countries returnerer {"code": 200, "data": [...]} i stedet. Sjekk hvert endepunkts dokumenterte svar. Hvis en kropp ikke er gyldig JSON, for eksempel etter en uventet serverfeil, behandle forespørselen som mislykket og prøv på nytt senere.

API-resultatkoder og HTTP-status

status.code er API-resultatkoden. Den er ikke HTTP-statusen. Autentiseringsfeil sendes med HTTP 401. Ellers rapporterer søkeendepunktene resultater som 404 og 500 kun i status.code og setter ikke en tilsvarende HTTP-status. Et ikke-funnet- eller manglende-parameter-resultat kan derfor ankomme med en vellykket HTTP-status. Sjekk alltid status.code før du bruker response.

Resultatkode 500 med meldingen ISO Code parameter is required betyr at en obligatorisk parameter mangler. Rett forespørselen i stedet for å behandle den som et serverbrudd.

Følg next_function

Søkeresultater inkluderer next_function. Det er en relativ bane uten innledende skråstrek, noen ganger med en spørrestreng, for eksempel v3/getareas/US eller v3/getareas/US?state=NY. Prefiks den med https://api.multitel.net/ for å bygge neste forespørsel, og autentiser den forespørselen på samme måte. Valgfrie filtre du sendte, for eksempel pid, blir ikke overført til next_function. Legg dem til igjen hvis du trenger dem.

Valgfri beholdningsvelger (pid)

getcountries, getstates og getareas godtar en valgfri spørringsparameter pid som begrenser resultater til én beholdningskilde. Bruk den kun med en verdi gitt av MultiTEL, enten i numerisk variant eller i 32-tegns heksadesimal variant. Utelat den ved vanlig bruk. Send pid i spørrestrengen. Hvis endepunktet ikke gjenkjenner eller godtar verdien, ignorerer det den uten feil, og forespørselen oppfører seg som om pid var utelatt.

Skill søk fra bestillinger

Land-, delstat- og områdesøk endrer ikke kontoen din. Spesialnummerkatalogen (other) oppdaterer katalogdetaljer og lagrer pristilbud for kontoen din, men den legger ikke inn en bestilling. Ingen søkeforespørsel reserverer et nummer, og beholdningen kan endres mellom forespørsler. Gå gjennom kravene og prisen for et nummer før du bruker et bestillingsendepunkt.

For kjøp, tildelinger, meldinger, fakssendinger og andre handlinger, følg det endepunktets egne regler for nye forsøk. Hvis en handling får tidsavbrudd etter innsending, sjekk statusen eller kontopostene dine før du gjentar den. Et tapt svar beviser ikke at handlingen mislyktes.