Vyhledání dostupných telefonních čísel

Vyberte konkrétní prefix

Použijte volání pro zjištění zemí a oblastí pokrytí a poté getprefixes bez seskupování. Zkopírujte hodnotu vybraného prefixu v poli uuid. Pokud returns_numbers má hodnotu 0, číslo se u tohoto prefixu přiděluje při objednání; použijte vrácenou hodnotu next_function namísto vyžadování seznamu jednotlivých čísel.

Procházejte dávku s omezenou velikostí

Pro běžné vyhledávání použijte compact=1 a požadovanou velikost dávky uveďte jak v cestě, tak v parametru quantity v dotazu, jak je uvedeno níže. Parametr pro stránku ani kurzor neexistuje. Kompaktní výsledek představuje vzorek; opakování požadavku nezaručuje další stránku bez překryvu s předchozími výsledky. Prázdný výsledek nebo malý počet výsledků nepovažujte za údaj o celkovém počtu čísel v nabídce.

Najděte snadno zapamatovatelnou posloupnost číslic

Zadejte number_filter_mode=contains nebo ends_with společně s number_filter_value. Hodnota musí obsahovat 1–15 číslic. Vyhledávání může před použitím filtru načíst jen omezené dávky kandidátů, a proto může další vyhovující čísla v nabídce přehlédnout. Pokud potřebujete, aby požadované vyhledávání provedl podporovaný zdroj, vyžádejte si selektor pid od MultiTEL a použijte filter_required=1; chybějící nebo nepodporovaný výběr zdroje způsobí vrácení chyby API.

Zkontrolujte vybrané číslo

Ze stejného výsledku načtěte number, info.uuid, vybranou hodnotu price[].uuid, názvy dostupných funkcí a požadavky na registraci. Pole price může nabízet více tarifů s různými počty kanálů a sazbami. Peněžní hodnoty a množství mohou být zakódovány jako řetězce. Volitelná metadata, včetně info.state, se mezi zdroji liší; nevyžadujte jednotnou strukturu údaje o státu a neodvozujte ceny z identifikátoru.

Při zpracování bez průběžného odesílání se nejprve odstraní duplicitní kandidáti a rozdělí se počet vybíraných položek mezi zdroje; teprve poté se vybraná dávka seřadí podle měsíční ceny prvního tarifu. Jiné způsoby zpracování mohou začít odesílat data dříve, takže nelze u každého požadavku zaručit celkové seřazení ani odstranění duplicit. Seřazení také nedokazuje, že vrácený vzorek obsahuje nejlevnější číslo z celého katalogu.

Objednejte samostatně a ověřte výsledek

Vyhledávání nic nekupuje ani nerezervuje. Vrácené identifikátory čísla a tarifu si uchovejte pro proces objednání pod stejným účtem. Před odesláním objednávky zkontrolujte konkrétní tarif, požadavky a poplatky. Požadavky na registraci mohou aktivaci zpozdit; výsledek vyhledávání nestanovuje žádnou pevnou lhůtu aktivace.

Požadavek

Použijte aktivovaný účet API MultiTEL: pro účet s heslem přihlašovací údaje HTTP Basic, pro účet s tokenem pak Authorization: Bearer. Platí oprávnění účtu a jeho omezení IP adres. Viz společné pokyny k autentizaci.

Parametry cesty a parametry dotazu v URL. Pro veřejný postup vyhledávání použijte GET. Obslužná rutina přijímá také vybrané hodnoty z formuláře či požadavku, nejde však o vyhledávací API přijímající tělo ve formátu JSON.

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

Odpověď

Jeden objekt JSON obsahující status a response. Při úspěchu má status.code hodnotu 200 a response je pole položek s čísly. status.results udává počet položek vráceného pole; status.msg může mít hodnotu Results: N nebo při průběžně odesílané odpovědi OK. Bez compact=1 některá vyhledávání zapisují pole response postupně a končí položkou status, proto počkejte na úplné tělo JSON. Nejde o JSON oddělený novými řádky. Kontrolujte status.code, i když přenos HTTP proběhne úspěšně. Typická pole jsou uvedena níže; metadata specifická pro jednotlivé zdroje a volitelná pole se liší. Všechny identifikátory považujte za neprůhledné hodnoty a číslo uchovávejte společně s vybranou hodnotou price[].uuid.

Ukázková struktura odpovědi; nejde o skutečná data účtu ani aktuální cenovou nabídku.

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

Chyby

• 401: Autentizace se nezdařila. Neplatné či chybějící přihlašovací údaje a zamítnutý přístup k účtu API nevedou k získání výsledků vyhledávání.
• 404: Invalid prefix ID, Invalid country, Invalid area nebo No numbers found. Přečtěte si status.msg; chybová odpověď není pole čísel.
• 400: NUMBER_FILTER_INVALID v response.code: neplatný režim, hodnota, která není tvořena 1–15 číslicemi, nebo filter_required bez současného zadání režimu a hodnoty.
• 422: NUMBER_FILTER_UNSUPPORTED v response.code: buď se u daného prefixu číslo přiděluje při objednání (reason=order_only_prefix a next_function určuje cestu pro objednání), nebo výslovně vybraný zdroj nedokáže požadovaný filtr podporovat.

Dostupnost a vedlejší účinky

• Tato obslužná rutina vyhledává a připravuje cenové nabídky; neodesílá objednávku čísla ani nestrhává poplatek za jeho nákup. Může obnovovat mezipaměti katalogu, odstraňovat z nich zastaralé položky nabídky, ukládat cenové tarify pro konkrétní účet a zapisovat protokoly vyhledávání.
• Dostupnost je výsledkem platným k určitému okamžiku, nikoli rezervací. Následná objednávka může selhat nebo vrátit jinou dostupnost. Před opakováním nákupu ověřte výsledek objednávky a uveďte své záznamy do souladu s ním.
• Ceny jsou specifické pro daný účet. Identifikátor vybraného tarifu uchovejte pro použití se stejným účtem a podmínky i poplatky objednávky zkontrolujte samostatně; samotný tento koncový bod nedokazuje, že cena zůstane platná až do pozdějšího objednání.
• Číslo a ceny v příkladu jsou smyšlené ukázky struktury odpovědi, nikoli aktuální cenová nabídka. Možnosti čísla, počty kanálů, dobu trvání smlouvy a informace o registraci je nutné načíst ze skutečného vybraného výsledku.
• Některé popisy registrace obsahují formátovaný text nebo odkazy. Při zobrazování vrácených řetězců ve vlastní aplikaci s nimi zacházejte jako s nedůvěryhodnými daty.
• Dostupnost mobilních čísel a příslušné příznaky závisejí na tom, zda účet splňuje podmínky, a na nabídce čísel. Samotný prefix v katalogu nebo příznak is_mobile nedokazuje mobilní možnosti konkrétního čísla.