Autentisering och API-svar

Använd API-autentiseringsuppgifter

Skicka v3-begäranden över HTTPS till https://api.multitel.net. Alla slutpunkter i den här guiden kräver autentisering. Behåll autentiseringsuppgifterna på din server och placera dem aldrig i webbläsarens JavaScript, på offentliga sidor, i skärmbilder eller i källkodshantering.

Använd en av dessa autentiseringsformer:

• HTTP Basic med API-användarnamnet och lösenordet som har konfigurerats för ditt MultiTEL-konto.
• Bearer-token i headern Authorization: Bearer YOUR_API_TOKEN, för ett aktiverat API-konto som har konfigurerats för tokenautentisering. Tokenbegäranden accepteras endast från adresser som är tillåtna för det API-kontot.

Om en IP-tillåtelselista är konfigurerad för ditt API-konto, skicka alla begäranden från tillåtna 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'

Variablerna i dessa exempel är platshållare för autentiseringsuppgifter som du lagrar privat i din miljö.

Hantera autentiseringsfel

Autentiseringsfel skickas med HTTP-status 401. Kroppen använder standardkuvertet, med status.code satt till 401 och en tom sträng som response.

• Inga autentiseringsuppgifter: status.msg är Username and password are required, och svaret innehåller en Basic-autentiseringsutmaning.
• Bearer-token avvisad: om headern Authorization använder schemat Bearer och token är okänd, inaktiverad eller inte tillåten från din adress, har status.msg värdet Invalid bearer token. Inga andra autentiseringsuppgifter prövas när en Bearer-header finns.
• Ogiltiga Basic-autentiseringsuppgifter: status.msg börjar med A valid username and password pair are required., och svaret innehåller en Basic-autentiseringsutmaning. Meddelandet kan innehålla mer diagnostext, så parsa det inte i programkod.

Försök inte automatiskt igen med samma autentiseringsuppgifter. Många misslyckade försök från en adress inom en kort period kan leda till att ytterligare begäranden från den adressen blockeras.

Läs svarskroppen

De flesta v3-slutpunkter, inklusive getcountries, getstates, getareas och other, returnerar JSON i detta 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"
    }
  ]
}

Detta är ett illustrativt landlistsvar, inte ett uttalande om aktuellt lager eller aktuella funktioner.

Ett felsvar ser ut så här:

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

Om ett svar inte kan kodas har kroppen status.code 500, status.msg Response encoding error, och ett tomt objekt som response.

Den äldre slutpunkten GET /v3/countries returnerar {"code": 200, "data": [...]} i stället. Kontrollera varje slutpunkts dokumenterade svar. Om en kropp inte är giltig JSON, till exempel efter ett oväntat serverfel, behandla begäran som misslyckad och försök igen senare.

API-resultatkoder och HTTP-status

status.code är API-resultatkoden. Det är inte HTTP-statusen. Autentiseringsfel skickas med HTTP 401. I övrigt rapporterar upptäcktsslutpunkterna resultat som 404 och 500 endast i status.code och anger inte en matchande HTTP-status. Ett resultat som anger att något inte hittades eller att en parameter saknas kan därför ankomma med en lyckad HTTP-status. Kontrollera alltid status.code innan du använder response.

Resultatkod 500 med meddelandet ISO Code parameter is required betyder att en obligatorisk parameter saknas. Korrigera begäran i stället för att behandla den som ett serveravbrott.

Följ next_function

Upptäcktsresultaten innehåller next_function. Det är en relativ sökväg utan inledande snedstreck, ibland med en frågesträng, till exempel v3/getareas/US eller v3/getareas/US?state=NY. Prefixa den med https://api.multitel.net/ för att bygga nästa begäran, och autentisera den begäran på samma sätt. Valfria filter som du skickade, till exempel pid, överförs inte till next_function. Lägg till dem igen om du behöver dem.

Valfri lagerväljare (pid)

getcountries, getstates och getareas accepterar en valfri frågeparameter pid som begränsar resultaten till en lagerkälla. Använd den endast med ett värde från MultiTEL, antingen i dess numeriska form eller i dess hexadecimala form med 32 tecken. Uteslut den vid normal användning. Skicka pid i frågesträngen. Om slutpunkten inte känner igen eller accepterar värdet ignorerar den det utan fel, och begäran beter sig som om pid hade utelämnats.

Separera upptäckt från beställningar

Land-, delstats- och områdesuppslagningar ändrar inte ditt konto. Katalogen för specialnummer (other) uppdaterar kataloguppgifter och sparar prisofferter för ditt konto, men den lägger ingen beställning. Ingen upptäcktsbegäran reserverar ett nummer, och lagret kan ändras mellan begäranden. Granska kraven och priset för ett nummer innan du använder en beställningsslutpunkt.

För köp, tilldelningar, meddelanden, faxsändningar och andra åtgärder, följ den slutpunktens egna återförsöksregler. Om tidsgränsen löper ut efter att en åtgärd har skickats, kontrollera dess status eller dina kontoposter innan du upprepar den. Ett förlorat svar bevisar inte att åtgärden misslyckades.