ETA V.11 API ile E-Ticaret Siparişi Aktarımı: Lisans ve İstek Sınırı

ETA V.11 API ile sipariş aktarımı kimler için mümkün?

ETA V.11 API ile sipariş aktarımı, güncel ETA:V.11 sürümünü kullanan ve lisansında API Entegrasyon opsiyonu bulunan firmalar için mümkündür. ETA Bilgisayar, V.11 için "ETAV11 REST API" adlı bir REST API yayımlıyor; belge ETA Bilgi Merkezi'nde herkese açık ve OpenAPI tanımı indirilebiliyor. Belgenin kendi ifadesiyle API, güncel ETA versiyonu ile API Entegrasyon opsiyonu ve kullanıcı lisans sayısına bağlı olarak çalışıyor.

ETA:SQL ve ETA:V.8-SQL için bu API'nin geçerli olduğuna dair bir belge bulamadık. Bu sürümlerde yol, okuma için ODBC, yazma için Transfer ve Veri Aktarma modülleridir. Hangi sürümde olduğunuz bu yüzden ilk sorudur.

Lisans durumu ve opsiyon fiyatı yetkili ETA bayinizin alanıdır. Biz entegrasyonun kaç oturum açacağını hesaplayıp bu görüşmeye veri sağlarız, lisans satmayız.

Eski sürümler için Transfer yolu

ETA:SQL ya da V.8-SQL kullanıyorsanız sipariş ve fatura aktarımı Transfer ve Veri Aktarma modülleriyle dosya üzerinden kurulur. Desteklenen biçimler TXT, XLS, CSV ve XML'dir; iki modül de ayrı lisans kalemidir.

Bu yolda entegrasyon, kaynaktaki siparişleri belirli aralıklarla ETA'nın beklediği dosya düzenine çevirir ve ilgili modülle aktarıma hazırlar. Bu yolda doğrulama aktarımdan sonra da yapılır: aktarılan belge sayısı ve toplamları kaynakla karşılaştırılır, fark çıkan dosya listelenir. Dosya düzeni değiştiğinde iş çoğu zaman kod değişikliği değil, tanım güncellemesi olur.

V.11'de de API belgesinde yer almayan kayıtlar için bu modüller kullanılmaya devam eder. Sipariş trafiği yoğunsa V.11'e geçiş, belirli aralıklarla dosyayla çalışan akışı kayıt bazında ve Kontrol metoduyla doğrulanan bir akışa çevirebilir. Geçiş kararı ve lisans bayinizin alanıdır.

Oturum, lisans ve yetki: entegrasyon bir kullanıcı gibi çalışır

ETA V.11 API'de her bağlantı bir oturumla başlar ve her oturum bir kullanıcı lisansı tutar. EtaLogin isteğinde lisansın set ve ürün numarası, programın kurulu olduğu klasör, API kullanıcısının kodu ve şifresi, şirket kodu, şirket dönemi, işyeri kodu ve program ile API sürüm numaraları gönderilir. Karşılığında süresi belli bir token döner; sonraki istekler bu token ile yapılır, token yoksa ya da süresi dolmuşsa istek reddedilir.

Bu yapının sipariş aktarımına üç sonucu vardır:

1. Şirket ve dönem oturumla seçilir. Siparişin hangi şirkete ve hangi döneme yazılacağı oturum açılırken belirlenir. Yıl dönümünde yeni dönemin nasıl seçileceği baştan yazılmazsa, yeni yılın ilk siparişleri eski dönemin oturumuyla gönderilir.
2. Oturum bir lisans koltuğudur. Belgeye göre EtaLogout, oturumla birlikte kullanıcı lisans bağlantısını da kapatıyor. Entegrasyon oturumu açık unutursa, ofiste aynı anda programa girmek isteyen biri lisans bulamayabilir. Bu yüzden entegrasyon tek oturum açar, bekleyen işleri bitirir ve oturumu kapatır.
3. Hatalı girişler kilit üretir. Varsayılan ayarda 60 saniye içinde 3 başarısız giriş denemesi sınırı vardır; sınır aşılınca doğru bilgilerle yapılan giriş bile süre dolana kadar işlenmez. API kullanıcısının şifresi değiştiğinde entegrasyon art arda yeniden denerse kendini kilitler. Şifre hatası alındığında yeniden deneme durdurulur ve sorumluya bildirim gider.

Silme uç noktaları için yetkisi dar bir kullanıcı

ETA V.11 API'de kartlar ve belgeler için silme metotları da bulunur; sipariş, fatura ve irsaliye için Sil işlemi belgede tanımlıdır. Bir entegrasyonun yanlış bir parametreyle kayıt silebilmesi kabul edilebilir bir risk değildir.

Bu yüzden ETA'da API için ayrı bir kullanıcı tanımlanmasını ve bu kullanıcının yalnızca entegrasyonun gerçekten ihtiyaç duyduğu işlemlere yetkili olmasını öneriyoruz. Yazdığımız kodda silme çağrısı, açıkça istenmedikçe yer almaz. Pazaryerinde iptal edilen bir sipariş için kayıt silmek yerine, iptalin ETA'da nasıl karşılanacağı mali müşavir ve muhasebe ekibiyle kararlaştırılır.

API kullanıcısının ayrı olmasının bir faydası daha var: bir personel işten ayrıldığında ya da şifresini değiştirdiğinde entegrasyon durmaz.

Sipariş mi, fatura mı? ETA'ya hangi belge yazılmalı?

Siparişin ETA'ya sipariş fişi olarak mı yoksa fatura olarak mı yazılacağı, hazırlık ve sevkiyatın nerede izlendiğine bağlıdır. API belgesinde sipariş, irsaliye ve fatura için aynı beş işlem bulunur: Ekle, Kontrol, Listele, Oku ve Sil.

Sipariş fişi modelinde entegrasyon açısından önemli alanlar belgede açıkça tanımlı: cari kodu, depo kodu, evrak numarası alanları, rezerv ayırma seçeneği, KDV dahil fiyat seçeneği, sevk ve fatura adresi alanları, taşıyıcı takip numarası. Satırlarda stok kodu ve barkod, birim, miktar, fiyat, beş kademe iskonto ve renk-beden boyutları bulunuyor.

Satır tipi alanı, entegrasyon için en kullanışlı ayrıntılardan biridir. Belgeye göre bir satır stok kartı, hizmet kartı, açıklama satırı, indirim satırı ya da masraf satırı olabiliyor. Müşteriden alınan kargo ücreti bu sayede ürün satırlarının yanına hizmet satırı olarak eklenebilir. Hangi kalemin nasıl kaydedileceği ise mali müşavirinizle belirlenir.

e-Fatura ve e-Arşiv tarafı

Fatura modelinde e-Fatura senaryosu, belge durumu ve yanıt bilgileri için alanlar, cari kartta da e-Fatura senaryosu ve posta kutusu alanları bulunuyor. Faturanın GİB'e gönderim adımını API'nin kendisinin yapıp yapmadığı ise belgede yazmıyor. Bu adım, kurulumunuzdaki e-Dönüşüm akışına göre bayinizle teyit edilir; entegrasyon tasarımı bu teyitten sonra tamamlanır.

Kontrol metodu: kaydetmeden önce sor

Kontrol metodu, belgeyi kaydetmeden önce ETA'nın hesapladığı değerleri ya da bulduğu hatayı döndüren bir ön kontrol adımıdır. ETA'nın belgesindeki tanımıyla bu metot kayıt öncesi fiş alanlarını hesaplar ve kontrolleri yapar. E-ticaret siparişinde bu, iki sistemin aynı toplamı bulup bulmadığını kayıttan önce görmenin yoludur.

Önerdiğimiz akış şöyledir:

1. Sipariş kaynaktan okunur, stok kodu ve cari eşleştirmesi yapılır. Eşleşmeyen satır varsa sipariş bekleme listesine düşer.
2. Sipariş Kontrol metoduna gönderilir.
3. ETA'nın döndürdüğü genel toplam, KDV ve iskonto tutarı kaynaktaki tutarla karşılaştırılır.
4. Fark yoksa sipariş Ekle ile kaydedilir; fark varsa kayıt yapılmaz ve fark nedeniyle birlikte listeye düşer.
5. ETA'nın döndürdüğü kayıt bilgisi, kaynak sipariş numarasıyla birlikte entegrasyonun kendi eşleşme tablosuna yazılır.
6. Aynı sipariş ikinci kez gelirse eşleşme tablosuna bakılır, ETA'ya yeniden yazılmaz.

Beşinci ve altıncı adım mükerrer kaydı önler. Ağ kesildiğinde ya da yanıt zaman aşımına uğradığında, siparişin ETA'da oluşup oluşmadığı Listele metoduyla filtre ve sayfalama kullanılarak doğrulanabilir. Kaynak sipariş numarasını sipariş fişinin evrak numarası ya da açıklama alanlarından birinde taşımak bu doğrulamayı kolaylaştırır; hangi alanın kullanılacağı kurulumunuzdaki numaralandırma düzenine göre seçilir.

Kuruş farkları çoğunlukla yuvarlama ve KDV dahil ya da hariç fiyat seçiminden doğar. Örnek senaryo: web sitesi KDV dahil satır fiyatını iki ondalıkla yuvarlıyor, sipariş ise ETA'ya KDV hariç fiyatla gönderiliyor. Kontrol adımı bu farkı kayıttan önce gösterir; hangi tarafın kuralının esas alınacağı bir kez kararlaştırılır.

İstek sınırı: kampanya gününü hesaplayın

ETA V.11 API'nin varsayılan ayarında aynı IP adresi 60 saniyede en fazla 60 istek gönderebilir; sınır aşılınca istek reddedilir. Bu değerler API'nin kendi ayar dosyasından değiştirilebilir ve değişiklik için API servisi yeniden başlatılır. Yani API, ETA'nın kurulu olduğu ortamda sizin kontrolünüzde çalışan bir servistir, bir bulut hizmeti değildir.

Diyelim ki bir kampanya gününde 600 sipariş geldi ve her sipariş için bir Kontrol ve bir Ekle isteği gönderiliyor. Bu 1.200 istek eder; varsayılan sınırla bu iş en az 20 dakika sürer. Mükerrer kontrolü için ayrıca Listele çağrılırsa süre uzar. Aynı sınırı stok ve fiyat okuma istekleri de paylaştığı için bunlar da hesaba katılır.

Bunun pratik sonuçları şunlardır:

• Siparişler bir kuyruğa alınır ve sınıra uygun hızda işlenir; kuyruğun uzunluğu izlenir.
• Stok ve fiyat yalnızca değişen kayıtlar için okunur; tüm kartları her seferinde çekmek sınırı boşa harcar.
• Toplu raporlama ve yıllar boyu karşılaştırma API yerine ODBC ile yapılır.
• API dışarıdan erişileceği için ağ ve güvenlik duvarı kurgusu bilgi işlem sorumlunuzla birlikte yapılır.
• Belgede API servisinin çalışma durumunu bildiren bir durum metodu da var; entegrasyon bu metodu düzenli sorgulayarak servisin ayakta olup olmadığını izleyebilir.

Başlamadan önce kontrol listesi

ETA entegrasyonu için geliştirmeye başlamadan önce şu maddelerin yazılı olarak netleşmesi gerekir:

• ETA ürün ve sürüm bilgisi, Hakkında ekranındaki versiyon dahil
• Lisansta API Entegrasyon opsiyonu ve boşta kullanıcı lisansı olup olmadığı
• API servisinin çalışacağı makine, ağ erişimi ve güvenlik duvarı kurgusu
• Ayrı API kullanıcısı ve yetkileri, silme yetkisi dahil
• Şirket kodu, dönem ve işyeri; dönem geçişinin nasıl yapılacağı
• Siparişin sipariş, irsaliye ya da fatura olarak mı yazılacağı
• e-Fatura ve e-Arşiv gönderiminin hangi akışla yapılacağı
• Stok kodu ve cari eşleştirme kuralları, kargo ve indirim satırlarının kaydı
• Kampanya günü için beklenen sipariş sayısı ve istek sınırı ayarı

Sıkça Sorulan Sorular

ETA'nın e-ticaret entegrasyonu için API'si var mı?

ETA:V.11 için var. ETA Bilgisayar, "ETAV11 REST API" adlı belgelenmiş bir REST API yayımlıyor; sipariş, irsaliye ve fatura için ekleme, kontrol, listeleme, okuma ve silme işlemleri tanımlı. API güncel V.11 sürümü, lisansta API Entegrasyon opsiyonu ve kullanıcı lisansı istiyor.

ETA V.11 API'si ETA:SQL veya V.8-SQL'de çalışır mı?

Bu sürümler için API'nin geçerli olduğuna dair bir belge bulamadık. Bu kurulumlarda sipariş ve fatura aktarımı Transfer ve Veri Aktarma modülleriyle TXT, XLS, CSV ya da XML dosyası üzerinden kurulur. Okuma tarafı ODBC ile yapılır.

API oturumu neden bir kullanıcı lisansı kullanıyor?

ETA'nın belgesine göre oturum açma kullanıcı lisans sayısına bağlı ve oturum kapatma kullanıcı lisans bağlantısını da kapatıyor. Pratikte entegrasyon, programı kullanan bir kişi gibi bir koltuk tutar. Bu yüzden entegrasyon tek oturumla çalışır ve işini bitirince oturumu kapatır; ihtiyaç duyulan lisans sayısı bayinizle birlikte hesaplanır.

Dakikada 60 istek sınırı yetmezse ne yapılır?

Önce istek sayısı azaltılır: yalnızca değişen kayıtlar taşınır, toplu raporlar ODBC'ye alınır, siparişler kuyruğa konur. Bu yeterli değilse sınır, API'nin ayar dosyasından değiştirilebilir ve değişiklik servis yeniden başlatılınca geçerli olur. Ayarı değiştirmeden önce sunucunun bu yükü kaldırıp kaldırmadığı bilgi işlem sorumlunuzla birlikte değerlendirilir.

ETA API'si faturayı GİB'e de gönderiyor mu?

Fatura modelinde e-Fatura senaryosu ve belge durumu için alanlar bulunuyor, ancak gönderim adımını API'nin kendisinin yapıp yapmadığı belgede yazmıyor. Bu konu kurulumunuzdaki e-Dönüşüm akışına göre yetkili bayinizle teyit edilir. Entegrasyonun faturayı hangi aşamaya kadar taşıyacağı bu teyitten sonra netleşir.

Sonraki adım: kurulumunuzu birlikte okuyalım

ETA:V.11 kullanıyorsanız ve siparişleri elle giriyorsanız, ilk adım yukarıdaki kontrol listesini sizin kurulumunuz üzerinde doldurmaktır. ETA Bilgisayar'ın bayisi değiliz; lisans ve opsiyon bayinizin alanında kalır, biz ETA'nın belgelenmiş API'si ya da aktarım modülleri üzerinden çalışan entegrasyonu yazarız. Kapsam ve fiyat sözleşmede yazılıdır, teslim sonrası 15 gün ücretsiz hata düzeltme standardımızdır. İlk keşif görüşmesi online ve ücretsizdir; iletişime geçin ya da isterseniz WhatsApp'tan yazın.