Todennus ja API-vastaukset

Käytä API-tunnistetietoja

Lähetä v3-pyynnöt HTTPS:n kautta osoitteeseen https://api.multitel.net. Jokainen tämän oppaan päätepiste vaatii todennuksen. Säilytä tunnistetiedot palvelimellasi äläkä koskaan sijoita niitä selaimen JavaScript-koodiin, julkisille sivuille, kuvakaappauksiin tai lähdekoodinhallintaan.

Käytä jotakin näistä tunnistetietomuodoista:

• HTTP Basic API-käyttäjätunnuksella ja salasanalla, jotka on määritetty MultiTEL-tilillesi.
• Bearer-tunnus otsakkeessa Authorization: Bearer YOUR_API_TOKEN, kun kyseessä on käyttöön otettu API-tili, joka on määritetty tunnistepohjaiseen todennukseen. Tunnistepyynnöt hyväksytään vain osoitteista, jotka on sallittu kyseiselle API-tilille.

Jos sallittujen IP-osoitteiden luettelo on määritetty API-tilillesi, lähetä kaikki pyynnöt sallituista osoitteista.

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

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

Näiden esimerkkien muuttujat ovat paikkamerkkejä tunnistetiedoille, joita säilytät yksityisesti ympäristössäsi.

Käsittele todennusvirheet

Todennusvirheet lähetetään HTTP-tilalla 401. Runko käyttää vakiokuorta, jossa status.code on 401 ja tyhjä merkkijono kentässä response.

• Ei tunnistetietoja: status.msg on Username and password are required, ja vastaus sisältää Basic-todennushaasteen.
• Bearer-tunnus hylätty: jos Authorization-otsikko käyttää Bearer-skeemaa ja tunnus on tuntematon, poistettu käytöstä tai sitä ei ole sallittu osoitteestasi, status.msg on Invalid bearer token. Muita tunnistetietoja ei kokeilla, kun Bearer-otsikko on läsnä.
• Virheelliset Basic-tunnistetiedot: status.msg alkaa merkkijonolla A valid username and password pair are required., ja vastaus sisältää Basic-todennushaasteen. Viesti voi sisältää lisää diagnostiikkatekstiä, joten älä jäsennä sitä.

Älä yritä automaattisesti uudelleen samoilla tunnistetiedoilla. Monet epäonnistuneet yritykset yhdestä osoitteesta lyhyessä ajassa voivat johtaa siihen, että kyseisestä osoitteesta tulevat lisäpyynnöt estetään.

Lue vastauksen runko

Useimmat v3-päätepisteet, mukaan lukien getcountries, getstates, getareas ja other, palauttavat vastauksen JSON-muodossa tässä kuoressa:

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

Tämä on havainnollistava maaluettelon vastaus, ei väite nykyisestä varastosta tai ominaisuuksista.

Virhevastaus näyttää tältä:

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

Jos vastausta ei voida koodata, rungossa on status.code 500, status.msg Response encoding error, ja tyhjä objekti kentässä response.

Vanha päätepiste GET /v3/countries palauttaa tämän sijaan {"code": 200, "data": [...]}. Tarkista kunkin päätepisteen dokumentoitu vastaus. Jos runko ei ole kelvollinen JSON, esimerkiksi odottamattoman palvelinvirheen jälkeen, käsittele pyyntö epäonnistuneena ja yritä myöhemmin uudelleen.

API-tuloskoodit ja HTTP-tila

status.code on API-tuloskoodi. Se ei ole HTTP-tila. Todennusvirheet lähetetään arvolla HTTP 401. Muuten hakupäätepisteet ilmoittavat tuloksia, kuten 404 ja 500 vain kohdassa status.code eivätkä aseta vastaavaa HTTP-tilaa. Ei-löytynyt- tai puuttuva-parametri-tulos voi siksi saapua onnistuneella HTTP-tilalla. Tarkista aina status.code ennen kentän response käyttöä.

Tuloskoodi 500 viestillä ISO Code parameter is required tarkoittaa, että pakollinen parametri puuttuu. Korjaa pyyntö sen sijaan, että käsittelisit sitä palvelinkatkoksena.

Seuraa next_function-linkkejä

Hakutulokset sisältävät next_function-kentän. Se on suhteellinen polku ilman alussa olevaa vinoviivaa, joskus kyselymerkkijonolla, kuten v3/getareas/US tai v3/getareas/US?state=NY. Lisää sen eteen https://api.multitel.net/ muodostaaksesi seuraavan pyynnön, ja todenna kyseinen pyyntö samalla tavalla. Valinnaisia suodattimia, jotka lähetit, kuten pid, ei siirretä kohteeseen next_function. Lisää ne tarvittaessa uudelleen.

Valinnainen varastovalitsin (pid)

getcountries, getstates ja getareas hyväksyvät valinnaisen kyselyparametrin pid, joka rajaa tulokset yhteen varastolähteeseen. Käytä sitä vain MultiTEL:n antamalla arvolla, joko sen numeerisessa muodossa tai sen 32-merkkisessä heksadesimaalimuodossa. Jätä se pois normaalissa käytössä. Lähetä pid kyselymerkkijonossa. Jos päätepiste ei tunnista tai hyväksy arvoa, se jättää sen huomiotta ilman virhettä, ja pyyntö käyttäytyy ikään kuin pid olisi jätetty pois.

Erota haut tilauksista

Maa-, osavaltio- ja aluehaut eivät muuta tiliäsi. Erikoisnumeroluettelo (other) päivittää luettelon tiedot ja tallentaa hintatarjoukset tilillesi, mutta se ei tee tilausta. Mikään hakupyyntö ei varaa numeroa, ja varasto voi muuttua pyyntöjen välillä. Tarkista numeron vaatimukset ja hinta ennen tilauspäätepisteen käyttöä.

Ostoissa, liittämisissä, viesteissä, faksilähetyksissä ja muissa toimissa noudata kyseisen päätepisteen omia uudelleenyrityssääntöjä. Jos toimi aikakatkaistaan lähettämisen jälkeen, tarkista sen tila tai tilitietosi ennen sen toistamista. Kadonnut vastaus ei todista, että toimi epäonnistui.