Membuat logika validasi

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:

  • Perbaiki—alamat mungkin berisi masalah yang signifikan.
    Pertimbangkan untuk meminta informasi selengkapnya kepada pelanggan Anda.
  • Tambahkan sub-lokasi—alamat mungkin tidak memiliki sub-lokasi.
    Pertimbangkan untuk meminta pelanggan menambahkan nomor unit.
  • Konfirmasi—alamat mungkin berisi masalah kecil.
    Pertimbangkan untuk meminta pelanggan mengonfirmasi bahwa alamatnya sudah benar.
  • Terima—alamat mungkin tidak berisi masalah.
    Pertimbangkan untuk menggunakan alamat tersebut tanpa permintaan lebih lanjut, dengan risiko Anda sendiri.

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 verdict menunjukkan bahwa mungkin ada masalah signifikan pada alamat. Misalnya, verdict.possibleNextAction adalah FIX. Pertimbangkan untuk meminta informasi selengkapnya kepada pelanggan Anda.

Alur kerja

  1. Selidiki komponen alamat jika perlu.
  2. Minta pelanggan untuk memperbaiki masalah alamat.
  3. Minta validasi untuk alamat yang diperbarui.
  4. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui.
  5. Lanjutkan dengan alamat.
Tambahkan sub-lokasi

Respons dari verdict menunjukkan bahwa alamat mungkin tidak memiliki sub-lahan. Misalnya, verdict.possibleNextAction adalah CONFIRM_ADD_SUBPREMISES. Pertimbangkan untuk meminta pelanggan menambahkan nomor unit.

Alur kerja

  1. Minta pelanggan untuk menambahkan nomor unit.
  2. Minta validasi untuk alamat yang diperbarui.
  3. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui.
  4. Lanjutkan dengan alamat.
Konfirmasi alamat

Respons dari verdict menunjukkan bahwa mungkin ada masalah kecil pada alamat. Misalnya, verdict.possibleNextAction adalah CONFIRM. Sebaiknya minta pelanggan Anda untuk meninjau alamat.

Alur kerja

  1. Koreksi yang diperlukan:
    1. Selidiki komponen alamat jika perlu.
    2. Minta validasi untuk alamat yang diperbarui.
    3. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui.
    4. Lanjutkan dengan alamat.
  2. Tidak perlu koreksi:
    1. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Lihat Menangani alamat yang diperbarui.
    2. Lanjutkan dengan alamat.
Terima alamat

Respons dari verdict menunjukkan bahwa mungkin tidak ada masalah dengan alamat. Misalnya, verdict.possibleNextAction adalah ACCEPT. Pertimbangkan untuk melanjutkan dengan alamat tersebut seperti yang Anda lakukan untuk tingkat risiko.

Alur kerja

Lanjutkan dengan alamat yang ditampilkan.

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.

Contoh alamat perbaikan

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.

Contoh konfirmasi alamat

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.

Contoh alamat yang disetujui