Dokumen ini menjelaskan proses untuk membuat sistem pemeriksaan alamat guna menangani berbagai respons dari Address Validation API. Panduan ini membahas cara menafsirkan respons API untuk menentukan kapan dan bagaimana meminta pelanggan Anda untuk mendapatkan informasi selengkapnya.
Secara umum, respons API menentukan cara berikut yang harus dilakukan sistem Anda untuk menangani alamat:
Pertimbangkan untuk meminta informasi selengkapnya kepada pelanggan Anda.
Perbaiki—alamat mungkin berisi masalah yang signifikan.
Pertimbangkan untuk meminta pelanggan menambahkan nomor unit.
Tambahkan sub-lokasi—alamat mungkin tidak memiliki
sub-lokasi.
Pertimbangkan untuk meminta pelanggan mengonfirmasi bahwa alamatnya sudah benar.
Konfirmasi—alamat mungkin berisi masalah kecil.
Pertimbangkan untuk menggunakan alamat tersebut tanpa permintaan lebih lanjut, dengan risiko Anda sendiri.
Terima—alamat mungkin tidak berisi masalah.
Tujuan utama
Dokumen ini membantu Anda mengubah sistem untuk menganalisis respons API dengan sebaik mungkin dan menentukan tindakan berikutnya yang akan dilakukan dengan alamat yang diberikan. Pseudocode berikut menggambarkan kemungkinan alur.
if (verdict.possibleNextAction == FIX)
Prompt the user to fix the address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
Prompt the user to add a unit number.
else if (verdict.possibleNextAction == CONFIRM)
Confirm with the user that the address is correct.
else
Continue with the address returned by the API.
Logika yang tepat bergantung pada situasi Anda - lihat Menyesuaikan logika validasi untuk mengetahui detail selengkapnya.
Kemungkinan alur kerja
Tabel di bawah ini merangkum kemungkinan alur kerja yang dapat Anda terapkan untuk meminta pelanggan berdasarkan respons API.
Perilaku sistem Anda | ||
---|---|---|
Perbaiki alamat |
Respons dari
|
|
Tambahkan sub-lokasi |
Respons dari
|
|
Konfirmasi alamat |
Respons dari
|
|
Terima alamat |
Respons dari
|
Menyesuaikan logika validasi
Meskipun Anda dapat menggunakan hasil dari kolom verdict.possibleNextAction
untuk
menentukan cara sistem Anda melanjutkan respons API, Anda juga dapat
mempertimbangkan untuk membuat logika kustom, seperti untuk menangani kebutuhan khusus bisnis.
Tujuan bagian ini adalah untuk mengilustrasikan cara mengembangkan logika kustom Anda sendiri untuk menafsirkan respons API guna menentukan apakah dan bagaimana Anda ingin meminta pelanggan. Bagian ini membahas tingkat risiko dan sinyal respons API tambahan yang perlu dipertimbangkan untuk penyesuaian Anda.
Meskipun demikian, meskipun Anda hanya mengandalkan verdict.possibleNextAction
untuk memutuskan
langkah berikutnya, sinyal tambahan yang dijelaskan di bawah masih dapat membantu Anda
memahami detail tentang potensi masalah pada alamat.
Toleransi risiko
Saat mendesain cara sistem Anda merespons sinyal dari Address Validation API, rekomendasi berikut dapat membantu Anda membuat model respons yang lebih efektif. Namun, ini hanyalah rekomendasi, jadi perlu diingat bahwa penerapan Anda harus sesuai dengan model bisnis Anda.
Panduan | Detail | |
---|---|---|
Tingkat risiko |
Pertimbangkan tingkat toleransi untuk situasi Anda saat menyeimbangkan antara meminta koreksi dan menerima alamat seperti yang dimasukkan. |
Address Validation API menampilkan berbagai sinyal yang dapat Anda gabungkan dengan tingkat risiko untuk mengoptimalkan proses validasi. Misalnya, jika alamat memiliki nomor jalan yang belum dikonfirmasi, Anda tetap dapat menerimanya. Di sisi lain, jika operasi bisnis Anda memerlukan presisi alamat yang lebih tinggi, Anda dapat meminta pengguna. Untuk contoh yang dapat termasuk dalam salah satu kategori tersebut, lihat Nomor jalan non-AS yang tidak dikonfirmasi di Menerima alamat - contoh. |
Menerima alamat |
Sebaiknya izinkan sistem Anda menerima entri asli jika pelanggan tidak merespons perintah. |
Dalam kasus ini, pelanggan mungkin telah memasukkan alamat yang tidak ada dalam sistem, seperti untuk bangunan baru. |
Contoh alur checkout yang menghindari risiko
Jika ingin mengurangi risiko pengiriman yang gagal, Anda dapat menyesuaikan logika untuk lebih sering meminta pelanggan. Misalnya, daripada menggunakan logika yang dijelaskan di bagian Tujuan kunci, Anda dapat menggunakan logika berikut.
if (verdict.possibleNextAction == FIX or verdict.validationGranularity
== OTHER or verdict.validationGranularity == ROUTE)
Prompt customer to fix their address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
Prompt customer to add a unit number.
else if (verdict.possibleNextAction == CONFIRM or verdict.validationGranularity
== PREMISE_PROXIMITY or verdict.hasSpellCorrectedComponents or
verdict.hasReplacedComponents or verdict.hasInferredComponents)
Prompt customer to confirm their address.
else
Proceed with the returned address.
Contoh alur checkout yang mudah
Jika ingin mengurangi hambatan dalam alur checkout, Anda dapat menyesuaikan logika untuk lebih jarang meminta pelanggan. Misalnya, daripada menggunakan logika yang dijelaskan di bagian Tujuan kunci, Anda dapat menggunakan logika berikut.
if (verdict.possibleNextAction == FIX)
Prompt customer to fix their address.
else if (verdict.hasReplacedComponents)
Prompt customer to confirm their address.
else
Proceed with the returned address.
Sinyal FIX
Perbaiki alamat jika hasilnya menunjukkan dengan jelas bahwa alamat tersebut mungkin tidak dapat dikirim. Sistem Anda kemudian dapat meminta pelanggan untuk memberikan informasi yang diperlukan, setelah itu Anda menerbitkan ulang alur kerja untuk mendapatkan alamat yang dapat dikirim.
Kolom berikut dari respons Address Validation API dapat digunakan selain
verdict.possibleNextAction
untuk menentukan apakah alamat memiliki masalah utama,
dan apa masalah tersebut.
Perincian validasi | Jika enum tingkat perincian validasi untuk alamat adalah
OTHER , kemungkinan alamat tersebut salah.
|
---|---|
Komponen tidak ada | Jika address.missingComponentTypes tidak kosong, kemungkinan alamat tersebut tidak memiliki informasi penting.
|
Komponen yang mencurigakan | Jika enum tingkat konfirmasi untuk komponen adalah
UNCONFIRMED_AND_SUSPICIOUS , kemungkinan komponen tersebut
salah.
|
Komponen yang belum terselesaikan | unresolvedToken adalah bagian dari input yang tidak dikenali sebagai bagian alamat yang valid. |
Konfirmasi DPV USPS | Jika uspsData.dpvConfirmation adalah N ,
atau kosong, mungkin ada masalah dengan alamat. Kolom ini hanya
tersedia untuk alamat AS. Untuk mengetahui detail selengkapnya tentang uspsData.dpvConfirmation ,
lihat Menangani alamat Amerika Serikat.
|
Sinyal CONFIRM_ADD_SUBPREMISES (khusus alamat AS)
Anda meminta pelanggan untuk meninjau alamat dan mempertimbangkan untuk menambahkan nomor unit saat respons Address Validation API menunjukkan bahwa alamat mungkin tidak memiliki sub-lokasi. Dalam hal ini, alamat bangunan kemungkinan valid, tetapi Anda ingin lebih yakin bahwa alamat yang dihasilkan adalah alamat yang diinginkan pelanggan.
Kolom berikut dari respons Address Validation API dapat digunakan selain
verdict.possibleNextAction
untuk menentukan apakah alamat kemungkinan tidak memiliki
sub-premis.
Missing subpremise component
|
Jika kolom address.missingComponentTypes berisi nilai subpremise , hal ini menunjukkan bahwa nomor unit tidak ada dalam alamat.
|
---|---|
Konfirmasi DPV USPS | Jika uspsData.dpvConfirmation adalah S , berarti
nomor utama alamat telah dicocokkan dengan alamat di
database USPS. Namun, alamat juga diharapkan berisi nomor sekunder. Kolom ini hanya tersedia untuk alamat di Amerika Serikat. Untuk detail
selengkapnya tentang uspsData.dpvConfirmation , lihat
Menangani alamat Amerika Serikat.
|
Menambahkan contoh alamat sub-lokasi
Sinyal KONFIRMASI
Anda mengonfirmasi alamat saat verdict menunjukkan bahwa Address Validation API menyimpulkan atau membuat perubahan pada komponen alamat untuk menghasilkan alamat yang divalidasi. Dalam kasus ini, Anda memiliki alamat yang dapat dikirim, tetapi lebih memilih keyakinan yang lebih besar bahwa alamat yang dihasilkan adalah alamat yang dimaksud oleh pelanggan.
Kolom berikut dari respons Address Validation API dapat digunakan selain
verdict.possibleNextAction
untuk menentukan apakah alamat memiliki masalah kecil,
dan apa masalah tersebut.
Perincian validasi | Jika validationGranularity untuk alamat adalah
ROUTE atau PREMISE_PROXIMITY , alamat mungkin
salah.
|
---|---|
Data yang disimpulkan | Jika kolom hasInferredComponents adalah true ,
Anda tahu bahwa API mengisi informasi yang diperoleh dari komponen alamat
lainnya.
|
Data yang diganti | Jika kolom hasReplacedComponents adalah true , API akan mengganti data yang dimasukkan dengan data yang dianggapnya membuat alamat valid.
|
Koreksi ejaan | Jika kolom hasSpellCorrectedComponents adalah true ,
API akan memperbaiki ejaan beberapa komponen yang salah eja.
|
Sinyal ACCEPT
Anda dapat menerima alamat jika respons API Address Validation API memberikan tingkat keyakinan yang tinggi bahwa alamat dapat dikirim dan dapat digunakan tanpa interaksi pelanggan lebih lanjut dalam proses downstream.
Kolom berikut dari respons Address Validation API dapat digunakan selain
verdict.possibleNextAction
untuk menentukan apakah alamat memiliki kualitas
yang dapat diterima.
Perincian validasi | validationGranularity dari PREMISE sering kali
dapat diterima, meskipun nilai ROUTE mungkin masih menunjukkan
alamat yang dapat dikirim.
|
---|---|
Tidak ada data yang disimpulkan | Jika kolom hasInferredComponents adalah false ,
Anda tahu bahwa tidak ada komponen dalam output yang disimpulkan.
|
Tidak ada data yang diganti | Jika kolom hasReplacedComponents adalah false ,
Anda tahu bahwa tidak ada data input yang telah diganti.
|
Tidak ada koreksi ejaan | Jika kolom hasSpellCorrectedComponents adalah false ,
Anda tahu bahwa tidak ada koreksi ejaan yang telah dilakukan.
|
Konfirmasi DPV USPS | Jika uspsData.dpvConfirmation adalah Y , berarti alamat telah dicocokkan dengan alamat di database USPS. Kolom
ini hanya tersedia untuk alamat AS. Untuk mengetahui detail selengkapnya tentang
uspsData.dpvConfirmation , lihat
Menangani alamat Amerika Serikat.
|