17TRACK Fulfillment ve İade Entegrasyonu için USPS API Dokümantasyon Kontrol Listesi

USPS ile 17TRACK arasında güvenilir bir entegrasyon, birbirine bağlı ancak ayrı iki iş akışı olarak planlanmalıdır: USPS belgeleri taşıyıcıya yönelik verileri ve hizmetleri yönetirken, 17TRACK taşıyıcılar arasında gönderi görünürlüğü için daha kapsamlı bir takip katmanı sağlayabilir. Gerçekleştirme ve iadeler için uygulama ekibi, üretim kodunu yazmadan önce kimlik doğrulama, gönderi tanımlayıcıları, olay eşleme, ücret ve etiket sorumlulukları, yoklama veya bildirim davranışı, hata yönetimi ve giden teslimat ile tersine lojistik arasındaki sınırları doğrulamalıdır.

Bu kontrol listesi, USPS ile ilgili gönderi verilerini bir sipariş yönetim sistemine, depo iş akışına, müşteriye yönelik takip deneyimine veya iade sürecine bağlayan geliştiriciler, e-ticaret operasyon ekipleri ve çözüm sahipleri için hazırlanmıştır. Bu liste, her USPS API yeteneğinin 17TRACK üzerinden kullanılabildiğini veya bir takip API'sinin kendi başına etiket oluşturduğunu, posta ücreti satın aldığını ya da fiziksel iadeleri yönettiğini varsaymaz.

1. Önce entegrasyon sınırını tanımlayın

Her sistemin ne yapmasının beklendiğini belgeleyerek başlayın. USPS belgeleri, USPS hizmetlerini ve onaylı bir entegratör için kullanılabilir arayüzleri açıklar. Uygulamanın taşıyıcıdan bağımsız bir takip iş akışına veya gönderi olayları için tek bir arayüze ihtiyaç duyduğu durumlarda 17TRACK'in Tracking API documentation belgesi ilgilidir. Proje ayrıca e-ticaret iadeleri yönetimini de içeriyorsa 17RETURNS product page ilgilidir. Bunlar ilişkili kullanım alanlarıdır, ancak birbirlerinin yerine kullanılamazlar.

• USPS: takip, adres hizmetleri, fiyatlandırma, hizmet bilgileri veya belgelenmiş diğer API'ler gibi taşıyıcıya yönelik hangi işlevlerin gerekli olduğunu doğrulayın.
• 17TRACK Tracking API: USPS takip numaralarının nasıl gönderildiğini, sorgulandığını, güncellendiğini ve uygulamanın normalize edilmiş olay modelinde nasıl temsil edildiğini doğrulayın.
• Gerçekleştirme platformu: envanter tahsisi, siparişin serbest bırakılması, etiket oluşturma, posta ücreti satın alma, depo onayı ve gönderi oluşturma işlemlerinden sorumlu sistemi belirleyin.
• İade iş akışı: iadeyi kimin onayladığını, iade talimatlarını veya etiketlerini kimin oluşturduğunu, iade edilen paketi kimin kaydettiğini ve geri ödeme veya değişim sonucuna kimin karar verdiğini tanımlayın.

Bu nedenle ilk mimari karar “hangi uç noktayı çağırmalıyız?” değil, “her iş eyleminin sahibi hangi sistem?” sorusudur. Bir taşıyıcı takip API'si, gerçekleştirme veya iadeler için kayıt sistemi olmadan görünürlüğü artırabilir.

2. Güncel USPS geliştirici belgelerini doğrulayın

USPS Web Tools and APIs information sayfasını başlangıç noktası olarak kullanın, ardından USPS tarafından bağlantısı verilen güncel geliştirici belgelerini ve ürüne özel referansları takip edin. Güncel durumunu kontrol etmeden eski bir kod örneğindeki uç noktayı, kimlik doğrulama yöntemini, alan adını veya kullanımdan kaldırma bildirimini kopyalamaktan kaçının.

Uygulamadan önce aşağıdaki belge bilgilerini bir proje kaydında toplayın:

• Gerekli USPS API ürününün veya ürünlerinin tam adı.
• Test ve üretim için güncel temel URL ve ortam ayrıntıları.
• Kayıt süreci, uygulama kimlik bilgileri ve bu kimlik bilgilerinin izin verilen kullanımı.
• Seçilen API için belgelenmişse kimlik doğrulama akışı, belirteç ömrü, kapsamlar ve kimlik bilgisi yenileme gereklilikleri.
• Gerekli üstbilgiler, içerik türleri, istek biçimleri, yanıt biçimleri ve sürüm tanımlayıcıları.
• Desteklenen işlemler ve hesap, hizmet, coğrafya veya veri türüne dayalı kısıtlamalar.
• Hız sınırları, zaman aşımı yönergeleri, bakım bildirimleri ve belgelenmiş hata yanıtları.
• USPS yanıt verilerinin depolanmasını, görüntülenmesini, yeniden kullanılmasını ve dağıtılmasını düzenleyen şartlar.

Bir gereklilik resmi belgelerde belirtilmemişse USPS veya ilgili hesap temsilcisiyle doğrudan doğrulanmak üzere işaretleyin. Eski bir USPS Web Tools örneğinin güncel API'yi temsil ettiğini varsaymayın ve bir USPS ürününde açıklanan bir işlevin başka bir üründe de mevcut olduğunu varsaymayın.

3. Kimlik doğrulama ve güvenlik kontrol listesi oluşturun

Kimlik doğrulama, iş mantığından ayrı olarak test edilmelidir. Ekip, uygulama kodunu değiştirmeden veya ilgisiz takip işlevlerini kesintiye uğratmadan kimlik bilgilerini iptal edip değiştirebilmelidir.

1. İstemci sırlarını, API anahtarlarını, belirteçleri ve sertifikaları kaynak kodu veya istemci tarafı uygulama yerine yönetilen bir gizli bilgi deposunda saklayın.
2. Seçilen USPS API'sinin güncel belgelerde açıklanan kimlik doğrulama yöntemini kullanıp kullanmadığını doğrulayın. Belirteç istekleri, kapsamlar, süre sonu ve yenileme veya yeniden yetkilendirme davranışı dahil olmak üzere belgelenen akışı tam olarak uygulayın.
3. USPS izin veriyorsa ayrı kimlik bilgileri veya ortamlar kullanın; böylece test trafiği üretim trafiğiyle karıştırılmaz.
4. Müşteri adresi verilerine, gönderi verilerine ve iade bilgilerine erişimi, bu verilere ihtiyaç duyan rollere göre sınırlandırın.
5. Kimlik bilgilerini ve gereksiz kişisel bilgileri uygulama günlüklerinden maskeleyin.
6. Kimlik doğrulama hatalarını bir korelasyon tanımlayıcısıyla kaydedin, ancak gizli bilgileri veya hassas yüklerin tamamını günlüğe yazmaktan kaçının.
7. Bir belirtecin süresi dolduğunda, kimlik bilgisi iptal edildiğinde, istek yeniden oynatıldığında veya kimlik doğrulama hizmeti geçici olarak kullanılamadığında oluşan davranışı test edin.

Bir 17TRACK entegrasyonu için, ilgili belgeler açıkça başka bir düzen tanımlamadıkça taşıyıcı kimlik bilgilerini ve 17TRACK kimlik bilgilerini kavramsal olarak ayrı tutun. 17TRACK üzerinden yönlendirilen bir takip isteğinin USPS posta ücreti, hesap veya etiket hizmetlerine erişim sağladığı varsayılmamalıdır.

4. Tanımlayıcıları ve veri sahipliğini doğrulayın

Gönderi kimliği, yinelenen siparişlerin ve bozulan iade bağlantılarının sık rastlanan bir kaynağıdır. Sistemleri bağlamadan önce bir alan eşlemesi oluşturun. En azından aşağıdaki değerleri birbirinden ayırın:

Mümkün olduğunda orijinal taşıyıcı olayını ve normalize edilmiş dahili durumu koruyun. “Taşımada” gibi normalize edilmiş bir durum mağazalar için yararlıdır, ancak operasyon ekipleri inceleme amacıyla orijinal USPS olay metnine, konumuna ve olay zamanına yine de ihtiyaç duyabilir.

5. Takip verisi alımını ve durum eşlemesini tasarlayın

Canlı trafiğe bağlanmadan önce işletmenin gerçekten ihtiyaç duyduğu yaşam döngüsü durumlarını listeleyin. Yaygın durumlar arasında etiket oluşturuldu, kabul edildi, taşımada, dağıtıma çıktı, teslim edildi, teslimat istisnası ve gönderene iade bulunabilir. Kesin USPS olay sözlüğü ve 17TRACK üzerinden sunulan olaylar, ilgili belgelerde ve test yanıtlarında doğrulanmalıdır; yalnızca durum adlarından eşleme oluşturmayın.

Her olay için şunları tanımlayın:

• Kaynak sistem ve orijinal olay kodu veya açıklaması.
• Normalize edilmiş dahili durum.
• Olayın müşteriye görünür, yalnızca operasyonlara özel veya her ikisi olup olmadığı.
• Siparişi ilerletip ilerletemeyeceği, bir SLA'yı duraklatıp duraklatmayacağı, bildirim tetikleyip tetiklemeyeceği veya istisna vakası açıp açmayacağı.
• Daha sonraki bir olayın bunu düzeltebilecek veya geçersiz kılabilecek olup olmadığı.
• Yinelenen ve sıra dışı gelen olayların nasıl işleneceği.

Yeni takip numaralarının sisteme nasıl gireceğine de karar verin. Bir gönderi, ilk taşıyıcı taraması görünmeden önce oluşturulabilir. Uygulamanız “takip numarası kaydedildi” durumunu “taşıyıcı paketi kabul etti” durumundan ayırmalıdır; taranmamış bir gönderiyi ağda hareket etmeye başlamış gibi göstermemelidir.

6. Yoklama ve bildirimler arasında karar verin

Uygulama, yeni takip bilgilerinin nasıl alınacağını belgelemelidir. Seçilen USPS veya 17TRACK ürünü bir bildirim mekanizmasını destekliyorsa abonelik modelini, teslim biçimini, yeniden deneme davranışını, imzalama veya doğrulama yöntemini ve sınırlarını resmi belgelerde doğrulayın. Yoklama gerekiyorsa aralığı, durma koşullarını, geri çekilme stratejisini ve yeni olayı olmayan gönderilerin nasıl ele alınacağını tanımlayın.

Bir müşteri takip sayfasını yeniledi diye aşırı sıklıkta yoklama yapmayın. Uygun olduğunda sunucu tarafında bir olay deposu veya önbellek kullanın, geçici hatalar için üstel geri çekilme uygulayın ve veri alımını idempotent hâle getirin. Başarısız bir istek ikinci bir gönderi, ikinci bir iade veya yinelenen müşteri bildirimi oluşturmamalıdır.

Operasyonel uyarılar kimlik doğrulama hatalarını, sürekli hız sınırı yanıtlarını, hatalı biçimlendirilmiş taşıyıcı yanıtlarını, olay işleme hatalarını ve çözümlenmeden kalan gönderilerdeki artışı kapsamalıdır. İzleme hem API sağlığını hem de iş sağlığını göstermelidir: başarılı bir HTTP yanıtı, bir gönderinin doğru siparişle eşleştirildiği anlamına gelmez.

7. Gerçekleştirme ile iadeleri birbirinden ayırın

Giden gerçekleştirme ve iadeler gönderi verilerini paylaşır, ancak farklı iş kurallarına sahiptir. Giden gerçekleştirme genellikle bir siparişle başlar ve teslimat veya bir istisnayla sona erer. İade bir müşteri veya satıcı kararıyla başlar, yetkilendirme gerektirebilir ve teslim alma incelemesi, geri ödeme, değişim veya başka bir sonuçla sona erer.

İade entegrasyonu için taşıyıcı takibini eklemeden önce şu kararları belgeleyin:

• Hangi iade nedenleri kabul edilir ve kim onaylar?
• İade etiketi satıcının gönderim platformu, USPS ile ilgili bir iş akışı, üçüncü taraf bir iade sistemi veya başka bir sağlayıcı tarafından mı oluşturulur?
• İade takip numarası, giden takip numarasının yerine geçmeden orijinal siparişe nasıl bağlanır?
• Hangi olay “iade taşımada”, “iade teslim edildi” veya “inceleme için alındı” olarak kabul edilir?
• Bir iade depoya teslim edildiğinde, ürün incelenene kadar beklemede kalabilir mi?
• Müşteri yetkisiz bir paket gönderirse veya farklı bir taşıyıcı kullanırsa ne olur?

Projenin özel bir iade yönetimi iş akışına ihtiyaç duyduğu durumlarda 17RETURNS ilgili olabilir; 17TRACK API ise gönderi görünürlüğüyle ilgilidir. Etiket oluşturma, geri ödeme yetkilendirmesi, depo teslim alma veya taşıyıcı hesabı yönetimi gibi işlevleri herhangi bir ürüne atamadan önce güncel ürün belgelerini doğrulayın.

8. Entegrasyonu gerçekçi senaryolarla test edin

Tek bir teslim edilmiş paket için yapılan başarılı yol testi yeterli değildir. Aşağıdakileri içeren bir test matrisi oluşturun:

1. Yakın zamanda olayı olmayan geçerli bir USPS takip numarası.
2. Birden fazla olayın sıra dışında alındığı bir gönderi.
3. Tekrarlanan teslimat veya istisna olayları.
4. Geçersiz, yanlış yazılmış veya desteklenmeyen bir tanımlayıcı.
5. Gönderene iade edilen bir paket.
6. Aynı siparişle ilişkilendirilmiş bir giden gönderi ve bir iade gönderisi.
7. API zaman aşımı, hız sınırı yanıtı, kimlik doğrulama hatası ve hatalı biçimlendirilmiş yanıt.
8. Taşıyıcı ataması başlangıçta bilinmeyen veya doğrulama gerektiren bir gönderi.
9. Bir operasyon kullanıcısı siparişi düzenlerken yeni olay alan müşteriye yönelik bir sayfa.

Her senaryo için beklenen veritabanı sonucunu, müşteri mesajını, operasyon eylemini, yeniden deneme davranışını ve denetim izini kaydedin. Sentetik veya yetkilendirilmiş verilerle test edin ve kişisel adreslerin ve iletişim bilgilerinin günlüklerde veya herkese açık takip sayfalarında onaylanan iş amacı dışında gösterilmediğini doğrulayın.

9. Üretime hazır olma incelemesi

Başlatmadan önce eylem sahibi şu beş pratik soruyu yanıtlayabilmelidir: Gönderiyi hangi sistem oluşturur? Takip numarasının sahibi hangi sistemdir? Müşteri bildirimlerini hangi sistem gönderir? İade vakasını hangi sistem yönetir? Eksik veya çelişkili bir olayı hangi ekip inceler?

İncelemeyi yalnızca güncel USPS belgelerini, seçilen 17TRACK API belgelerini ve ürüne özel şartları veya operasyonel yönergeleri kontrol ettikten sonra tamamlayın. Uç nokta referanslarının, alan eşlemelerinin, test kanıtlarının, kimlik bilgisi sahiplerinin, eskalasyon irtibatlarının ve doğrudan doğrulama gerektiren varsayımların sürümlendirilmiş kaydını tutun. Bir API sürümü, taşıyıcı iş akışı, depo süreci veya iade politikası değiştiğinde kaydı yeniden gözden geçirin.

SSS

17TRACK her gerçekleştirme işlevi için USPS API'sinin yerini alabilir mi?

Hiçbir varsayımda bulunulmamalıdır. 17TRACK bir takip katmanı olarak değerlendirilebilir, ancak fiyatlandırma, adres hizmetleri, posta ücreti veya diğer taşıyıcı işlemleri gibi USPS'ye yönelik işlevler ilgili ürün belgelerine ve hesap gerekliliklerine göre doğrulanmalıdır. Takip görünürlüğü, etiket satın alma veya gerçekleştirme işlemiyle aynı şey değildir.

Hem USPS hem de 17TRACK entegrasyonlarına ihtiyacım var mı?

Her zaman değil. Uygulama yalnızca dar kapsamlı bir USPS işlevine ihtiyaç duyuyorsa doğrudan USPS entegrasyonu uygun olabilir. Birden fazla taşıyıcı arasında normalize edilmiş takip veya taşıyıcıdan bağımsız bir takip iş akışına ihtiyaç varsa 17TRACK ilgili olabilir. Karar yalnızca takip numarasına göre değil, gerekli yeteneklere, sahiplik modeline ve veri akışına göre verilmelidir.

İade takip numarası giden takip numarasının yerine geçmeli mi?

Hayır. İadeyi, orijinal siparişe ve gerçekleştirme kaydına bağlı ayrı bir gönderi veya iade hareketi olarak saklayın. Bu, giden teslimat geçmişini korur ve iadenin kendi olaylarına, istisnalarına ve operasyonel sonucuna sahip olmasını sağlar.

Eksik takip olayları nasıl ele alınmalıdır?

Belgelendirilmiş bir yeniden deneme ve eskalasyon politikası tanımlayın. Eksik bir olay normal taşıyıcı zamanlamasını, geçersiz bir tanımlayıcıyı, veri alım hatasını veya taşıyıcı tarafındaki gecikmeyi yansıtabilir. Tek bir yoklama denemesinde yeni olay alınmadı diye gönderiyi kayıp olarak etiketlemekten kaçının.

USPS kimlik bilgileri nerede saklanmalıdır?

Yönetilen sunucu tarafı gizli bilgi deposu kullanın ve erişimi role göre sınırlandırın. Kimlik bilgilerini asla mağaza JavaScript'ine, mobil istemci koduna, herkese açık depolara veya günlük dosyalarına koymayın. Üretime geçmeden önce güncel USPS kimlik doğrulama ve kimlik bilgisi yönetimi gerekliliklerini doğrulayın.

Kaynaklar

• USPS Web Tools and APIs — USPS'nin işletme API bilgileri için resmi başlangıç noktası.
• 17TRACK Tracking API Documentation — 17TRACK API entegrasyonu için resmi belgeler.
• 17RETURNS — iade yönetimi kullanım alanları için resmi ürün bilgileri.
• 17TRACK API — takip API'si senaryoları için resmi ürün genel görünümü.