--- title: "Migracja z Telserv do Bird" description: "Przenieś integrację z partnerskim API Telserv do Bird API, dopasuj każdą grupę operacji do jej wywołania Bird i zobacz, jak każde zadanie realizuje Bird." canonical: "https://bird.com/pl-pl/dokumentacja/guides/numbers/migrate/telserv" --- # 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](/docs/api/authentication) 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](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) 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`](/docs/api/reference/list-workspace-numbers). Osoba kontaktowa ds. migracji potwierdzi, kiedy to nastąpi. Aby uzyskać identyfikator `nda_` przeniesionego numeru, wyszukaj go za pomocą `GET /v1/numbers?number=`, 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](/docs/api/regions) 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 | Obszar | Partnerskie API Telserv | Bird API | | ---------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Uwierzytelnianie | Nagłówek `X-ApiKey` (V2) lub parametr `apiKey` (V1), weryfikowany względem listy dozwolonych adresów IP | `Authorization: Bearer` z kluczem API, którego zakresy wskazują dostępne obszary produktu. Lista dozwolonych adresów IP jest opcjonalna: ustaw ją w sekcji **IP restrictions** na kluczu w [**API keys**](https://bird.com/dashboard/w/api-keys) | | Identyfikatory | Liczby całkowite. Zakup numeru nadaje mu nowy `id` | Prefiksowane TypeID, takie jak `nda_`, `nor_`, `vnu_` i `spt_`. Numer zachowuje swój identyfikator `nda_`, dopóki jest przydzielony do Ciebie | | Numery telefonów | Cyfry bez wiodącego `+` | E.164 z wiodącym `+` | | Paginacja | Przesunięcia `start` i `limit`, do 1000 na stronę | Kursory: `limit` do 100 (domyślnie 25), następnie `starting_after` ustawiony na `next_cursor` poprzedniej strony. Zobacz [Paginacja](/docs/api/pagination) | | Błędy | `errorCode` podaje klasę wyjątku, a `403` obejmuje brakujący zasób i wiele błędów walidacji | `error.code` to stabilny kod `E` ze stroną dokumentacji i, jeśli znany jest sposób naprawy, z `remediation`. Brakujący zasób zwraca `404`, niespełniony warunek wstępny `412`, a nieprawidłowe dane wejściowe `422` ze szczegółami pól. Zobacz [Błędy](/docs/guides/errors) | | Środowiska | LIVE i SANDBOX, każde z własnymi kluczami | Jedno środowisko. Każde zamówienie kupuje i obciąża za prawdziwy numer, a każde połączenie testowe jest prawdziwym połączeniem | | Ponawianie | Brak klucza idempotentności | Nagłówek `Idempotency-Key` przy zapisach. Ten sam klucz i treść odtwarzają pierwszą odpowiedź z kodem `Idempotency-Replay: true`; ten sam klucz z inną treścią zwraca `409`. Zobacz [Idempotentność](/docs/guides/idempotency) | Bird API odrzuca nierozpoznany parametr zapytania z kodem `422` i błędem [`E01029`](/docs/api/errors/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`](/docs/api/reference/list-workspace-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`](/docs/api/reference/list-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](#skieruj-numer-na-trunk-sip) pokazuje żądanie, a [Zarządzanie numerami telefonów](/docs/guides/numbers/managing-numbers#find-the-voice-record-that-routes-a-number) 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 | Zadanie | Telserv | Bird | | --------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Wyszukaj numery na sprzedaż | `GET /shop` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Sprawdź jeden numer | `GET /shop/{stockDnisId}` | [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) | | Kup numer | `POST /shop/{stockDnisId}` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | | Zarezerwuj numer | `POST /shop/{stockDnisId}/reserve`, `GET /shop/reserved` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | - **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ą](#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 | Zadanie | Telserv | Bird | | --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Wyświetl swoje numery | `GET /numbers` | [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) | | Odczytaj jeden numer | `GET /numbers/{dnisId}` | [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) z identyfikatorem `nda_` lub `nal_` alokacji oraz [`GET /v1/voice/numbers/{number_id}`](/docs/api/reference/get-voice-number) z identyfikatorem `vnu_` rekordu głosowego | | Zmień numer | `PATCH /numbers/{dnisId}` | [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) z identyfikatorem `nda_` lub `nal_` alokacji oraz [`PATCH /v1/voice/numbers/{number_id}`](/docs/api/reference/update-voice-number) z identyfikatorem `vnu_` rekordu głosowego | | Zwolnij numer | `DELETE /numbers/{dnisId}?requestedCancelDate=` | [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) na koniec opłaconego okresu lub [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) od razu, w obu przypadkach z identyfikatorem `nda_` alokacji | - **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`](/docs/api/reference/list-numbers-orders). [Uzgodnij swoje numery](#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](#zwolnij-numer) pokazuje oba żądania. ### Miejsca docelowe i profile | Zadanie | Telserv | Bird | | --------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Wysyłaj połączenia do sprzętu SIP | `POST /numbers/{dnisId}/destinations` | [`POST /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/create-voice-trunk-gateway), potem skieruj `trunk` | | Przekieruj połączenia na telefon | `POST /numbers/{dnisId}/destinations` | Skieruj `forward` | | Przestań odbierać połączenia | `DELETE /numbers/{dnisId}/destinations` | Skieruj `reject` | | Odczytaj profile docelowe | `GET /destinationprofiles`, `GET /destinationprofiles/{id}` | [`GET /v1/voice/trunks`](/docs/api/reference/list-voice-trunks) i [`GET /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/list-voice-trunk-gateways) | | Zastosuj profil do numeru | `POST /numbers/{dnisId}/destinations/profile` | Skieruj `trunk` z `trunk_id` | - **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](/docs/guides/voice/caller-ids); niezweryfikowany numer zwraca `412` z [`E21053`](/docs/api/errors/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 | Zadanie | Telserv | Bird | | --------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Odczytaj wymagania | `GET /products/conditions`, `GET /masterdata/productconditions` | [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements) dla numeru albo z `program` i bez `subject_id`, aby odczytać formularz wymagany przez kraj, zanim będziesz mieć numer | | Prześlij dokument | `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), a następnie wskaż załącznik w zgłoszeniu. Zobacz [Złóż dokumentację własności](#złóż-dokumentację-własności) | | Wyślij dane użytkownika końcowego | `POST /numbers/{dnisId}/enduserdata` | [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), z dokumentami, w jednym żądaniu. Zobacz [Złóż dokumentację własności](#złóż-dokumentację-własności) | | Zastąp dokument | `POST /numbers/{dnisId}/documents` ponownie | [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission) z odrzuconymi lub wygasłymi odpowiedziami | | Sprawdź postęp dokumentacji | `GET /numbers/{dnisId}/documents` | `ownership` na [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) oraz zgłoszenie, aby poznać werdykt dla każdej odpowiedzi | - **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](/docs/guides/numbers/ownership-paperwork#upload-each-document) 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](/docs/guides/numbers/ownership-paperwork#submit-every-answer)). - **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ź](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer)). - **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](#złóż-dokumentację-własności) pokazuje żądania, a [Złóż dokumentację własności numeru](/docs/guides/numbers/ownership-paperwork) opisuje cały proces, w tym składanie z dashboardu i razem z zamówieniem. ### Produkty i dane główne | Zadanie | Telserv | Bird | | ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Przeglądaj produkty | `GET /products`, `GET /products/{productId}` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers), który wymaga `country_code` i zwraca numery dostępne w sprzedaży w tym jednym kraju. Bird nie ma globalnego katalogu produktów i nic nie odpowiada `productId`. Żadne API nie wyświetla krajów ani typów numerów dostępnych w sprzedaży; strona [cennika numerów telefonicznych](/pricing/numbers) podaje standardowe ceny Bird według kraju. | 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](/pricing/numbers). `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](/pricing/voice). Typy numerów Telserv odpowiadają wartościom `number_type` w Bird w następujący sposób: | `numberType` w Telserv | Bird `number_type` | | ---------------------- | ------------------------------------------ | | `DID` | `local` lub `national`, zależnie od numeru | | `FreePhone` | `toll_free` | | `Mobile` | `mobile` | ## 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: ```bash 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](/docs/api/reference/list-available-numbers) pokazuje przykładowy wynik. Wynik z `pricing.recurring_price: null` nie podaje ceny cyklicznej. [Skontaktuj się z działem sprzedaży](/contact-sales), 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`](/docs/api/errors/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: ```bash 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](/docs/guides/numbers/buying-numbers#poll-an-order-that-did-not-finish), 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](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) 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}`](/docs/api/reference/get-workspace-number) i sprawdź, czy `status` ma wartość `active`. Jeśli status jest oczekujący, [złóż dokumentację własności](#złóż-dokumentację-własności). [Status przydzielonego numeru](/docs/guides/numbers/overview#the-status-of-an-allocated-number) 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: ```bash 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`: ```bash 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`](/docs/api/errors/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`: ```bash 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`: ```bash 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](/docs/guides/numbers/ownership-paperwork#submit-every-answer) wyjaśnia każdą odmowę. 5. Gdy weryfikator odrzuci odpowiedź, zastąp tylko tę odpowiedź, jak opisuje [Popraw odrzuconą odpowiedź](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer): ```bash 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}`](/docs/api/reference/get-workspace-number). 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](/docs/guides/numbers/ownership-paperwork) 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](/docs/guides/voice/receiving-calls#set-a-default-route) 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](/docs/guides/voice/sip-trunks) 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`: ```bash 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}`: ```bash 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](/docs/guides/voice/receiving-calls#what-a-gateway-needs) wyjaśnia `priority` i formaty numerów. Ponowne utworzenie tej samej bramy bez klucza idempotentności zwraca `409` z [`E21047`](/docs/api/errors/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`: ```bash curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` 4. Skieruj numer na trunk: ```bash 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`](/docs/api/errors/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](/docs/guides/voice/receiving-calls#deliver-calls-to-a-sip-trunk) 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. ```bash 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: | Filtr Telserv na `GET /numbers` | Filtr Bird na `GET /v1/numbers` | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number`, który dopasowuje początek numeru | `prefix` bez `country_code`, który dopasowuje cyfry od początku pełnego numeru | | `prefix`, który równa się kodowi dostępu i kierunkowemu, np. `3170` | `country_code` z `prefix` ustawionym na cyfry krajowe: `country_code=NL&prefix=70` | | `reference` z wartością częściową | `search`, który dopasowuje część numeru, nazwy lub referencji, bez rozróżniania wielkości liter | | `reference` z dokładną wartością w cudzysłowie | `reference`, który zwraca numery z tą dokładną referencją. Dopasowanie rozróżnia wielkość liter | | Nowość w Bird | `number` zwraca jeden pełny numer podany z kodem kraju, z `+` lub `00` albo bez: `+31612345678`, `31612345678` i `0031612345678` znajdują ten sam numer | [Znajdź numer na swojej liście](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) 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](/docs/guides/numbers/managing-numbers#list-every-number-you-hold) 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`](/docs/api/reference/list-numbers-orders). ## Zwolnij numer Oba żądania dotyczą numeru dedykowanego, wskazanego przez jego identyfikator `nda_`; numer współdzielony jest odrzucany z [`E14002`](/docs/api/errors/E14002). Aby zachować numer do końca okresu, za który już zapłaciłeś, anuluj go: ```bash 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: ```bash 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`](/docs/api/errors/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](/docs/guides/numbers/managing-numbers#release-a-number) 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](/docs/guides/voice/destinations), 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](/docs/guides/voice/caller-ids) Twojego obszaru roboczego, a testowany numer w `to`: ```json { "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: ```bash 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}`](/docs/api/reference/get-voice-leg) lub wyświetl etapy połączeń wykonanych na ten numer za pomocą [`GET /v1/voice/legs`](/docs/api/reference/list-voice-legs) i jego filtra `to`, a następnie sprawdź, czy Twój sprzęt odebrał połączenie. [Utwórz połączenie głosowe](/docs/guides/voice/create-calls) opisuje wymagania dotyczące identyfikatora dzwoniącego i miejsca docelowego oraz zasady ponownych prób. ## Następne kroki - [Kup i zwolnij numer](/docs/guides/numbers/buying-numbers) - [Zarządzanie numerami telefonów](/docs/guides/numbers/managing-numbers) - [Złóż dokumentację własności numeru](/docs/guides/numbers/ownership-paperwork) - [Odbieranie połączeń](/docs/guides/voice/receiving-calls) - [Trunki SIP](/docs/guides/voice/sip-trunks) - [Idempotentność](/docs/guides/idempotency) ## Related resources - [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer) - [SMS numbers](/sms-api/features/numbers) (product) - [Number types](/docs/guides/numbers/number-types) (docs) [Get an implementation brief](/learn/workspace?topic=phone-numbers)