Wyświetlanie typów numerów specjalnych i cen dla danego kraju

Numery lokalne wyszukuje się za pomocą getcountries i getareas. Aby wyszukać numery krajowe, bezpłatne, o współdzielonych kosztach, globalne i komórkowe, wywołaj other z kodem ISO kraju.

• Grupy są wyświetlane w ustalonej kolejności, a grupy bez pozycji są pomijane.
• Każda pozycja zawiera plany cenowe Twojego konta w polu prices. Wybierz plan na podstawie jego pól channels, monthly_price, setup_price, per_minute i free_minutes, a następnie zachowaj jego price_id do składania zamówień, jeśli dany punkt końcowy go wymaga.
• Jeśli needs_registration ma wartość interpretowaną jako prawda, przeczytaj restrictions przed złożeniem zamówienia. Traktuj ten tekst jako niezaufaną treść do wyświetlenia.
• Kieruj się polem next_function: v3/getnumbers/{uuid} pozwala wybrać konkretny numer, a v3/order/{uuid} składa zamówienie bezpośrednio na podstawie pozycji.
• Pusta lista response z kodem 200 oznacza, że w chwili żądania nie znaleziono żadnych typów numerów specjalnych. Jeśli katalog był tymczasowo niedostępny, odpowiedź może być niekompletna lub nie być poprawnym JSON-em, więc spróbuj ponownie później.
• Dla krajów spoza katalogu zwracany jest kod 404 bez odpowiadającego mu statusu HTTP. Zawsze sprawdzaj status.code.

Żądanie

Wymagane: uwierzytelnianie HTTP Basic lub token Bearer (zobacz Uwierzytelnianie i odpowiedzi API). Nieudane uwierzytelnienie powoduje zwrócenie odpowiedzi HTTP 401 przed rozpoczęciem wyszukiwania.

GET z parametrem isocode w ścieżce. Jeśli segment ścieżki zostanie pominięty, zamiast niego odczytywane jest pole isocode zakodowane w formacie formularza.

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

Odpowiedź

Standardowa struktura odpowiedzi. W przypadku powodzenia status.code ma wartość 200, status.msg jest puste, a status.results określa liczbę grup. response jest listą grup. Pola grupy: group_key (znormalizowany klucz typu: national, tollfree, sharedcost, global, mobile lub inny klucz alfanumeryczny zapisany małymi literami); group_name (nazwa do wyświetlenia); group_type_uuid (nieprzezroczysty identyfikator typu); items. Kolejność grup: national, tollfree, sharedcost, global, mobile, a następnie pozostałe klucze według group_name. Grupy bez pozycji w items są pomijane, podobnie jak typ lokalny. W przypadku US grupa numerów komórkowych jest pomijana, chyba że Twoje konto ma włączony dostęp do numerów komórkowych z US. Pozycje są sortowane według name (bez rozróżniania wielkości liter), a następnie według prefix. Pola pozycji: uuid (nieprzezroczysty identyfikator pozycji używany w next_function); area_uuid (nieprzezroczysty identyfikator grupy katalogowej); country_uuid (nieprzezroczysty identyfikator kraju); prefix (pełny prefiks rozpoczynający się od znaku '+' i telefonicznego kodu kraju); name (nazwa w katalogu; znaki cudzysłowu mogą być poprzedzone ukośnikiem odwrotnym jako znakiem ucieczki); metered, overflow i needs_registration (flagi, które mogą mieć typ boolean lub number; każdą wartość interpretowaną jako prawda traktuj jako tak); restrictions (puste, gdy rejestracja nie jest wymagana; w przeciwnym razie tekst wymagań, który może zawierać podziały wiersza HTML i odnośnik, otaczające cudzysłowy oraz znaki z sekwencjami ucieczki; traktuj go jako niezaufany tekst do wyświetlenia); state (dla US, CA i PR kod stanu lub pusta lista, jeśli kod nie jest znany; dla pozostałych krajów kod ISO kraju); country_iso; is_mobile (1 w grupie numerów komórkowych, w przeciwnym razie 0); number_type (taka sama wartość jak group_key); available (liczba zgłoszona przez katalog dla pozycji, typu integer, lub 0, jeśli nie została zgłoszona); sms_coverage (1, jeśli którakolwiek funkcja wspomina o SMS lub MMS); returns_numbers (1, gdy można wyświetlić listę konkretnych numerów); next_function ('v3/getnumbers/{uuid}', gdy returns_numbers ma wartość 1, w przeciwnym razie 'v3/order/{uuid}'); prices; features (lista ciągów znaków opisujących dostępne funkcje); group_key; group_type_uuid. Każda pozycja w prices zawiera price_id (nieprzezroczysty identyfikator planu), is_customer_custom (true, gdy obowiązują indywidualne ceny dla Twojego konta; tylko w przypadku planów bez kanałów wliczonych w cenę), per_minute i free_minutes (ciągi znaków reprezentujące liczby dziesiętne), setup_price i monthly_price (ciągi znaków z dwiema cyframi po separatorze dziesiętnym) oraz channels (liczba kanałów wliczonych w cenę, typu integer). Pozycje bez żadnego planu cenowego są pomijane. Dla każdego typu numeru uwzględnia się najwyżej 1000 pozycji katalogu na żądanie. Jeśli żaden typ nie ma pozycji, response jest pustą listą, a status.results ma wartość 0. Jeśli wyszukiwanie w katalogu na żywo zakończy się niepowodzeniem, odpowiedź może nie mieć tej struktury lub może brakować w niej grup.

Przykładowa struktura odpowiedzi; nie przedstawia danych konta na żywo ani aktualnej wyceny.

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

Błędy

• 500: msg 'ISO Code parameter is required': brak parametru isocode lub jego wartość jest pusta. Jest to błąd żądania, który można poprawić. Odpowiadający mu status HTTP nie jest ustawiany.
• 404: msg 'Error: no such country': kraj jest nieznany lub nie jest powiązany z katalogiem numerów specjalnych. Odpowiadający mu status HTTP nie jest ustawiany.
• 401: Brak uwierzytelnienia lub uwierzytelnienie nie powiodło się. Odpowiedź jest wysyłana ze statusem HTTP 401.

Dostępność i skutki uboczne

• Nie składa zamówienia. Kod tego punktu końcowego nie zawiera kroku naliczania opłat.
• Odświeża szczegóły katalogu i wyceny dla Twojego konta, zastępując wcześniejsze wyceny tych samych planów. Sposób, w jaki punkty końcowe do składania zamówień korzystają z tych wycen, opisano osobno.
• Ceny są właściwe dla Twojego konta i mogą uwzględniać indywidualne stawki. Odpowiedź nie określa waluty.
• Wyszukuje dane w katalogu na żywo, więc może działać wolniej niż inne wywołania służące do wyszukiwania dostępnych numerów. Wyniki mogą się zmieniać między wywołaniami.