Mendaftarkan pengirim SMS melalui API

Beberapa negara hanya mengirimkan SMS dari pengirim yang terdaftar untuk negara tersebut. Melalui API, Anda mengklaim pengirim, membuat registrasinya untuk negara tujuan, dan mengajukan dokumen yang diminta registrasi tersebut, sama seperti langkah yang dilakukan dasbor. Registrasi dapat langsung mengenakan biaya penyiapan begitu dibuat, jadi periksa harga dan wallet Anda terlebih dahulu.

Sebelum memulai

• Kunci API dengan sms_management pada level tulis untuk membuat pengirim dan registrasi, serta compliance pada level tulis untuk mengajukan dokumennya.
• Untuk memeriksa harga dan dana wallet terlebih dahulu, diperlukan token OAuth pengguna yang didelegasikan, seperti dijelaskan dalam Memeriksa harga registrasi dan dana wallet. Kunci API tidak dapat membaca penagihan organisasi.

Contoh-contoh ini membaca kunci Anda dari BIRD_API_KEY, host regional-nya dari BIRD_API_URL, negara tujuan dari COUNTRY_CODE, dan pengenal scr_ registrasi dari REGISTRATION_ID setelah Anda memilikinya.

Memeriksa harga registrasi dan dana wallet

Untuk menampilkan informasi harga dan wallet yang sama seperti di dasbor, gunakan GET /v1/organization/billing/prices/resolve dan GET /v1/organization/billing/wallets. Pembacaan ini memerlukan token OAuth pengguna yang didelegasikan dengan org:billing:read. Kunci API workspace, kunci master organisasi, dan token akun layanan tidak dapat memberikan izin penagihan organisasi ini.

Gunakan penemuan sumber daya terlindungi OAuth dan metadata server otorisasi untuk memperoleh issuer, registration_endpoint, authorization_endpoint, dan token_endpoint, seperti dijelaskan dalam Penemuan OAuth. Daftarkan klien OAuth publik milik Anda sendiri di registration_endpoint yang ditemukan, dengan menyertakan client_name, redirect_uris, dan token_endpoint_auth_method: "none". Arahkan pengguna ke authorization_endpoint yang ditemukan dengan client_id tersebut, response_type=code, redirect_uri yang telah Anda daftarkan, state baru, scope=org:billing:read, code_challenge yang diturunkan dari verifier Anda, dan code_challenge_method=S256. Di layar persetujuan, pengguna memilih workspace dalam organisasi yang dimaksud dan memberikan org:billing:read jika perannya mengizinkan. Validasi state terhadap nilai yang Anda kirim dan iss terhadap issuer dari hasil penemuan, lalu tukarkan kode di token_endpoint yang ditemukan dengan grant_type=authorization_code, code yang dikembalikan, client_id, redirect_uri yang sama, dan code_verifier asli. Gunakan token akses yang dihasilkan sebagai BIRD_OAUTH_TOKEN. Patuhi expires_in-nya; simpan token refresh dengan aman dan ganti setelah setiap refresh berhasil. Jalankan percobaan refresh secara berurutan karena setiap token refresh hanya dapat dipakai sekali. Lakukan otorisasi ulang saat grant refresh kedaluwarsa atau dicabut.

Token ini terikat pada workspace yang dipilih dan organisasinya; pembacaan penagihan berlaku untuk organisasi tersebut. X-Organization-Id tidak dapat mengalihkannya ke organisasi lain; ulangi otorisasi untuk organisasi tersebut. Tetapkan host regional secara eksplisit saat mengonfigurasi SDK dengan token ini.

Untuk pengirim SMS alfanumerik, tentukan harga penyiapan pendaftarannya berdasarkan negara tujuan:

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"

Tentukan product_slug=sms_sender dengan dimensi yang sama untuk harga berulang. Untuk pemeriksaan saldo yang sama dengan dashboard, jumlahkan gross_price.amount dari respons penyiapan dengan tagihan berulang pertama, yaitu gross_price.amount dari respons berulang dikalikan dengan intervals_per_charge-nya. Bandingkan total tersebut dengan balance pada dompet di data yang currency_code-nya cocok dengan gross_price.currency_code kedua harga. Gunakan aritmetika desimal tanpa membulatkan jumlah yang dikembalikan. Jika total melebihi saldo, selisihnya adalah kekurangan dana; isi ulang saldo atau periksa pengaturan kredit organisasi Anda sebelum membuat pendaftaran. Server juga memperhitungkan batas kredit apa pun dalam pemeriksaan kemampuan bayar akhirnya. Pembacaan ini menampilkan harga dan dana saat ini; pembacaan ini tidak mencadangkan dana atau menyetujui pendaftaran.

Dapatkan pendaftaran yang akan diajukan

1. Temukan pengirim dengan GET /v1/sms/senders atau GET /v1/sms/senders/{sender_id}. Jika perlu, buat pengirim dengan POST /v1/sms/senders.
2. Baca GET /v1/sms/senders/{sender_id}/requirements untuk negara tujuan. Ikuti langkah next-nya. Jika Anda diminta membuat pendaftaran, periksa harganya seperti di Periksa harga pendaftaran dan dana dompet, lalu panggil POST /v1/sms/senders/{sender_id}/registrations dengan country_code.
3. Baca kembali persyaratan pengirim, lalu simpan registration_id (scr_) dari baris tersebut sebagai REGISTRATION_ID dan program-nya sebagai PROGRAM. Ajukan dokumen hanya jika has_compliance_requirements pada baris tersebut bernilai true. Jika nilainya false, pendaftaran tidak memerlukan pengajuan atau ditangani oleh program khusus, jadi ikuti next pada baris tersebut. Program khusus seperti verifikasi nomor bebas pulsa dan 10DLC memiliki langkahnya sendiri.

Membaca pengirim memerlukan sms_management:read; membuat pengirim dan pendaftaran memerlukan sms_management:write. Mengajukan dokumennya juga memerlukan compliance:write.

Ajukan dokumen pendaftaran

Bagian ini berlaku untuk pendaftaran yang has_compliance_requirements-nya bernilai true.

Baca apa saja yang diminta pendaftaran dengan GET /v1/compliance/requirements, dengan sms_sender sebagai subject_kind dan pendaftaran sebagai 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"

Kolom-kolomnya dibaca sama seperti untuk nomor; Baca apa yang diminta negara menjelaskan setiap kolom, dan Unggah setiap dokumen membahas file yang diminta kolom document. Ajukan setiap jawaban dengan POST /v1/compliance/submissions, dengan pendaftaran sebagai subjeknya:

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" }]
  }'

Contoh ini menampilkan satu jawaban. Kirim satu entri untuk setiap kolom yang required-nya bernilai true, serta untuk setiap kolom opsional yang memiliki jawaban nyata, seperti dijelaskan di Kirim setiap jawaban. Respons 201 mengembalikan pengajuan; simpan csb_ id-nya. Pengirim tidak memiliki kolom ownership, jadi pantau peninjauan dengan membaca pengajuan menggunakan GET /v1/compliance/submissions/{submission_id}, yang jawabannya memuat state dan, jika ditolak, reason, atau dengan membaca kembali persyaratan pengirim untuk melihat status pendaftaran. Ganti jawaban yang ditolak dengan POST /v1/compliance/submissions/{submission_id}/resupply, seperti ditunjukkan di Perbaiki jawaban yang ditolak.

Langkah berikutnya

• Ajukan dokumen kepemilikan nomor
• ID pengirim SMS