Skip to main content
AnasayfaBlogKılavuzlarGönderi Takip Verilerini Bir Oms'ye Bağlama: Sipariş Eşleme ve Senkronizasyon Kuralları

Gönderi Takip Verilerini Bir Oms'ye Bağlama: Sipariş Eşleme ve Senkronizasyon Kuralları

17TRACK

Gönderi takip verilerini bir sipariş yönetim sistemine (OMS) bağlamak için takip edilen her paketi dahili bir gönderi kaydıyla eşleştirin, ardından bu gönderiyi siparişi ve siparişin fulfillment satırlarıyla ilişkilendirin. Takip güncellemelerini sağlayıcının desteklediği arayüz üzerinden alın, orijinal olayları koruyun ve yinelenen kayıtlar, geç güncellemeler, gönderi durumu ve siparişin tamamlanması için açık kurallar uygulayın. Sipariş tanımlayıcısı olarak yalnızca takip numarasını kullanmayın veya tek bir teslimat olayının çok paketli bir siparişi otomatik olarak kapatmasına izin vermeyin.

Gönderi Takip Verilerini Bir OMS Siparişine Bağlama

Bu kılavuz, bu bağlantıyı uygulayan entegrasyon mühendisleri ve e-ticaret operasyon ekipleri içindir. Önerilen tasarım, taşıyıcı gözlemlerini iş kararlarından ayırır: takip verileri bir paketin yolculuğunu açıklar; OMS ise bu yolculuğun fulfillment, müşteri iletişimi ve siparişin kapatılması açısından ne anlama geldiğine karar verir.

Her kaydın sahibi olan sistemi belirleyin

Bir API bağlantısı oluşturmadan önce OMS yöneticisi, fulfillment ekibi ve müşteri hizmetleri ekibiyle sahiplik konusunda anlaşın. Aksi takdirde teknik açıdan başarılı bir entegrasyon bile geçerli iş verilerinin üzerine yazabilir.

  • OMS: Siparişlerin, sipariş satırlarının, gerekli miktarların, iptallerin ve siparişin tamamlanmasına ilişkin kuralların sahibidir.
  • Fulfillment sistemi: Paketleme tahsisleri ve etiket atamaları dahil olmak üzere oluşturduğu gönderi veya paket kayıtlarının sahibidir. Bu sistem OMS’nin kendisi veya ayrı bir depo sistemi olabilir.
  • Takip sağlayıcısı: Takip gözlemlerini ve sağlayıcı tarafından tanımlanan durum sınıflandırmalarını sağlar.
  • Entegrasyon katmanı: Tanımlayıcılar arası referansların, olay işleme, normalleştirme, yeniden deneme işlemleri ve senkronizasyon denetim kayıtlarının sahibidir.

Bunları yazılımınızla ilgili varsayımlar olarak değil, önerilen sınırlar olarak ele alın. İstisnaları belgeleyin. Örneğin depo bir gönderi etiketini değiştirebiliyorsa entegrasyon, yeni gözlemlenen numaranın eskisinin yerine geçtiğini tahmin etmek yerine bu sistemden açık bir güncelleme almalıdır.

Durumları senkronize etmeden önce sipariş-paket eşlemesini oluşturun

Pratik bir ilişki şu şekildedir: sipariş → fulfillment → paket → takip ataması. OMS’niz farklı adlar kullanabilir veya bu kayıtlardan bazılarını birleştirebilir. Veritabanı yapısı farklı olsa bile ilişkileri koruyun.

Bir siparişte birden fazla fulfillment, bir fulfillment içinde de birden fazla paket bulunabilir. Bir paket ayrıca yeni bir takip ataması veya ilişkili bir son kilometre tanımlayıcısı edinebilir. Bu tanımlayıcılar ek sipariş miktarları oluşturmamalıdır.

KayıtÖnerilen alanlarAmaç
SiparişKiracı veya mağaza kimliği, değişmez OMS sipariş kimliğiSatıcıları birbirinden ayırır ve görünen sipariş numaralarına bağımlılığı önler.
FulfillmentFulfillment kimliği, sipariş kimliği, tahsis edilen satır kimlikleri ve miktarlarıSatın alınan hangi ürünlerin fulfillment sürecinde olduğunu belirler.
PaketDahili paket kimliği, fulfillment kimliği, mevcutsa paket tahsisleriTakip etiketlerinden bağımsız, sabit bir kimlik sağlar.
Takip atamasıAtama kimliği, paket kimliği, sağlayıcı hesabı, taşıyıcı tanımlayıcısı, takip numarası, etkin dönemGelen takip gözlemlerini doğru paket ve atama yaşam döngüsüyle ilişkilendirir.

Güncellemeleri kayıtlı bir çapraz referans üzerinden eşleştirin

Bir gönderi oluşturulduğunda, takip için kaydetmeden önce dahili kimliklerini kalıcı olarak saklayın. Belgelenmiş kayıt sürecinin döndürdüğü sağlayıcı tarafından verilen takip kayıt kimliğini saklayın. Sağlayıcı bir satıcı referansını destekliyorsa opak bir dahili referans kullanın ve eşlemeyi yerel olarak koruyun.

Gelen güncellemelerde önce kayıtlı sağlayıcı kayıt kimliğini doğru sağlayıcı hesabı ve kiracı içinde çözümleyin. Bu tanımlayıcı kullanılamıyorsa takip numarası, taşıyıcı kimliği, hesap bağlamı ve atama geçmişinden oluşan belgelenmiş birleşimi kullanın. Bunu bir arama stratejisi olarak değerlendirin; birleşimin küresel olarak benzersiz olduğuna dair garanti olarak değil.

Müşteri adı, e-posta adresi veya kapsamı belirtilmemiş görünen sipariş numarasına göre eşleştirme yapmayın. Baştaki sıfırların korunması için takip numaralarını metin olarak saklayın. İlgili taşıyıcı veya sağlayıcı sözleşmesi bu normalleştirmeye izin vermediği sürece karakterleri kaldırmaktan veya büyük/küçük harfleri değiştirmekten kaçının.

Bir arama eşleşme döndürmezse veya birden fazla olası eşleşme döndürürse güncellemeyi inceleme için karantinaya alın. Çözümlenmemiş bir olay, yanlış müşterinin siparişine güvenle güncelleme yapmaktan daha güvenlidir.

Bölünmüş siparişleri paket tahsisleri uydurmadan yönetin

Üç birim içeren örnek bir siparişi ele alalım. Paket A iki birim, Paket B ise bir birim taşımaktadır. Paket A’nın teslim edilmesi, iki birim için teslimat kanıtı bulunduğu anlamına gelir; tüm siparişin teslim edildiği anlamına gelmez.

Fulfillment sistemi yalnızca her iki paketin aynı fulfillment’a ait olduğunu kaydediyorsa birim düzeyinde tahsisler uydurmayın. Tüm gerekli paketlerin teslim edilip edilmediğini yine hesaplayabilirsiniz; ancak ürün düzeyindeki teslimat raporlaması, tahsis verileri mevcut olana kadar kullanılamaz veya açıkça belirsiz olarak kalmalıdır.

Takip API’sini dayanıklı bir veri alma katmanı üzerinden bağlayın

Sağlayıcı iletişimini OMS yazma işlemlerinden ayrı tutan bir işlem hattı kullanın:

Gönderi oluşturma → takip kaydı oluşturma → gelen güncelleme veya zamanlanmış alma → dayanıklı olay depolama → eşleme ve normalleştirme → OMS güncellemesi → mutabakat

17TRACK uygulaması için Tracking API ürün sayfası ve resmî API belgeleri ilgili başlangıç noktalarıdır. Adaptörü uygulamadan önce geçerli kayıt arayüzünü, taşıyıcı tanımlayıcılarını, güncelleme iletim seçeneklerini, kimlik doğrulama gereksinimlerini, durum tanımlarını ve hesap sınırlarını doğrulayın. Bu kılavuzdaki veri modeli bir entegrasyon önerisidir; 17TRACK’in bu alan adlarını kullandığı veya OMS’niz için yerel bir bağlayıcı sağladığı iddiası değildir.

Seçtiğiniz sağlayıcı webhook’ları destekliyorsa gelen isteklerin kimliğini belgelenmiş mekanizmasını kullanarak doğrulayın ve kabul edilen mesajları onaylamadan önce dayanıklı biçimde saklayın. Yavaş OMS işlemlerini istek yolunun dışında tutun. Belirli bir yanıt gövdesi veya zaman aşımı olduğunu varsaymak yerine sağlayıcının gerçek onay ve yeniden deneme sözleşmesine uyun.

Yoklama gerekiyorsa API’nin desteklediği yerlerde alma ilerlemesini saklayın, eşzamanlılığı kontrol edin ve belgelenmiş hız sınırlarına uyun. Ne webhook’un alınması ne de başarılı bir yoklama isteği OMS’nin güncellendiğini kanıtlar; bu sonuçları ayrı ayrı kaydedin.

Yeniden denemelere ve geç gelen olaylara dayanıklı senkronizasyon kuralları tanımlayın

1. İşlemeyi idempotent hale getirin

Aynı gözlemin iki kez işlenmesi gönderiyi çoğaltmamalı, miktarları iki kez ilerletmemeli veya aynı müşteri bildirimini yeniden göndermemelidir. HTTP, rastgele bir POST işlemini idempotent hale getirmez; entegrasyonun yinelenen kayıt korumasını uygulaması gerekir. RFC 9110, HTTP yöntemlerinin idempotensiğini açıklar.

Belgelenmiş ve mevcut olduğunda sabit bir sağlayıcı olay kimliği kullanın. Aksi takdirde atama kimliği ve olay zaman damgası, kaynak durumu ve konum gibi ilgili olay alanlarından bir parmak izi tanımlayın. Çakışma veya değişen olay açıklamaları olasılığını belgeleyin. Başka bir OMS işlemi üretmediğinde bile ham gözlemi saklayın.

Her yan etkiyi ayrı ayrı koruyun. Örneğin OMS durum yazma işlemi ile e-posta bildiriminin kendi tekilleştirme kontrolleri olmalıdır. Bir işlem çökmesinin kabul edilmiş bir olayı planlanmış güncelleme olmadan bırakmasını önlemek için işlemsel bir outbox veya eşdeğer dayanıklı iş kaydı kullanın.

2. Olay zamanını ve alınma zamanını ayrı saklayın

Bir olayın gerçekleşme zamanı ile entegrasyonunuzun onu aldığı zaman farklı soruları yanıtlar. Her ikisini, orijinal zaman damgası gösterimi ve sağlanan saat dilimi farkıyla birlikte saklayın. Saat dilimi bilinmeyen bir olaya sessizce depo saat dilimini atamayın.

Geç gelen bir taşıma sürecindeki tarama normalde daha yeni teslim edildi durumunun yerine geçmek yerine geçmişi zenginleştirmelidir. Ancak yalnızca zaman damgaları yeterli değildir: sağlayıcı bir düzeltme yayımlayabilir ve olaylarda eksik zaman bilgisi bulunabilir. Kullanılabilir olduğunda belgelenmiş sıra veya revizyon alanlarını ve açık bir düzeltme politikasını kullanın.

3. Kaynak ayrıntılarını silmeden durumları normalleştirin

OMS’nin anlayacağı küçük bir dahili kelime dağarcığı oluşturun; örneğin taşıyıcı kabulü bekleniyor, transit halinde, dağıtıma çıktı, teslim edildi, istisna ve iade ediliyor. Sağlayıcının belgelenmiş durumlarını bu sözlüğe eşleyin. Bunlar evrensel taşıyıcı tanımları değil, önerilen dahili kategorilerdir.

Orijinal durum kodunu, açıklamayı, olay konumunu, sağlayıcı kayıt referansını ve eşleme kuralı sürümünü saklayın. Eşlenmemiş bir değer, teslim edildi veya başarısız olarak varsayılan bir duruma dönüştürülmek yerine incelenebilir bir koşul oluşturmalıdır. Etiket oluşturma, kaynak olay bu yorumu açıkça desteklemediği sürece taşıyıcının fiziksel kabulünün kanıtı olarak değerlendirilmemelidir.

4. Basit bir sayısal sıralama yerine geçiş kuralları kullanın

Gönderi durumları her zaman düz bir çizgi oluşturmaz. Bir istisnanın ardından normal transit süreci gelebilir ve teslimat girişimi teslimat anlamına gelmez. İade hareketi daha önceki bir teslimat olayından sonra başlayabilir.

  • Sonraki kanıtlar hareketin yeniden başladığını desteklediğinde bir istisnanın temizlenmesine izin verin.
  • Sıradan bir geçmiş taramasının teslim edildi durumunun yerine sessizce geçmesini önleyin.
  • Belgelenmiş bir düzeltmeye kontrollü bir revizyon yolu üzerinden izin verin.
  • OMS desteklediğinde iade hareketini giden gönderinin tamamlanmasından ayrı izleyin.
  • Belirsiz veya çelişkili kanıtları operasyon kuyruğuna yönlendirin.

Bu kuralları sürümlendirin. Bir eşleme değiştiğinde bunun yalnızca yeni olaylara mı uygulanacağına veya geçmiş kayıtların kontrollü biçimde yeniden hesaplanmasının gerekip gerekmediğine karar verin.

Sipariş durumunu gerekli fulfillment yükümlülüklerine göre hesaplayın

Paket durumu ve sipariş durumu ayrı alanlar olmalıdır. Teslim edildi olarak işaretlenen bir paket o paket için kanıt sağlar; siparişin tamamlanması ise kalan gerekli miktarlara ve iş politikanıza bağlıdır.

Yararlı bir varsayılan kural, yalnızca teslimat gerektiren tüm miktarlar geçerli paket düzeyinde teslimat kanıtına sahip olduğunda ve gerekli tahsisler çözümlenmemiş kalmadığında siparişi tamamen teslim edildi olarak işaretlemektir. İptal edilen miktarları OMS’nin iptal kurallarına göre hariç tutun. Dijital ürünleri, mağazadan teslim siparişlerini ve diğer nakliye dışı yükümlülükleri kendi tamamlanma koşullarıyla yönetin.

İkame gönderileri açık ilişkiler gerektirir. Kayıp bir paket değiştirilirse ikamenin orijinal teslimat yükümlülüğünün yerine geçip geçmeyeceğine karar verin. Aksi takdirde orijinal paket tamamlanmayı süresiz olarak engelleyebilir veya her iki paket de fulfillment’a sayılabilir. Kararı yalnızca takip durumundan türetmek yerine kaydedin.

Teslimat tamamlanmasını finansal kapanıştan, iade uygunluğundan ve itiraz çözümünden ayrı tutun. Bir taşıyıcının teslimat olayı otomatik olarak iade yetkisi vermemeli veya müşteri talebini sonuçlandırmamalıdır.

Denetim izini kaybetmeden hatalardan kurtulun

Geçici hataları sınırlı geri çekilme ve belgelenmiş yeniden deneme yönergeleriyle yeniden deneyin. Geçici bağlantı hatalarını geçersiz tanımlayıcılardan, süresi dolmuş kimlik bilgilerinden, izin hatalarından ve şema uyumsuzluklarından ayırın. Son gruptakiler sonsuz yeniden deneme değil, düzeltici işlem gerektirir.

Etkilenen kiracıyı, paketi, olay referansını, denenmiş işlemi, hata sınıflandırmasını ve sonraki eylemi içeren bir başarısız işler kuyruğu tutun. Gereksiz müşteri verilerini veya kimlik bilgilerini günlüklere kopyalamadan inceleme yapmaya yetecek bağlamı kaydedin.

Normal güncelleme yoluna ek olarak mutabakat çalıştırın. Takip bilgileri güncel olmayan etkin gönderileri, OMS yazma işlemleri başarısız olan kabul edilmiş olayları, eşleşmeyen gözlemleri ve entegrasyonun hesapladığı durum ile OMS arasındaki farklılıkları inceleyin. İnceleme sıklığını keyfî bir evrensel takvim uygulamak yerine teslimat taahhütlerine, API sınırlarına ve operasyonel riske göre belirleyin.

Sahiplik atayın: mühendislik ekibi veri alma ve yazma hatalarını ele alır; fulfillment operasyonları eksik paket ilişkilerini çözer; müşteri hizmetleri müşteri iletişimi gerektiren istisnaları inceler. Sorumlu bir sahibi olmayan kuyruk yalnızca bir depolama alanıdır.

Başlatmadan önce eşlemeyi ve iş kurallarını test edin

Kontrollü test verileri ve sınırlı bir üretim kullanıma alma süreci kullanın. Aşağıdaki durumları hem olay geçmişine hem de ortaya çıkan OMS kaydına karşı test edin:

  • Tek paketli bir sipariş normal biçimde teslimata ilerler.
  • Bölünmüş bir siparişte bir paket teslim edilmiş, diğeri hâlâ hareket halindedir.
  • Aynı olay, yinelenen yan etkiler olmadan tekrar tekrar alınır.
  • Daha eski bir transit taraması teslimattan sonra gelir.
  • Bilinmeyen bir taşıyıcı veya durum inceleme kuyruğuna girer.
  • Bir etiket, başka bir fulfillment yükümlülüğü oluşturmadan değiştirilir.
  • Bir ikame gönderi, onaylanmış bir kural uyarınca orijinal paketin yerini alır.
  • Bir olay kabul edildikten sonra OMS kullanılamaz hale gelir.
  • Bir işlem OMS yazma işlemi ile onayı arasında yeniden başlar.
  • Aynı görünen sipariş numarası iki mağazada bulunur ve kiracılar arası eşleştirme yapılmaz.

Kabul edilen her olay izlenebilir bir işleme sonucuna sahip olduğunda, belirsiz eşleşmeler siparişleri otomatik olarak güncelleyemediğinde ve operatörler başarısız işleri güvenle yeniden oynatabildiğinde kullanıma başlayın. Bunlar, yalnızca bir API isteğinin başarılı olduğunu göstermekten daha yararlı kabul kriterleridir.

SSS

Takip numaralarını doğrudan siparişlere bağlayabilir miyim?

Kesinlikle tek paketli bir iş akışında doğrudan ilişki başlangıçta yeterli olabilir. Yine de sipariş ile takip ataması arasında dahili bir gönderi kimliği kullanın. Bu, sipariş kaydının anlamını değiştirmeden bölünmüş gönderiler, yeniden etiketleme ve ikameler için geçiş yolu sağlar.

Entegrasyon webhook mu yoksa yoklama mı kullanmalı?

Sağlayıcının desteklediği ve altyapınızla uyumlu olan iletim mekanizmasını kullanın. Webhook’lar tekrarlanan veri almayı azaltabilir; yoklama ise mevcut olduğunda veri alma tabanlı iş akışlarını ve mutabakatı destekleyebilir. Her iki yaklaşım da dayanıklı depolama, yinelenen kayıtların ele alınması ve kurtarma ihtiyacını ortadan kaldırmaz.

Bir takip olayının eşleşen siparişi yoksa ne olmalı?

Olayı eşleşmeyen olaylar kuyruğunda saklayın ve kayıt oluşturma kaydını, kiracı bağlamını, taşıyıcı kimliğini ve gönderi oluşturma zamanlamasını inceleyin. Otomatik olarak bir sipariş oluşturmayın veya olayı makul görünen bir müşteriye bağlamayın. Eşleme düzeltildikten sonra olayı yeniden oynatın.

Teslimat bildirimleri OMS’den mi yoksa takip sisteminden mi gönderilmeli?

Her bildirim türü ve tetikleyici için tek bir sahip seçin. İki sistem aynı mesajı gönderebiliyorsa yollardan birini devre dışı bırakın veya dayanıklı bir bildirim defteri paylaşın. Ayrıca özellikle bölünmüş fulfillment durumunda bir mesajın tek bir pakete mi yoksa siparişin tamamına mı atıfta bulunduğuna karar verin.

İstisna durumu siparişin başarısız olduğu anlamına mı gelir?

Hayır. İstisna, mutlaka kalıcı bir sonuç olmayan ve yorumlanması gereken bir gözlemdir. Nedeni koruyun, sonraki olayları izleyin ve operasyonların ne zaman müdahale etmesi gerektiğine karar vermek için eskalasyon politikanızı kullanın.

Kaynaklar