Egy ország speciális számtípusainak és árainak listázása

A helyi számok felderítésére a következők szolgálnak: getcountries és getareas. Országos, díjmentes, megosztott költségű, globális és mobilszámokhoz hívja meg a következő végpontot: other, az ország ISO-kódjával.

• A csoportok rögzített sorrendben jelennek meg, a bejegyzés nélküli csoportok kimaradnak.
• Minden bejegyzés felsorolja a fiókjához tartozó díjcsomagokat a következő mezőben: prices. A csomag kiválasztásához vegye figyelembe a következő mezők értékeit: channels, monthly_price, setup_price, per_minute és free_minutes; a rendeléshez pedig őrizze meg a következő mező értékét: price_id, ha a rendelési végpont kéri azt.
• Ha a needs_registration értéke logikai értelemben igaznak számít, rendelés előtt olvassa el a restrictions tartalmát. Ezt a szöveget nem megbízható megjelenítési tartalomként kezelje.
• Kövesse a következő mező útmutatását: next_function: v3/getnumbers/{uuid} lehetővé teszi egy konkrét szám kiválasztását, míg a v3/order/{uuid} közvetlenül a bejegyzésből rendel.
• Az üres response lista és a következő kód: 200 azt jelenti, hogy a kérés időpontjában nem találhatók speciális számtípusok. Ha a katalógus átmenetileg nem volt elérhető, a válasz hiányos lehet, vagy nem feltétlenül érvényes JSON, ezért próbálkozzon újra később.
• A katalógusban nem szereplő országok esetén a visszaadott kód: 404, ennek megfelelő HTTP-állapot nélkül. Mindig ellenőrizze a következő mezőt: status.code.

Kérés

Szükséges: 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 HTTP 401 választ ad, még a keresés végrehajtása előtt.

GET kérés, az útvonalban megadott isocode 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/other/FR'

Válasz

Szabványos válaszkeret. Siker esetén a status.code értéke 200, a status.msg üres, a status.results pedig a csoportok számát adja meg. A response a csoportok listája. A csoportok mezői: group_key (normalizált típuskulcs: national, tollfree, sharedcost, global, mobile vagy más, kisbetűs alfanumerikus kulcs); group_name (megjelenítendő név); group_type_uuid (belső felépítését tekintve nem értelmezendő típusazonosító); items. A csoportok sorrendje: national, tollfree, sharedcost, global, mobile, majd a többi kulcs a group_name szerint rendezve. Az üres items mezőjű csoportok kimaradnak, ahogyan a helyi típus is. A US esetében a mobilcsoport kimarad, kivéve, ha fiókja engedélyezve van a US mobilszámainak használatára. A bejegyzések rendezése a name szerint történik, a kis- és nagybetűk megkülönböztetése nélkül, majd a prefix szerint. A bejegyzések mezői: uuid (belső felépítését tekintve nem értelmezendő bejegyzésazonosító, amelyet a next_function használ); area_uuid (a katalóguscsoport belső felépítését tekintve nem értelmezendő azonosítója); country_uuid (belső felépítését tekintve nem értelmezendő országazonosító); prefix (teljes előhívó, amely '+' jellel és az ország hívószámával kezdődik); name (katalógusbeli név; az idézőjelek fordított perjellel escape-elve is megjelenhetnek); metered, overflow és needs_registration (boolean vagy number típusú jelzők; minden logikai értelemben igaznak számító értéket igenként kezeljen); restrictions (üres, ha nincs szükség regisztrációra, egyébként a követelmények szövege, amely HTML-sortöréseket és hivatkozást, körülzáró idézőjeleket és escape-elt karaktereket is tartalmazhat; nem megbízható megjelenítési szövegként kezelje); state (US, CA és PR esetén államkód, vagy üres lista, ha nem ismert; más országok esetén az ország ISO-kódja); country_iso; is_mobile (1 a mobilcsoportban, egyébként 0); number_type (megegyezik a group_key értékével); available (a katalógus által a bejegyzéshez közölt darabszám, integer típussal, illetve 0, ha nincs közölt adat); sms_coverage (1, ha bármely képesség SMS-t vagy MMS-t említ); returns_numbers (1, ha konkrét számok listázhatók); next_function ('v3/getnumbers/{uuid}', ha a returns_numbers értéke 1, egyébként 'v3/order/{uuid}'); prices; features (a képességeket leíró karakterláncok listája); group_key; group_type_uuid. Minden prices bejegyzés a következő mezőket tartalmazza: price_id (belső felépítését tekintve nem értelmezendő csomagazonosító), is_customer_custom (true, ha a fiókjára egyedi árazás vonatkozik; csak a csatornákat nem tartalmazó csomagoknál), per_minute és free_minutes (tizedes számokat tartalmazó karakterláncok), setup_price és monthly_price (két tizedesjegyet tartalmazó karakterláncok), valamint channels (a csomagban foglalt csatornák száma, integer típussal). A díjcsomag nélküli bejegyzések kimaradnak. Kérésenként és számtípusonként legfeljebb 1000 katalógusbejegyzést vesz figyelembe a rendszer. Ha egyik típushoz sem tartozik bejegyzés, a response üres lista, a status.results értéke pedig 0. Ha az élő katalógus lekérdezése sikertelen, előfordulhat, hogy a válasz nem ezt a válaszkeretet használja, vagy csoportok hiányoznak belőle.

Szemléltető válaszstruktúra; nem a fiók élő adatait vagy aktuális árajánlatot tartalmaz.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "group_key": "tollfree",
      "group_name": "Toll-free",
      "group_type_uuid": "00000000-0000-4000-8000-0000000000a1",
      "items": [
        {
          "uuid": "0000000000000000000000000000b001",
          "area_uuid": "0000000000000000000000000000a001",
          "country_uuid": "0000000000000000000000000000c001",
          "prefix": "+33800",
          "name": "Example Toll-free",
          "metered": true,
          "overflow": 0,
          "needs_registration": 0,
          "restrictions": "",
          "state": "FR",
          "country_iso": "FR",
          "is_mobile": 0,
          "number_type": "tollfree",
          "available": 10,
          "sms_coverage": 0,
          "returns_numbers": 1,
          "next_function": "v3/getnumbers/0000000000000000000000000000b001",
          "prices": [
            {
              "price_id": "0000000000000000000000000000d001",
              "is_customer_custom": false,
              "per_minute": "0.05",
              "free_minutes": "0",
              "setup_price": "0.00",
              "monthly_price": "5.00",
              "channels": 2
            }
          ],
          "features": ["voice"],
          "group_key": "tollfree",
          "group_type_uuid": "00000000-0000-4000-8000-0000000000a1"
        }
      ]
    }
  ]
}

Hibák

• 500: msg 'ISO Code parameter is required': az isocode hiányzik vagy üres. Ez javítható kérési hiba. Ennek megfelelő HTTP-állapot nincs beállítva.
• 404: msg 'Error: no such country': az ország ismeretlen, vagy nem kapcsolódik a speciális számok katalógusához. Ennek megfelelő HTTP-állapot nincs beállítva.
• 401: A hitelesítés hiányzik vagy sikertelen. HTTP 401 állapottal érkezik.

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

• Nem ad le rendelést. Ennek a végpontnak a kódjában nincs díjterhelési lépés.
• Frissíti a fiókjához tartozó katalógusadatokat és árajánlatokat, felülírva az ugyanazon csomagokra vonatkozó korábbi ajánlatokat. Külön dokumentáció ismerteti, hogyan használják fel ezeket az ajánlatokat a rendelési végpontok.
• Az árak a fiókjára vonatkoznak, és egyedi árazást is tartalmazhatnak. A válasz nem ad meg pénznemet.
• Élő katalóguslekérdezéseket végez, ezért lassabb lehet más felderítési hívásoknál. Az eredmények a hívások között változhatnak.