Doğrulama mantığınızı oluşturun

Bu belgede, Adres Doğrulama API'sinden gelen çeşitli yanıtları işlemek için bir adres kontrol sistemi oluşturma süreci açıklanmaktadır. Müşterilerinizden daha fazla bilgi istemek için ne zaman ve nasıl istem oluşturacağınızı belirlemek amacıyla API yanıtını nasıl yorumlayacağınız açıklanır.

Genel olarak API yanıtı, sisteminizin bir adresi aşağıdaki şekillerde işlemesi gerektiğini belirler:

• Düzeltin: Adreste önemli sorunlar olabilir.
  Müşterinizden daha fazla bilgi istemeyi deneyin.
• Alt birim ekleyin: Adreste alt birim eksik olabilir.
  Müşterinizden birim numarası eklemesini isteyebilirsiniz.
• Onayla: Adreste küçük sorunlar olabilir.
  Müşterinizden adresin doğru olduğunu onaylamasını isteyebilirsiniz.
• Kabul et: Adres sorun içermeyebilir.
  Adresi daha fazla istemde bulunmadan, kendi sorumluluğunuzda kullanmayı düşünebilirsiniz.

Temel amaç

Bu belge, sisteminizi API yanıtını en iyi şekilde analiz edecek ve sağlanan adreslerle ilgili sonraki işlemleri belirleyecek şekilde değiştirmenize yardımcı olur. Aşağıdaki sözde kodda olası bir akış gösterilmektedir.

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.

Tam mantık, durumunuza bağlıdır. Daha fazla bilgi için Doğrulama mantığınızı özelleştirme başlıklı makaleyi inceleyin.

Örnek iş akışları

Aşağıdaki tabloda, API yanıtına göre müşterinize istem göndermek için uygulayabileceğiniz örnek iş akışları özetlenmektedir.

Sistem davranışınız
Adresi düzeltin.	verdict yanıtı, adreste önemli sorunlar olabileceğini gösterir. Örneğin, verdict.possibleNextAction, FIX'dir. Müşterinizden daha fazla bilgi istemeyi deneyin. İş akışı Gerekirse adres bileşenlerini inceleyin. Müşteriden adres sorunlarını düzeltmesini isteme Güncellenen adres için doğrulama isteğinde bulunun. (İsteğe bağlı) API için geri bildirim uç noktasına istek gönderin. Güncellenen adresleri işleme başlıklı makaleyi inceleyin. Adresle devam edin.
Alt tesis ekleme	verdict'dan gelen yanıt, adreste alt birim eksik olabileceğini gösteriyor. Örneğin, verdict.possibleNextAction CONFIRM_ADD_SUBPREMISES olur. Müşterinizden birim numarası eklemesini isteyebilirsiniz. İş akışı Müşteriden birim numarası eklemesini isteme Güncellenen adres için doğrulama isteğinde bulunun. (İsteğe bağlı) API için geri bildirim uç noktasına istek gönderin. Güncellenen adresleri işleme başlıklı makaleyi inceleyin. Adresle devam edin.
Adresi onaylayın.	verdict yanıtı, adreste küçük sorunlar olabileceğini gösteriyor. Örneğin, verdict.possibleNextAction CONFIRM olur. Müşterinizden adresi incelemesini isteyebilirsiniz. İş akışı Düzeltme gerekiyor: Gerekirse adres bileşenlerini inceleyin. Güncellenen adres için doğrulama isteğinde bulunun. (İsteğe bağlı) API için geri bildirim uç noktasına istek gönderin. Güncellenen adresleri işleme başlıklı makaleyi inceleyin. Adresle devam edin. Düzeltme gerekmiyor: (İsteğe bağlı) API için geri bildirim uç noktasına istek gönderin. Güncellenen adresleri işleme başlıklı makaleyi inceleyin. Adresle devam edin.
Adresi kabul et	verdict'dan gelen yanıt, adreste sorun olmayabileceğini gösteriyor. Örneğin, verdict.possibleNextAction ACCEPT olur. Adresle ilgili işlemlere risk düzeyinize göre devam edebilirsiniz. İş akışı İade edilen adresle devam edin.

Not: Aynı adres için Adres Doğrulama API'sine istekleri tekrarladığınızda, sonucu belirtmek için provideValidationFeedback numaralı telefonu arayabilirsiniz. Güncellenen adresleri işleme başlıklı makaleyi inceleyin.

Demoyu deneyin. Bu belgenin geri kalanında, yukarıda açıklanan düzeltme, onaylama ve kabul etme akışı sürecini anlamanıza yardımcı olmak için çeşitli örnekler verilmektedir. Bu örnekleri Address Validation API demosunda girerek sonuçları inceleyebilirsiniz.

Doğrulama mantığınızı özelleştirme

Sisteminizin API yanıtıyla nasıl devam edeceğini belirlemek için verdict.possibleNextAction alanındaki sonuçları kullanabilirsiniz. Bununla birlikte, işletmeye özgü ihtiyaçları karşılamak gibi özel bir mantık oluşturmayı da düşünebilirsiniz.

Bu bölümün amacı, müşterinize istem göndermek isteyip istemediğinizi ve nasıl istem göndereceğinizi belirlemek için API yanıtını yorumlamaya yönelik kendi özel mantığınızı nasıl geliştirebileceğinizi göstermektir. Bu bölümde, risk seviyeleri ve özelleştirme için dikkate alınması gereken ek API yanıt sinyalleri ele alınmaktadır.

Bununla birlikte, bir sonraki adımlarınıza karar vermek için yalnızca verdict.possibleNextAction simgesini kullanıyor olsanız bile, aşağıda açıklanan ek sinyaller adresle ilgili olası sorunlar hakkında ayrıntılı bilgi edinmenize yardımcı olabilir.

Risk toleransı

Sisteminizin Adres Doğrulama API'sinden gelen sinyallere nasıl yanıt vereceğini tasarlarken aşağıdaki öneriler daha etkili bir yanıt modeli oluşturmanıza yardımcı olabilir. Ancak bunlar yalnızca öneri olduğundan uygulamanızın iş modelinize uygun olması gerektiğini unutmayın.

	Yönergeler	Ayrıntılar
Risk düzeyi	Düzeltme isteme ve girilen adresi kabul etme arasında denge kurarken durumunuzla ilgili tolerans seviyesini göz önünde bulundurun.	Adres Doğrulama API'si, doğrulama sürecinizi optimize etmek için risk düzeyinize dahil edebileceğiniz çeşitli sinyaller döndürür. Örneğin, bir adresin onaylanmamış bir sokak numarası varsa yine de kabul edebilirsiniz. Öte yandan, işletme faaliyetiniz daha fazla adres hassasiyeti gerektiriyorsa kullanıcınızdan bunu yapmasını isteyebilirsiniz. Her iki kategoriye de girebilecek bir örnek için Adresi kabul etme - örnekler bölümündeki ABD dışı onaylanmamış sokak numarası'na bakın.
Adresleri kabul etme	Müşteri istemlere yanıt vermezse sisteminizin orijinal girişi kabul etmesine izin vermek iyi bir uygulamadır.	Bu gibi durumlarda müşteri, sistemde bulunmayan bir adres (ör. yeni bir inşaat) girmiş olabilir.

Riskten kaçınan ödeme akışı örneği

Teslimat hataları riskini azaltmak istiyorsanız müşterilerinize daha sık istem göndermek için mantığınızı özelleştirebilirsiniz. Örneğin, Temel amaç bölümünde açıklanan mantığı kullanmak yerine aşağıdaki mantığı kullanabilirsiniz.

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.

Kolay ödeme akışı örneği

Ödeme akışınızdaki sürtünmeyi azaltmak istiyorsanız müşterilerinize daha az sıklıkta istem göstermek için mantığınızı özelleştirebilirsiniz. Örneğin, Temel amaç bölümünde açıklanan mantığı kullanmak yerine aşağıdaki mantığı kullanabilirsiniz.

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.

FIX sinyalleri

Sonuçlar, adresin teslim edilemeyebileceğini açıkça gösterdiğinde adresi düzeltin. Ardından sisteminiz, müşteriden gerekli bilgileri sağlamasını isteyebilir. Bu işlemden sonra, teslimat adresi almak için iş akışınızı yeniden yayınlarsınız.

Bir adreste büyük sorunlar olup olmadığını ve bu sorunların neler olduğunu belirlemek için verdict.possibleNextAction'ya ek olarak Address Validation API yanıtının aşağıdaki alanları kullanılabilir.

Doğrulama ayrıntı düzeyi	Bir adresin doğrulama ayrıntı düzeyi numaralandırması OTHER olduğunda adresin yanlış olması muhtemeldir.
Eksik bileşenler	address.missingComponentTypes boş olmadığında adresin önemli bilgilerinin eksik olması muhtemeldir.
Şüpheli bileşenler	Bir bileşenin onay düzeyi numaralandırması UNCONFIRMED_AND_SUSPICIOUS olduğunda bileşen büyük olasılıkla yanlıştır.
Çözümlenmemiş bileşenler	unresolvedToken, girişin geçerli bir adres bölümü olarak tanınmayan kısmıdır.
USPS DPV Onayı	uspsData.dpvConfirmation, N veya boş olduğunda adreste bir sorun olabilir. Bu alan yalnızca ABD adresleri için kullanılabilir. uspsData.dpvConfirmation hakkında daha fazla bilgi için ABD adreslerini işleme başlıklı makaleyi inceleyin.

Düzeltilmiş adres örnekleri

CONFIRM_ADD_SUBPREMISES sinyalleri (yalnızca ABD adresleri)

Adres Doğrulama API'si yanıtı, adreste bir alt tesisin eksik olabileceğini gösterdiğinde müşterinizden adresi incelemesini ve bir birim numarası eklemeyi düşünmesini istersiniz. Bu durumlarda, binanın adresi muhtemelen geçerlidir ancak sonuçtaki adresin müşteri tarafından amaçlanan adres olduğundan daha fazla emin olmak istersiniz.

Bir adreste alt tesisin eksik olup olmadığını belirlemek için Adres Doğrulama API yanıtının aşağıdaki alanları verdict.possibleNextAction'ya ek olarak kullanılabilir.

Missing subpremise component	address.missingComponentTypes alanı subpremise değerini içerdiğinde adreste daire numarasının eksik olduğu anlaşılır. Not: Alan, subpremise dışında türler içeriyorsa işlem DÜZELTME kategorisine girer. Bileşen türlerinin tam listesini Coğrafi Kodlama dokümanlarında bulabilirsiniz.
USPS DPV Onayı	uspsData.dpvConfirmation S olduğunda, adresin birincil numarasının USPS veritabanındaki bir adresle eşleştiği anlamına gelir. Ancak adresin ikincil bir numara da içermesi bekleniyordu. Bu alan yalnızca ABD adresleri için kullanılabilir. uspsData.dpvConfirmation hakkında daha fazla bilgi için ABD adreslerini işleme başlıklı makaleyi inceleyin.

Alt tesis adresi ekleme örnekleri

CONFIRM sinyalleri

Karar, Adres Doğrulama API'sinin doğrulanmış bir adres oluşturmak için adres bileşenlerini tahmin ettiğini veya bu bileşenlerde değişiklik yaptığını gösterdiğinde adresi onaylarsınız. Bu gibi durumlarda, teslim edilebilir bir adresiniz vardır ancak sonuçtaki adresin müşteri tarafından amaçlanan adres olduğundan daha fazla emin olmak istersiniz.

Adres Doğrulama API yanıtının aşağıdaki alanları, bir adreste küçük sorunlar olup olmadığını ve bu sorunların neler olduğunu belirlemek için verdict.possibleNextAction'ya ek olarak kullanılabilir.

Doğrulama ayrıntı düzeyi	Bir adres için validationGranularity değeri ROUTE veya PREMISE_PROXIMITY olduğunda adres yanlış olabilir.
Tahmin edilen veriler	hasInferredComponents alanı true olduğunda API'nin, diğer adres bileşenlerinden elde ettiği bilgileri doldurduğunu anlarsınız.
Değiştirilen veriler	hasReplacedComponents alanı true olduğunda API, girilen verileri adresi geçerli kılmak için uygun gördüğü verilerle değiştirir.
Yazım düzeltmeleri	hasSpellCorrectedComponents alanı true olduğunda API, yazımı yanlış olan bazı bileşenlerin yazımını düzeltti.

Adres örneklerini onaylama

ACCEPT sinyalleri

Adres Doğrulama API'si API yanıtı, adresin teslim edilebilir olduğuna ve sonraki süreçte başka müşteri etkileşimi olmadan kullanılabileceğine dair yüksek düzeyde güven sağladığında adresi kabul edebilirsiniz.

Not: Bir adresi kabul edip etmeyeceğinize veya müşterinizden daha fazla bilgi isteyip istemeyeceğinize karar verirken risk seviyenizi göz önünde bulundurun.

Adresin kabul edilebilir kalitede olup olmadığını belirlemek için verdict.possibleNextAction'ya ek olarak Adres Doğrulama API yanıtının aşağıdaki alanları kullanılabilir.

Doğrulama ayrıntı düzeyi	validationGranularity PREMISE değeri genellikle kabul edilebilir olsa da ROUTE değeri, teslim edilebilir bir adresi gösterebilir.
Çıkarım yapılan veri yok	hasInferredComponents alanı false olduğunda, çıkıştaki hiçbir bileşenin çıkarılmadığını anlarsınız.
Değiştirilen veri yok	hasReplacedComponents alanı false olduğunda giriş verilerinin değiştirilmediğini anlarsınız.
Yazım düzeltmesi yok	hasSpellCorrectedComponents alanı false olduğunda yazım düzeltmesi yapılmadığını anlarsınız.
USPS DPV Onayı	uspsData.dpvConfirmation Y olduğunda, adresin USPS veritabanındaki bir adresle eşleştiği anlamına gelir. Bu alan yalnızca ABD adresleri için kullanılabilir. uspsData.dpvConfirmation hakkında daha fazla bilgi için ABD adreslerini işleme başlıklı makaleyi inceleyin.

Kabul edilen adres örnekleri