Lista obszarów dostępności numerów w kraju

Po wybraniu kraju (oraz, w przypadku Stanów Zjednoczonych lub Kanady, opcjonalnie stanu z getstates) wywołaj getareas, aby sprawdzić, gdzie oferowane są numery. Zachowaj identyfikator obszaru uuid do następnego kroku.

Dla każdego obszaru dostępny jest jeden z dwóch kolejnych kroków:

• available > 0: next_function ma wartość v3/getprefixes/{uuid}, z parametrem ?state= dołączonym w przypadku filtrowania według stanu. Użyj tego adresu, aby przeglądać prefiksy.
• available = 0: obszar ma prefiksy, ale nie ma dostępnych numerów, a next_function ma wartość v3/order/{uuid}. Wymagania dotyczące tego kroku znajdziesz w dokumentacji składania zamówień.

available to łączna liczba dostępnych numerów w całym obszarze, nawet przy filtrowaniu według stanu. Filtr stanu przyjmuje kod lub pełną nazwę, ale działa tylko dla US i CA. Jeśli zastosowanie filtra stanu zwróci komunikat No areas found, spróbuj ponownie bez tego filtra. Kontrole są wykonywane w następującej kolejności: brak kodu kraju, nieznany kraj, filtr stanu dla innego kraju, nieprawidłowy stan, brak pasujących obszarów. Każdy z tych przypadków zwraca kod 500 lub 404 w status.code, bez odpowiadającego mu statusu HTTP.

Żądanie

Wymagane: uwierzytelnianie HTTP Basic lub token Bearer (zobacz Uwierzytelnianie i odpowiedzi API). Nieudane uwierzytelnianie skutkuje odpowiedzią HTTP 401 przed rozpoczęciem wyszukiwania.

Żądanie GET z parametrem isocode w ścieżce oraz opcjonalnymi parametrami state i pid w ciągu zapytania. 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/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

Odpowiedź

Standardowa struktura odpowiedzi. W przypadku powodzenia status.code ma wartość 200, status.msg ma wartość 'Results: N', status.results ma wartość N, a response jest listą posortowaną według nazwy obszaru. Pola: uuid (nieprzezroczysty identyfikator obszaru używany w następnym kroku); country_uuid (nieprzezroczysty, 32-znakowy identyfikator kraju, niewymagany w dalszych krokach); name; area_type i number_type (określenia katalogowe; wpisy nie muszą dotyczyć lokalnych typów numerów); country_iso; is_mobile (0 lub 1, na podstawie flag numerów komórkowych obszaru; zawsze 0 dla US, chyba że na Twoim koncie włączono obsługę numerów komórkowych z US); available (łączna liczba dostępnych numerów we wszystkich pasujących prefiksach obszaru, bez ograniczenia do wskazanego stanu); sms_coverage (0 lub 1); returns_numbers (0 lub 1, najwyższa wartość flagi wśród prefiksów obszaru); latitude i longitude; state_iso; next_function. state_iso: przy zastosowaniu filtra stanu jest to rozpoznany kod filtra. Dla US i CA bez filtra jest to kod stanu, którego nazwa jest taka sama jak nazwa obszaru; w przeciwnym razie zapisana wartość obszaru, a jeśli jej brak — kod wyznaczony na podstawie danych prefiksów obszaru. Dla pozostałych krajów jest to zapisana wartość, która może być pusta. next_function ma wartość 'v3/getprefixes/{uuid}' (z dołączonym '?state={code}' przy zastosowaniu filtra), gdy available jest większe niż 0, a w przeciwnym razie — 'v3/order/{uuid}'. Obszary bez żadnego pasującego prefiksu są pomijane. Obszary z prefiksami, ale bez dostępnych numerów, są zwracane z wartością available równą 0.

Przykładowa struktura odpowiedzi; nie przedstawia rzeczywistych danych konta ani aktualnej oferty cenowej.

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

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': kod kraju jest nieznany. Odpowiadający mu status HTTP nie jest ustawiany.
• 404: msg 'State filter is only available for US and CA': przesłano niepustą wartość parametru state dla innego kraju. Odpowiadający mu status HTTP nie jest ustawiany.
• 404: msg 'Invalid state': wartość state nie jest ani znanym kodem, ani znaną nazwą stanu lub prowincji w danym kraju. Odpowiadający mu status HTTP nie jest ustawiany.
• 404: msg 'No areas found': żaden obszar nie odpowiada filtrom kraju, źródła i stanu. Odpowiadający mu status HTTP nie jest ustawiany.
• 401: brak uwierzytelnienia lub uwierzytelnianie nie powiodło się. Odpowiedź jest wysyłana ze statusem HTTP 401.

Dostępność i skutki uboczne

• Wyszukiwanie jest dostępne wyłącznie dla kont klientów. Nie rezerwuje, nie zamawia ani nie zmienia niczego.
• available ma charakter informacyjny i może się zmienić przed następnym krokiem.