Membuat logika validasi

Dokumen ini menjelaskan proses untuk membangun sistem pemeriksaan alamat guna menangani berbagai respons dari Address Validation API. Bagian ini membahas cara menafsirkan respons API untuk menentukan kapan dan bagaimana cara meminta informasi lebih lanjut dari pelanggan Anda.

Secara umum, respons API menentukan cara berikut yang harus dilakukan sistem Anda untuk menangani alamat:

• Perbaiki—alamat mungkin berisi masalah signifikan.
  Pertimbangkan untuk meminta informasi lebih lanjut kepada pelanggan Anda.
• Tambahkan sublokasi—alamat mungkin tidak memiliki sublokasi.
  Pertimbangkan untuk meminta pelanggan menambahkan nomor unit.
• Konfirmasi—alamat mungkin berisi masalah kecil.
  Pertimbangkan untuk meminta pelanggan Anda mengonfirmasi bahwa alamat sudah benar.
• Terima—alamat mungkin tidak berisi masalah.
  Pertimbangkan untuk menggunakan alamat tanpa meminta lagi, dengan risiko Anda sendiri.

Tujuan utama

Dokumen ini membantu Anda mengubah sistem untuk menganalisis respons API dengan sebaik-baiknya dan menentukan tindakan selanjutnya yang harus 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 Anda untuk mengetahui detail selengkapnya.

Contoh alur kerja

Tabel di bawah merangkum contoh alur kerja yang dapat Anda terapkan untuk memicu pelanggan berdasarkan respons API.

Perilaku sistem Anda
Perbaiki alamat	Respons dari verdict menunjukkan bahwa mungkin ada masalah signifikan dengan alamat tersebut. Misalnya, verdict.possibleNextAction adalah FIX. Pertimbangkan untuk meminta informasi lebih lanjut kepada pelanggan Anda. Alur kerja Selidiki komponen alamat jika perlu. Mendorong pelanggan untuk memperbaiki masalah alamat. Minta validasi untuk alamat yang diperbarui. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui. Lanjutkan dengan alamat.
Menambahkan sub-lokasi	Respons dari verdict menunjukkan bahwa alamat mungkin tidak memiliki sub-lokasi. Misalnya, verdict.possibleNextAction adalah CONFIRM_ADD_SUBPREMISES. Pertimbangkan untuk meminta pelanggan Anda menambahkan nomor unit. Alur kerja Minta pelanggan untuk menambahkan nomor unit. Minta validasi untuk alamat yang diperbarui. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui. Lanjutkan dengan alamat.
Konfirmasi alamat	Respons dari verdict menunjukkan bahwa mungkin ada masalah kecil dengan alamat tersebut. Misalnya, verdict.possibleNextAction adalah CONFIRM. Pertimbangkan untuk meminta pelanggan meninjau alamat. Alur kerja Koreksi yang diperlukan: Selidiki komponen alamat jika perlu. Minta validasi untuk alamat yang diperbarui. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui. Lanjutkan dengan alamat. Tidak perlu koreksi: (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui. Lanjutkan dengan alamat.
Terima alamat	Respons dari verdict menunjukkan bahwa mungkin tidak ada masalah dengan alamat. Misalnya, verdict.possibleNextAction adalah ACCEPT. Pertimbangkan untuk melanjutkan penggunaan alamat tersebut sebagaimana yang Anda lakukan untuk tingkat risiko Anda. Alur kerja Lanjutkan dengan alamat yang dikembalikan.

Catatan: Saat mengulangi permintaan ke Address Validation API untuk alamat yang sama, Anda dapat melakukan panggilan ke provideValidationFeedback untuk menunjukkan hasil Anda. Lihat Menangani alamat yang diupdate.

Coba demo. Bagian selanjutnya dari dokumen ini menggunakan berbagai contoh untuk membantu Anda memahami proses alur perbaikan, konfirmasi, dan penerimaan yang dijelaskan di atas. Anda dapat menjelajahi hasil dari contoh ini dengan memasukkannya di demo Address Validation API.

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 Anda dapat mengembangkan logika kustom sendiri untuk menafsirkan respons API guna menentukan apakah dan bagaimana Anda ingin memunculkan perintah kepada 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 selanjutnya, sinyal tambahan yang dijelaskan di bawah masih dapat membantu Anda memahami detail tentang potensi masalah terkait 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 ingatlah 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 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 akurasi alamat yang lebih tinggi, Anda dapat meminta pengguna. Untuk contoh yang dapat termasuk dalam salah satu kategori, lihat Nomor jalan yang tidak dikonfirmasi di luar AS di Terima 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 di sistem, seperti untuk konstruksi baru.

Contoh alur pembayaran yang menghindari risiko

Jika ingin mengurangi risiko pengiriman gagal, Anda dapat menyesuaikan logika untuk lebih sering meminta pelanggan. Misalnya, daripada menggunakan logika yang dijelaskan di bagian Tujuan utama, 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 pembayaran dengan hambatan rendah

Jika ingin mengurangi hambatan dalam alur checkout, Anda dapat menyesuaikan logika untuk meminta pelanggan lebih jarang. Misalnya, daripada menggunakan logika yang dijelaskan di bagian Tujuan utama, 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 digunakan untuk pengiriman. Sistem Anda kemudian dapat meminta pelanggan untuk memberikan informasi yang diperlukan, setelah itu Anda menerbitkan ulang alur kerja untuk mendapatkan alamat pengiriman.

Kolom berikut dari respons Address Validation API dapat digunakan selain verdict.possibleNextAction untuk menentukan apakah alamat memiliki masalah besar, dan apa saja masalah tersebut.

Perincian validasi	Jika enum perincian validasi untuk alamat adalah OTHER, kemungkinan alamat tersebut salah.
Komponen tidak ada	Jika address.missingComponentTypes tidak kosong, kemungkinan alamat tidak memiliki informasi penting.
Komponen 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 alamatnya. Kolom ini hanya tersedia untuk alamat AS. Untuk mengetahui detail selengkapnya tentang uspsData.dpvConfirmation, lihat Menangani alamat Amerika Serikat.

Contoh perbaikan alamat

Sinyal CONFIRM_ADD_SUBPREMISES (khusus alamat Amerika Serikat)

Anda meminta pelanggan untuk meninjau alamat dan mempertimbangkan untuk menambahkan nomor unit jika respons Address Validation API menunjukkan bahwa alamat mungkin tidak memiliki sub-lokasi. Dalam kasus ini, alamat bangunan kemungkinan valid, tetapi Anda ingin lebih yakin bahwa alamat yang dihasilkan adalah alamat yang diinginkan oleh pelanggan.

Kolom berikut dalam respons Address Validation API dapat digunakan selain verdict.possibleNextAction untuk menentukan apakah alamat kemungkinan tidak memiliki sub-lokasi.

Missing subpremise component	Jika kolom address.missingComponentTypes berisi nilai subpremise, hal itu menunjukkan bahwa nomor unit tidak ada dalam alamat. Catatan: Jika kolom berisi jenis selain subpremise, tindakan akan termasuk dalam kategori PERBAIKAN. Lihat daftar lengkap jenis komponen dalam dokumentasi Geocoding.
Konfirmasi DPV USPS	Jika uspsData.dpvConfirmation adalah S, itu berarti nomor utama alamat telah dicocokkan dengan alamat dalam database USPS. Namun, alamat diharapkan berisi nomor sekunder juga. Kolom ini hanya tersedia untuk alamat di Amerika Serikat. Untuk mengetahui detail selengkapnya tentang uspsData.dpvConfirmation, lihat Menangani alamat Amerika Serikat.

Contoh alamat sub-lokasi

Sinyal KONFIRMASI

Anda mengonfirmasi alamat saat hasil menunjukkan bahwa Address Validation API menyimpulkan atau mengubah 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 dimaksudkan oleh pelanggan.

Kolom berikut dalam respons Address Validation API dapat digunakan selain verdict.possibleNextAction untuk menentukan apakah alamat memiliki masalah kecil, dan apa saja masalah tersebut.

Perincian validasi	Jika validationGranularity untuk alamat adalah ROUTE atau PREMISE_PROXIMITY, alamat tersebut mungkin salah.
Data yang disimpulkan	Jika kolom hasInferredComponents adalah true, Anda tahu bahwa API mengisi informasi yang dikumpulkan dari komponen alamat lainnya.
Data yang diganti	Jika kolom hasReplacedComponents adalah true, maka API mengganti data yang dimasukkan dengan data yang dianggap membuat alamat valid.
Koreksi ejaan	Jika kolom hasSpellCorrectedComponents adalah true, API akan mengoreksi ejaan beberapa komponen yang salah eja.

Contoh konfirmasi alamat

Sinyal SETUJU

Anda dapat menerima alamat jika respons API Address Validation API memberikan tingkat keyakinan yang tinggi bahwa alamat tersebut dapat digunakan untuk pengiriman dan dapat digunakan tanpa interaksi pelanggan lebih lanjut dalam proses hilir.

Catatan: Pertimbangkan tingkat risiko Anda saat memutuskan apakah akan menerima alamat atau meminta informasi lebih lanjut kepada pelanggan Anda.

Kolom berikut dari respons Address Validation API dapat digunakan selain verdict.possibleNextAction untuk menentukan apakah kualitas alamat dapat diterima.

Perincian validasi	validationGranularity PREMISE sering kali dapat diterima, meskipun nilai ROUTE masih dapat 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 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 dalam database USPS. Kolom ini hanya tersedia untuk alamat di Amerika Serikat. Untuk mengetahui detail selengkapnya tentang uspsData.dpvConfirmation, lihat Menangani alamat Amerika Serikat.

Contoh alamat yang diterima