Ověřování a odpovědi API

Použijte přihlašovací údaje API

Odesílejte požadavky v3 přes HTTPS na adresu https://api.multitel.net. Každý koncový bod v této příručce vyžaduje ověření. Uchovávejte přihlašovací údaje na svém serveru a nikdy je neuvádějte v kódu v jazyce JavaScript spouštěném v prohlížeči, na veřejných stránkách, na snímcích obrazovky ani ve správě zdrojového kódu.

Použijte jednu z těchto forem přihlašovacích údajů:

• HTTP Basic s uživatelským jménem a heslem API nakonfigurovanými pro váš účet MultiTEL.
• Token Bearer v hlavičce Authorization: Bearer YOUR_API_TOKEN pro povolený účet API nakonfigurovaný k ověřování tokenem. Požadavky s tokenem jsou přijímány pouze z adres povolených pro daný účet API.

Pokud je nakonfigurován seznam povolených adres IP pro váš účet API, odesílejte všechny požadavky z povolených adres.

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

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

Proměnné v těchto příkladech jsou zástupné symboly pro přihlašovací údaje, které soukromě ukládáte ve svém prostředí.

Zpracujte selhání ověřování

Selhání ověření jsou odesílána se stavem HTTP 401. Tělo používá standardní obálku, přičemž status.code je nastaven na 401 a pole response je prázdný řetězec.

• Žádné přihlašovací údaje: status.msg je Username and password are required, a odpověď obsahuje výzvu k ověření Basic.
• Token Bearer zamítnut: pokud hlavička Authorization používá schéma Bearer a token je neznámý, deaktivovaný nebo z vaší adresy nepovolený, status.msg je Invalid bearer token. Pokud je přítomna hlavička Bearer, nezkoušejí se žádné další přihlašovací údaje.
• Neplatné přihlašovací údaje Basic: status.msg začíná textem A valid username and password pair are required., a odpověď obsahuje výzvu k ověření Basic. Zpráva může obsahovat další diagnostické informace, takže ji neparsujte v programu.

Neopakujte automaticky pokus se stejnými přihlašovacími údaji. Mnoho neúspěšných pokusů z jedné adresy během krátké doby může způsobit zablokování dalších požadavků z této adresy.

Přečtěte tělo odpovědi

Většina koncových bodů v3 včetně getcountries, getstates, getareas a other, vrací JSON v této obálce:

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

Toto je ilustrativní odpověď se seznamem zemí, nikoli prohlášení o aktuálním inventáři nebo funkcích.

Chybová odpověď vypadá takto:

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

Pokud odpověď nelze zakódovat, tělo obsahuje status.code 500, status.msg Response encoding error, a prázdný objekt jako response.

Starší koncový bod GET /v3/countries vrací {"code": 200, "data": [...]} namísto toho. Zkontrolujte dokumentovanou odpověď každého koncového bodu. Pokud tělo není platný JSON, například po neočekávaném selhání serveru, považujte požadavek za neúspěšný a opakujte jej později.

Kódy výsledků API a stav HTTP

status.code je kód výsledku API. Nejde o stav HTTP. Selhání ověření jsou odesílána s HTTP 401. Jinak koncové body pro zjišťování hlásí výsledky, jako je například 404 a 500 pouze v status.code a nenastavují odpovídající stav HTTP. Výsledek nenalezení nebo chybějícího parametru proto může dorazit s úspěšným stavem HTTP. Vždy zkontrolujte status.code před použitím response.

Kód výsledku 500 se zprávou ISO Code parameter is required znamená, že chybí povinný parametr. Opravte požadavek, místo abyste jej považovali za výpadek serveru.

Sledujte next_function

Výsledky zjišťování obsahují next_function. Jedná se o relativní cestu bez úvodního lomítka, někdy s řetězcem dotazu, například v3/getareas/US nebo v3/getareas/US?state=NY. Přidejte před ni https://api.multitel.net/ k sestavení dalšího požadavku a ověřte tento požadavek stejným způsobem. Volitelné filtry, které jste odeslali, například pid, se nepřenášejí do next_function. V případě potřeby je přidejte znovu.

Volitelný selektor inventáře (pid)

getcountries, getstates a getareas přijímají volitelný parametr dotazu pid, který zužuje výsledky na jeden zdroj inventáře. Použijte jej pouze s hodnotou poskytnutou společností MultiTEL, buď v číselné podobě, nebo v 32znakové šestnáctkové podobě. Pro běžné použití jej vynechejte. Odešlete pid v řetězci dotazu. Pokud koncový bod hodnotu nerozpozná nebo nepřijme, ignoruje ji bez chyby a požadavek se chová, jako kdyby pid byl vynechán.

Oddělte zjišťování od objednávek

Vyhledávání zemí, států a oblastí nemění váš účet. Katalog zvláštních čísel (other) aktualizuje podrobnosti katalogu a ukládá cenové nabídky pro váš účet, ale nezadává objednávku. Žádný požadavek na zjišťování nerezervuje číslo a inventář se může mezi požadavky změnit. Před použitím objednávkového koncového bodu si prostudujte požadavky a cenu čísla.

U nákupů, přiřazení, zpráv, odesílání faxů a dalších akcí dodržujte vlastní pravidla pro opakování daného koncového bodu. Pokud po odeslání požadavku na akci vyprší časový limit, zkontrolujte stav akce nebo záznamy svého účtu, než požadavek zopakujete. Ztracená odpověď nedokazuje, že akce selhala.