API Entegrasyonu: Veri Sözleşmesi ve Hata Yönetimi
API bağlantısında veri sözleşmesini, yetkileri ve hata yönetimini belirleyin.
API ve Sistem Entegrasyonu
HazırSoft entegrasyon projelerinde yalnız veri aktarımını değil, kaynağın yetkisini ve karşı sistemin kabulünü tasarlar. Sipariş, stok, fatura ve ödeme için eşleştirme, tekrar işleme ve mutabakat kuralları belirlenir. Resmî API veya desteklenen dosya erişimleri incelenerek hangi bilginin hangi yönde taşınabileceği netleştirilir. Türkiye çapında ve Avrupa Birliği, Almanya, Avusturya veya İsviçre odaklı operasyonlar için entegrasyon yazılımını uzaktan geliştirebiliriz. Türkçe ya da İngilizce teknik oturumlarda örnek kayıtlar ve API belgeleri üzerinden ilerler; bağlantıyı teslim ederken erişim sorumluluklarını ve aktarım sınırlarını açıklığa kavuştururuz.

Hizmet kapsamı
Kanal API yetkilerini inceleyerek kategori, varyant ve dış sipariş kimliklerini işletmenin kayıtlarıyla eşleştirin.
Ayrıntıya gitGönderi oluşturma, etiket basımı, taşıyıcı kabulü ve iade takibini farklı işlem durumlarıyla yönetin.
Ayrıntıya gitERP sürümü ve erişim haklarına göre cari, stok ve belge akışları; kaynak ile hedef arasında mutabakat.
Ayrıntıya gitFatura taslağı, entegratör gönderimi, kabul ve iptal süreçlerini belge kimliğiyle izlenebilir hâle getirin.
Ayrıntıya gitSatıcı hesabının desteklediği tahsilat ve iade işlemlerini doğrulanmış sağlayıcı sonuçlarıyla ilişkilendirin.
Ayrıntıya gitDosya güncelliği, webhook imzası, gönderim limitleri ve belirsiz yanıtlar için ayrı veri aktarım kuralları.
Ayrıntıya gitEntegrasyonun amacı yalnız iki uygulama arasında bağlantı açmak değildir; hangi bilginin hangi sistemde doğru kabul edildiğini belirlemektir. Ürün adı katalogda, kullanılabilir stok ERP sisteminde ve teslimat durumu taşıyıcıda yönetilebilir. Bu kaynaklar aynı veriyi farklı zamanlarda günceller. Her alan için yetkili kaynak, aktarım yönü ve kabul edilen gecikme yazılmadan çift yönlü bağlantı kurmak çelişkileri büyütebilir.
Başlangıçta veri akış haritası çıkarırız. Sipariş alınması, onaylanması, sevk edilmesi ve faturalanması birbirinden ayrı olaylardır. İptal veya kısmi iade bu zincirin hangi noktalarını değiştirir? Kaynak sistemde oluşan düzeltme hedefte nasıl karşılanır? Otomasyon, insan kararının gerekli olduğu durumları ortadan kaldırmaz; onları görünür bir inceleme kuyruğuna taşıyabilir.
İşletme ekibinin başarısız aktarımı görebilmesi gerekir. Başarılı yanıt alınması, kaydın karşı tarafta doğru işlendiğinin tek kanıtı değildir. İşlem kimliği, hedef belge numarası ve mutabakat sonuçları birlikte değerlendirilir. E-ticaret sitesi kurulurken veya mevcut altyapıya eklenirken veri sorumluluğu aynı dikkatle tasarlanır.
Pazaryeri bağlantısında kanalın satıcı API erişimi, hesap yetkileri ve güncel kullanım sınırları incelenir. Trendyol, Hepsiburada, N11, Amazon veya Pazarama adı tek başına tüm verilerin aktarılabileceğini göstermez. Kategori ve zorunlu özellikler kanala göre değişebilir. Ürün kartının bir kez oluşturulması, her kanalda aynı anlamı taşıdığı varsayımıyla yapılmaz.
Stok kodu, barkod ve varyant kimliği arasında eşleştirme tablosu hazırlanır. Bir ürünün paket veya renk seçenekleri yanlış eşleştirilirse stok güncellemesi yanlış ilana gider. Silinen ürün, kapanan ilan ve kabul edilmeyen kategori bilgisi ayrı durumlar olarak görünür. Kanal bazlı fiyat kuralında komisyon, vergi ve yuvarlama varsayımları işletme tarafından onaylanır.
Siparişler aynı dış kimlikle tekrar gelebilir. Aktarım kaydı bu kimliği korur; yeniden çekme ikinci sipariş oluşturmamalıdır. Kısmi sevkiyat, iptal talebi ve iade, tek bir tamamlandı bayrağına indirgenmez. Pazaryerine gönderilen fatura veya takip bilgisi reddedildiğinde operasyon ekibi durumun hangi aşamada kaldığını görebilmelidir.
Standart kataloglarda mevcut entegratör paneli yeterli olabilir. Özel bağlantı, kurumun kendi yazılımında karar verdiği veya farklı depo ve bayi kuralları uyguladığı durumda değerlendirilir. Sağlayıcının belge ve test erişimi görülmeden kanal desteği kesinleştirilmez. Akışın kapsamı, sistem adından ziyade izin verilen işlemlerle tanımlanır.
Kargo kaydı oluşturmak ile paketin taşıyıcıya teslim edilmesi ayrı olaylardır. Etiket oluşturulduğunda siparişin teslim edildiği söylenmez. Paket sayısı, ağırlık, desi, adres ve hizmet tipi gönderi isteğine dönüşür. Aynı sipariş yeniden işlendiğinde ikinci gönderi oluşmaması için dış kayıt kimliği ve oluşturma sonucu saklanır.
Yurtiçi Kargo, Aras Kargo, MNG Kargo, PTT Kargo ve Sürat Kargo gibi taşıyıcılarda erişim koşulları ilgili hesap ve anlaşmaya bağlıdır. İşe başlamadan servis belgeleri ve izinler incelenir. Her firmanın aynı teslimat durumlarını veya iade işlemlerini sunduğu varsayılmaz. Taşıyıcı durumları işletmenin sipariş durumlarıyla eşleştirilir; bilinmeyen kodlar sessizce teslim edildi sayılmaz.
Toplu etiket basımında başarısız kaydın diğer siparişleri durdurup durdurmayacağı belirlenir. Gün sonunda oluşturulan gönderilerle taşıyıcının kabul ettikleri karşılaştırılabilir. Takip bildirimi müşteriye aktarılırken durumun zamanı ve kaynağı dikkate alınır; gecikmiş bildirim güncel durumu geriye götürmemelidir.
ERP bağlantısında önce muhasebe programının sunduğu resmi arayüz ve kullanım hakkı incelenir. Logo, Netsis, Nebim, DIA, AkınSoft veya Uyumsoft ürünlerinin sürümleri ve modülleri farklı erişim imkânları taşıyabilir. Program adının listede bulunması, kurulacak her akışın teknik olarak mümkün olduğu anlamına gelmez. Yerel sunucuda çalışan yapılar için güvenli ara servis ihtiyacı değerlendirilebilir.
Cari hesap, stok kodu, vergi alanı ve belge türü eşleştirmesi muhasebe ve operasyon çalışanlarıyla yapılır. Aynı müşterinin birden fazla kartı varsa hangi kartın kullanılacağı kararlaştırılır. Genel bir isim benzerliği otomatik kimlik kabul edilmez. Tarih, para birimi, birim dönüşümü ve yuvarlama kuralları örnek belgelerde denenir.
ERP kayıt oluşturmayı kabul ettiğinde belge kimliği saklanır. Daha sonra gelen düzeltme yeni belge mi, revizyon mu veya ters kayıt mı gerektirir? Bu karar programın desteklediği yöntemlerle birlikte belirlenir. Doğrudan veritabanına yazmak, üretici onayı olmadan kestirme yol sayılmaz. İşletmenin özgün operasyonları işletmeye özel yazılımda yürütülürken resmî kayıtların yetkili sistemi korunabilir.
Geçiş ve günlük işletmede mutabakat raporu önemlidir. Kaynakta onaylanmış ancak ERP tarafından kabul edilmemiş siparişler, tutar farkları ve eşleşmeyen kartlar görünür tutulur. Operasyon ekibi sorunu düzelttikten sonra güvenli yeniden işleme yapabilir; aynı belgeyi oluşturma riski taşıyan kör tekrar uygulanmaz.
E-fatura bağlantısı çalışılan özel entegratörün desteklediği API ve belge akışına dayanır. Mükellef sorgusu, belge türü, vergi alanları ve alıcı bilgisi gönderimden önce doğrulanır. Muhasebe çalışanının onaylaması gereken kararlar yazılım tarafından varsayılmaz. Güncel yasal yükümlülük ve belge senaryoları mali müşavirle teyit edilmelidir; teknik entegrasyon hukuki değerlendirme yerine geçmez.
Fatura taslağı, entegratöre gönderim, kabul ve alıcıya iletim ayrı durumlardır. Yanıt beklerken aynı belgeyi tekrar göndermek mükerrer işlem riski doğurabilir. Belge kimliği ve sağlayıcı sonucu ilişkilendirilir; belirsiz durumda sorgulama yapılır. Kullanıcı paneli yalnız başarılı ya da başarısız mesajı değil, hangi aşamada beklediğini göstermelidir.
İptal, itiraz ve kısmi iade kullanılan belge türünün kurallarıyla planlanır. Siparişin ticari durumu ile faturanın hukuki durumu birbirine karıştırılmaz. Belge erişimi, arşivleme ve dosyanın kime gösterileceği kurumun sorumlulukları çerçevesinde belirlenir. Kabul senaryosunda tutar, vergi, para birimi ve belge ilişkileri örnek kayıtlarla karşılaştırılır.
Ödeme bağlantısında tarayıcının veya mobil uygulamanın başarı ekranına dönmesi tek başına tahsilat kanıtı değildir. Sonuç sağlayıcının doğrulanan yanıtı ve işlem sorgusuyla ilişkilendirilir. İşlem kimliği, tutar, para birimi ve sipariş bağı kontrol edilir. İmzalı bildirimlerin doğrulanması ve yinelenen bildirimlerin aynı sonucu üretmesi tasarımın temelidir.
Banka sanal POS veya iyzico, PayTR gibi kuruluşlarda satıcı hesabı, sözleşme ve kullanım yetkisi ön koşuldur. Stripe ve PayPal gibi uluslararası seçeneklerin işletmenin ülkesi ve hesap yapısı için kullanılabilirliği ayrıca araştırılır; Türkiye’de her işletmeye açık olduğu söylenmez. Taksit, abonelik ve iade yetenekleri sağlayıcının gerçek koşullarıyla kapsamlandırılır.
Kart verisi tutmak yerine sağlayıcının desteklediği barındırılan veya belirteçli ödeme yöntemleri değerlendirilir. 3D Secure sonucu ile sipariş kesinleşmesi arasındaki ilişki açıklanır. Zaman aşımında kullanıcıya yeniden ödeme çağrısı yapmadan önce ilk girişimin durumu araştırılmalıdır. Kısmi iade, birden fazla iade ve başarısız iade operasyon panelinde ayrı görülebilir.
Kabul yalnız başarılı ödeme üzerinden yapılmaz. Reddedilen kart, terk edilen doğrulama, gecikmiş bildirim ve yanlış tutar senaryoları test ortamında ele alınır. Sağlayıcı test ortamının canlı sistemi tam temsil etmeyebileceği bilinir; sınırlı canlı doğrulama yetkili hesap ve onaylanmış kapsamla planlanır.
REST API, webhook ve dosya alışverişi farklı teslim davranışları taşır. API yanıtı işlem hakkında bilgi verir; webhook gecikebilir veya yeniden gönderilebilir; XML dosyası yalnız oluşturulduğu anın görüntüsünü temsil eder. Yöntem seçimi verinin değişme sıklığına ve karşı tarafın sunduğu imkânlara dayanır. Anlık kelimesi yerine ölçülebilir aktarım aralığı ve kabul edilen gecikme tanımlanır.
| Yöntem | Tasarım konusu | Kabul örneği |
|---|---|---|
| REST API | Limit, yetki ve belirsiz yanıt | Yanıt kesilince kayıt durumu sorgulanır |
| Webhook | İmza ve tekrar gönderim | Aynı olay ikinci işlem oluşturmaz |
| XML dosyası | Biçim ve veri güncelliği | Eksik dosya eski kataloğu silmez |
Yeniden deneme her hataya aynı uygulanmaz. Geçici bağlantı problemi ile geçersiz ürün kodu farklıdır. Geçersiz kayıt düzeltilmeden tekrar gönderilirse yalnız yük artar. Kuyrukta işlem kimliği, deneme sonucu ve son hata görünür olur. API limitleri aşılmadan gönderim hızı ayarlanır; karşı tarafın kesintisi kayıp kayıt olarak gizlenmez.
XML aktarımında dosyanın tamamlanmış olması, kodlama, tarih biçimi ve ürün eşleştirmesi kontrol edilir. Boş veya kesilmiş bir dosya bütün stokların sıfırlanması için otomatik kanıt sayılmaz. Veri silme ve toplu değişiklik kuralları ayrıca belirlenir. Belgesiz kurum içi sistemlerde özel API geliştirme değerlendirilir; erişim hakkı ve veri sorumluluğu yine ön koşuldur.
Çalışma süreci
Entegrasyonu teknik erişimden başlayıp işlem mutabakatına kadar izleriz. Her aşamada erişim koşulları, veri anlamı ve işletme ekibinin müdahale edeceği noktalar belirlenir.
Sistem sahiplerini, aktarılacak alanları ve kaynak yetkisini çıkarırız. Örnek kayıtlarla yön, sıklık ve gecikme beklentisi belirlenir; erişim gerektiren hesaplar açıklanır.
API belgeleri, test ortamları ve kullanım hakları incelenir. Sözleşmeli ve faturalı kapsamda dış bağımlılıklar ile sağlanması gereken erişimler ayrı gösterilir.
Kimlik, durum, birim ve tarih eşleştirmesi hazırlanır. Kuyruk, tekrar işleme ve hata sınıfları bu tabloya göre geliştirilir; aynı olayın farklı sıralarda gelmesi ele alınır.
Normal kayıt yanında iptal, kısmi iade, gecikmiş bildirim ve yanıt kesilmesi denenir. Kaynak ve hedef belgeleri karşılaştırılır; belirsiz sonuçların sorgulanması doğrulanır.
Seçilen kanal veya ürün grubuyla aktarım başlatılır. Operasyon ekibi başarısız kayıtları inceler; sonuçlar mutabakatla onaylandıkça akış genişletilir.
Entegrasyon kodu ve akış dokümanı devredilir. Teslim sonrası bir yıl teknik destek koşulları, geliştirilen bağlantının hataları ile sağlayıcının yeni API değişiklikleri ayrıştırılarak açıklanır.
Fiyatlandırma
Entegrasyon bedeli sistem sayısından öte veri anlamlarını uzlaştırma ve hata durumlarını yönetme emeğine bağlıdır. Sağlayıcı erişimleri incelenmeden yalnız marka adları üzerinden kapsam belirlenmez.
Tek bir pazaryeri bağlantısı ile pazaryeri, ERP, kargo ve e-fatura zincirinin tamamı aynı iş yükü değildir.
Sitenizin yazılımı ve kaynak koduna erişim durumu, entegrasyonun siteye mi yoksa ayrı bir ara katmana mı kurulacağını belirler.
Günde bir kez çalışan tek yönlü aktarım ile çift yönlü, anlık senkronizasyon farklı mimari ve test emeği gerektirir.
İyi belgelenmiş, test ortamı sunan bir API hızlı bağlanır; belgesi olmayan sistemlerde keşif ve geliştirme uzar.
Ürün sayısı, varyant yapısı ve tutarsız stok kodları eşleştirme süresini uzatır; kanal bazlı fiyatlama veya çoklu depo gibi kurallar kapsamı büyütür.
Operasyon kuyruğunun takibi, sağlayıcı sürüm değişiklikleri ve yeni kanal ihtiyaçları için sorumluluk ve bakım modeli belirlenir.
Net fiyat için: Kullandığınız sistemleri, aktarılacak bir örnek kaydı ve sorun yaşanan adımı <a href="/teklif-al">paylaşın</a>. Erişim koşulları ve mutabakat ihtiyacı üzerinden bağlantı kapsamını çıkaralım.
Ücretsiz Teklif AlReferanslar
Aşağıdaki siteler şu anda yayında; adreslerine gidip kendiniz inceleyebilirsiniz.
Tüm referanslarSıkça sorulanlar
Dış sipariş veya olay kimliği korunur. Tekrar gelen veri mevcut işlemle ilişkilendirilir; ikinci sipariş oluşturulmaz. Sipariş revizyonu ile aynı olayın tekrarı ayrı tanımlanır. Sağlayıcının kimlik modeli bu kontrolün nasıl kurulacağını belirler.
Stok kaynağı başlangıçta kararlaştırılır. Kullanılabilir, fiziksel ve rezerve stok aynı alan olmayabilir. Eşleştirme ve hesap yöntemi yazılır; fark raporu operasyon ekibine gösterilir. İki tarafın birbirini sürekli güncellemesi çözüm olarak varsayılmaz. Kaynak ayrımını değerlendirmek için kullandığınız ERP sürümünü ve stok örneğini iletebilirsiniz.
Önce sonuç belirsiz mi yoksa kesin başarısız mı ayrılır. Kayıt karşı tarafta oluşmuş olabilir. Destekleniyorsa işlem kimliğiyle sorgulama yapılır; güvenli tekrar koşulu sağlanmadan yeni kayıt gönderilmez. Geçersiz veri hataları düzeltme kuyruğuna gider.
Desteklenen API, eklenti veya dosya erişimi incelenir. Ayrı ara katman bazı durumlarda uygundur. Erişim hakkı olmayan kapalı sistemde bağlantı vaat edilmez. Kaynak değişikliği ve barındırma koşulları teknik değerlendirmede açıklanır.
Güncel yükümlülükler ve belge kuralları mali müşavir ile ilgili entegratör üzerinden teyit edilir. Yazılım bu kararları uygulayan teknik akışı kurar. Sipariş iptali, fatura iptali ve iade belgesi aynı durum değildir; ayrı senaryolarla tanımlanır.
Anahtarlar kaynak dosyalarından ayrı, kısıtlı erişimle tutulur. Gerekli yetkiler seçilir; gizli değerler işlem kayıtlarına yazılmaz. Anahtar yenileme ve iptal yöntemi belirlenir. Kişisel verinin gereksiz alanlara kopyalanması önlenmeye çalışılır.
Duyuru, geçiş tarihi ve etkilenen işlemler incelenir. Yeni sürüm test ortamında mevcut eşleştirmelerle karşılaştırılır. Uyarlamanın kapsamı ve yayın planı belirlenir; sağlayıcı değişikliği sessizce tamamlandı kabul edilmez. Operasyon ekibi geçiş etkisi hakkında bilgilendirilir.
Birlikte düşünün
Blog
API bağlantısında veri sözleşmesini, yetkileri ve hata yönetimini belirleyin.
Pazaryeri ürün eşlemesini, stok akışını ve aktarım hatalarını planlayın.
Siparişten faturaya belge durumlarını ve iptal akışını birlikte tasarlayın.
Teklif alın
İhtiyacınızı netleştirelim
HazırSoft destek ekibi sizinle ilgilenecek. Bilgilerinizi bırakın, hemen sohbete başlayalım.