Veri Eşleme ve Dönüştürme: Farklı API'leri ve Veri Formatlarını Kullanma

Her e-ticaret platformu farklı bir dil konuşur. Amazon, siparişleri iç içe geçmiş adres nesneleriyle XML olarak gönderir. Shopify, JSON'u düz dize alanlarıyla döndürür. eBay, REST ve eski XML-RPC'nin bir karışımını kullanır. WooCommerce meta verileri anahtar-değer dizilerine yerleştirir. ERP'niz her şeyin doğrulanmış veri türleriyle belirli bir dahili formatta olmasını bekler.

Veri eşleme ve dönüştürme, çok kanallı entegrasyonun çalışmasını sağlayan çeviri katmanıdır. Doğru yaptığınızda veriler sistemler arasında sessizce akar. Yanlış anladığınızda, müşteri telefon numaralarının neden şehir alanını doldurduğunu veya ürün ağırlıklarının neden 2,2 kat azaldığını bulmak için saatler harcarsınız.

Önemli Çıkarımlar

• Kanonik bir veri modeli (dahili standart), N'den N'ye eşlemeyi, N'den 1'e artı 1'den N'ye lehine ortadan kaldırır
• Birim dönüştürme hataları, sınır ötesi e-ticarette en yaygın ve en pahalı veri eşleme hatasıdır
• Savunma amaçlı ayrıştırma — her alanı doğrulayın, her eksik değeri varsayılan olarak belirleyin — basamaklı hataları önler
• Eşlemelerinizi kodunuzla birlikte sürümlendirin; API değişiklikleri, sürümlendirilmiş şemalar olmadan entegrasyonları sessizce bozar

---

Kanonik Veri Modeli

Kanonik bir model olmadan, 5 kanalı ERP'nize bağlamak, her biri diğer sistemin tuhaflıklarını ele alan 10 benzersiz eşleme (5 gelen + 5 giden) gerektirir. Altıncı bir kanalın eklenmesi 2 eşlemenin daha yapılmasını gerektirir.

Kanonik bir modelde, her kanal tek bir dahili formata eşlenir ve bu formattan ayrılır. Altıncı bir kanal eklemek için, kaç tane kanalın mevcut olduğuna bakılmaksızın yalnızca 1 yeni gelen eşleyici ve 1 yeni giden eşleyici gerekir.

Kanonik Modelin Tasarlanması

Kanonik modeliniz şöyle olmalıdır:

• Tüm kanalların üst kümesi: Bazı kanallar her alanı kullanmasa bile herhangi bir kanalın ihtiyaç duyabileceği her alanı içerir
• Kesinlikle yazılmış: Tarihler ISO 8601'dir, ağırlıklar gram cinsindendir, para birimleri ISO 4217 kodlarını kullanır, fiyatlar değişken değil tam sayılardır (sent)
• Sürümlü: Şema değişiklikleri açık ve geriye dönük olarak uyumludur
• Belgelenmiş: Her alanın bir açıklaması, veri türü, doğrulama kuralı ve kaynak eşlemesi vardır

Örnek: Kanonik Sıra Modeli

Basitleştirilmiş kanonik düzen:

Her kaynağın aynı kanonik yapıya nasıl eşleştiğine dikkat edin. Dönüşüm, yol farklılıklarını (yuvalanmış ve düz), adlandırma farklılıklarını (camelCase, PascalCase ve Snake_case) ve biçim farklılıklarını (tarihler, sayılar, para birimleri) ele alır.

---

Harita Oluşturmada Karşılaşılan Zorluklar ve Çözümler

Veri eşleme uç durumlarla doludur. İşte en sık karşılaşılan sorunlar ve bunların nasıl çözüleceği.

---

Birim Dönüşümü

Birim dönüştürme hataları gerçek anlamda maddi hasara neden olur. Sitenizde 2,2 kg olarak listelenen bir ürünün Amazon'da 2,2 lb olarak görünmesi, nakliye maliyeti tahminlerinin yanlış olduğu, boyutsal ağırlık hesaplamalarının yanlış olduğu ve müşterilerin beklenenden iki kat daha ağır bir ürün aldığı anlamına gelir.

Ağırlık Dönüşümü

Kural: Tüm ağırlıkları dahili olarak gram cinsinden saklayın. Giden çıkışı, her kanalın gerektirdiği birime dönüştürün. Gelen verilerde ünite etiketine asla güvenmeyin; değerin ürün kategorisi için anlamlı olduğunu doğrulayın. 2 gram ağırlığındaki bir dizüstü bilgisayarın kilogram cinsinden olduğu açıktır.

Boyut Dönüşümü

Boyutlar da aynı derecede haindir. Amazon ABD inç bekliyor. Amazon DE santimetre bekliyor. Gönderim yazılımınız milimetreye ihtiyaç duyabilir.

Kural: Tüm boyutları dahili olarak milimetre cinsinden saklayın. Kanal başına giden çıkışı dönüştürün. Boyutların fiziksel olarak makul olduğunu doğrulayın.

Para Birimi Dönüştürme

Çoklu para birimi kullanımı başka bir katman ekler. Kanonik modeliniz, fiyatları temel para biriminin en küçük biriminde saklar (ABD Doları için sent, GBP için peni, EUR için santimetre).

Sınır ötesi siparişler için hem orijinal para birimi tutarını hem de dönüştürülen temel para birimi tutarını kullanılan döviz kuruyla birlikte saklayın. Bu, para birimiyle ilgili tutarsızlıklar için bir denetim izi oluşturur.

---

Veri Normalleştirme Modelleri

Ham pazar verileri karmaşıktır. Normalleştirme, kanonik modelinize girmeden önce onu temizler.

Metin Normalleştirme

• Boşlukları kırp: Baştaki ve sondaki boşluklar API yanıtlarında yaygındır
• Unicode'u normalleştir: Tam genişlikteki karakterleri, akıllı tırnakları ve özel karakterleri, uygun olduğunda ASCII eşdeğerlerine dönüştürün
• Büyük/küçük harf standardizasyonu: Dahili verileri tutarlı bir büyük/küçük harflerle saklayın (ör. ülke kodları için BÜYÜK, adlar için Büyük/Küçük, e-postalar için daha düşük)
• HTML varlık kod çözme: & ila &, < ila <, vb.

Adres Normalleştirme

Adresler kanallar arasında en tutarsız veri türüdür. Bir normalizasyon hattı şunları yapmalıdır:

1. Serbest metin adreslerini yapılandırılmış bileşenlere (cadde, şehir, eyalet, posta, ülke) ayrıştırın
2. Posta kodlarını ülke biçimi kurallarına göre doğrulayın
3. Ülkeyi ISO 3166-1 alfa-2 kodlarına göre normalleştirin (ABD, GB, DE — "Amerika Birleşik Devletleri", "İngiltere", "Almanya" değil)
4. Eyaleti/bölgeyi standart kısaltmalara göre normalleştirin
5. Şehir/eyalet/posta kombinasyonlarının coğrafi olarak tutarlı olduğunu doğrulayın

SKU Normalleştirmesi

Farklı kaynaklardan gelen SKU'lar aynı ürün için farklı formatlar kullanabilir:

• Tedarikçi: "ABC-001-BLK-L"
• Amazon: "ABC001BLKL"
• Shopify: "abc-001-siyah-büyük"
• eBay: "ABC 001 Siyah L"

Kurallı modeliniz tek bir dahili SKU biçimi kullanmalı ve harici SKU biçimlerini dahili kimliklerle eşleştiren bir arama tablosu sağlamalıdır.

---

API Biçimi İşleme

Farklı API'ler verileri farklı formatlarda döndürür. Dönüşüm katmanınızın hepsini işlemesi gerekir.

JSON (Shopify, Walmart, TikTok Shop)

Çoğu modern API JSON'u kullanır. Ayrıştırma basittir ancak şunlara dikkat edin:

• Sayısal hassasiyet: JSON numaraları, büyük tamsayılar (2^53'ün üzerindeki sipariş kimlikleri) için hassasiyeti kaybedebilir. Gerekirse dizeler olarak ayrıştırın.
• İç içe yapılar: Shopify, teslimat adreslerini yanıtın içindeki siparişlerin içine yerleştirir. Doğru yol navigasyonunu kullanın.
• Sayfalandırma: İmleç tabanlı (Shopify) veya sayfa tabanlı. Sayfalar arasında hız sınırlamasını yönetin.

XML (Amazon SP-API raporları, eBay)

XML, ad alanları, öznitelikler ve öğeler ve kodlama bildirimleri ile karmaşıklık katar.

• Ad alanı yönetimi: Amazon raporları, XPath sorgularının çalışması için kaydedilmesi gereken XML ad alanlarını kullanır
• CDATA bölümleri: Metin içeriği, bazı ayrıştırıcıların çıkardığı ve diğerlerinin koruduğu CDATA'ya sarılmış olabilir
• Karakter kodlama: Her zaman UTF-8 olarak ayrıştırın. Bazı eski yayınlar ISO-8859-1'i beyan eder.

CSV/TSV (Google Alışveriş, Amazon düz dosyaları)

Feed tabanlı kanallar tablo verilerini kabul eder.

• Sütun sırası önemlidir: Bazı yayınlar başlığa değil, konuma bağlıdır
• Kaçış: Virgül içeren alanlar tırnak içine alınmalıdır. Tırnak işaretleri içeren alanlarda çift tırnak işareti kullanılmalıdır.
• Kodlama: Dosya başlangıcındaki BOM (Bayt Sırası İşareti), bazı sistemlerde ayrıştırma hatalarına neden olur. Çıkar onu.
• Satır sonları: Windows (CRLF) ile Unix (LF) karşılaştırması. Ayrıştırmadan önce normalleştirin.

EDI (Kurumsal perakende, 3PL'ler)

Elektronik Veri Değişimi hâlâ büyük perakendeciler ve 3PL'ler tarafından kullanılıyor. EDI belgeleri (850 Satınalma Siparişi, 856 Ön Sevk Bildirimi, 810 Fatura), X12 veya EDIFACT standartlarıyla tanımlanan sabit genişlikli veya sınırlayıcıyla ayrılmış formatları kullanır.

---

Dönüşümde Hata İşleme

Veriler beklenen şemanızla eşleşmediğinde, dönüşüm katmanının şuna karar vermesi gerekir: başarısız, varsayılan veya bayrak.

Strateji Matrisi

Doğrulama İşlem Hattı

Her kayıt, dönüşümden sonra bir doğrulama hattından geçmelidir:

1. Şema doğrulama: Kayıt beklenen yapıyla eşleşiyor mu?
2. Tür doğrulama: Sayılar aslında sayı mı, tarihler aslında tarih mi?
3. İş kuralı doğrulama: Siparişin toplamı olumlu mu? Teslimat adresi hizmet verdiğiniz bir ülkede mi?
4. Referans doğrulama: SKU ürün kataloğunuzda mevcut mu?

Doğrulamayı geçemeyen kayıtlar karantinaya alınır; sessizce düşürülmek veya kötü verilerle işlenmek yerine manuel inceleme için bir hata kuyruğunda saklanır.

Bu doğrulama hatalarını izlemek için bkz. Entegrasyon İzleme.

---

Versiyon Oluşturma ve Değişiklik Yönetimi

API'ler değişir. Shopify her üç ayda bir yeni bir API sürümü sunar. Amazon, SP-API modellerini periyodik olarak günceller. eBay eski uç noktaları kullanımdan kaldırıyor. Haritalama katmanınızın bu değişiklikleri kesinti olmadan işlemesi gerekir.

Sürüm Oluşturma Stratejisi

• API sürümlerini sabitle: Her zaman aradığınız API sürümünü belirtin. Shopify, 2025-01 talebinde bulunmanıza olanak tanır. Amazon SP-API, eski model sürümlerini kullanır.
• Eşleştiricilerinizi sürümlendirin: Bir kanal API'si değiştiğinde, mevcut olanı değiştirmek yerine yeni bir eşleyici sürümü oluşturun. Geçiş sırasında her iki sürümü de paralel olarak çalıştırın.
• Otomatik regresyon testleri: Her eşleyici için bir dizi örnek girdi ve beklenen çıktı sağlayın. Bir haritalayıcı değiştiğinde testler istenmeyen regresyonları yakalar.
• Kullanımdan kaldırılma izleme: API değişiklik günlüklerine ve sonlandırma bildirimlerine abone olun. Taşıma işlemlerini kullanımdan kaldırma tarihlerinden 60 gün önce planlayın.

Entegrasyon mimarisinin tamamı için sütun gönderisine bakın: The Ultimate eCommerce Integration Guide.

---

Sıkça Sorulan Sorular

Bir kanalda var olan ancak diğerinde olmayan alanları nasıl yönetirim?

Kanonik modeliniz tüm alanların üst kümesini içerir. Alanı olmayan bir kanaldan gelen verileri dönüştürürken, bunu boş veya makul bir varsayılana ayarlayın. Giden bağlantıyı, alan kabul etmeyen bir kanala dönüştürürken, onu atlayın. Kanonik model evrensel bir tercüman görevi görür; her dilde her kavram için bir kelime yoktur ve bu iyidir.

Node.js yığınında veri dönüşümü için en iyi kitaplık hangisidir?

JSON dönüşümleri için JSONata, Lodash (yol erişimi ve düzenleme için) ve Zod (doğrulama için) gibi kitaplıklar çoğu ihtiyacı karşılar. XML için, ayrıştırma için fast-xml-parser'ı ve oluşturma için xmlbuilder2'yi kullanın. CSV için Papa Parse uç durumları iyi yönetir. Karmaşık ETL işlem hatları için Apache NiFi'yi veya kapsamlı birim testleriyle özel dönüşüm işlevlerini düşünün.

Canlı API'lere başvurmadan veri eşlemelerini nasıl test edebilirim?

Gerçek API yanıtlarını fikstür olarak kaydedin ve bunları birim testlerinde kullanın. Her eşleyicinin, gerçek dünyadan örnekler, uç durumlar (boş alanlar, maksimum uzunluklar, özel karakterler) ve hata durumları (yanlış biçimlendirilmiş veriler) içeren kapsamlı bir test paketi olmalıdır. Eşleme kodunu değiştiren her işlemde bu testleri CI/CD'de çalıştırın. Nock (Node.js) veya WireMock (Java) gibi araçlar, entegrasyon testleri için API uç noktalarını taklit edebilir.

Bir ETL aracı kullanmalı mıyım yoksa özel dönüşüm kodu mu yazmalıyım?

Tanınmış platformlarla standart e-Ticaret entegrasyonları için, uygulama katmanınızdaki (Node.js/TypeScript veya Python) özel kodun bakımı, ayrı bir ETL aracından daha kolaydır. ETL platformları (Fivetran, Airbyte, Apache NiFi), 20'den fazla veri kaynağını karmaşık dönüşüm hatlarıyla entegre ettiğinizde değer katar. 3-8 kanallı e-Ticaret entegrasyonları için, iyi test kapsamına sahip, amaca yönelik olarak oluşturulmuş haritalayıcılar daha basit ve daha fazla hata ayıklanabilir.

---

Sırada Ne Var

Veri eşleme, çok kanallı entegrasyonu güvenilir kılan gösterişsiz temeldir. Dönüşüm katmanınız her uç durumu incelikle ele aldığında entegrasyon yığınınızın geri kalanı temiz, tutarlı, doğrulanmış veriler üzerinde çalışır ve gece geç saatlerde yapılan hata ayıklama oturumları ortadan kalkar.

Odoo'yu 15'ten fazla pazara bağlayan önceden oluşturulmuş veri haritalayıcıları için ECOSIRE entegrasyon hizmetlerini keşfedin veya entegrasyonunuz için özel dönüşüm gereksinimlerini görüşmek üzere ekibimizle iletişime geçin.

---

ECOSIRE tarafından yayınlandı — işletmelerin Odoo ERP, Shopify eCommerce ve OpenClaw AI genelinde yapay zeka destekli çözümlerle ölçeklenmesine yardımcı oluyor.