Egy ország lefedettségi körzeteinek listázása

Válasszon országot (az Egyesült Államok vagy Kanada esetén tetszés szerint államot vagy tartományt is ebből: getstates), majd hívja meg ezt: getareas, hogy lássa, hol kínálnak számokat. A következő lépéshez őrizze meg a körzet ezen azonosítóját: uuid.

Minden körzet két lehetséges következő lépés egyikéhez vezet:

• available > 0: next_function értéke v3/getprefixes/{uuid}; ehhez ?state= kapcsolódik, ha államra szűrt. Használja a prefixek böngészésére.
• available = 0: a körzethez tartoznak prefixek, de nincs készlet, és next_function értéke v3/order/{uuid}. E lépés követelményeit a rendelési dokumentáció ismerteti.

available a teljes körzetre vonatkozó összeg, államszűrés esetén is. Az államszűrő kódot vagy teljes nevet fogad el, de csak US és CA esetén működik. Ha az államszűrő ezt adja vissza: No areas found, próbálja újra a szűrő nélkül. Az ellenőrzések sorrendje: hiányzó országkód, ismeretlen ország, más országhoz megadott államszűrő, érvénytelen állam, megfelelő körzet hiánya. Ezek mindegyike a következő kódok egyikét adja vissza: 500 vagy 404 ebben: status.code, megfelelő HTTP-állapotkód beállítása nélkül.

Kérés

Kötelező: HTTP Basic hitelesítés vagy Bearer token (lásd: Hitelesítés és API-válaszok). Sikertelen hitelesítés esetén a rendszer a lekérdezés végrehajtása előtt HTTP 401 választ ad.

GET kérés, az útvonalban az isocode, a lekérdezési karakterláncban pedig a nem kötelező state és pid paraméterrel. Ha az útvonalszegmens hiányzik, a rendszer helyette egy űrlapkódolású isocode mezőt olvas be.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

Válasz

Szabványos válaszburkoló. Siker esetén a status.code értéke 200, a status.msg értéke 'Results: N', a status.results értéke N, a response pedig a körzet neve szerint rendezett lista. Mezők: uuid (a következő lépésben használt, önmagában nem értelmezendő körzetazonosító); country_uuid (önmagában nem értelmezendő, 32 karakteres országazonosító, később nincs rá szükség); name; area_type és number_type (katalógusbeli leíró értékek; a bejegyzések nem feltétlenül helyi számtípusok); country_iso; is_mobile (0 vagy 1, a körzet mobiljelzői alapján; US esetén mindig 0, kivéve, ha a fiókjában engedélyezve vannak a US mobilszámai); available (a körzet megfelelő prefixeihez tartozó teljes készlet, a kért államra való korlátozás nélkül); sms_coverage (0 vagy 1); returns_numbers (0 vagy 1, a körzet prefixei között szereplő legmagasabb jelzőérték); latitude és longitude; state_iso; next_function. state_iso: államszűrő esetén a feloldott szűrőkód. US és CA esetén szűrő nélkül annak az államnak a kódja, amelynek neve megegyezik a körzet nevével; ennek hiányában a körzet tárolt értéke, majd ennek hiányában a körzet prefixadataiból származtatott kód. Más országok esetén a tárolt érték, amely üres is lehet. A next_function értéke 'v3/getprefixes/{uuid}' (szűrés esetén '?state={code}' kiegészítéssel), ha az available nagyobb mint 0, egyébként 'v3/order/{uuid}'. Azok a körzetek kimaradnak, amelyekhez egyetlen megfelelő prefix sem tartozik. A prefixekkel rendelkező, de készlet nélküli körzeteknél a visszaadott available értéke 0.

A válasz szerkezetét szemléltető példa; nem élő fiókadat vagy aktuális árajánlat.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

Hibák

• 500: msg 'ISO Code parameter is required': az isocode hiányzik vagy üres. Ez a kérés javítható hibája. A rendszer nem állít be megfelelő HTTP-állapotkódot.
• 404: msg 'Error: no such country': az országkód ismeretlen. A rendszer nem állít be megfelelő HTTP-állapotkódot.
• 404: msg 'State filter is only available for US and CA': más országhoz nem üres state paramétert küldtek. A rendszer nem állít be megfelelő HTTP-állapotkódot.
• 404: msg 'Invalid state': a state sem az ország ismert államkódjának, sem ismert államnevének nem felel meg. A rendszer nem állít be megfelelő HTTP-állapotkódot.
• 404: msg 'No areas found': egyetlen körzet sem felel meg az ország-, forrás- és államszűrőknek. A rendszer nem állít be megfelelő HTTP-állapotkódot.
• 401: A hitelesítés hiányzik vagy sikertelen. HTTP 401 állapotkóddal érkezik.

Elérhetőség és mellékhatások

• Ügyfélfiókok esetén kizárólag lekérdezés. Semmit nem foglal le, nem rendel meg és nem módosít.
• Az available tájékoztató jellegű, és a következő lépés előtt változhat.