Zarejestruj nadawcę SMS przez API

Niektóre kraje dostarczają SMS tylko od nadawcy zarejestrowanego dla danego kraju. Przez API przejmujesz nadawcę, tworzysz jego rejestrację dla kraju docelowego i składasz dokumenty, których wymaga ta rejestracja. To te same kroki, które wykonuje panel. Rejestracja może naliczyć opłatę za konfigurację zaraz po utworzeniu, więc najpierw sprawdź cenę i swój portfel.

Zanim zaczniesz

• Klucz API z uprawnieniem sms_management na poziomie zapisu do tworzenia nadawców i rejestracji oraz compliance na poziomie zapisu do składania ich dokumentów.
• Aby najpierw sprawdzić ceny i środki w portfelu, potrzebujesz delegowanego tokenu użytkownika OAuth, opisanego w sekcji Sprawdź ceny rejestracji i środki w portfelu. Klucz API nie może odczytywać rozliczeń organizacji.

Przykłady odczytują klucz z BIRD_API_KEY, jego host regionalny z BIRD_API_URL, kraj docelowy z COUNTRY_CODE, a identyfikator scr_ rejestracji z REGISTRATION_ID, gdy już go masz.

Sprawdź ceny rejestracji i środki w portfelu

Aby wyświetlić te same informacje o cenach i portfelu co panel, użyj GET /v1/organization/billing/prices/resolve i GET /v1/organization/billing/wallets. Te odczyty wymagają delegowanego tokenu użytkownika OAuth z org:billing:read. Klucze API obszaru roboczego, główne klucze organizacji i tokeny kont usługowych nie mogą nadać tego uprawnienia do rozliczeń organizacji.

Użyj wykrywania chronionych zasobów OAuth i metadanych serwera autoryzacji, aby uzyskać issuer, registration_endpoint, authorization_endpoint i token_endpoint, zgodnie z opisem w sekcji Wykrywanie OAuth. Zarejestruj własnego publicznego klienta OAuth pod wykrytym registration_endpoint, podając client_name, redirect_uris i token_endpoint_auth_method: "none". Przekieruj użytkownika do wykrytego authorization_endpoint z tym client_id, response_type=code, zarejestrowanym redirect_uri, nowym state, scope=org:billing:read, wartością code_challenge wyprowadzoną z weryfikatora oraz code_challenge_method=S256. Na ekranie zgody użytkownik wybiera obszar roboczy w docelowej organizacji i przyznaje org:billing:read, jeśli pozwala na to jego rola. Sprawdź state względem wysłanej wartości, a iss względem wystawcy z wykrywania, a następnie wymień kod pod wykrytym token_endpoint, podając grant_type=authorization_code, zwrócony code, client_id, ten sam redirect_uri i oryginalny code_verifier. Uzyskany token dostępu użyj jako BIRD_OAUTH_TOKEN. Przestrzegaj jego expires_in; bezpiecznie przechowuj token odświeżania i zastępuj go po każdym udanym odświeżeniu. Wykonuj próby odświeżenia kolejno, ponieważ każdy token odświeżania jest jednorazowy. Ponów autoryzację, gdy uprawnienie do odświeżania wygaśnie lub zostanie cofnięte.

Token jest powiązany z wybranym obszarem roboczym i jego organizacją; odczyty rozliczeń dotyczą tej organizacji. X-Organization-Id nie może przełączyć go na inną organizację; w tym celu powtórz autoryzację dla tamtej organizacji. Konfigurując SDK z tym tokenem, jawnie ustaw host regionalny.

Dla alfanumerycznego nadawcy SMS ustal cenę konfiguracji jego rejestracji na podstawie kraju docelowego:

curl --get "$BIRD_API_URL/v1/organization/billing/prices/resolve" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN" \
  --data-urlencode 'product_slug=sms_sender_registration' \
  --data-urlencode "dimensions[country_code]=$COUNTRY_CODE" \
  --data-urlencode 'dimensions[sender_type]=alphanumeric'

curl "$BIRD_API_URL/v1/organization/billing/wallets" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN"

Aby ustalić cenę cykliczną, rozwiąż product_slug=sms_sender z tymi samymi wymiarami. Aby sprawdzić saldo tak samo jak dashboard, dodaj gross_price.amount z odpowiedzi dotyczącej konfiguracji do pierwszej opłaty cyklicznej, czyli wartości gross_price.amount z odpowiedzi dotyczącej ceny cyklicznej pomnożonej przez jej intervals_per_charge. Porównaj tę sumę z balance portfela w data, którego currency_code odpowiada wartości gross_price.currency_code obu cen. Używaj arytmetyki dziesiętnej i nie zaokrąglaj zwróconych kwot. Jeśli suma przekracza saldo, różnica stanowi brakującą kwotę. W takim przypadku przed utworzeniem rejestracji doładuj portfel lub sprawdź warunki kredytowe swojej organizacji. Podczas końcowego sprawdzania, czy organizację stać na rejestrację, serwer uwzględnia też ewentualny limit kredytowy. Te odczyty pokazują aktualne ceny i środki. Nie rezerwują środków ani nie zatwierdzają rejestracji.

Pobierz rejestrację, dla której składasz dokumenty

1. Znajdź nadawcę za pomocą GET /v1/sms/senders lub GET /v1/sms/senders/{sender_id}. W razie potrzeby utwórz go za pomocą POST /v1/sms/senders.
2. Odczytaj GET /v1/sms/senders/{sender_id}/requirements dla kraju docelowego. Wykonaj podane tam kroki next. Jeśli trzeba utworzyć rejestrację, sprawdź jej cenę zgodnie z sekcją Sprawdź ceny rejestracji i środki w portfelu, a następnie wywołaj POST /v1/sms/senders/{sender_id}/registrations z country_code.
3. Ponownie odczytaj wymagania dotyczące nadawcy i zapisz wartość registration_id (scr_) z wiersza jako REGISTRATION_ID, a jego program jako PROGRAM. Składaj dokumenty tylko wtedy, gdy has_compliance_requirements w wierszu ma wartość true. Gdy ma wartość false, rejestracja nie wymaga zgłoszenia albo obsługuje ją dedykowany program, więc zamiast tego wykonaj next z wiersza. Dedykowane programy, takie jak weryfikacja numerów bezpłatnych i 10DLC, mają własne kroki.

Odczyt nadawców wymaga sms_management:read, a tworzenie nadawców i rejestracji wymaga sms_management:write. Składanie ich dokumentów wymaga też compliance:write.

Złóż dokumenty rejestracji

Ta sekcja dotyczy rejestracji, której has_compliance_requirements ma wartość true.

Odczytaj, czego wymaga rejestracja, za pomocą GET /v1/compliance/requirements, podając sms_sender jako subject_kind i rejestrację jako subject_id:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=sms_sender&subject_id=$REGISTRATION_ID&country_code=$COUNTRY_CODE&program=$PROGRAM" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Pola mają takie samo znaczenie jak w przypadku numeru. Każde z nich opisuje sekcja Odczytaj, czego wymaga kraj, a pliki, których wymaga pole document, opisuje sekcja Prześlij każdy dokument. Złóż wszystkie odpowiedzi za pomocą POST /v1/compliance/submissions, wskazując rejestrację jako podmiot:

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: sender-$REGISTRATION_ID" \
  --data '{
    "subject_kind": "sms_sender",
    "subject_id": "'"$REGISTRATION_ID"'",
    "program": "'"$PROGRAM"'",
    "country_code": "'"$COUNTRY_CODE"'",
    "answers": [{ "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }]
  }'

Przykład zawiera jedną odpowiedź. Wyślij po jednym wpisie dla każdego pola, którego required ma wartość true, oraz dla każdego pola opcjonalnego, na które masz rzeczywistą odpowiedź, zgodnie z sekcją Złóż wszystkie odpowiedzi. Odpowiedź 201 zwraca zgłoszenie. Zapisz jego csb_ id. Nadawca nie ma pola ownership, więc śledź przegląd, odczytując zgłoszenie za pomocą GET /v1/compliance/submissions/{submission_id}. Jego odpowiedzi zawierają state, a w przypadku odrzucenia także reason. Status rejestracji możesz też sprawdzić, ponownie odczytując wymagania dotyczące nadawcy. Zastąp odrzucone odpowiedzi za pomocą POST /v1/compliance/submissions/{submission_id}/resupply, jak pokazuje sekcja Popraw odrzuconą odpowiedź.

Następne kroki

• Złóż dokumenty potwierdzające własność numeru
• Identyfikatory nadawcy SMS