--- title: "Migrasi dari Telserv ke Bird" description: "Pindahkan integrasi API partner Telserv ke Bird API, petakan setiap kelompok operasi ke panggilan Bird-nya, dan lihat cara setiap pekerjaan dilakukan di Bird." canonical: "https://bird.com/id-id/dokumentasi/guides/numbers/migrate/telserv" --- # Migrasi dari Telserv ke Bird Panduan ini ditujukan untuk integrasi yang memanggil API partner Telserv, V1 atau V2, untuk membeli, merutekan, dan melepas nomor, dan yang sekarang berpindah ke Bird API. Bird API melayani setiap produk Bird, sehingga operasi nomor dan suaranya mengikuti konvensi Bird sendiri, bukan konvensi Telserv. Sebagian besar kemampuan yang digunakan integrasi Anda memiliki panggilan Bird. Endpoint, payload, identifier, dan autentikasi berbeda, jadi rencanakan untuk menulis ulang integrasi tersebut. Jika Bird melakukan suatu pekerjaan dengan cara berbeda, panduan ini menunjukkan caranya. Panduan ini masih dalam pengembangan. Panduan ini mencakup apa yang dilakukan Bird saat ini, dan bertambah seiring berjalannya migrasi. Jika operasi Telserv yang Anda gunakan belum tercantum di sini, operasi tersebut masih perlu pelingkupan dan pengerjaan sebelum dapat ditambahkan; tanyakan kepada kontak migrasi Anda. ## Sebelum Anda mulai - Organisasi Bird dengan verifikasi identitas yang sudah selesai, yang diperlukan untuk pembelian nomor pertama. - [Kunci API](/docs/api/authentication) dengan scope yang digunakan resep ini: `numbers` pada level tulis untuk nomor dan order, `compliance` pada level tulis untuk operasi dokumen kepemilikan yang berdiri sendiri, dan `voice_management` pada level tulis untuk trunk SIP, nomor suara, dan nomor terverifikasi. Panggilan uji juga memerlukan `voice:write`, dan membaca leg panggilan memerlukan `voice:read`. - Saldo wallet. Order dibayar dari wallet. [Ketika order ditolak](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) menjelaskan penolakan `402` dan `412`. Nomor yang dikelola integrasi Anda di Telserv tidak perlu dibeli ulang. Setelah nomor Anda dipindahkan ke workspace Bird Anda, nomor tersebut muncul di [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Kontak migrasi Anda mengonfirmasi kapan hal itu terjadi. Untuk mendapatkan identifier `nda_` dari nomor yang dipindahkan, cari nomor tersebut dengan `GET /v1/numbers?number=`, berikan digitnya beserta kode negara, dan simpan `id` sebagai `NUMBER_ID`. Contoh-contoh ini membaca kunci Anda dari `BIRD_API_KEY` dan [host regional](/docs/api/regions)-nya dari `BIRD_API_URL`: `https://eu1.platform.bird.com` untuk kunci `bk_eu1_`, atau `https://us1.platform.bird.com` untuk kunci `bk_us1_`. Variabel lainnya, seperti `TRUNK_ID` dan `NUMBER_ID`, menyimpan identifier dari respons sebelumnya; setiap langkah menyebutkan identifier yang ditetapkannya. ## Apa yang berubah dalam kontrak | Area | API partner Telserv | Bird API | | --------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Autentikasi | Header `X-ApiKey` (V2) atau parameter `apiKey` (V1), diperiksa terhadap daftar IP yang diizinkan | `Authorization: Bearer` dengan kunci API yang scope-nya menyebutkan area produk yang boleh digunakan. Daftar IP yang diizinkan bersifat opsional: atur di bagian **IP restrictions** pada kunci di [**Kunci API**](https://bird.com/dashboard/w/api-keys) | | Identifier | Integer. Membeli nomor memberinya `id` baru | TypeID berprefiks seperti `nda_`, `nor_`, `vnu_`, dan `spt_`. Sebuah nomor mempertahankan id `nda_`-nya selama dialokasikan kepada Anda | | Nomor telepon | Digit tanpa awalan `+` | E.164 dengan awalan `+` | | Paginasi | Offset `start` dan `limit`, hingga 1000 per halaman | Kursor: `limit` hingga 100 (default 25), lalu `starting_after` diisi dengan `next_cursor` halaman sebelumnya. Lihat [Paginasi](/docs/api/pagination) | | Kesalahan | `errorCode` menyebut kelas pengecualian, dan `403` mencakup sumber daya tidak ditemukan serta banyak kegagalan validasi | `error.code` adalah kode `E` yang stabil dengan halaman dokumentasi dan, jika pemulihan diketahui, sebuah `remediation`. Sumber daya tidak ditemukan menjawab `404`, prasyarat tidak terpenuhi `412`, dan input tidak valid `422` dengan detail field. Lihat [Kesalahan](/docs/guides/errors) | | Lingkungan | LIVE dan SANDBOX, masing-masing dengan kunci sendiri | Satu lingkungan. Setiap order membeli dan menagih nomor nyata, dan setiap panggilan uji adalah panggilan nyata | | Percobaan ulang | Tidak ada kunci idempotensi | Header `Idempotency-Key` pada operasi tulis. Key dan body yang sama membalas respons pertama dengan `Idempotency-Replay: true`; key yang sama dengan body berbeda menjawab `409`. Lihat [Idempotensi](/docs/guides/idempotency) | Bird API menolak parameter kueri yang tidak dikenali dengan `422` dan [`E01029`](/docs/api/errors/E01029). Hapus filter khusus Telserv seperti `city` dari permintaan Anda, jangan meneruskannya begitu saja. ## Dua identifier untuk satu nomor Nomor berkemampuan suara yang dialokasikan ke workspace Anda memiliki dua rekaman, masing-masing dengan identifier sendiri: - Alokasi, dikembalikan oleh [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). `id`-nya diawali `nda_` untuk nomor khusus dan `nal_` untuk nomor bersama, dan `number_id` pada pesanan adalah identifier `nda_` dari nomor yang dibelinya. Gunakan untuk membaca, memberi nama, dan mereferensikan nomor, serta untuk melepas nomor khusus. - Rekaman suara, `vnu_`, dikembalikan oleh [`GET /v1/voice/numbers`](/docs/api/reference/list-voice-numbers). Gunakan untuk membaca dan mengubah tujuan panggilan masuk nomor tersebut. Nomor tanpa kemampuan suara, seperti nomor khusus SMS, tidak memiliki rekaman suara. Operasi suara menolak identifier `nda_` atau `nal_` dengan `422`. Untuk menemukan rekaman suara sebuah nomor, tampilkan daftar nomor suara dengan `search` disetel ke digit nomor tersebut dan ambil entri yang `provider.number_id`-nya sama dengan `id` alokasi. [Rutekan nomor ke trunk SIP Anda](#rutekan-nomor-ke-trunk-sip-anda) menunjukkan permintaannya, dan [Mengelola nomor telepon Anda](/docs/guides/numbers/managing-numbers#find-the-voice-record-that-routes-a-number) membahas pencarian tersebut. `GET /numbers/{dnisId}` milik Telserv menjadi dua pembacaan di Bird: alokasi untuk status dan dokumen kepemilikan, dan rekaman suara untuk rute. ## Petakan operasi Telserv ke Bird Setiap tabel mencantumkan pekerjaan, panggilan Telserv yang melakukannya, dan panggilan Bird yang melakukannya sekarang. Catatan di bawah setiap tabel membahas perubahan pada permintaan atau responsnya. ### Belanja | Pekerjaan | Telserv | Bird | | ---------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Cari nomor yang dijual | `GET /shop` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Periksa satu nomor | `GET /shop/{stockDnisId}` | [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) | | Beli nomor | `POST /shop/{stockDnisId}` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | | Amankan nomor | `POST /shop/{stockDnisId}/reserve`, `GET /shop/reserved` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | - **Pencarian.** `country_code` wajib diisi, sehingga satu pencarian mencakup satu negara. `prefix` menerima digit nasional setelah kode negara: Telserv `prefix=3170` menjadi `country_code=NL&prefix=70`. Persempit berdasarkan kode area dengan `prefix` sebagai pengganti `city`, dan berdasarkan `number_type` serta `capabilities` sebagai pengganti `productId`. - **Dokumen kepemilikan dalam hasil pencarian.** Setiap hasil memuat `ownership_registration_required` sebagai pengganti filter `excludeNumbersRequireVerification`. Nilai `true` berarti nomor ditagih sejak pembelian, tetapi tidak mengirim SMS dan tidak membawa panggilan suara masuk maupun keluar sampai dokumennya disetujui. - **Periksa satu nomor.** Nomor diakses berdasarkan nomor E.164-nya. - **Harga.** Telserv mengembalikan `pricing.staticPricing` pada pembacaan detail nomor dan produk. Di Bird, setiap hasil pencarian memuat harga untuk organisasi Anda di `pricing`: `setup_price` sebagai pengganti `nrc`, dan `recurring_price` per `recurring_period` sebagai pengganti `mrc`, dengan `intervals_per_charge` untuk jumlah periode yang dicakup satu tagihan. [Cari dan beli nomor dengan referensi Anda](#cari-dan-beli-nomor-dengan-referensi-anda) menjelaskan kolom harga. - **Beli.** Kirim `number` dan opsional `reference`. Pesanan dibayar dari wallet Anda. Sebagian besar pesanan menjawab `201`; pesanan yang menunggu operator menjawab `202`, dan Anda melakukan polling. - **Amankan.** Memesan nomor langsung mengamankannya. Periksa kandidat terlebih dahulu, lalu pesan. ### Nomor | Pekerjaan | Telserv | Bird | | --------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Tampilkan daftar nomor Anda | `GET /numbers` | [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) | | Baca satu nomor | `GET /numbers/{dnisId}` | [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) dengan id `nda_` atau `nal_` milik alokasi, dan [`GET /v1/voice/numbers/{number_id}`](/docs/api/reference/get-voice-number) dengan id `vnu_` milik rekaman suara | | Ubah nomor | `PATCH /numbers/{dnisId}` | [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) dengan id `nda_` atau `nal_` milik alokasi, dan [`PATCH /v1/voice/numbers/{number_id}`](/docs/api/reference/update-voice-number) dengan id `vnu_` milik rekaman suara | | Lepas nomor | `DELETE /numbers/{dnisId}?requestedCancelDate=` | [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) di akhir periode yang sudah dibayar, atau [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) sekarang, keduanya dengan id `nda_` milik alokasi | - **Daftar.** Daftar ini berisi nomor yang dialokasikan untuk Anda saat ini. Nomor yang sudah dilepas dan Anda pesan di Bird tetap terlihat melalui pesanannya di [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders). [Rekonsiliasi nomor Anda](#rekonsiliasi-nomor-anda) memetakan filter-filternya. - **Baca.** Status, dokumen kepemilikan, dan harga ada di alokasi, sedangkan rute ada di rekaman suara. Objek `pricing` pada alokasi, dengan `recurring_price` per `recurring_period` dan `intervals_per_charge`, menggantikan `pricing.staticPricing.mrc`, dan daftar juga menyertakannya, sedangkan `GET /numbers` milik Telserv tidak. - **Ubah.** `name` dan `reference` ada di alokasi, sedangkan rute ada di rekaman suara. Atur codec paksa dan batas panggilan bersamaan di peralatan SIP Anda. `destinationDistributionType` menjadi gateway `priority` di trunk SIP: `FailOver` memberikan setiap gateway `priority` yang berbeda, dan `RoundRobin` memberikan nilai yang sama kepada semuanya. - **Lepas.** `DELETE` mempertahankan nomor hingga akhir periode yang sudah Anda bayar, lalu melepasnya. `POST …/release` melepasnya langsung. Keduanya tidak menerima tanggal. [Melepas nomor](#melepas-nomor) menampilkan kedua permintaan. ### Tujuan dan profil | Pekerjaan | Telserv | Bird | | -------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Kirim panggilan ke peralatan SIP | `POST /numbers/{dnisId}/destinations` | [`POST /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/create-voice-trunk-gateway), lalu rutekan `trunk` | | Teruskan panggilan ke telepon | `POST /numbers/{dnisId}/destinations` | Rutekan `forward` | | Berhenti menerima panggilan | `DELETE /numbers/{dnisId}/destinations` | Rutekan `reject` | | Baca profil tujuan | `GET /destinationprofiles`, `GET /destinationprofiles/{id}` | [`GET /v1/voice/trunks`](/docs/api/reference/list-voice-trunks) dan [`GET /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/list-voice-trunk-gateways) | | Terapkan profil ke nomor | `POST /numbers/{dnisId}/destinations/profile` | Rutekan `trunk` dengan `trunk_id` | - **Peralatan SIP.** Gateway menjadi bagian dari trunk dan melayani setiap nomor yang dirutekan ke sana, sehingga nomor yang membutuhkan daftar tujuan berbeda memerlukan trunk berbeda. `sortOrder` menjadi `priority`. Terapkan waktu dering dan jendela waktu pada peralatan SIP Anda. - **Teruskan.** Atur `forward_to` dan `forward_as`. `forward_to` harus berupa salah satu [nomor terverifikasi](/docs/guides/voice/caller-ids) Anda; nomor yang belum diverifikasi menjawab `412` dengan [`E21053`](/docs/api/errors/E21053). `forward_as` menentukan nomor mana yang ditampilkan sebagai penelepon pada panggilan yang diteruskan. Satu nomor hanya memiliki satu rute pada satu waktu, jadi untuk beralih dari peralatan SIP ke nomor telepon, teruskan panggilan dari peralatan SIP Anda. - **Berhenti menerima panggilan.** Nomor menolak panggilan sampai Anda merutekannya kembali. Untuk mempertahankan default tetap sebagai pengganti profil default, rutekan nomor ke trunk yang memuat gateway default Anda. - **Profil.** `distributionType` menjadi `priority`: `FailOver` memberikan setiap gateway `priority` yang berbeda, dan `RoundRobin` memberikan nilai yang sama kepada semuanya. Distribusi diatur per trunk, jadi nomor yang membutuhkan distribusi berbeda memerlukan trunk berbeda. Placeholder `{dnis}` menjadi `{number}` di `destination_format`, dan `prefixCLIP` menjadi teks sebelum `{number}` di `origination_format`. - **Terapkan profil.** Trunk dialamatkan berdasarkan identifier `spt_`-nya, sedangkan Telserv mengalamatkan profil berdasarkan nama. ### Dokumen dan data pengguna akhir | Pekerjaan | Telserv | Bird | | ------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Baca persyaratan | `GET /products/conditions`, `GET /masterdata/productconditions` | [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements) untuk nomor tersebut, atau dengan `program` dan tanpa `subject_id` untuk formulir yang diminta suatu negara sebelum Anda memiliki nomor | | Unggah dokumen | `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), lalu cantumkan lampiran tersebut dalam pengajuan. Lihat [Ajukan dokumen kepemilikan](#ajukan-dokumen-kepemilikan) | | Kirim data pengguna akhir | `POST /numbers/{dnisId}/enduserdata` | [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), bersama dokumennya, dalam satu permintaan. Lihat [Ajukan dokumen kepemilikan](#ajukan-dokumen-kepemilikan) | | Ganti dokumen | `POST /numbers/{dnisId}/documents` lagi | [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission) dengan jawaban yang ditolak atau kedaluwarsa | | Cek progres dokumen | `GET /numbers/{dnisId}/documents` | `ownership` pada [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number), dan pengajuan untuk keputusan atas setiap jawaban | - **Persyaratan.** Katalog persyaratan Telserv mencakup semua produk sekaligus; Bird membaca satu formulir setiap kali. Minta persyaratan satu nomor dengan `subject_kind=number`, identifier `nda_`-nya sebagai `subject_id`, dan `country_code`-nya, atau baca formulir sebelum membeli dengan `program` diisi jenis nomor dan tanpa `subject_id`. Setiap entri di `fields` menggantikan satu persyaratan atau label pengguna akhir Telserv: `key`-nya adalah kunci tempat Anda menjawab, dan `data_type` `document` menandai entri yang memerlukan file. - **Dokumen.** Unggah file sebagai `multipart/form-data`, bukan `fileContent` base64; [Unggah setiap dokumen](/docs/guides/numbers/ownership-paperwork#upload-each-document) mencantumkan file yang diterima. Mengunggah file yang sama dua kali mengembalikan lampiran yang sama. Unggahan saja tidak mengajukan apa pun: pengajuan yang merujuk `attachment_id`-nya yang mengajukannya. - **Data pengguna akhir dan dokumen sekaligus.** Telserv menerima setiap dokumen dalam panggilan tersendiri, dan data pengguna akhir sebagai satu daftar label dalam panggilan lain. Bird menerima semua jawaban, baik isian maupun dokumen, dalam satu pengajuan, dan tidak ada draf: permintaan tersebut langsung mengajukan jawaban untuk ditinjau. Setelah itu, ikuti `ownership.next`, yang menyebutkan resupply untuk koreksi dan pengajuan baru hanya jika diperlukan ([Ajukan semua jawaban](/docs/guides/numbers/ownership-paperwork#submit-every-answer)). - **Penggantian.** Kirim hanya jawaban yang Anda ganti, dan jawaban lainnya mempertahankan status tinjauannya. Telserv menerima file baru untuk suatu persyaratan selama nomor menunggu verifikasi, dan file itu mengatur ulang tinjauan persyaratan tersebut; Bird mengganti jawaban yang ditolak, kedaluwarsa, atau belum diberikan, dan menolak jawaban yang masih ditinjau atau sudah diterima, kecuali jawaban bertanda `editable_for_verifier_repair` selama koreksi yang kami minta masih terbuka ([Koreksi jawaban yang ditolak](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer)). - **Progres.** `ownership.status` dan `ownership.next` melaporkan posisi nomor tersebut. Setiap jawaban memiliki `state` sendiri, dan jawaban yang ditolak menyertakan `reason` dari peninjau. Bird juga mengirim email berisi setiap hasil kepada pemilik organisasi Anda dan kepada orang yang terakhir mengajukan atau mengoreksi pengajuan. `ownership` biasanya `null` jika nomor tidak memerlukan dokumen. [Ajukan dokumen kepemilikan](#ajukan-dokumen-kepemilikan) menampilkan permintaannya, dan [Mengajukan dokumen kepemilikan nomor](/docs/guides/numbers/ownership-paperwork) membahas seluruh alurnya, termasuk pengajuan dari dashboard dan bersama pesanan. ### Produk dan data master | Pekerjaan | Telserv | Bird | | --------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Telusuri produk | `GET /products`, `GET /products/{productId}` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers), yang mewajibkan `country_code` dan mengembalikan nomor yang dijual di satu negara tersebut. Bird tidak memiliki katalog produk global, dan tidak ada yang setara dengan `productId`. Tidak ada API yang mencantumkan negara dan jenis nomor yang dijual; halaman [harga nomor telepon](/pricing/numbers) mencantumkan harga standar Bird per negara. | Setiap hasil pencarian menjelaskan produknya dengan `number_type`, `capabilities`, dan `ownership_registration_required`, serta menyertakan harga untuk organisasi Anda sebagai pengganti `pricing.staticPricing` produk (`nrc` dan `mrc`). Harga standar Bird ada di halaman [harga nomor telepon](/pricing/numbers). `sessionPricing` per menit dari Telserv tidak memiliki padanan di pembacaan ini; tarif suara ada di halaman [harga suara](/pricing/voice). Tipe nomor Telserv dipetakan ke `number_type` milik Bird seperti berikut: | `numberType` Telserv | Bird `number_type` | | -------------------- | -------------------------------------------- | | `DID` | `local` atau `national`, tergantung nomornya | | `FreePhone` | `toll_free` | | `Mobile` | `mobile` | ## Yang bekerja secara berbeda Pekerjaan Telserv berikut dilakukan secara berbeda di Bird. Rencanakan sebelum Anda memindahkan integrasi yang bergantung pada salah satunya. - **Dokumen kepemilikan.** Ajukan dokumen dan data pengguna akhir sebuah nomor dalam satu pengajuan, tanpa draf, dan perbaiki jawaban yang ditolak dengan resupply. - **Reservasi.** Pesan nomor setelah Anda memilihnya; pesanan mengamankan nomor tersebut. - **Pengaturan panggilan per nomor.** Terapkan codec paksa, batas panggilan bersamaan, waktu dering, dan jendela waktu pada peralatan SIP Anda. - **Tanggal pelepasan.** Bird melepaskan nomor di akhir periode yang sudah dibayar atau langsung, bukan pada tanggal yang Anda pilih. Simpan tanggal pembatalan yang Anda kirim ke Telserv di sisi Anda, dan tindak lanjuti masing-masing saat jatuh tempo. - **Saldo wallet.** Periksa saldo dan isi ulang di dashboard. ## Cari dan beli nomor dengan referensi Anda Cari satu negara. Kombinasikan `number_type`, `capabilities`, dan `prefix` untuk mempersempit hasil: ```bash curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Setiap hasil memuat objek `pricing` dengan harga yang dibayar organisasi Anda untuk nomor tersebut, sebelum pajak dan dalam mata uang penagihan Anda, dengan harga yang Anda sepakati bersama Bird sudah diterapkan: - `setup_price` dikenakan sekali saat Anda memesan nomor. Biaya yang dipublikasikan sebesar nol memiliki `amount` bernilai `"0"`. Field itu sendiri bernilai `null` jika tidak ada biaya pemasangan, dan juga setiap kali `recurring_price` bernilai `null`, karena nomor tersebut tidak dapat dipesan. - `recurring_price` adalah tarif per `recurring_period`. - `intervals_per_charge` adalah jumlah `recurring_period` yang dicakup satu tagihan. Biaya berulang sebelum pajak adalah `recurring_price` dikalikan `intervals_per_charge`, dikenakan saat nomor ditetapkan ke workspace Anda dan pada setiap perpanjangan; biaya pemasangan terpisah. Untuk pesanan yang menunggu operator, penetapan terjadi saat pesanan selesai. [Referensi API](/docs/api/reference/list-available-numbers) menampilkan contoh hasil. Hasil dengan `pricing.recurring_price: null` tidak memberikan harga berulang. [Hubungi tim penjualan](/contact-sales) agar negara dan jenis nomor tersebut diberi harga untuk Anda sebelum memesan. Dashboard dan API menggunakan harga organisasi yang sama, termasuk konversi ke mata uang penagihan Anda. Pembacaan harga tidak mengunci kuotasi: perubahan tarif atau nilai tukar sebelum tagihan berikutnya dapat mengubah jumlahnya. Jika pencarian harga gagal, hasil pencarian mengembalikan `503` dengan [`E14009`](/docs/api/errors/E14009). Coba lagi pembacaan dengan exponential backoff; kegagalan pencarian harga tidak pernah berarti nomor tersebut tidak dikenai biaya. Untuk mengonfirmasi kandidat dan harganya sebelum Anda memesannya, baca dengan `GET /v1/numbers/available/{number}`. Respons `404` berarti nomor tersebut sudah tidak dijual. Pesan nomor dengan referensi yang Anda gunakan di Telserv, dan pilih kunci idempotensi yang Anda simpan untuk percobaan ulang pembelian ini: ```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"}' ``` Respons `201` memiliki `status: completed` dan sebuah `number_id`, identifier `nda_` nomor tersebut. Simpan sebagai `NUMBER_ID`. Respons `202` berarti pesanan menunggu operator: [polling pesanan](/docs/guides/numbers/buying-numbers#poll-an-order-that-did-not-finish) sampai `status`-nya menjadi `completed` atau `failed`. Biaya pemasangan yang sudah dikenakan tidak dikembalikan jika pesanan kemudian gagal. Referensi ditetapkan pada nomor saat pesanan selesai. Referensi menampung hingga 100 karakter dan tidak harus unik. Mencoba lagi pesanan untuk nomor yang sudah dialokasikan ke workspace Anda mengembalikan pesanan yang sudah ada, sehingga percobaan ulang tidak menagih dua kali. [Membeli dan melepas nomor](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) menjelaskan penolakan-penolakannya. Untuk menetapkan atau mengubah referensi nanti, kirim `reference` (dan opsional `name`) ke `PATCH /v1/numbers/{number_id}`. Kirim `null` untuk mengosongkan field. ## Periksa bahwa nomor dapat membawa panggilan Nomor yang `status`-nya `pending_ownership_registration` sudah dialokasikan dan ditagih, tetapi tidak mengirim SMS dan menolak panggilan suara masuk dan keluar sampai dokumen kepemilikannya disetujui. Sebelum Anda merutekan nomor atau melakukan panggilan uji ke nomor tersebut, baca nomor itu dengan [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) dan periksa bahwa `status` bernilai `active`. Jika statusnya masih tertunda, [ajukan dokumen kepemilikan](#ajukan-dokumen-kepemilikan). [Status nomor yang dialokasikan](/docs/guides/numbers/overview#the-status-of-an-allocated-number) menjelaskan setiap nilai. Contoh-contoh di bawah menggunakan nomor ponsel Belanda. Periksa `status` nomor Anda sendiri dengan cara yang sama, apa pun negaranya. ## Ajukan dokumen kepemilikan Telserv menerima dokumen kepemilikan nomor dengan satu `POST /numbers/{dnisId}/documents` per dokumen dan satu `POST /numbers/{dnisId}/enduserdata` untuk semua label. Bird menerima keduanya dalam satu pengajuan, setelah Anda mengunggah dokumennya. 1. Baca `country_code` nomor tersebut dan simpan sebagai `COUNTRY_CODE`. Perintah ini mengekstraknya dengan `jq`; baca secara manual jika Anda tidak menggunakan `jq`: ```bash COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code) ``` 2. Baca apa yang diminta negara nomor tersebut. Setiap entri di `fields` memiliki `key` yang menjadi tempat jawaban Anda, sebuah `data_type`, dan `required`, yang menunjukkan apakah Anda wajib menjawabnya. Simpan `program` yang disebutkan respons sebagai `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" ``` Respons `422` dengan [`E19001`](/docs/api/errors/E19001) berarti tidak ada formulir kepemilikan untuk negara tersebut. 3. Unggah setiap dokumen yang diminta field `document`, sebagai file, bukan base64 `fileContent`. Simpan `id` dari respons, yaitu identifier `tca_` lampiran, sebagai `ATTACHMENT_ID`: ```bash curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --form "file=@registration-certificate.pdf" ``` 4. Kirim semua jawaban sekaligus: satu entri untuk setiap field yang `required`-nya `true`, dan untuk setiap field opsional yang benar-benar Anda miliki jawabannya, dengan data pengguna akhir sebagai `value` dan setiap dokumen sebagai `attachment_id`. Biarkan field opsional kosong daripada mengarang nilainya. Contoh ini menampilkan dua jawaban; tambahkan jawaban wajib lainnya sebelum mengirim. Permintaan ini mengajukan jawaban untuk ditinjau. Simpan `id` dari respons, yaitu identifier `csb_` pengajuan, sebagai `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"'"}]}' ``` Respons `201` mengembalikan pengajuan. Respons `422` tidak mengajukan apa pun: perbaiki body dan kirim dengan kunci idempotensi baru, karena kunci lama akan memutar ulang penolakan tersebut. [Kirim semua jawaban](/docs/guides/numbers/ownership-paperwork#submit-every-answer) menjelaskan setiap penolakan. 5. Jika peninjau menolak suatu jawaban, ganti hanya jawaban tersebut, seperti dijelaskan di [Perbaiki jawaban yang ditolak](/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"}]}' ``` Untuk mengajukan dokumen sekaligus saat membeli, kirim `answers` yang sama di blok `compliance` pada `POST /v1/numbers/orders`. Pesanan tersebut menggunakan scope `numbers` yang sudah ada pada level tulis, termasuk saat pesanan memuat dokumen kepemilikan. Pantau peninjauan dengan `ownership.status` pada [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number). Jawaban tersebut merupakan pernyataan hukum yang dibuat atas nama bisnis Anda, jadi ajukan hanya jawaban yang sudah dikonfirmasi oleh orang yang bertanggung jawab atasnya. [Ajukan dokumen kepemilikan nomor](/docs/guides/numbers/ownership-paperwork) membahas setiap permintaan, peninjauan, dan pengajuan bersama pesanan. ## Rutekan nomor ke trunk SIP Anda Nomor baru tidak memiliki rute sendiri, sehingga mengikuti [rute default](/docs/guides/voice/receiving-calls#set-a-default-route) workspace Anda. Rute default itu awalnya `reject`, tetapi di workspace yang sudah menetapkannya, nomor baru menjawab panggilan sesuai rute tersebut begitu nomor dialokasikan. Untuk mengirimkan panggilannya ke peralatan Anda, buat trunk SIP dengan panggilan masuk aktif, tambahkan gateway, dan arahkan nomor ke trunk tersebut. [Trunk SIP](/docs/guides/voice/sip-trunks) membahas cara menghubungkan peralatan Anda ke trunk. 1. Buat trunk dengan panggilan masuk aktif. Simpan `id` dari respons, yaitu identifier `spt_` trunk, sebagai `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. Tambahkan gateway. Secara default, gateway menerima nomor tujuan dan nomor pemanggil dalam format E.164 dengan `+`. Jika perangkat Anda mengharapkan nomor tanpa `+`, seperti yang dilakukan placeholder `{dnis}` Telserv, atur `destination_format` untuk nomor tujuan dan `origination_format` untuk nomor pemanggil ke `{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}"}' ``` Untuk failover, tambahkan gateway kedua; [Yang dibutuhkan gateway](/docs/guides/voice/receiving-calls#what-a-gateway-needs) menjelaskan `priority` dan format nomor. Membuat gateway yang sama lagi tanpa kunci idempotensi menghasilkan respons `409` dengan [`E21047`](/docs/api/errors/E21047). 3. Temukan rekaman suara nomor tersebut. Cari dengan digit nomor dan ambil `id` dari entri yang `provider.number_id`-nya adalah `id` alokasi. Simpan sebagai `VOICE_NUMBER_ID`: ```bash curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` 4. Arahkan nomor ke 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"'"}}}' ``` Respons `200` menampilkan rute baru. Trunk dengan panggilan masuk nonaktif menjawab `412` dengan [`E21052`](/docs/api/errors/E21052). Menonaktifkan panggilan masuk pada trunk, atau menghapus trunk, mengembalikan setiap nomor yang diarahkan ke trunk tersebut ke rute default workspace Anda, dan mengaktifkannya kembali tidak memulihkan rute-rute tersebut. [Kirim panggilan ke trunk SIP](/docs/guides/voice/receiving-calls#deliver-calls-to-a-sip-trunk) menjelaskan hal ini serta rute `trunk`, `forward`, dan `reject`. ## Rekonsiliasi nomor Anda Telusuri daftar dengan ukuran halaman terbesar. Kirim `next_cursor` setiap halaman sebagai `NEXT_CURSOR` untuk membaca halaman berikutnya, sampai `next_cursor` bernilai `null`. Daftar tidak mengembalikan jumlah total. ```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" ``` Filter daftar Telserv dipetakan ke filter Bird seperti ini: | Filter Telserv pada `GET /numbers` | Filter Bird pada `GET /v1/numbers` | | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number`, yang mencocokkan awal nomor | `prefix` tanpa `country_code`, yang mencocokkan digit dari awal nomor lengkap | | `prefix`, yang sama dengan kode akses dan kode area seperti `3170` | `country_code` dengan `prefix` diisi digit nasional: `country_code=NL&prefix=70` | | `reference` dengan nilai parsial | `search`, yang mencocokkan sebagian nomor, nama, atau referensi, tanpa mempedulikan huruf besar/kecil | | `reference` dengan nilai persis yang dikutip | `reference`, yang mengembalikan nomor dengan referensi persis tersebut. Pencocokan ini peka huruf besar/kecil | | Baru di Bird | `number` mengembalikan satu nomor lengkap yang diberikan dengan kode negaranya, dengan atau tanpa `+` atau `00`: `+31612345678`, `31612345678`, dan `0031612345678` menemukan nomor yang sama | [Temukan nomor di daftar Anda](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) membahas setiap filter secara detail. Setiap entri memuat `pricing`, dengan `recurring_price` per `recurring_period` dan `intervals_per_charge`. Kecuali harga ditetapkan untuk nomor tersebut, `recurring_price` adalah tarif organisasi Anda saat ini, dan setiap perpanjangan mengenakan tarif yang berlaku saat diperpanjang, sehingga tagihan yang sudah dikenakan bisa berbeda dari tarif tersebut. [Daftar semua nomor yang Anda miliki](/docs/guides/numbers/managing-numbers#list-every-number-you-hold) menjelaskan mata uang yang digunakan untuk menagih setiap nomor, kapan `pricing` atau harganya bernilai `null`, dan apa yang harus dilakukan jika `pricing.error` terisi. Nomor yang sudah dilepas tidak lagi muncul di daftar ini, dan membacanya berdasarkan `number_id` menghasilkan `404`. Jika Anda memesannya di Bird, pesanan yang sudah selesai tetap ada di [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders). ## Melepas nomor Kedua permintaan berlaku untuk nomor khusus, berdasarkan identifier `nda_`-nya; nomor bersama ditolak dengan [`E14002`](/docs/api/errors/E14002). Untuk mempertahankan nomor hingga akhir periode yang sudah Anda bayar, batalkan nomor tersebut: ```bash curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: cancel-CUST-778812" ``` Respons `202` mengembalikan nomor dengan `releases_at`, yaitu akhir periode yang sudah dibayar. Nomor mempertahankan statusnya saat ini hingga saat itu, langganannya tidak diperpanjang, dan nomor dilepas pada waktu tersebut. Permintaan ulang mengembalikan `releases_at` yang sama, dan pembatalan tidak dapat dibatalkan. Nomor yang tidak memiliki langganan langsung dilepas, dan responsnya adalah `200` dengan `status` nomor disetel ke `released`. Untuk melepas nomor sekarang, termasuk nomor yang sudah dijadwalkan untuk pembatalan: ```bash curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: release-CUST-778812" ``` Respons `204` berarti nomor telah dilepas, berlaku segera. Sisa periode saat ini tidak dikembalikan. Selama pembayaran perpanjangan untuk nomor tersebut tertunggak, kedua permintaan menjawab `409` dengan [`E03015`](/docs/api/errors/E03015) sampai pembayaran dilunasi. Tidak satu pun permintaan menerima tanggal, jadi simpan jadwal yang Anda kirim ke Telserv sebagai `requestedCancelDate` di sisi Anda. Untuk mempertahankan nomor hingga tanggalnya, batalkan nomor tersebut setelah tanggal jatuh dalam periode penagihan saat ini: nomor dilepas saat periode itu berakhir, pada atau setelah tanggal tersebut. Untuk melepasnya tepat pada tanggal itu, lepaskan nomor pada hari itu. [Melepas nomor](/docs/guides/numbers/managing-numbers#release-a-number) menjelaskan apa yang dilakukan setiap permintaan terhadap nomor, tagihannya, dan percobaan ulang. ## Lakukan panggilan uji ke nomor Anda Untuk memeriksa rute secara menyeluruh, lakukan panggilan ke nomor tersebut dari nomor lain yang boleh ditampilkan workspace Anda sebagai caller ID. Negara nomor tersebut harus diaktifkan di [tujuan panggilan suara](/docs/guides/voice/destinations) Anda, atau panggilan tidak akan terhubung. Permintaan di bawah menjalankan urutan inline yang menutup panggilan begitu dijawab, sehingga tidak perlu urutan tersimpan. Panggilan ini adalah panggilan nyata, dan biaya panggilan normal berlaku. Simpan permintaan sebagai `test-call.json`. Masukkan caller ID yang Anda tampilkan di `from`, yaitu nomor milik atau [nomor terverifikasi](/docs/guides/voice/caller-ids) workspace Anda, dan nomor yang diuji di `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": {} } } ``` Kirim: ```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 ``` Atur `TEST_CALL_KEY` ke nilai baru untuk setiap pengujian, dan gunakan kembali saat Anda mencoba lagi pengujian yang sama setelah timeout atau hasil yang tidak jelas: kunci dan permintaan yang sama dalam tiga jam akan memutar ulang penerimaan pertama alih-alih melakukan panggilan kedua. Respons `202` menerima panggilan dan mengembalikan `initial_leg_id`-nya. Penerimaan tidak membuktikan panggilan terhubung: baca leg dengan [`GET /v1/voice/legs/{leg_id}`](/docs/api/reference/get-voice-leg), atau tampilkan daftar leg yang dilakukan ke nomor tersebut dengan [`GET /v1/voice/legs`](/docs/api/reference/list-voice-legs) dan filter `to`-nya, lalu periksa bahwa peralatan Anda menerima panggilan tersebut. [Membuat panggilan suara](/docs/guides/voice/create-calls) membahas persyaratan caller ID dan tujuan serta aturan percobaan ulang. ## Langkah selanjutnya - [Membeli dan melepas nomor](/docs/guides/numbers/buying-numbers) - [Mengelola nomor telepon Anda](/docs/guides/numbers/managing-numbers) - [Ajukan dokumen kepemilikan nomor](/docs/guides/numbers/ownership-paperwork) - [Menerima panggilan](/docs/guides/voice/receiving-calls) - [Trunk SIP](/docs/guides/voice/sip-trunks) - [Idempotensi](/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)