Zamawianie numerów telefonicznych z prefiksu

Zamawianie z prefiksu

Użyj tej operacji, gdy katalog prefiksów wskazuje, że należy zamówić określoną liczbę numerów z prefiksu zamiast wybierać poszczególne dostępne numery. Zacznij od krajów, obszarów lub stanów oraz prefiksów. Zachowaj identyfikator prefiksu i plan cenowy z tego samego aktualnego wyniku. W przypadku konkretnego numeru wybranego z listy dostępnych numerów skorzystaj z instrukcji Zakup wybranego numeru telefonicznego.

To żądanie może spowodować zakup numerów i naliczenie opłat. Nie jest to wycena, rezerwacja ani próba bez realizacji. Przed wysłaniem sprawdź opłaty aktywacyjne i miesięczne, stawki za minuty połączeń przychodzących, minuty w pakiecie, kanały, wymagania rejestracyjne oraz limity zakupów na koncie. Wynik z katalogu nie rezerwuje numerów ani nie gwarantuje niezmienności cen. Sprawdzenie zasilenia konta może nastąpić przed realizacją; sam błąd nie dowodzi, że nie doszło do zakupu ani zasilenia konta.

Wysłanie żądania zakupu

Korzystaj z włączonego konta API przez HTTPS, z dozwolonego źródłowego adresu IP. Ustaw zmienne zgodnie z bieżącym wyborem w katalogu i zatwierdzoną konfiguracją dostarczania połączeń. Poniższe polecenie kupuje jeden numer.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Powyżej przedstawiono żądanie POST z danymi formularza. Koordynator odczytuje również obiekt JSON, gdy Content-Type ma wartość application/json. Pola JSON zastępują odpowiadające im pola formularza lub żądania. Konsekwentnie używaj jednego kodowania; nie wysyłaj sprzecznych wartości w parametrach zapytania i treści żądania.

Ustawienia dostarczania i odnawiania

Wybierz takie same ustawienia dostarczania, jakie zostałyby użyte dla tego numeru w portalu. Są to zaawansowane wartości konfiguracyjne, a nie instrukcje tworzenia hostowanej centrali PBX ani łącza trunk do odbierania połączeń. Użyj ponownie sprawdzonej, działającej konfiguracji konta i po zakupie zweryfikuj zapisany numer. Samo zaakceptowanie zakupu nie potwierdza, że dostarczanie połączeń głosowych lub wiadomości SMS działa.

Te pola są normalizowane i przekazywane do procesu zakupu, ale sposób ich zapisywania różni się między ścieżkami obsługi poszczególnych pul numerów. Obecna trasa zamawiania nie udostępnia pól ścisłych limitów wyceny opisanych w instrukcji zakupu wybranego numeru jako równoważnych zabezpieczeń. Korzystaj z uprawnień do zakupów i limitów cen na koncie oraz sprawdź wynikową konfigurację numeru.

Odczytanie pełnego wyniku

Przetwórz treść JSON i sprawdź status.code oraz status.msg, nawet gdy żądanie HTTP zakończy się powodzeniem. Ta trasa zapisuje własną odpowiedź JSON, a współdzielona funkcja pomocnicza odpowiedzi również nie zawsze odwzorowuje kod aplikacji na status HTTP. Kody aplikacji mogą być liczbami JSON lub ciągami znaków zawierającymi liczby. Nie wymagaj obecności status.results; to pole nie występuje w standardowym wyniku zamówienia.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

Powyższy identyfikator, numer i ceny są fikcyjne. Traktuj identyfikator zamówienia jako nieprzezroczysty, bez interpretowania jego struktury. numbers zawiera listę numerów, które ta odpowiedź zgłasza jako zakupione; porównaj jej długość z zamówioną liczbą. Kwoty cen są ciągami znaków, a ta odpowiedź zaokrągla stawki pieniężne do dwóch miejsc po przecinku, w tym per_minute; oryginalną precyzję stawek uzyskasz z aktualnego katalogu. Minuty w pakiecie i kanały mogą zostać zwrócone jako wartości liczbowe lub ciągi znaków zawierające liczby.

Blok ceny opisuje wybrany plan użyty do utworzenia odpowiedzi, a nie szczegółową fakturę dla każdego numeru ani łączną kwotę zamówienia. Poszczególne dostępne numery rozpatrywane przy zakupie mogą mieć różne plany. Zweryfikuj poszczególne zakupione numery i transakcje na koncie, zamiast mnożyć wartości z tego bloku i zakładać, że potwierdza to ostateczną kwotę.

Częściowe zakupy i niepewne wyniki

Kodowi aplikacji 200 może towarzyszyć ostrzeżenie i mniejsza liczba numerów niż zamówiona. Późniejszy błąd nie cofa zakupu już kupionych numerów. Zachowaj zwrócony identyfikator zamówienia, numery i komunikat. Sprawdź zgodność tych numerów ze swoją pulą numerów i transakcjami na koncie, zanim zdecydujesz, czy zamówić pozostałą liczbę.

Przekroczenie limitu czasu, zerwanie połączenia podczas żądania, nieprawidłowo sformowana odpowiedź lub błąd po wysłaniu nie są dowodem, że nic się nie wydarzyło. Nie wysyłaj automatycznie kolejnego żądania zakupu, nawet z tym samym oznaczeniem. Zachowaj pierwotne żądanie, oznaczenie i każdy zwrócony identyfikator zamówienia, sprawdź pulę numerów oraz transakcje na koncie i skontaktuj się z pomocą techniczną, jeśli wynik nadal jest niepewny.

Niepotwierdzone zamówienie może zwrócić kod aplikacji 400 z komunikatem, że nadal trwa jego potwierdzanie. Zachowaj zwrócony identyfikator zamówienia i zweryfikuj ten zakup; nie jest to polecenie ponownego wysłania żądania. Mechanizm odzyskiwania zapisanych zamówień śledzi pierwotne zamówienie wewnętrznie. Nowe żądanie tej operacji tworzy oddzielną próbę zakupu zamiast wznawiać zamówienie na podstawie Twojego oznaczenia, może więc spowodować zakup kolejnych numerów i naliczenie za nie opłat. Nie używaj powtarzanych żądań zakupu do sprawdzania statusu ani przeszukiwania puli numerów.

Rejestracja i aktywacja

Zakupiony lub przydzielony numer może nadal wymagać rejestracji lub aktywacji. Jeśli needs_registration ma wartość 1, sprawdź restrictions i registration_requirements. To ostatnie pole może wskazywać v3/get_requirements z wartościami country i number_type. Przeprowadź wymagany proces weryfikacji tożsamości lub adresu i potwierdź status numeru, zanim zaczniesz polegać na połączeniach przychodzących lub wiadomościach.

features opisuje deklarowane możliwości; nie potwierdza działania routingu, zatwierdzenia kampanii, dostarczania SMS ani odbierania faksów. Sprawdź zapisane ustawienia dostarczania i wykonaj odpowiedni test usługi, gdy numer będzie aktywny.

Powiadomienia zwrotne o zamówieniu

Powiadomienia zwrotne wysyłają metodą POST dane JSON zawierające status zamówienia i odpowiedź, z dodanym Twoim oznaczeniem, jeśli je podano. Są wysyłane dla zgłoszonych zakupów, także przy wynikach częściowych. Nieudane powiadomienie zwrotne nie cofa zakupu. Dostarczenie może być ponawiane, dlatego obsługuj duplikaty według identyfikatora zamówienia i weryfikuj numery, zamiast wysyłać kolejne żądanie zakupu.

Ta trasa nie dodaje podpisu kryptograficznego do powiadomienia zwrotnego. Traktuj je jako powiadomienie wymagające porównania z pulą numerów odczytaną po uwierzytelnieniu, a nie jako samodzielne upoważnienie do naliczania opłat, uruchamiania usług lub przyznawania dostępu. Nie umieszczaj danych uwierzytelniających API w adresie URL powiadomień zwrotnych. Wysłanie kolejnego żądania zakupu z innym adresem URL powiadomień zwrotnych nie aktualizuje pierwotnego zamówienia; tworzy oddzielną próbę zakupu. Zachowaj identyfikator pierwotnego zamówienia, gdy prosisz pomoc techniczną o zbadanie jego powiadomienia zwrotnego.

Błędy wymagające obsługi