Hitelesítés és API-válaszok

Használjon API-hitelesítő adatokat

Küldje a v3 kéréseket HTTPS kapcsolaton keresztül a következő címre: https://api.multitel.net. Ebben az útmutatóban minden végpont hitelesítést igényel. Tartsa a hitelesítő adatokat a saját kiszolgálóján, és soha ne helyezze el őket böngészőoldali JavaScript kódban, nyilvános oldalakon, képernyőképeken vagy verziókezelőben.

Használja a következő hitelesítőadat-formák egyikét:

• HTTP Basic az API felhasználónévvel és jelszóval, amelyet a MultiTEL-fiókjához állítottak be.
• Bearer-token egy Authorization: Bearer YOUR_API_TOKEN fejlécben, egy engedélyezett, tokenhitelesítésre beállított API-fiókhoz. A tokenkérelmeket csak az adott API-fiókhoz engedélyezett címekről fogadjuk el.

Ha IP-engedélyezési lista van beállítva az API-fiókjához, minden kérést az engedélyezett címekről küldjön.

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

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

Az ezekben a példákban szereplő változók a környezetben privát módon tárolt hitelesítő adatok helyőrzői.

A hitelesítési hibák kezelése

A hitelesítési hibákat HTTP 401-es állapottal küldjük. A törzs a szabványos burkolót használja, amelyben status.code értéke 401 és üres sztring tartozik a következő mezőhöz: response.

• Nincsenek hitelesítő adatok: status.msg értéke Username and password are required, és a válasz tartalmaz egy Basic hitelesítési kihívást.
• Bearer-token elutasítva: ha az Authorization fejléc a Bearer sémát használja, és a token ismeretlen, le van tiltva vagy az Ön címéről nem engedélyezett, status.msg értéke Invalid bearer token. Más hitelesítő adatot nem próbálunk meg, ha Bearer fejléc van jelen.
• Érvénytelen Basic hitelesítő adatok: status.msg a következővel kezdődik: A valid username and password pair are required., és a válasz tartalmaz egy Basic hitelesítési kihívást. Az üzenet további diagnosztikai szöveget is tartalmazhat, ezért ne elemezze.

Ne próbálkozzon újra automatikusan ugyanazokkal a hitelesítő adatokkal. Ha egy címről rövid időn belül sok sikertelen kísérlet érkezik, az adott címről érkező további kérések blokkolását okozhatja.

A válasz törzsének olvasása

A legtöbb v3 végpont, beleértve getcountries, getstates, getareas és other, JSON formátumban tér vissza ebben a burkolóban:

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

Ez egy szemléltető országlistaválasz, nem pedig az aktuális készletre vagy képességekre vonatkozó állítás.

Egy hibaválasz így néz ki:

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

Ha egy válasz nem kódolható, a törzs a következőket tartalmazza: status.code 500, status.msg Response encoding error, és üres objektum tartozik a következő mezőhöz: response.

Az örökölt GET /v3/countries végpont ehelyett a következőt adja vissza: {"code": 200, "data": [...]}. Ellenőrizze az egyes végpontok dokumentált válaszát. Ha egy törzs nem érvényes JSON, például váratlan kiszolgálóhiba után, tekintse a kérést sikertelennek, és próbálkozzon újra később.

API eredménykódok és HTTP állapot

status.code az API eredménykód. Nem azonos a HTTP állapottal. A hitelesítési hibákat HTTP 401-es állapottal küldjük. Egyébként a felderítési végpontok az olyan kimeneteleket, mint például 404 és 500 kizárólag a status.code mezőben jelentik, és nem állítanak be megfelelő HTTP állapotot. Ezért egy nem található vagy hiányzó paraméterre vonatkozó eredmény sikeres HTTP állapottal is érkezhet. Mindig ellenőrizze status.code értékét, mielőtt a következőt használná: response.

Az 500 eredménykód a következő üzenettel: ISO Code parameter is required azt jelenti, hogy egy kötelező paraméter hiányzik. Javítsa ki a kérést, ahelyett hogy kiszolgálóhibaként kezelné.

Kövesse a next_function mezőt

A felderítési találatok tartalmazzák a következőt: next_function. Ez egy relatív útvonal kezdő perjel nélkül, néha lekérdezési sztringgel, például v3/getareas/US vagy v3/getareas/US?state=NY. Egészítse ki az elején a következővel: https://api.multitel.net/ a következő kérés összeállításához, és hitelesítse azt a kérést ugyanúgy. Az elküldött opcionális szűrőket, például pid, a rendszer nem viszi át a következő mezőbe: next_function. Szükség esetén adja meg őket újra.

Opcionális készletválasztó (pid)

getcountries, getstates és getareas elfogadnak egy opcionális pid lekérdezési paramétert, amely az eredményeket egyetlen készletforrásra szűkíti. Csak a MultiTEL által megadott értékkel használja, numerikus formában vagy 32 karakteres hexadecimális formában. Normál használathoz hagyja ki. Küldje a következőt: pid a lekérdezési sztringben. Ha a végpont nem ismeri fel vagy nem fogadja el az értéket, hiba nélkül figyelmen kívül hagyja, és a kérés úgy viselkedik, mintha pid ki lett volna hagyva.

A felderítés és a megrendelések szétválasztása

Az ország-, állam- és körzetlekérdezések nem módosítják a fiókját. A különleges számok katalógusa (other) frissíti a katalógus adatait, és ár-ajánlatokat ment a fiókjához, de nem ad le megrendelést. Egyetlen felderítési kérés sem foglal le számot, és a készlet a kérések között változhat. Tekintse át egy szám követelményeit és árát, mielőtt megrendelő végpontot használna.

Vásárlások, hozzárendelések, üzenetek, faxküldések és egyéb műveletek esetében kövesse az adott végpont saját újrapróbálkozási szabályait. Ha egy művelet beküldés után időtúllépéssel jár, ellenőrizze az állapotát vagy a fiókrekordjait, mielőtt megismételné. Az elveszett válasz nem bizonyítja, hogy a művelet sikertelen volt.