Pesan nomor telepon dari sebuah prefiks

Pesan dari sebuah prefiks

Gunakan operasi ini ketika katalog prefiks mengarahkan Anda untuk memesan sejumlah nomor dari sebuah prefiks alih-alih memilih satu per satu nomor yang tersedia. Mulailah dengan negara, wilayah atau negara bagian, dan prefiks. Simpan pengenal prefiks dan paket harga dari hasil terbaru yang sama. Untuk nomor tertentu yang dipilih dari daftar nomor yang tersedia, gunakan Beli nomor telepon yang dipilih.

Permintaan ini dapat membeli nomor dan menimbulkan biaya. Ini bukan penawaran harga, reservasi, atau simulasi. Tinjau biaya penyiapan dan bulanan, tarif per menit panggilan masuk, menit yang termasuk dalam paket, kanal, persyaratan registrasi, dan batas pembelian akun sebelum mengirimkannya. Hasil katalog tidak mencadangkan persediaan atau mengunci harga. Pemeriksaan pendanaan akun dapat dilakukan sebelum pemenuhan pesanan; kesalahan saja tidak membuktikan bahwa tidak terjadi pembelian atau pendanaan akun.

Kirim permintaan pembelian

Gunakan akun API yang telah diaktifkan melalui HTTPS dari alamat IP sumber yang diizinkan. Tetapkan variabel berdasarkan pilihan katalog Anda saat ini dan konfigurasi pengiriman yang telah Anda setujui. Perintah berikut membeli satu nomor.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Pengiriman formulir melalui POST ditampilkan di atas. Koordinator juga membaca objek JSON ketika Content-Type bernilai application/json. Kolom JSON menggantikan kolom formulir/permintaan yang bersesuaian. Gunakan satu pengodean secara konsisten; jangan mengirim nilai kueri dan isi permintaan yang saling bertentangan.

Parameter pemilihan pesanan dan notifikasi
Parameter	Arti
pengenal prefiks dalam jalur	UUID prefiks yang dikembalikan oleh katalog. Pengenal negara, wilayah, harga, atau nomor individual tidak dapat digunakan sebagai penggantinya.
quantity	Kirim bilangan bulat dari 1 hingga 100. Nilai default adalah 1. Nilai di bawah 1 dipaksa menjadi 1; ini bukan permintaan yang hanya melakukan validasi. Nilai di atas 100 memicu pengecualian sebelum penanganan respons normal koordinator ini, jadi jangan mengandalkan struktur JSON biasanya untuk masukan tidak valid tersebut.
price_id	Pengenal harga publik untuk paket yang dipilih. priceid adalah alias lama. Pengenal yang tidak cocok dapat menyebabkan pemilihan paket lain sebagai cadangan tanpa pemberitahuan; kolom ini bukan pengunci harga yang ketat. Pastikan batas harga akun sebelum membeli dan periksa harga yang dikembalikan sesudahnya.
channels	Jumlah kanal dari paket yang dipilih. Jika kecocokan harga yang persis tidak digunakan, jumlah kanal yang cocok dapat memengaruhi pemilihan paket cadangan. Jumlah kanal saja tidak menjamin bahwa paket tertentu dibeli.
reference	Label Anda untuk pembelian atau kelompok pembelian. Gunakan nilai ASCII yang singkat, paling banyak 255 byte; nilai yang lebih panjang akan dipotong. Nilai ini disimpan bersama pembelian yang berhasil dan disertakan dalam callback jika diberikan. Pesanan terpisah dapat memiliki referensi yang sama. Ini bukan kunci idempotensi: mengirim operasi ini lagi dapat membeli nomor tambahan dan mengenakan biaya atasnya, bahkan dengan referensi yang sama dan kolom yang identik.
webhook_url	URL callback opsional. Gunakan endpoint HTTPS yang Anda kendalikan. URL HTTP dan HTTPS lolos validator dasar saat ini; URL yang tidak valid diabaikan, bukan menyebabkan pembelian ditolak. Callback merupakan notifikasi tambahan, bukan bukti bahwa permintaan aman untuk diulang.

Pengaturan pengiriman dan perpanjangan

Pilih pengaturan pengiriman yang sama dengan yang akan Anda gunakan untuk nomor tersebut di portal. Ini adalah nilai konfigurasi lanjutan, bukan instruksi untuk membuat Hosted PBX atau trunk originasi. Gunakan kembali konfigurasi akun yang diketahui berfungsi dan verifikasi nomor yang tersimpan setelah pembelian. Diterimanya pembelian saja tidak memverifikasi bahwa pengiriman suara atau SMS berfungsi.

Kolom pesanan tambahan
Kolom	Penggunaan dan kompatibilitas
uri, uri2, uri3	Tujuan suara utama dan tambahan. Berikan tujuan yang sesuai dengan mode penerusan dan dering yang dipilih.
forward_destination	Mode penerusan suara. forwarding_destination dan type adalah alias lama. Jika kolom ini tidak disertakan, nilai default jalur penyelesaian pembelian digunakan; kolom kosong bukan cara yang andal untuk menghapus preferensi yang sudah ada.
ring_type	Mode dering suara; ringtype adalah aliasnya. Gunakan nilai yang didukung dari konfigurasi nomor akun Anda.
sms_forward_destination, sms_uri	Mode dan tujuan pengiriman SMS. Alias lamanya adalah smsringtype dan smsuri. Beberapa jalur penyelesaian pembelian menerapkan tujuan SMS default akun ketika nilai ini kosong. Ketersediaan SMS bergantung pada nomor yang dipilih serta aktivasi/registrasinya.
overflow	Pengaturan luapan yang diminta. Ketersediaan paket dan jalur penyelesaian pembelian memengaruhi apakah pengaturan ini didukung.
force_codec, force_dtmf	Pengaturan kodek dan DTMF yang diminta. Alias lamanya adalah forcecodec dan forcedtmf. Verifikasi konfigurasi yang tersimpan untuk persediaan yang dipilih.
origination_trunk_id	Pengenal konfigurasi trunk yang sudah ada, jika berlaku. Ini tidak membuat trunk. Jika tidak disertakan, nilai default penyelesaian pembelian digunakan.
autorenew	Pengaturan perpanjangan yang diminta. Jangan berasumsi bahwa 0 menonaktifkan perpanjangan: beberapa jalur penyelesaian pembelian memperlakukan nilai yang dianggap kosong, termasuk 0, sebagai pengaturan default yang aktif. Periksa dan, jika perlu, ubah perpanjangan pada nomor yang dibeli melalui portal.

Kolom-kolom ini dinormalisasi dan diteruskan ke proses penyelesaian pembelian, tetapi penyimpanannya berbeda di antara jalur persediaan. Rute pemesanan saat ini tidak menyediakan kolom pembatas penawaran harga yang ketat dari panduan pembelian nomor pilihan sebagai pengaman yang setara. Gunakan izin pembelian dan batas harga akun, lalu periksa konfigurasi nomor yang dihasilkan.

Baca hasil selengkapnya

Uraikan isi JSON dan periksa status.code serta status.msg meskipun permintaan HTTP berhasil. Rute ini menulis respons JSON-nya sendiri, dan fungsi pembantu respons bersama juga tidak selalu memetakan kode aplikasi ke status HTTP. Kode aplikasi dapat berupa angka JSON atau string numerik. Jangan mensyaratkan adanya status.results; kolom tersebut tidak ada dalam hasil pemesanan normal.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

Pengenal, nomor, dan harga di atas bersifat fiktif. Perlakukan ID pesanan sebagai pengenal yang tidak perlu ditafsirkan strukturnya. numbers mencantumkan nomor yang dilaporkan oleh respons ini sebagai telah dibeli; bandingkan jumlah elemennya dengan jumlah yang Anda minta. Besaran harga berupa string dan respons ini membulatkan tarif moneter hingga dua angka desimal, termasuk per_minute; gunakan katalog terbaru untuk memperoleh presisi tarif aslinya. Menit yang termasuk dalam paket dan kanal dapat diterima sebagai nilai numerik atau string numerik.

Blok harga menjelaskan paket terpilih yang digunakan untuk menyusun respons, bukan faktur terperinci untuk setiap nomor atau total pesanan. Beberapa kandidat dalam persediaan dapat memiliki paket yang berbeda. Cocokkan setiap nomor yang dibeli dan transaksi akun, alih-alih mengalikan nilai dalam blok ini dan menganggapnya sebagai bukti total akhir.

Pembelian parsial dan hasil yang belum pasti

Kode aplikasi 200 dapat disertai peringatan dan jumlah nomor yang lebih sedikit daripada yang diminta. Kegagalan setelahnya tidak membatalkan nomor yang sudah dibeli. Simpan ID pesanan, nomor, dan pesan yang dikembalikan. Cocokkan nomor-nomor tersebut dengan inventaris dan transaksi akun Anda sebelum memutuskan apakah akan memesan jumlah yang tersisa.

Batas waktu yang terlampaui, permintaan yang terputus, respons dengan format tidak valid, atau kesalahan setelah pengiriman bukan bukti bahwa tidak terjadi apa-apa. Jangan otomatis mengirim pembelian lain, meskipun menggunakan referensi yang sama. Simpan permintaan asli, referensi, dan ID pesanan apa pun yang dikembalikan, periksa inventaris dan transaksi akun, lalu hubungi dukungan jika hasilnya masih belum pasti.

Pesanan yang belum dikonfirmasi dapat mengembalikan kode aplikasi 400 dengan pesan bahwa pesanan masih dalam proses konfirmasi. Simpan ID pesanan yang dikembalikan dan cocokkan pembelian tersebut; ini bukan instruksi untuk mengirimkannya lagi. Pemulihan pesanan yang tercatat melacak pesanan asli secara internal. Permintaan baru ke operasi ini membuat upaya pembelian terpisah, bukan melanjutkan pesanan berdasarkan referensi Anda, sehingga dapat membeli lebih banyak nomor dan mengenakan biaya atasnya. Jangan menggunakan permintaan pembelian berulang untuk memeriksa status atau mencari persediaan.

Registrasi dan aktivasi

Nomor yang telah dibeli atau dialokasikan mungkin masih memerlukan registrasi atau aktivasi. Jika needs_registration bernilai 1, periksa restrictions dan registration_requirements. Kolom yang terakhir dapat menunjukkan v3/get_requirements dengan nilai country dan number_type. Selesaikan alur kerja identitas/alamat yang berlaku dan pastikan status nomor sebelum mengandalkannya untuk panggilan masuk atau perpesanan.

features menjelaskan kemampuan yang diiklankan; kolom ini tidak memverifikasi perutean langsung, persetujuan kampanye, pengiriman SMS, atau penerimaan faks. Periksa pengaturan pengiriman yang tersimpan dan lakukan pengujian layanan yang sesuai ketika nomor sudah aktif.

Callback pesanan

Callback mengirim JSON melalui POST yang berisi status dan respons pesanan, dengan referensi Anda ditambahkan jika diberikan. Callback dikirim untuk pembelian yang dilaporkan, termasuk hasil parsial. Callback yang gagal tidak membatalkan pembelian. Pengiriman dapat dicoba ulang, jadi tangani duplikat berdasarkan ID pesanan dan cocokkan nomor-nomornya, alih-alih mengirim pembelian lain.

Rute ini tidak menambahkan tanda tangan kriptografis pada callback. Perlakukan callback sebagai notifikasi untuk dicocokkan dengan inventaris Anda yang diakses melalui autentikasi, bukan sebagai otorisasi tersendiri untuk mengenakan biaya, menyediakan layanan, atau memberikan akses. Jangan menaruh kredensial API dalam URL callback. Mengirim pembelian lain dengan URL callback berbeda tidak memperbarui pesanan asli; tindakan itu membuat upaya pembelian terpisah. Simpan ID pesanan asli saat meminta dukungan menyelidiki callback-nya.

Kegagalan yang perlu ditangani

Hasil aplikasi
Hasil	Tindakan yang perlu dilakukan
400 dan pesan bahwa prefiks tidak valid	Baca kembali katalog prefiks dan gunakan pengenalnya yang berlaku saat ini. Bedakan pesan ini dari pesan bahwa pesanan asli masih dalam proses konfirmasi.
403 atau kegagalan terkait kebijakan/saldo akun	Tinjau izin pembelian, batas harga akun, batas jumlah, dan pendanaan. Kode aplikasi lain dapat diteruskan dari pemeriksaan tersebut; simpan pesan yang sebenarnya.
404 atau tidak ada persediaan yang tersedia	Perbarui informasi ketersediaan. Jangan berulang kali melakukan pembelian dari prefiks yang persediaannya sudah habis.
409 dan pesan terkait konfirmasi pembelian, penolakan penyedia, atau pesanan yang dibatalkan	Simpan ID pesanan yang dikembalikan dan pesan yang sebenarnya. Cocokkan permintaan dengan inventaris dan transaksi akun serta konfirmasikan dengan dukungan sebelum mengirim pembelian lain. Menggunakan kembali referensi yang sama tidak membuat permintaan lain menjadi aman.
200 dengan peringatan atau jumlah nomor yang lebih sedikit	Sebagian nomor telah dibeli. Cocokkan alokasi yang dikembalikan dan transaksi sebelum memesan lebih banyak.
Kegagalan server/transport atau respons yang tidak dapat dibaca	Perlakukan hasil sebagai sesuatu yang mungkin belum pasti sampai inventaris dan transaksi memastikan apa yang terjadi.