Migracja z Telserv do Bird

Ten przewodnik jest przeznaczony dla integracji wywołujących partnerskie API Telserv, V1 lub V2, w celu kupowania, kierowania i zwalniania numerów, które teraz przenoszą się do Bird API.

Bird API obsługuje każdy produkt Bird, więc operacje na numerach i głosie stosują konwencje Bird, a nie Telserv. Większość funkcji używanych przez Twoją integrację ma odpowiadające wywołanie Bird. Endpointy, ładunki, identyfikatory i uwierzytelnianie się różnią, więc zaplanuj przepisanie integracji. Tam, gdzie Bird realizuje zadanie inaczej, ten przewodnik pokazuje jak.

Ten przewodnik jest w trakcie tworzenia. Opisuje możliwości Bird i rozrasta się wraz z postępem migracji. Jeśli operacja Telserv, której używasz, nie jest tu wymieniona, przed jej dodaniem trzeba jeszcze określić zakres prac i ją zaimplementować; zapytaj o nią osobę kontaktową ds. migracji.

Zanim zaczniesz

• Organizacja Bird z ukończoną weryfikacją tożsamości, której wymaga pierwszy zakup numeru.
• Klucz API z zakresami używanymi w przepisach: numbers na poziomie zapisu dla numerów i zamówień, compliance na poziomie zapisu dla samodzielnych operacji na dokumentacji własności oraz voice_management na poziomie zapisu dla trunków SIP, numerów głosowych i zweryfikowanych numerów. Połączenie testowe wymaga również voice:write, a odczyt etapów połączenia wymaga voice:read.
• Saldo portfela. Zamówienia są opłacane z portfela. Gdy zamówienie zostaje odrzucone wyjaśnia odrzucenia 402 i 412.

Numery zarządzane przez Twoją integrację w Telserv nie muszą być kupowane ponownie. Gdy Twoje numery zostaną przeniesione do Twojego obszaru roboczego Bird, pojawią się w GET /v1/numbers. Osoba kontaktowa ds. migracji potwierdzi, kiedy to nastąpi. Aby uzyskać identyfikator nda_ przeniesionego numeru, wyszukaj go za pomocą GET /v1/numbers?number=<digits>, podając cyfry z kodem kraju, i zachowaj id jako NUMBER_ID.

Przykłady odczytują Twój klucz z BIRD_API_KEY, a jego hosta regionalnego z BIRD_API_URL: https://eu1.platform.bird.com dla klucza bk_eu1_ lub https://us1.platform.bird.com dla klucza bk_us1_. Pozostałe zmienne, takie jak TRUNK_ID i NUMBER_ID, przechowują identyfikator z wcześniejszej odpowiedzi; każdy krok podaje, który ustawia.

Co się zmienia w kontrakcie

Bird API odrzuca nierozpoznany parametr zapytania z kodem 422 i błędem E01029. Usuń filtry dostępne tylko w Telserv, takie jak city, ze swoich żądań, zamiast przekazywać je dalej.

Dwa identyfikatory dla jednego numeru

Numer z obsługą połączeń głosowych przydzielony do Twojego obszaru roboczego ma dwa rekordy, każdy z własnym identyfikatorem:

• Alokacja, zwracana przez GET /v1/numbers. Jej id zaczyna się od nda_ dla numeru dedykowanego i od nal_ dla współdzielonego, a number_id zamówienia to identyfikator nda_ kupionego numeru. Używaj jej do odczytu, nazywania i przypisywania referencji numeru oraz do zwalniania numeru dedykowanego.
• Rekord głosowy, vnu_, zwracany przez GET /v1/voice/numbers. Używaj go do odczytu i zmiany miejsca, do którego trafiają połączenia przychodzące na numer. Numer bez obsługi połączeń głosowych, na przykład numer wyłącznie SMS, nie ma rekordu głosowego.

Operacje głosowe odrzucają identyfikator nda_ lub nal_ z kodem 422. Aby znaleźć rekord głosowy numeru, wyświetl listę numerów głosowych z parametrem search ustawionym na cyfry numeru i wybierz wpis, którego provider.number_id odpowiada id alokacji. Skieruj numer na trunk SIP pokazuje żądanie, a Zarządzanie numerami telefonów opisuje wyszukiwanie.

GET /numbers/{dnisId} z Telserv zamienia się w dwa odczyty w Bird: alokację dla statusu i dokumentacji własnościowej oraz rekord głosowy dla trasy.

Mapowanie operacji Telserv na Bird

Każda tabela zawiera zadanie, wywołanie Telserv, które je wykonywało, oraz wywołanie Bird, które wykonuje je teraz. Uwagi pod każdą tabelą opisują, co zmienia się w żądaniu lub odpowiedzi.

Sklep

• Wyszukiwanie. country_code jest wymagany, więc wyszukiwanie obejmuje jeden kraj. prefix przyjmuje krajowe cyfry po kodzie kraju: Telserv prefix=3170 staje się country_code=NL&prefix=70. Zawęź wyniki według kodu kierunkowego za pomocą prefix zamiast city oraz według number_type i capabilities zamiast productId.
• Dokumentacja w wynikach wyszukiwania. Każdy wynik zawiera ownership_registration_required zamiast filtra excludeNumbersRequireVerification. Wartość true oznacza, że numer jest rozliczany od zakupu, ale nie wysyła SMS i nie obsługuje przychodzących ani wychodzących połączeń głosowych, dopóki jego dokumentacja nie zostanie zatwierdzona.
• Sprawdzanie pojedynczego numeru. Numer jest adresowany przez swój numer E.164.
• Ceny. Telserv zwracał pricing.staticPricing w szczegółowych odczytach numeru i produktu. W Bird każdy wynik wyszukiwania zawiera cenę dla Twojej organizacji w pricing: setup_price zamiast nrc oraz recurring_price za recurring_period zamiast mrc, z intervals_per_charge określającym, ile okresów obejmuje jedna opłata. Wyszukaj i kup numer z własną referencją opisuje pola cenowe.
• Zakup. Wyślij number i opcjonalnie reference. Zamówienie jest opłacane z portfela. Większość zamówień zwraca 201; zamówienie oczekujące na operatora zwraca 202 i należy je cyklicznie odpytywać.
• Rezerwacja. Zamówienie numeru rezerwuje go. Najpierw sprawdź kandydata, a potem go zamów.

Numery

• Lista. Lista zawiera numery aktualnie przydzielone do Ciebie. Zwolniony numer zamówiony w Bird pozostaje widoczny przez swoje zamówienie w GET /v1/numbers/orders. Uzgodnij swoje numery opisuje mapowanie filtrów.
• Odczyt. Status, dokumenty własności i cena znajdują się w alokacji, a trasa w rekordzie głosowym. Obiekt pricing alokacji, z recurring_price za recurring_period i intervals_per_charge, zastępuje pricing.staticPricing.mrc, a lista również go zawiera, czego GET /numbers w Telserv nie robił.
• Zmiana. name i reference znajdują się w alokacji, a trasa w rekordzie głosowym. Ustaw wymuszony kodek i limit jednoczesnych połączeń na swoim sprzęcie SIP. destinationDistributionType staje się priority bramy na trunku SIP: FailOver nadaje każdej bramie inny priority, a RoundRobin nadaje im ten sam.
• Zwolnienie. DELETE utrzymuje numer do końca opłaconego okresu i wtedy go zwalnia. POST …/release zwalnia go natychmiast. Żadne z tych żądań nie przyjmuje daty. Zwolnij numer pokazuje oba żądania.

Miejsca docelowe i profile

• Sprzęt SIP. Brama należy do trunka i obsługuje każdy numer skierowany na niego, więc numery wymagające różnych list docelowych wymagają różnych trunków. sortOrder staje się priority. Czas dzwonienia i okna czasowe ustaw na swoim sprzęcie SIP.
• Przekierowanie. Ustaw forward_to i forward_as. forward_to musi być jednym z Twoich zweryfikowanych numerów; niezweryfikowany numer zwraca 412 z E21053. forward_as określa, który numer przekierowane połączenie pokazuje jako dzwoniącego. Numer ma jedną trasę w danym momencie, więc aby przełączyć się ze sprzętu SIP na numer telefonu, przekieruj połączenie ze swojego sprzętu SIP.
• Zatrzymanie przyjmowania połączeń. Numer odrzuca połączenia, dopóki nie wytyczysz mu trasy ponownie. Aby zachować stałe ustawienie domyślne zamiast domyślnego profilu, skieruj numer na trunk zawierający Twoje domyślne bramy.
• Profile. distributionType staje się priority: FailOver nadaje każdej bramie inny priority, a RoundRobin nadaje im ten sam. Dystrybucja jest ustawiana per trunk, więc numery wymagające różnej dystrybucji potrzebują różnych trunków. Symbol zastępczy {dnis} staje się {number} w destination_format, a prefixCLIP staje się tekstem przed {number} w origination_format.
• Zastosowanie profilu. Trunk jest adresowany przez swój identyfikator spt_, podczas gdy Telserv adresował profil po nazwie.

Dokumenty i dane użytkownika końcowego

• Wymagania. Katalog warunków Telserv obejmował wszystkie produkty naraz; Bird odczytuje jeden formularz naraz. Zapytaj o wymagania jednego numeru za pomocą subject_kind=number, jego identyfikatora nda_ jako subject_id i jego country_code albo odczytaj formularz przed zakupem, ustawiając program na typ numeru i pomijając subject_id. Każdy wpis w fields zastępuje warunek lub etykietę użytkownika końcowego z Telserv: jego key wskazuje, pod czym podajesz odpowiedź, a data_type document oznacza wpis wymagający pliku.
• Dokumenty. Prześlij plik jako multipart/form-data zamiast fileContent w base64; Prześlij każdy dokument wymienia akceptowane pliki. Dwukrotne przesłanie tego samego pliku zwraca ten sam załącznik. Samo przesłanie niczego nie składa: składa to zgłoszenie, które wskazuje jego attachment_id.
• Dane użytkownika końcowego i dokumenty razem. Telserv przyjmował każdy dokument w osobnym wywołaniu, a dane użytkownika końcowego jako jedną listę etykiet w kolejnym. Bird przyjmuje wszystkie odpowiedzi, tekstowe i dokumenty, w jednym zgłoszeniu i nie ma wersji roboczych: żądanie składa odpowiedzi do weryfikacji. Następnie śledź ownership.next, które wskazuje uzupełnienie w przypadku poprawek, a nowe zgłoszenie tylko wtedy, gdy jest potrzebne (Prześlij wszystkie odpowiedzi).
• Zastąpienia. Wyślij tylko odpowiedzi, które zastępujesz, a pozostałe zachowają swoją weryfikację. Telserv przyjmował nowy plik dla warunku, gdy numer oczekiwał na weryfikację, a plik resetował weryfikację tego warunku; Bird zastępuje odpowiedź odrzuconą, wygasłą lub jeszcze niedostarczoną i odrzuca odpowiedź nadal weryfikowaną lub już zaakceptowaną, z wyjątkiem odpowiedzi oznaczonej jako editable_for_verifier_repair, gdy otwarta jest poprawka, o którą poprosiliśmy (Popraw odrzuconą odpowiedź).
• Postęp. ownership.status i ownership.next informują o stanie numeru. Każda odpowiedź ma własny state, a odrzucona zawiera reason od weryfikującego. Bird wysyła też każdy wynik e-mailem do właścicieli Twojej organizacji oraz do osoby, która ostatnio złożyła lub poprawiła zgłoszenie. ownership zwykle ma wartość null, gdy numer nie wymaga dokumentacji.

Złóż dokumentację własności pokazuje żądania, a Złóż dokumentację własności numeru opisuje cały proces, w tym składanie z dashboardu i razem z zamówieniem.

Produkty i dane główne

Każdy wynik wyszukiwania opisuje swój produkt za pomocą number_type, capabilities i ownership_registration_required oraz zawiera cenę dla Twojej organizacji zamiast pricing.staticPricing produktu (nrc i mrc). Ceny standardowe Bird znajdują się na stronie cennika numerów telefonicznych. sessionPricing z Telserv, naliczane za minutę, nie ma odpowiednika w tych odczytach; stawki za połączenia głosowe znajdują się na stronie cennika usług głosowych.

Typy numerów Telserv odpowiadają wartościom number_type w Bird w następujący sposób:

Co działa inaczej

Te zadania z Telserv działają inaczej w Bird. Zaplanuj je, zanim przeniesiesz integrację, która zależy od któregoś z nich.

• Dokumentacja. Złóż dokumenty i dane użytkownika końcowego numeru w jednym zgłoszeniu, bez wersji roboczych, a odrzucone odpowiedzi popraw przez ponowne dostarczenie.
• Rezerwacje. Zamów numer, kiedy go wybierzesz; zamówienie go rezerwuje.
• Ustawienia połączeń per numer. Ustaw wymuszony kodek, limit równoczesnych połączeń, czas dzwonienia i okna czasowe na swoim sprzęcie SIP.
• Data zwolnienia. Bird zwalnia numer na koniec opłaconego okresu albo natychmiast, a nie w wybranej przez Ciebie dacie. Zachowaj daty anulowania, które wysyłałeś do Telserv, po swojej stronie i wykonaj każdą z nich, gdy nadejdzie jej termin.
• Saldo portfela. Sprawdź saldo i doładuj je w dashboardzie.

Wyszukaj i kup numer z własną referencją

Wyszukaj w jednym kraju. Połącz number_type, capabilities i prefix, aby zawęzić wyniki:

curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Każdy wynik zawiera obiekt pricing z ceną, jaką Twoja organizacja płaci za numer, netto (bez podatku) i w Twojej walucie rozliczeniowej, z uwzględnieniem cen uzgodnionych z Bird:

• setup_price jest pobierana jednorazowo przy zamówieniu numeru. Opublikowana opłata zerowa ma amount równe "0". Samo pole ma wartość null, gdy opłata aktywacyjna nie obowiązuje, a także zawsze, gdy recurring_price ma wartość null, ponieważ takiego numeru nie można zamówić.
• recurring_price to stawka za recurring_period.
• intervals_per_charge określa, ile recurring_period obejmuje jedno naliczenie. Opłata cykliczna przed opodatkowaniem to recurring_price pomnożona przez intervals_per_charge, pobierana w momencie przypisania numeru do Twojego obszaru roboczego i przy każdym odnowieniu; opłata aktywacyjna jest osobna. W przypadku zamówienia oczekującego na operatora przypisanie następuje po zrealizowaniu zamówienia.

Dokumentacja API pokazuje przykładowy wynik. Wynik z pricing.recurring_price: null nie podaje ceny cyklicznej. Skontaktuj się z działem sprzedaży, aby przed złożeniem zamówienia ustalić cenę dla tego kraju i typu numeru.

Dashboard i API używają tej samej ceny organizacji, łącznie z przeliczeniem na Twoją walutę rozliczeniową. Odczyt ceny nie blokuje wyceny: zmiany taryfy lub kursu walutowego przed późniejszym obciążeniem mogą zmienić jego kwotę. Jeśli wyszukiwanie ceny się nie powiedzie, wyszukiwanie zwraca 503 z E14009. Spróbuj ponownie odczytać cenę z wykładniczym wydłużaniem odstępów; niepowodzenie wyszukiwania ceny nigdy nie oznacza, że numer nic nie kosztuje.

Aby potwierdzić kandydata i jego cenę przed złożeniem zamówienia, odczytaj go za pomocą GET /v1/numbers/available/{number}. 404 oznacza, że numer nie jest już dostępny w sprzedaży.

Zamów numer z referencją używaną w Telserv i wybierz klucz idempotentności, który zachowasz na wypadek ponownej próby tego zakupu:

curl --request POST "$BIRD_API_URL/v1/numbers/orders" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-CUST-778812" \
  --data '{"number": "+31612345678", "reference": "CUST-778812"}'

Odpowiedź 201 zawiera status: completed i number_id, identyfikator nda_ numeru. Zachowaj go jako NUMBER_ID. Odpowiedź 202 oznacza, że zamówienie czeka na operatora: odpytuj zamówienie, aż jego status przyjmie wartość completed lub failed. Opłata aktywacyjna już pobrana nie jest zwracana, jeśli zamówienie potem się nie powiedzie. Referencja jest ustawiana na numerze po zakończeniu zamówienia. Może mieć do 100 znaków i nie musi być unikalna.

Gdy spróbujesz ponownie zamówić numer już przydzielony do Twojego obszaru roboczego, otrzymasz istniejące zamówienie, więc ponowna próba nie powoduje podwójnego obciążenia. Kup i zwolnij numer opisuje odmowy.

Aby ustawić lub zmienić referencję później, wyślij reference (i opcjonalnie name) do PATCH /v1/numbers/{number_id}. Wyślij null, aby wyczyścić pole.

Sprawdź, czy numer może obsługiwać połączenia

Numer, którego status ma wartość pending_ownership_registration, jest przydzielony i rozliczany, ale nie wysyła SMS i odrzuca przychodzące i wychodzące połączenia głosowe do czasu zatwierdzenia dokumentacji własności. Zanim skierujesz numer lub wykonasz do niego połączenie testowe, odczytaj go za pomocą GET /v1/numbers/{number_id} i sprawdź, czy status ma wartość active. Jeśli status jest oczekujący, złóż dokumentację własności. Status przydzielonego numeru opisuje każdą wartość.

Poniższe przykłady używają holenderskiego numeru komórkowego. Sprawdź status swojego numeru w ten sam sposób, niezależnie od kraju.

Złóż dokumentację własności

Telserv przyjmował dokumentację numeru przez jedno POST /numbers/{dnisId}/documents na dokument i jedno POST /numbers/{dnisId}/enduserdata dla wszystkich etykiet. Bird przyjmuje oba w jednym zgłoszeniu, po przesłaniu dokumentów.

1. Odczytaj country_code numeru i zachowaj go jako COUNTRY_CODE. Polecenie wyodrębnia go za pomocą jq; jeśli nie używasz jq, odczytaj go ręcznie:

   Przykład kodu

   COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

2. Odczytaj, czego wymaga kraj numeru. Każdy wpis w fields ma key, pod którym udzielasz odpowiedzi, data_type oraz required, które określa, czy odpowiedź jest obowiązkowa. Zachowaj program wskazany w odpowiedzi jako PROGRAM:

   Przykład kodu

   curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
     --header "Authorization: Bearer $BIRD_API_KEY"

   422 z E19001 oznacza, że dla tego kraju nie ma formularza własności.

3. Prześlij każdy dokument, którego wymaga pole document, jako plik zamiast base64 fileContent. Zachowaj id z odpowiedzi, identyfikator tca_ załącznika, jako ATTACHMENT_ID:

   Przykład kodu

   curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --form "file=@registration-certificate.pdf"

4. Prześlij wszystkie odpowiedzi naraz: jeden wpis dla każdego pola, którego required ma wartość true, oraz dla każdego pola opcjonalnego, na które masz prawdziwą odpowiedź, z danymi użytkownika końcowego jako value i każdym dokumentem jako attachment_id. Pomiń pole opcjonalne zamiast wymyślać dla niego wartość. Przykład pokazuje dwie odpowiedzi; przed wysłaniem dodaj pozostałe wymagane. To żądanie składa odpowiedzi do weryfikacji. Zachowaj id z odpowiedzi, identyfikator csb_ zgłoszenia, jako SUBMISSION_ID:

   Przykład kodu

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-CUST-778812" \
     --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}'

   Odpowiedź 201 zwraca zgłoszenie. 422 niczego nie składa: popraw treść i wyślij ją z nowym kluczem idempotentności, ponieważ dotychczasowy klucz odtwarza odmowę. Prześlij wszystkie odpowiedzi wyjaśnia każdą odmowę.

5. Gdy weryfikator odrzuci odpowiedź, zastąp tylko tę odpowiedź, jak opisuje Popraw odrzuconą odpowiedź:

   Przykład kodu

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-fix-1-CUST-778812" \
     --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Aby złożyć dokumentację podczas zakupu, wyślij to samo answers w bloku compliance żądania POST /v1/numbers/orders. Takie zamówienie korzysta z istniejącego zakresu numbers na poziomie zapisu, również wtedy, gdy zawiera dokumentację.

Śledź przegląd za pomocą ownership.status na GET /v1/numbers/{number_id}. Odpowiedzi są prawnym oświadczeniem składanym w imieniu Twojej firmy, więc składaj tylko odpowiedzi potwierdzone przez osobę, która za nie odpowiada. Złóż dokumentację własności numeru opisuje każde żądanie, przegląd i składanie dokumentacji razem z zamówieniem.

Skieruj numer na trunk SIP

Nowy numer nie ma własnej trasy, więc korzysta z domyślnej trasy Twojego obszaru roboczego. Ta trasa domyślnie ma wartość reject, ale w obszarze roboczym, który już ją ustawił, nowy numer odbiera połączenia zgodnie z nią od chwili przydzielenia. Aby dostarczać jego połączenia do swojego sprzętu, utwórz trunk SIP z włączonym połączeniem przychodzącym, dodaj do niego bramę i skieruj numer na trunk. Trunki SIP opisuje podłączanie sprzętu do trunka.

1. Utwórz trunk z włączonym połączeniem przychodzącym. Zachowaj id z odpowiedzi, identyfikator spt_ trunka, jako TRUNK_ID:

   Przykład kodu

   curl --request POST "$BIRD_API_URL/v1/voice/trunks" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: trunk-production-pbx" \
     --data '{"name": "Production PBX", "inbound_enabled": true}'

2. Dodaj bramę. Domyślnie brama otrzymuje numery wybierane i dzwoniące w formacie E.164 z ich +. Jeśli Twój sprzęt oczekuje numerów bez +, tak jak robił to symbol zastępczy {dnis} w Telserv, ustaw destination_format dla numeru wybieranego i origination_format dla numeru dzwoniącego na {number}:

   Przykład kodu

   curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: gateway-pbx-primary" \
     --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}'

   Aby zapewnić przełączanie awaryjne, dodaj drugą bramę; Czego potrzebuje brama wyjaśnia priority i formaty numerów. Ponowne utworzenie tej samej bramy bez klucza idempotentności zwraca 409 z E21047.

3. Znajdź rekord głosowy numeru. Wyszukaj po cyfrach numeru i weź id wpisu, którego provider.number_id jest id alokacji. Zachowaj go jako VOICE_NUMBER_ID:

   Przykład kodu

   curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \
     --header "Authorization: Bearer $BIRD_API_KEY"

4. Skieruj numer na trunk:

   Przykład kodu

   curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}'

   Odpowiedź 200 pokazuje nową trasę. Trunk z wyłączonym połączeniem przychodzącym zwraca 412 z E21052.

Wyłączenie połączenia przychodzącego na trunku lub usunięcie trunka przywraca każdy skierowany na niego numer do domyślnej trasy Twojego obszaru roboczego, a ponowne włączenie nie przywraca tych tras. Dostarczaj połączenia do trunka SIP wyjaśnia to oraz trasy trunk, forward i reject.

Uzgodnij swoje numery

Przeglądaj listę z największym rozmiarem strony. Przekaż next_cursor każdej strony jako NEXT_CURSOR, aby odczytać następną stronę, aż next_cursor będzie null. Lista nie zwraca łącznej liczby.

curl "$BIRD_API_URL/v1/numbers?limit=100" \
  --header "Authorization: Bearer $BIRD_API_KEY"

curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Filtry listy Telserv odpowiadają filtrom Bird w następujący sposób:

Znajdź numer na swojej liście opisuje szczegółowo każdy filtr.

Każdy wpis zawiera pricing, z recurring_price za recurring_period i intervals_per_charge. Jeśli cena nie jest ustalona dla danego numeru, recurring_price to bieżąca stawka Twojej organizacji, a każde odnowienie nalicza stawkę obowiązującą w momencie odnowienia, więc już naliczona opłata może się od niej różnić. Wyświetl wszystkie posiadane numery wyjaśnia, w jakiej walucie naliczana jest opłata za każdy numer, kiedy pricing lub jego ceny mają wartość null i co zrobić, gdy pricing.error jest ustawione.

Zwolniony numer znika z tej listy, a odczyt po number_id zwraca 404. Jeśli zamówiłeś go w Bird, jego zrealizowane zamówienie pozostaje w GET /v1/numbers/orders.

Zwolnij numer

Oba żądania dotyczą numeru dedykowanego, wskazanego przez jego identyfikator nda_; numer współdzielony jest odrzucany z E14002. Aby zachować numer do końca okresu, za który już zapłaciłeś, anuluj go:

curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: cancel-CUST-778812"

Odpowiedź 202 zwraca numer z releases_at, końcem jego opłaconego okresu. Numer zachowuje obecny status do tego czasu, jego subskrypcja nie jest odnawiana i zostaje zwolniony w tym momencie. Ponowne żądanie zwraca tę samą wartość releases_at, a anulowania nie można cofnąć. Numer bez subskrypcji jest zwalniany natychmiast, a odpowiedź to 200 z status numeru ustawionym na released.

Aby zwolnić numer teraz, w tym numer już zaplanowany do anulowania:

curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: release-CUST-778812"

Odpowiedź 204 oznacza, że numer jest zwolniony ze skutkiem natychmiastowym. Pozostała część bieżącego okresu nie jest zwracana.

Dopóki płatność za odnowienie numeru jest zaległa, oba żądania zwracają 409 z E03015, aż zostanie opłacona.

Żadne z żądań nie przyjmuje daty, więc zachowaj harmonogram, który wysyłałeś do Telserv jako requestedCancelDate, po swojej stronie. Aby zatrzymać numer do jego daty, anuluj go, gdy data przypada w bieżącym okresie rozliczeniowym: numer zostaje zwolniony, gdy ten okres się kończy, w dniu tej daty lub później. Aby oddać go dokładnie w danym dniu, zwolnij go tego dnia. Zwolnij numer opisuje, co każde żądanie robi z numerem i jego opłatami oraz co się dzieje, gdy spróbujesz ponownie.

Wykonaj połączenie testowe na swój numer

Aby sprawdzić trasę od początku do końca, wykonaj połączenie na numer z innego numeru, który Twój obszar roboczy może przedstawić jako identyfikator dzwoniącego. Kraj numeru musi być włączony w Twoich miejscach docelowych połączeń głosowych, w przeciwnym razie połączenie nie zostanie zrealizowane. Poniższe żądanie uruchamia sekwencję inline, która rozłącza się po odebraniu połączenia, więc zapisana sekwencja nie jest potrzebna. Wykonuje ono prawdziwe połączenie i obowiązują standardowe opłaty za połączenia.

Zapisz żądanie jako test-call.json. Umieść identyfikator dzwoniącego, który prezentujesz, w from, własny lub zweryfikowany numer Twojego obszaru roboczego, a testowany numer w to:

{
  "from": "+31612345679",
  "to": "+31612345678",
  "sequence": {
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "entry",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {},
          "input": {},
          "connections": { "event": { "node_id": "end", "port": "input" } }
        },
        { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} }
      ]
    },
    "entry_node_id": "entry",
    "trigger_data": {}
  }
}

Wyślij je:

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \
  --data-binary @test-call.json

Ustaw TEST_CALL_KEY na nową wartość przy każdym teście i użyj jej ponownie, gdy spróbujesz ponownie wykonać ten sam test po przekroczeniu limitu czasu lub przy niejasnym wyniku: ten sam klucz i żądanie w ciągu trzech godzin odtwarzają pierwszą akceptację zamiast wykonywać drugie połączenie. Odpowiedź 202 akceptuje połączenie i zwraca jego initial_leg_id. Akceptacja nie dowodzi, że połączenie zostało nawiązane: odczytaj etap połączenia za pomocą GET /v1/voice/legs/{leg_id} lub wyświetl etapy połączeń wykonanych na ten numer za pomocą GET /v1/voice/legs i jego filtra to, a następnie sprawdź, czy Twój sprzęt odebrał połączenie. Utwórz połączenie głosowe opisuje wymagania dotyczące identyfikatora dzwoniącego i miejsca docelowego oraz zasady ponownych prób.

Następne kroki

• Kup i zwolnij numer
• Zarządzanie numerami telefonów
• Złóż dokumentację własności numeru
• Odbieranie połączeń
• Trunki SIP
• Idempotentność