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 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. Sposób jego wyszukania opisuje strona Znajdź numer na liście.

Przykłady API odczytują klucz z BIRD_API_KEY, jego host regionalny 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}:

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:

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 wyjaśnia, jak ownership ma się do własnego pola status numeru.

Złóż dokumenty w panelu

1. Otwórz numer na stronie 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. Ustaw subject_kind na number, subject_id na identyfikator nda_ numeru, a country_code na własne COUNTRY_CODE numeru:

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 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 jako treść multipart/form-data, z bajtami pliku w części file. Zachowaj id z odpowiedzi, czyli identyfikator tca_ załącznika, jako ATTACHMENT_ID:

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 albo pobierz bajty bezpośrednio za pomocą GET /v1/compliance/attachments/{attachment_id}.

Prześlij wszystkie odpowiedzi

Złóż odpowiedzi za pomocą POST /v1/compliance/submissions. 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 <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> i <ATTACHMENT_ID>. Przykład pokazuje trzy z odpowiedzi wymaganych przez formularz:

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<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ść wyjaśnia, co jest zachowywane.

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 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, 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 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. Zamiast tego popraw zgłoszenie, jak opisano w sekcji 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. Aby zobaczyć ocenę każdej odpowiedzi, odczytaj zgłoszenie za pomocą GET /v1/compliance/submissions/{submission_id} 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. Dołącz tylko odpowiedzi, które zastępujesz; pozostałe nie zmieniają się. Pobierz submission_id z pola ownership numeru lub z odczytu wymagań:

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. 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, 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:

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. Po złożeniu odpowiedzi nowy numer ma wartość under_review ze swoim submission_id. Samo zamówienie opisuje strona Kup i zwolnij numer.

Użyj ponownie tożsamości firmy

Użyj GET /v1/compliance/identities/{identity_id}, 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} lub usuń ją za pomocą DELETE /v1/compliance/identities/{identity_id}. 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 opisuje, jak uzyskać tę rejestrację i najpierw sprawdzić jej cenę.

Gdy żądanie zostanie odrzucone

Strona Błędy opisuje treść odpowiedzi z błędem i jej remediation.

Następne kroki

• Przegląd numerów
• Kupowanie i zwalnianie numeru
• Zarządzanie numerami telefonów
• Migracja z Telserv do Bird