--- title: "Złóż dokumenty potwierdzające własność numeru" description: "Złóż dokumenty potwierdzające własność numeru telefonu, których wymaga dany kraj, z poziomu panelu lub przez API, śledź ich weryfikację i poprawiaj odrzucone odpowiedzi." canonical: "https://bird.com/pl-pl/dokumentacja/guides/numbers/ownership-paperwork" --- # Złóż dokumenty potwierdzające własność numeru Niektóre kraje wymagają informacji o tym, kto jest właścicielem numeru, zanim numer zacznie obsługiwać ruch. Dopóki te dokumenty nie zostaną zaakceptowane, a rejestracja numeru się nie zakończy, numer jest przydzielony do Ciebie i naliczane są za niego opłaty, ale jego `status` ma wartość `pending_ownership_registration`: nie obsługuje przychodzących ani wychodzących połączeń głosowych i nie wysyła SMS. Numer zaczyna obsługiwać ruch, gdy jego `status` ma wartość `active`, a `ownership.blocked_at` ma wartość `null`. Dokumenty złożysz z poziomu panelu lub przez API. Obie ścieżki korzystają z tych samych wymagań, zasad weryfikacji i procesu rejestracji. Pole `ownership.next` numeru podaje każdy krok, w tym moment, w którym należy złożyć nowe zgłoszenie. Składane odpowiedzi są oświadczeniem prawnym złożonym w imieniu Twojej firmy. Po akceptacji są przekazywane operatorowi lub regulatorowi w danym kraju pod nazwą firmy, której dotyczą. Dlatego przed złożeniem potwierdź je z osobą za nie odpowiedzialną i nie pozwalaj, by zautomatyzowane zadanie składało odpowiedzi, których nikt nie sprawdził. ## Zanim zaczniesz - Aby złożyć dokumenty z poziomu panelu, Twoja rola w obszarze roboczym musi pozwalać na edycję danych zgodności. Bez tego uprawnienia numer pokazuje status własności, ale nie ma przycisku do złożenia dokumentów. - Aby złożyć dokumenty przez samodzielne endpointy zgodności, potrzebujesz [klucza API](/docs/guides/authentication) z zakresem `compliance` na poziomie zapisu. Klucz z poziomem odczytu może sprawdzać wymagania i postęp weryfikacji, ale nie może składać dokumentów. Odczyt numeru wymaga też zakresu `numbers` na poziomie odczytu. W selektorze kluczy w panelu zakres `compliance` znajduje się w sekcji **Compliance**. - Identyfikator `nda_` numeru z [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Sposób jego wyszukania opisuje strona [Znajdź numer na liście](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list). Przykłady API odczytują klucz z `BIRD_API_KEY`, jego [host regionalny](/docs/api/regions) z `BIRD_API_URL`, a identyfikator numeru z `NUMBER_ID`. Każdy kolejny krok podaje zmienną, którą ustawia. Polecenia `jq` wyodrębniają jedno pole z odpowiedzi. Jeśli nie używasz `jq`, odczytaj to pole ręcznie. ## Sprawdź, czy numer wymaga dokumentów Odczytaj numer za pomocą [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number): ```bash curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Zapisz `country_code` numeru jako `COUNTRY_CODE`. Używają go zarówno odczyt wymagań, jak i zgłoszenie: ```bash COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code) ``` `ownership` ma wartość `null`, gdy kraj numeru nie wymaga żadnych dokumentów. Ma też wartość `null`, gdy nie udało nam się odczytać postępu dokumentów, a na numerze nie zapisano żadnej blokady. W takim przypadku odczytaj numer ponownie. W przeciwnym razie zawiera: - `status`: `needs_input` oznacza, że brakuje odpowiedzi lub wymagają one poprawienia, `under_review` oznacza, że Twoje odpowiedzi są weryfikowane, `approval_pending` oznacza, że dokumenty zostały zaakceptowane, a rejestracja jest jeszcze w toku; połączenia i wychodzące SMS pozostają zablokowane, dopóki ustawione jest `blocked_at`. `approved` oznacza, że rejestracja została zatwierdzona, choć połączenia i wychodzące SMS pozostają zablokowane, dopóki ustawione jest `blocked_at`. `not_required` oznacza, że nic więcej nie jest wymagane. `rejected` oznacza, że zgłoszenie zostało zamknięte lub minął termin na poprawki i nie przyjmuje już kolejnych poprawek. Skontaktuj się z pomocą techniczną, aby je ponownie otworzyć. `unknown` oznacza, że nie udało się odczytać statusu. Odczytaj numer ponownie. - `next`: kolejne kroki, które posuwają procedurę dokumentów naprzód. Krok `wait` oznacza, że w tej chwili nic nie musisz robić. Odczytaj to pole ponownie po każdej zmianie. - `submission_id`: najnowsze zgłoszenie dla numeru, gdy już jakieś istnieje. - `blocked_at`: moment rozpoczęcia blokady związanej z własnością numeru lub `null` po jej zniesieniu. Blokada wstrzymuje przychodzące i wychodzące połączenia głosowe oraz wychodzące SMS. [Status przydzielonego numeru](/docs/guides/numbers/overview#the-status-of-an-allocated-number) wyjaśnia, jak `ownership` ma się do własnego pola `status` numeru. ## Złóż dokumenty w panelu 1. Otwórz numer na stronie [**Numbers**](https://bird.com/dashboard/w/numbers). Jego wiersz **Ownership** pokazuje status dokumentów i kolejne kroki. 2. Gdy status to **Details needed**, wybierz **Update ownership details**. Otworzy się formularz **Prove ownership of this number**. 3. Wybierz firmę, do której należy numer, lub opisz nową, a następnie odpowiedz na każdą pozycję i prześlij wymagane w niej dokumenty. Jeśli pozycja udostępnia pusty formularz, możesz go pobrać, wypełnić i przesłać z powrotem. 4. Wybierz **Submit answers**. Wiersz **Ownership** zmienia stan na **Under review**. Jeśli weryfikator odrzuci odpowiedź, wiersz wraca do stanu **Details needed**: ponownie wybierz **Update ownership details**, popraw odpowiedzi wskazane w formularzu, a następnie wybierz **Update ownership details** na końcu formularza, aby je wysłać. Jeśli dla kraju numeru nie ma jeszcze formularza, strona formularza wyświetla komunikat **Ownership form unavailable**. Skontaktuj się z pomocą techniczną i poproś o formularz dla tego kraju. ## Złóż dokumenty przez API Aby złożyć dokumenty przez API, odczytaj wymagania kraju, prześlij każdy dokument, wyślij wszystkie odpowiedzi naraz, a następnie odczytuj numer, aby śledzić przegląd. ### Odczytaj wymagania kraju Odczytaj wymagania dla numeru za pomocą [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements). Ustaw `subject_kind` na `number`, `subject_id` na identyfikator `nda_` numeru, a `country_code` na własne `COUNTRY_CODE` numeru: ```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" ``` Odpowiedź podaje `program`, w ramach którego numer jest rejestrowany, zależny od typu numeru; zapisz go jako `PROGRAM`. Odpowiedź wymienia w `fields` każdą pozycję do wypełnienia, w kolejności, w jakiej należy je przedstawić. Dla każdego pola: - `key` to klucz, pod którym wysyłasz odpowiedź. - `data_type` określa sposób odpowiedzi. Pole `document` przyjmuje przesłany plik; każdy inny typ przyjmuje ciąg znaków, więc liczbę wysyłasz jako `"1500"`, a odpowiedź tak/nie jako `"true"`. Pole `enum` przyjmuje jedną z wartości `options`. - `required` określa, czy zatwierdzenie zależy od tego pola, a `help_text` opisuje, jak wygląda poprawna odpowiedź. - `max_items` jest ustawione w polu, które przyjmuje więcej niż jedną odpowiedź. - `template_url` zawiera link do pustego formularza, który należy pobrać, wypełnić i przesłać z powrotem, jeśli pole go ma. - `state` określa stan pozycji: `not_supplied` przed udzieleniem odpowiedzi, a następnie `supplied`, `in_review`, `approved` lub `rejected`, przy czym odrzucona pozycja zawiera `reason` recenzenta. Zaakceptowana odpowiedź może później otrzymać stan `expired` i wtedy trzeba ją podać ponownie, a `not_applicable` oznacza pozycję, która Cię nie dotyczy. `submission_id` ma wartość `null`, dopóki nie złożysz dokumentów. `needs_input` ma wartość `true`, dopóki jakakolwiek pozycja czeka na Ciebie. Odpowiedź `422` z [`E19001`](/docs/api/errors/E19001) oznacza, że nie mamy jeszcze formularza własności dla tego kraju. Skontaktuj się z pomocą techniczną, aby o niego poprosić. ### Prześlij każdy dokument Każdy plik wymagany przez pole `document` prześlij za pomocą [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment) jako treść `multipart/form-data`, z bajtami pliku w części `file`. Zachowaj `id` z odpowiedzi, czyli 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" ``` Akceptowane są pliki PNG, JPEG i PDF o rozmiarze do 10 MB, a typ jest odczytywany z zawartości pliku. Odpowiedź `201` zwraca nowy załącznik. Ponowne przesłanie tego samego pliku zwraca pierwszy załącznik z `200`, więc ponowna próba przesłania nie tworzy duplikatu. Załącznik, do którego nie odwołuje się żadne zgłoszenie, wygasa po siedmiu dniach. `download_url` załącznika to podpisany link ważny przez 24 godziny od pobrania załącznika. Aby uzyskać nowy link, wyświetl listę załączników za pomocą [`GET /v1/compliance/attachments`](/docs/api/reference/list-compliance-attachments) albo pobierz bajty bezpośrednio za pomocą [`GET /v1/compliance/attachments/{attachment_id}`](/docs/api/reference/get-compliance-attachment). ### Prześlij wszystkie odpowiedzi Złóż odpowiedzi za pomocą [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission). Wyślij `subject_kind` i `subject_id`, `program` zwrócone przy odczycie wymagań oraz `country_code` numeru. W `answers` wyślij po jednym wpisie dla każdego pola, którego `required` ma wartość `true`, oraz po jednym dla każdego pola opcjonalnego, na które masz rzeczywistą odpowiedź. Pomiń pole opcjonalne zamiast wymyślać dla niego wartość. Pole typowane przyjmuje `value`, pole dokumentu przyjmuje `attachment_id`, a pole z `max_items` przyjmuje `values` lub `attachment_ids`. Zapisz treść jako `submission.json`, wstawiając swoje wartości w miejsce ``, ``, `` i ``. Przykład pokazuje trzy z odpowiedzi wymaganych przez formularz: ```json { "subject_kind": "number", "subject_id": "", "program": "", "country_code": "", "answers": [ { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }, { "key": "business_registration_number", "value": "90012768" }, { "key": "business_registration_certificate", "attachment_id": "" } ] } ``` Wyślij ją z `Idempotency-Key`. Używaj tego samego klucza ponownie tylko przy ponownej próbie wysłania tej samej treści: odrzucenie może zostać zachowane i odtworzone, więc po `422` popraw treść i wyślij ją z nowym kluczem. [Idempotentność](/docs/guides/idempotency) wyjaśnia, co jest zachowywane. ```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-$NUMBER_ID" \ --data-binary @submission.json ``` Nie ma wersji roboczych: to żądanie składa odpowiedzi do weryfikacji, więc musi zawierać wszystkie wymagane odpowiedzi. Pominięte wymagane pole lub odpowiedź odrzucona przez formularz powoduje zwrócenie `422` z [`E01001`](/docs/api/errors/E01001) i jednym wpisem w `details` na każde pole, wskazane w `param`. W takim przypadku nic nie zostaje złożone. Odpowiedź `201` zwraca zgłoszenie ze wszystkimi odpowiedziami. Zachowaj jego `id`, czyli identyfikator `csb_` zgłoszenia, jako `SUBMISSION_ID`. Firma opisana w Twoim obszarze roboczym to tożsamość. Utwórz ją w **Identity Center** w panelu lub za pomocą [`POST /v1/compliance/identities`](/docs/api/reference/create-compliance-identity), wysyłając jej wyświetlaną nazwę `name`. Zgłoszenie numeru może też zawierać `identity` podane bezpośrednio zamiast `identity_id`. Pole `identity_id` w odpowiedzi na zgłoszenie wskazuje nową tożsamość, którą `POST /v1/compliance/identities` zwraca jako `id`. Używaj jej dla kolejnych numerów zamiast tworzyć nową. Aby złożyć dokumenty dla tożsamości, dodaj jej `identity_id`, a zapisane w niej odpowiedzi uzupełnią te, które pominiesz. [`GET /v1/compliance/identities`](/docs/api/reference/list-compliance-identities) wyświetla listę tożsamości firm. Złożone odpowiedzi jednowartościowe są zapisywane w tożsamości niezależnie od wyniku weryfikacji, więc następne zgłoszenie, które ją wskazuje, zaczyna od nich. Dokumenty i odpowiedzi wielowartościowe są wymagane za każdym razem od nowa. Używaj jednej tożsamości na firmę: jeśli składasz dokumenty za kilku klientów końcowych, nadaj każdemu własną tożsamość, w przeciwnym razie zaakceptowane odpowiedzi jednego klienta uzupełnią odpowiedzi innego. Śledź `ownership.next` zamiast składać dokumenty ponownie. Numer ma jedno zgłoszenie na każdą wersję formularza swojego kraju, więc ponowne złożenie, gdy to zgłoszenie jest otwarte, kończy się odpowiedzią `409` z [`E19009`](/docs/api/errors/E19009). Zamiast tego popraw zgłoszenie, jak opisano w sekcji [Popraw odrzuconą odpowiedź](#popraw-odrzuconą-odpowiedź). Gdy po zmianie formularza ponownie otworzymy zamknięte zgłoszenie, `next` prosi o nowe zgłoszenie do `POST /v1/compliance/submissions`. ### Śledź weryfikację dokumentów Każda odpowiedź jest oceniana osobno. Odczytaj numer ponownie i sprawdź `ownership.status` oraz `ownership.next`, jak w sekcji [Sprawdź, czy numer wymaga dokumentów](#sprawdź-czy-numer-wymaga-dokumentów). Aby zobaczyć ocenę każdej odpowiedzi, odczytaj zgłoszenie za pomocą [`GET /v1/compliance/submissions/{submission_id}`](/docs/api/reference/get-workspace-compliance-submission) lub ponownie odczytaj wymagania: każde pole zawiera swój `state`, a po odrzuceniu także `reason`. Po zakończeniu oceny wysyłamy wynik e-mailem do właścicieli Twojej organizacji oraz do ostatniej zapisanej osoby, która złożyła lub poprawiła zgłoszenie, jeśli taka osoba istnieje. Pierwsze złożenie kluczem API trafia do właścicieli. Późniejsza poprawka kluczem API zachowuje wcześniej zapisaną osobę jako odbiorcę. Twoja integracja poznaje wynik, odczytując `ownership.status`. ### Popraw odrzuconą odpowiedź Wyślij odpowiedzi zastępcze do [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission). Dołącz tylko odpowiedzi, które zastępujesz; pozostałe nie zmieniają się. Pobierz `submission_id` z pola `ownership` numeru lub z odczytu wymagań: ```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-$NUMBER_ID" \ --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}' ``` Odpowiedź `200` zwraca zgłoszenie z Twoimi odpowiedziami zastępczymi, które wracają do oceny. Gdy żadna wymagana odpowiedź nie jest już odrzucona, wygasła ani brakująca, pole `ownership.status` numeru wraca do `under_review`. Zastępuj odpowiedzi, których `state` to `rejected`, `expired` lub `not_supplied`. Gdy prosimy o poprawkę po zaakceptowaniu Twoich odpowiedzi, odpowiedź, której `editable_for_verifier_repair` to `true`, również można zastąpić do zamknięcia tej poprawki. Próba zastąpienia odpowiedzi w innym stanie, np. wciąż ocenianej lub zaakceptowanej poza poprawką, o którą prosiliśmy, kończy się odpowiedzią `422` z [`E19003`](/docs/api/errors/E19003). Dokument zastępczy to nowe przesłanie pliku: najpierw go prześlij, a potem wyślij jego `attachment_id`. ## Złóż dokumenty razem z zamówieniem Jeśli znasz odpowiedzi w chwili kupowania numeru, wyślij je w bloku `compliance` zamówienia w [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order), w tym samym kształcie `answers`, jaki przyjmuje zgłoszenie. Aby sprawdzić, czego wymaga kraj, zanim będziesz mieć numer, wywołaj odczyt wymagań bez `subject_id`, ustawiając `COUNTRY_CODE` i `NUMBER_TYPE` na `country_code` i `number_type` numeru z [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers): ```bash curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&country_code=$COUNTRY_CODE&program=$NUMBER_TYPE" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Zamówienie z blokiem `compliance` korzysta z istniejącego zakresu `numbers` zamówienia na poziomie zapisu. Zaakceptowane zamówienie zostaje zrealizowane w każdym przypadku: jeśli złożenie w bloku `compliance` zostanie odrzucone, numer nadal należy do Ciebie, a dokumenty składasz za pomocą `POST /v1/compliance/submissions`, jak w sekcji [Wyślij wszystkie odpowiedzi](#prześlij-wszystkie-odpowiedzi). Po złożeniu odpowiedzi nowy numer ma wartość `under_review` ze swoim `submission_id`. Samo zamówienie opisuje strona [Kup i zwolnij numer](/docs/guides/numbers/buying-numbers). ## Użyj ponownie tożsamości firmy Użyj [`GET /v1/compliance/identities/{identity_id}`](/docs/api/reference/get-compliance-identity), aby odczytać firmę i jej zapisane odpowiedzi. Zapisane odpowiedzi mogą zawierać `state` oceny, `reason` i `decided_at`; wartość bez decyzji z oceny może nie mieć stanu. Zmień nazwę firmy za pomocą [`PATCH /v1/compliance/identities/{identity_id}`](/docs/api/reference/update-compliance-identity) lub usuń ją za pomocą [`DELETE /v1/compliance/identities/{identity_id}`](/docs/api/reference/delete-compliance-identity). Odczyt wymaga `compliance:read`; tworzenie, zmiana nazwy i usuwanie wymagają `compliance:write`. Aby zweryfikować samą firmę, najpierw utwórz tożsamość. Odczytaj wymagania z `subject_kind=identity`, jej identyfikatorem `cid_` jako `subject_id`, `program=business` i `country_code=ZZ`. Złóż dokumenty dla tej samej tożsamości. Tożsamość podana bezpośrednio w zgłoszeniu numeru nie zastępuje tego procesu weryfikacji tożsamości. Ocena opiera się na przesłanych danych firmy, zadeklarowanych kontaktach i dowodach weryfikacyjnych. Złożenie dokumentów za pomocą klucza API lub w panelu nie tworzy innej relacji biznesowej. Dbaj o aktualność danych kontaktowych i dostarcz dowody, których wymaga formularz. ## Złóż dokumenty dla nadawcy SMS Dokumenty nadawcy SMS korzystają z tych samych żądań wymagań, załączników, zgłoszenia i poprawek, a ich przedmiotem jest rejestracja nadawcy. [Zarejestruj nadawcę SMS przez API](/docs/guides/sms/sender-registration-api) opisuje, jak uzyskać tę rejestrację i najpierw sprawdzić jej cenę. ## Gdy żądanie zostanie odrzucone | Odpowiedź | Co oznacza | Co zrobić | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `403` z `E02035` | Przy zapisie przez samodzielne punkty końcowe zgodności klucz nie ma zakresu `compliance` lub ma go tylko na poziomie odczytu. | Użyj klucza z `compliance` na poziomie zapisu. | | `422` z `E19001` | Nie mamy jeszcze formularza własności dla kraju numeru. | Skontaktuj się z pomocą techniczną i poproś o ten kraj. | | `422` z `E19013` | Odczyt wymagań nie zawierał ani `subject_id`, ani `program`. | Wyślij identyfikator `nda_` numeru albo `program`, gdy odczytujesz wymagania przed zakupem. | | `422` z `E01001` | W zgłoszeniu brakuje wymaganego pola lub jest w nim nieprawidłowa odpowiedź. | Popraw każde pole wskazane w `details` i wyślij całe zgłoszenie ponownie z nowym kluczem idempotencji. | | `409` z `E19009` | Numer ma już zgłoszenie dla swojego bieżącego formularza. | Zastąp odpowiedzi, które tego wymagają, żądaniem ponownego przesłania. | | `409` z `E01009` | Ponowne przesłanie dotyczy zamkniętego zgłoszenia. | Skontaktuj się z pomocą techniczną. Jeśli ponownie je otworzymy, złóż to, co wskazuje `ownership.next`. | | `422` z `E19003` | Zastąpienie dotyczy odpowiedzi, która jest w trakcie weryfikacji lub została zaakceptowana poza poprawką, o którą poprosiliśmy. | Zastępuj tylko odpowiedzi, których `state` to `rejected`, `expired` lub `not_supplied`. | | `404` z `E01008` | Numeru nie ma w tym obszarze roboczym lub `country_code` nie jest krajem numeru. | Wyślij `country_code`, które zwraca `GET /v1/numbers/{number_id}`. | Strona [Błędy](/docs/guides/errors) opisuje treść odpowiedzi z błędem i jej `remediation`. ## Następne kroki - [Przegląd numerów](/docs/guides/numbers/overview) - [Kupowanie i zwalnianie numeru](/docs/guides/numbers/buying-numbers) - [Zarządzanie numerami telefonów](/docs/guides/numbers/managing-numbers) - [Migracja z Telserv do Bird](/docs/guides/numbers/migrate/telserv) ## 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)