Znajdź dostępne numery telefonów

Wybierz pojedynczy prefiks

Użyj wywołań do wyszukiwania krajów i obszarów, a następnie getprefixes bez grupowania. Skopiuj z wybranego prefiksu wartość uuid. Jeśli returns_numbers wynosi 0, numer dla tego prefiksu jest przydzielany podczas zamawiania; użyj zwróconego pola next_function zamiast wymagać listy pojedynczych numerów.

Przeglądaj partię o ograniczonej wielkości

Przy zwykłym wyszukiwaniu użyj compact=1 i podaj żądaną wielkość partii zarówno w ścieżce, jak i w parametrze zapytania quantity zgodnie z poniższym przykładem. Nie ma parametru strony ani kursora. Wynik w trybie kompaktowym jest próbką; powtórzenie żądania nie gwarantuje kolejnej strony bez powtórzeń. Nie traktuj pustego wyniku ani niewielkiej liczby wyników jako informacji o całkowitej liczbie dostępnych numerów.

Znajdź łatwy do zapamiętania układ cyfr

Podaj number_filter_mode=contains lub ends_with wraz z number_filter_value. Wartość musi zawierać 1–15 cyfr. Wyszukiwanie może pobierać ograniczone partie numerów przed zastosowaniem filtra, więc może pominąć inne pasujące dostępne numery. Jeśli potrzebujesz źródła obsługującego wymagane wyszukiwanie, uzyskaj selektor pid od MultiTEL i użyj filter_required=1; brak wyboru lub wybór nieobsługiwanego źródła powoduje zwrócenie błędu API.

Sprawdź wybrany numer

Odczytaj number, info.uuid, wybraną wartość price[].uuid, nazwy dostępnych funkcji i wymagania rejestracyjne z tego samego wyniku. Tablica price może oferować wiele planów z różnymi liczbami kanałów i stawkami. Pola kwotowe i ilości mogą być zakodowane jako ciągi znaków. Opcjonalne metadane, w tym info.state, różnią się w zależności od źródła; nie wymagaj jednej uniwersalnej struktury pola stanu ani nie wywnioskuj cen z identyfikatora.

W ścieżce bez strumieniowania usuwa się duplikaty numerów kandydujących i dokonuje przydziału z poszczególnych źródeł, zanim wybrana partia zostanie posortowana według miesięcznej ceny pierwszego planu. Inne ścieżki mogą rozpocząć strumieniowanie wcześniej, dlatego nie ma gwarancji globalnego uporządkowania ani usunięcia duplikatów dla każdego żądania. Sortowanie nie dowodzi również, że zwrócona próbka zawiera najtańszy numer w całym katalogu.

Złóż osobne zamówienie i potwierdź wynik

Wyszukiwanie niczego nie kupuje ani nie rezerwuje. Zachowaj zwrócone identyfikatory numeru i planu do procesu zamawiania na tym samym koncie. Przed złożeniem zamówienia sprawdź rzeczywisty plan, wymagania i opłaty. Wymagania rejestracyjne mogą opóźnić aktywację; wynik wyszukiwania nie określa żadnego stałego terminu aktywacji.

Żądanie

Użyj aktywnego konta API MultiTEL: danych uwierzytelniających HTTP Basic dla konta z hasłem lub Authorization: Bearer dla konta z tokenem. Obowiązują uprawnienia konta i jego ograniczenia adresów IP. Zapoznaj się z ogólnymi wskazówkami dotyczącymi uwierzytelniania.

Parametry ścieżki i parametry zapytania URL. W publicznym procesie wyszukiwania używaj GET. Procedura obsługi przyjmuje również wybrane wartości formularza lub żądania, ale nie jest interfejsem API wyszukiwania z treścią żądania w formacie 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"

Odpowiedź

Jeden obiekt JSON zawierający status i response. W przypadku powodzenia status.code wynosi 200, a response jest tablicą pozycji z numerami. status.results to liczba elementów zwróconej tablicy; status.msg może mieć wartość Results: N lub OK w przypadku odpowiedzi strumieniowej. Bez compact=1 niektóre wyszukiwania zapisują tablicę response stopniowo i kończą polem status, dlatego poczekaj na pełną treść JSON. Nie jest to JSON z rekordami rozdzielanymi znakami nowego wiersza. Sprawdzaj status.code nawet wtedy, gdy transmisja HTTP zakończy się powodzeniem. Poniżej pokazano typowe pola; metadane właściwe dla źródła i pola opcjonalne mogą się różnić. Nie interpretuj wewnętrznej struktury żadnego identyfikatora i przechowuj numer wraz z wybraną dla niego wartością price[].uuid.

Przykładowa struktura odpowiedzi; nie są to rzeczywiste dane konta ani aktualna wycena.

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

Błędy

• 401: Uwierzytelnianie nie powiodło się. Nieprawidłowe lub brakujące dane uwierzytelniające oraz odmowa dostępu do konta API nie prowadzą do zwrócenia wyników wyszukiwania.
• 404: Invalid prefix ID, Invalid country, Invalid area lub No numbers found. Odczytaj status.msg; odpowiedź błędu nie jest tablicą numerów.
• 400: NUMBER_FILTER_INVALID w response.code: nieprawidłowy tryb, wartość inna niż ciąg 1–15 cyfr lub filter_required bez jednoczesnego podania trybu i wartości.
• 422: NUMBER_FILTER_UNSUPPORTED w response.code: albo numer dla prefiksu jest przydzielany w momencie zamawiania (reason=order_only_prefix, a next_function wskazuje ścieżkę zamawiania), albo jawnie wskazane źródło nie może obsłużyć wymaganego filtra.

Dostępność i skutki uboczne

• Ta procedura obsługi wyszukuje numery i przygotowuje wyceny; nie składa zamówienia na numer ani nie pobiera opłaty za jego zakup. Może odświeżać pamięć podręczną katalogu, usuwać z niej nieaktualne dane o dostępnych numerach, zapisywać plany taryfowe przypisane do konta i zapisywać dzienniki wyszukiwania.
• Dostępność jest wynikiem z określonego momentu, a nie rezerwacją. Późniejsze zamówienie może się nie powieść lub wykazać inną dostępność. Przed ponowieniem zakupu zweryfikuj i uzgodnij wynik poprzedniego zamówienia.
• Ceny są właściwe dla danego konta. Zachowaj identyfikator wybranego planu do użycia na tym samym koncie i osobno sprawdź warunki zamówienia oraz opłaty; sam ten punkt końcowy nie dowodzi, że cena pozostanie ważna do czasu późniejszego zamówienia.
• Przykładowy numer i ceny to fikcyjne dane ilustrujące strukturę odpowiedzi, a nie aktualna wycena. Możliwości numeru, liczby kanałów, okres obowiązywania oraz informacje rejestracyjne należy odczytać z rzeczywistego wybranego wyniku.
• Niektóre opisy wymagań rejestracyjnych zawierają sformatowany tekst lub linki. Podczas wyświetlania zwróconych ciągów znaków we własnej aplikacji traktuj je jako niezaufane dane.
• Dostępność numerów komórkowych i ich oznaczenia zależą od uprawnień konta do tej oferty oraz puli dostępnych numerów. Sam prefiks katalogowy lub flaga is_mobile nie określa możliwości konkretnego numeru w zakresie usług komórkowych.