Muat katalog pendaftaran perpesanan

Muat pilihan sebelum membuat formulir pendaftaran

Gunakan katalog pendaftaran perpesanan terkini untuk mengisi pilihan alih-alih menanamkan nilai registri secara tetap dalam kode. Untuk formulir merek, portal memuat katalog jenis usaha, industri, jenis pengenal usaha alternatif, hubungan dengan merek, negara, negara bagian AS, dan bursa efek. Untuk formulir kampanye, portal memuat kasus penggunaan, subkasus penggunaan yang valid, dan mitra konektivitas. Simpan setiap nilai yang dapat dibaca mesin yang dikembalikan beserta label tampilannya; gunakan nilai tersebut, bukan label yang diterjemahkan, saat menyusun permintaan berikutnya.

Pilih katalog

Tangani respons TCR secara langsung

Isi respons berasal langsung dari API TCR. Berbeda dengan banyak titik akhir lama /v3, respons ini tidak memiliki pembungkus tambahan status/response. Periksa status HTTP sebelum menafsirkan respons. Katalog dapat berisi label teks atau definisi terstruktur, jadi jangan menganggap setiap nilai memiliki kolom yang sama. Jika permintaan HTTP berhasil tetapi isinya bukan JSON yang valid dengan struktur yang diharapkan, laporkan kegagalan pencarian alih-alih diam-diam menggantinya dengan daftar kosong.

Pisahkan pilihan katalog dari kelayakan dan penetapan harga

Katalog kasus penggunaan umum tidak menunjukkan kasus penggunaan yang memenuhi syarat untuk suatu merek tertentu. Portal saat ini melakukan pencarian kelayakan khusus merek sebelum membuat kampanye dan memeriksa persyaratan operator yang dipilih. Demikian pula, metadata biaya pemasok bukan harga eceran akhir untuk akun. Tinjau harga akun yang berlaku dan ketentuan pendaftaran secara terpisah. Memuat katalog tidak memberikan persetujuan untuk merek, kampanye, atau nomor perpesanan.

Tangani katalog yang tidak tersedia

Pertahankan isian formulir pelanggan jika pencarian gagal. Tampilkan kesalahan, patuhi Retry-After jika dikembalikan, dan tambah jeda antarpercobaan ulang. Jangan terus-menerus memuat ulang setiap katalog atau menganggap kesalahan batas laju maupun transportasi data sebagai katalog kosong yang valid. GET ini tidak memerlukan kunci idempotensi dan tidak diputar ulang dari penyimpanan idempotensi untuk mutasi.

Permintaan

Gunakan akun API yang diaktifkan melalui HTTPS dari alamat IP sumber yang diizinkan. Rute saat ini mendukung kebijakan autentikasi akun, termasuk autentikasi Basic dan akun API bearer yang diaktifkan. Jangan gunakan kredensial penyedia.

Kirim GET dengan nama katalog yang didukung pada jalur. Sertakan filter katalog yang berlaku dalam string kueri. Isi permintaan tidak diperlukan.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

Respons

Rute TCR ini mengembalikan isi dari registri secara langsung beserta status HTTP-nya. Rute ini tidak menggunakan pembungkus status.code/status.msg/response dari v3 yang lama. Struktur katalog berbeda-beda: sebagian memetakan nilai ke objek deskriptif; lainnya memetakan nilai ke teks. Pertahankan kunci yang dapat dibaca mesin saat mengirim formulir berikutnya. Contoh usecase fiktif yang disingkat menggambarkan pemetaan dengan nilai berupa objek, bukan katalog aktif atau skema yang dijamin lengkap. Periksa status HTTP dan struktur JSON yang diharapkan.

Ilustrasi struktur respons; bukan data akun langsung atau penawaran harga terkini.

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

Kesalahan

• 401: Autentikasi akun gagal. Periksa kredensial API, status pengaktifan, dan pembatasan IP sumber yang berlaku.
• 400/404 dan kesalahan registri lainnya: Katalog atau filter tidak valid atau tidak tersedia. Rute saat ini mempertahankan status HTTP dan isi respons dari layanan hulu; tidak ada pembungkus kesalahan v3 yang universal.
• 429: Batas permintaan akun atau batas bersama penyedia telah tercapai. Patuhi Retry-After dan coba lagi dengan jeda yang semakin panjang.
• 502: Registri tidak dapat dihubungi. Ketersediaannya tidak diketahui; jangan menggantinya dengan pilihan kosong sebagai hasil yang berhasil.
• 503: Pembatas permintaan atau layanan hulu tidak tersedia. Periksa isi respons dan header Retry-After jika ada sebelum mencoba lagi.

Ketersediaan dan efek samping

• Dalam alur yang telah ditinjau, GET katalog ini tidak membuat merek atau kampanye, mengirim pendaftaran, mencadangkan sumber daya, atau mengenakan biaya pendaftaran. Permintaan ini menghubungi penyedia dan menulis catatan audit permintaan.
• Definisi katalog dan metadata biaya pemasok apa pun bukan penawaran harga eceran untuk pelanggan. Portal saat ini memperoleh harga eceran kampanye secara terpisah; fungsi bantu lama getCampaignPrice dan anotasi harga enumerasi lama tidak boleh dianggap sebagai kontrak penetapan harga rute ini.
• Entri katalog yang didukung bukan bukti bahwa merek tertentu memenuhi syarat untuk kasus penggunaan tersebut. Selesaikan pemeriksaan kelayakan khusus merek, pernyataan, persetujuan, dan peninjauan harga akun sebelum mengirim permintaan pendaftaran berikutnya.