E-ticaret sitenizi ERP ve e-faturaya bağlarken karar, çoğu firmanın sandığından daha basit bir soruya iner: mağazanız hazır bir entegratörün desteklediği platformlardan biri mi, yoksa kod tabanlı/özel bir yapı mı? Cevabınız birinciyse, çoğu durumda hazır entegratör (Entegra, Sopyo, Sentos gibi) yeterlidir: aylık abonelik artı belge başına kontör ödersiniz, kurulum hızlıdır, bakım yükü sizde değildir. Cevabınız ikinciyse — yani WooCommerce/Shopify/İkas gibi adı listelenmiş bir platformda değilseniz — hazır entegratörlerin "mutlu yolu" sizi kapsamaz ve özel bir API köprüsü yazdırmak (veya bir entegratörün API'sini kendi köprünüzden çağırmak) tek sağlıklı yol olur. Kritik teknik gerçek şudur: Türkiye'de e-Fatura/e-Arşiv, GİB'in zorunlu kıldığı yapılandırılmış bir XML belgesidir — PDF/tarama üzerinden OCR yapılmaz; belge programatik olarak üretilir ve saniyeler içinde iletilir. Yani "fatura entegrasyonu" bir görüntü tanıma değil, etiketli XML üretme/ayrıştırma işidir. Aşağıda kararı bir slogan değil, ölçülebilir bir karar matrisi ve toplam sahip olma maliyeti (TCO) mantığıyla veriyoruz. Sakarya merkezli bir B2B / white-label yazılım firması olarak bu tercihi ajans sahipleri ve kurumsal alıcılar için sürekli yaptığımız için, kullandığımız çerçeveyi olduğu gibi paylaşıyoruz.
Bu yazıda genel "entegrasyon iyidir" nutku yerine mekaniğe iniyoruz: e-faturanın XML gerçeği, neyin gerçekten senkronlanması gerektiği (stok, fiyat, sipariş, fatura, iade), hazır entegratörün artı/eksileri, özel köprünün artı/eksileri, bir karar matrisi ve son olarak "kontör mü, geliştirme+bakım mı?" TCO düşüncesi. Konuyu daha önce özel yazılım vs hazır yazılım ve şirkete özel ERP/CRM yazılarında genel çerçevede ele aldık; burada e-ticaret + ERP + e-fatura üçgenine özel bir katman ekliyoruz.
E-faturanın XML gerçeği: burada OCR yoktur
En yaygın yanlış varsayım, e-fatura entegrasyonunu "faturayı okutup sisteme aktarma" gibi düşünmektir. Türkiye'de durum farklıdır. GİB, e-Fatura/e-Arşiv için UBL-TR adlı yapılandırılmış bir XML standardını benimsemiştir; belgeler bu şema paketine göre (UTF-8 kodlamayla) hazırlanır. API entegrasyonu, sipariş/satış/ERP yazılımınızın GİB'e ya da bir özel entegratörün web servisine bağlanıp faturayı insan müdahalesi olmadan oluşturması, göndermesi ve durumunu izlemesi demektir — belge uçtan uca makine-yapılandırmalı XML olduğu için ne düzenlemede ne de gelen faturada bir OCR adımı yoktur.
Bunun pratik sonucu şudur: entegrasyonun kalbi, satır kalemleri, vergi oranları, cari (alıcı) bilgileri ve belge tipi gibi alanları doğru XML alanlarına haritalamaktır. GİB'in kendi resmi tanımına göre, e-Fatura üç yöntemle kesilebilir: e-Fatura Portalı, Entegrasyon (mükellefin kendi sisteminin 7/24 doğrudan bağlanması) ve Özel Entegrasyon/Özel Entegratör. Özel entegratör, GİB'in resmi ifadesiyle "teknik yeterliliğe sahip bir özel entegratörün bilgi işlem sistemi vasıtasıyla" mükellef adına e-fatura alıp göndermeye yarar; GİB testlerinden geçmiş ve onaylanmış olması gerekir (GİB — Özel Entegratörlük). Pratikte özel entegratör, GİB bağlantısını ve altyapısını üstlenip size çoğunlukla bir REST API açar. Bu ayrım, "hazır entegratör mü özel köprü mü" kararınızın da zeminidir; API tarafını API entegrasyon hizmeti kapsamında ele alıyoruz.
Aslında neyin senkronlanması gerekiyor?
Bir e-ticaret ↔ ERP ↔ e-fatura köprüsü tek bir "veri aktarımı" değildir; birbirinden farklı yaşam döngüleri olan beş akıştır. Hangi çözümü seçerseniz seçin, bu beşini de modellemek zorundasınız:
- Stok: Genellikle çift yönlü. ERP'deki adet değişimi siteye, sitedeki satış ERP'ye yansımalı. Aksi halde tükenen ürünü satmaya devam edersiniz.
- Fiyat & ürün: Fiyat/ürün tanımı çoğu kurulumda ERP'den siteye iner; kampanya fiyatları burada özel dikkat ister.
- Sipariş: Siteden ERP'ye akar. Kritik nokta: bu akış çoğu bağlayıcıda gerçek zamanlı push değil, aralıklı polling ile çalışır (aşağıda ayrıntısı).
- Fatura: Sipariş → fatura dönüşümü. Burada e-Fatura/e-Arşiv/e-SMM belgesi programatik üretilir ve GİB'e resmen tescillenir.
- İade: En çok atlanan akış. Kesilmiş bir e-Faturayı "silmek" mümkün değildir; iade/kısmi iade ayrı bir muhasebe belgesiyle (iade faturası) modellenir.
Bu beş akışın gecikme ve tutarlılık gereksinimleri farklıdır. Örneğin sipariş senkronunda birçok ERP entegrasyonu toplu/polling mantığıyla çalışır: IdeaSoft ve benzeri bağlayıcıların dokümanlarına göre, siteden gelen siparişler Mikro ERP'ye güvenli bir web-servis katmanı üzerinden yaklaşık 15 dakikalık aralıklarla düşer (doğrudan veritabanı erişimiyle değil), stok/ürün/fiyat çift yönlü senkronlanır (IdeaSoft — Mikro entegrasyonu). Bu ~15 dakika, bir bağlayıcı-uygulama davranışıdır, "Mikro" platformunun garantisi değil; üstelik "Mikro" farklı ürün hatlarını (Jump/Fly/eski sürümler) kapsar ve entegrasyon yüzeyleri değişir. Sipariş→fatura gecikmesini planlarken bu polling gerçeğini hesaba katmanız gerekir.
Idempotency: köprünün en sinsi mühendislik riski
Senkron polling ile çalıştığı ve e-Fatura/e-Arşiv belgeleri GİB'de bir kez tescillendiği için, naif bir köprü yeniden deneme (retry) veya tekrarlanan sipariş webhook'unda çift fatura kesebilir. Bu, hukuki bir belgeyi mükerrer üretmek demektir — hem müşteri hem mali açıdan sorunludur. Sağlam bir köprü, sipariş başına idempotency anahtarı, tam-olarak-bir-kez (exactly-once) fatura oluşturma ve e_invoice_sent/e_archive_sent gibi durum bayraklarının dikkatli yönetimini şart koşar. Bu, GİB'in tescilli-belge modelinden ve gözlemlenen polling davranışından türeyen doğrudan bir mühendislik gereksinimidir. Sanal POS tarafında benzer webhook/idempotency titizliğini sanal POS entegrasyonu rehberimizde ele almıştık; aynı disiplin fatura akışında da geçerlidir.
Hazır entegratör: artıları ve eksileri
Hazır entegratörler (Entegra, Sopyo, Sentos, İkas gibi) ERP/ön-muhasebe hedeflerine (Logo, Netsis, Mikro, Paraşüt ve dahası) ve e-fatura sistemine köprü kurar; ama desteği, sabit bir çoğunlukla-SaaS e-ticaret platformları listesi etrafında kuruludur. Örneğin Entegra; Logo, Netsis, Mikro, SAP, ETA, Zirve, DİA, Nebim, Paraşüt, Link, Microsoft Dynamics gibi ERP hedeflerini ve IdeaSoft, Ticimax, OpenCart, T-Soft, Hipotenüs, WooCommerce, Shopify, PrestaShop, Magento gibi e-ticaret platformlarını çift yönlü bağlar; tek tıkla sipariş→fatura, çift yönlü stok/fiyat senkronu ve otomatik cari oluşturma sunar (Entegra — e-ticaret entegrasyonu). Sopyo da benzer şekilde Shopify, WooCommerce, IdeaSoft, İkas, Ticimax gibi platformları Logo/Mikro/Paraşüt ve e-fatura hedefleriyle listeler.
| Artılar | Eksiler |
|---|---|
| Hızlı kurulum; kod yazmadan sipariş→fatura, stok/fiyat senkronu, otomatik cari. | Yalnızca adı listelenmiş platformları destekler; özel/kod tabanlı mağaza "mutlu yolun" dışındadır. |
| Bakım yükü sağlayıcıda: API sürüm değişimleri, GİB uyumu onların sorunu. | Tekrarlayan maliyet: abonelik + belge başına kontör; hacim arttıkça artar. |
| Birçok ERP/e-fatura hedefiyle hazır uyum; test yükü sizde değil. | Sınırlı özelleştirme; kendine özgü iş kuralları/alan haritaları için esneklik dar. |
| Küçük/orta hacim ve standart akışlar için düşük giriş maliyeti. | Kampanya/Black-Friday zirvesi kontör tüketimini ve hacim/limit riskini doğrudan yükseltir. |
Asıl boşluk burada: bu bağlayıcılar adı geçen, çoğunlukla-SaaS platformları hedefler ve tam özel/kod tabanlı mağazalar için destek listelemez. Sentos'un entegrasyon sayfası yalnızca belirli platformları (İkas, Ticimax, Shopify, IdeaSoft, Hipotenüs, T-Soft, OpenCart, WooCommerce, Ethica) listeler ve özel/tescilli yazılımdan söz etmez (Sentos — B2C entegrasyon). Benzer şekilde İkas'ın ön muhasebe/ERP entegrasyonları (Logo İşbaşı, Mikro, Nebim, Uyumsoft, Akınsoft Wolvox, DİA, Microsoft Dynamics, Netsis, Zirve, Link, ücretsiz BirFatura/Bizim Hesap vb.) mevcuttur — ama bunlar var çünkü İkas'ın kendisi barındırılan (hosted) SaaS platformudur; entegrasyon yüzeyi İkas-platformu ile ERP arasındadır, dolayısıyla kod tabanlı özel bir mağaza İkas üzerine geçmeden bunu yeniden kullanamaz (İkas — ön muhasebe entegrasyonları).
Özel API köprüsü: artıları ve eksileri
Özel köprü, sitenizin (veya ara servisinizin) doğrudan ERP'nin ve bir özel entegratörün/muhasebe platformunun API'lerini çağırdığı, iş kurallarınıza göre yazılmış bir katmandır. Modern hedeflerin API'leri buna elverişlidir. Örneğin Paraşüt, resmi bir REST API'si (v4) sunar; kimlik doğrulama için OAuth2 kullanır (host api.parasut.com, basePath /v4). Yetkilendirme /oauth/authorize ve /oauth/token uçlarından geçer; access_token Bearer tipindedir ve 2 saat içinde geçerliliğini yitirir, refresh_token ile yenilenir. Spesifikasyon üç OAuth2 grant tipini belgeler: authorization_code, password ve refresh_token; varsayılan yönlendirme adresi urn:ietf:wg:oauth:2.0:oob'dur (Paraşüt — resmi API dokümanı (swagger)).
Daha da önemlisi, Paraşüt API'si e-Fatura, e-Arşiv ve e-SMM kaynaklarını doğrudan açar: /{company_id}/e_invoices, /{company_id}/e_archives, PDF için .../pdf uçları ve fatura durum enum'u (printed, not_printed, invoices_not_sent, e_invoice_sent, e_archive_sent, e_smm_sent) belgelidir. Yani programatik fatura oluşturma ve PDF alma için ayrı bir OCR/belge adımına gerek yoktur. ERP tarafında ise Logo Netsis, resmi dokümantasyonunda "NetOpenX Rest" adıyla bir REST API sunar; bu API, NetOpenX işlevlerini standartlaştırarak web/mobil entegrasyonu için iş mantığını bozmadan ERP'ye veri itip çekmeyi sağlar (Logo — Netsis uyarlama araçları). Bu API'nin varlığı ve işlev kapsamı doğrulanmıştır; kesin kimlik doğrulama mekanizmasını (token mu, oturum mu) burada iddia etmiyoruz — kendi auth'u olan bir REST API olarak konumlandırmak yeterlidir.
| Artılar | Eksiler |
|---|---|
| Özel/kod tabanlı mağazayla çalışır; hazır listeye bağlı değilsiniz. | Peşin geliştirme maliyeti + sürekli bakım (API sürüm değişimi, retry, senkron sapması). |
| İş kurallarına tam uyum: alan haritası, idempotency, iade akışı sizin kontrolünüzde. | Doğru mühendislik gerektirir; OAuth token yenileme, hata/kuyruk yönetimi ihmal edilmemeli. |
| Kontör dışındaki mimariyi siz kurgularsınız; sağlayıcı kilidine mahkûm değilsiniz. | GİB/mevzuat ve entegratör API değişikliklerini kendi takviminizde takip zorunluluğu. |
| Hacimden bağımsız, öngörülebilir mimari; sürüm ve gözlemlenebilirlik sizde. | Not: e-fatura belgeleri yine bir özel entegratör/GİB üzerinden geçer; kontör kalemi çoğunlukla kaybolmaz. |
Not: Özel köprü "kontörden tamamen kurtulmak" demek değildir; e-fatura belgeleri yine GİB'e/özel entegratöre gider ve orada belge başına kontör tüketilir. Özel köprünün kazandırdığı, orkestrasyon ve iş mantığı katmanının size ait olmasıdır — hangi platformda olursanız olun. Özel köprü işini özel web yazılımı ve CRM/ERP çözümleri kapsamında birlikte yürütüyoruz.
Karar matrisi: hazır ne zaman yeter, özel ne zaman şart?
Kararı sezgisel kılmak için tek satırlık kurallar:
| Durum | Eğilim | Gerekçe |
|---|---|---|
| Mağaza, entegratörün listelediği bir SaaS platformda (WooCommerce, Shopify, İkas, Ticimax…) | Hazır entegratör | Mutlu yol kapsıyor; kurulum hızlı, bakım sağlayıcıda. |
| Tam özel / kod tabanlı mağaza, listelenmemiş yapı | Özel köprü | Hazır bağlayıcılar bu mağazayı kapsamaz; ERP/entegratör API'sini kendiniz çağırırsınız. |
| Standart akış, düşük özelleştirme, orta hacim | Hazır entegratör | Özel kurallar yoksa peşin dev maliyetine gerek yok. |
| Kendine özgü iş kuralları (özel iade mantığı, B2B fiyatlandırma, çok mağaza/çok cari) | Özel köprü | Alan haritası, idempotency, iade faturası akışı tam kontrol ister. |
| Çok yüksek/dalgalı hacim, sıkı SLA | Genellikle özel (veya melez) | Kontör ve limit yönetimi ile kuyruk/retry mimarisi öngörülebilirlik ister. |
Karar "hangisi daha iyi" değil, "mağazanız hangi kutuya düşüyor"dur. Listelenmiş bir SaaS platformdaysanız hazır entegratör çoğu zaman yeter; özel/kod tabanlı bir mağaza ya da kendine özgü iş kurallarınız varsa özel köprü bir tercih değil, gerekliliktir.
İade akışını hafife almayın
Hangi yolu seçerseniz seçin, iadeyi ayrı modellemek zorundasınız. Kesilmiş bir e-Fatura/e-Arşiv GİB'de tescillendiği için basitçe "silinemez": kısa bir iptal penceresi içinde e-Arşiv iptal edilip GİB'e raporlanabilir, o pencere kapandıktan sonra düzeltme/iade bir iade (credit) belgesiyle yapılır (Paraşüt — e-Arşiv iptal vs iade). Tam ve kısmi iadenin ayrı ayrı ele alınması; stok, cari bakiye ve vergi kayıtlarının tutarlı kalması için şarttır. İptal penceresinin gün sayısını burada kesin bir kural gibi vermiyoruz — kaynaklar farklılaşır; net bir süre gerekiyorsa güncel GİB e-Arşiv tebliğ/kılavuzunu esas alın.
TCO düşüncesi: kontör mü, geliştirme + bakım mı?
Karar aslında bir maliyet biçimi tercihidir: hazır entegratör tekrarlayan (abonelik + belge başına kontör) bir gider, özel köprü ise peşin geliştirme + sürekli bakım gideridir. Rakamlar 2026 itibarıyla dalgalıdır ve sağlayıcıya/hacme göre değişir; bu yüzden aşağıdakileri kesin fiyat değil, yaklaşık pazar aralıkları olarak okuyun.
- Kontör (belge başına dijital kredi): Genellikle her giden belge için ~1 kontör harcanır (bazı sağlayıcılar geleni de ücretlendirir). 2026 pazar-karşılaştırma verilerine göre ana akım sağlayıcılarda kontör birim fiyatı ortalama yaklaşık 0,75–1,50 TL/belge aralığındadır; ERP-entegre kurumsal entegratörlerde bu belge başına daha yüksek (bildirilen ~5–10 TL) olabilir (Faturaport — 2026 kontör fiyatları (resmi liste değil)). Bunlar resmi vendor fiyatı değil, tarihli pazar karşılaştırmasıdır.
- Abonelik: Faturaport'un 2026 maliyet rehberi abonelik bandlarını yıllık verir (örn. yalnız e-fatura ~300–1.500 TL/yıl; KOBİ ~1.500–6.000 TL/yıl; kurumsal ~6.000–50.000+ TL/yıl, teklif bazlı), ayrıca yinelenen mali mühür/e-imza sertifika maliyetleri vardır (Faturaport — 2026 e-fatura maliyet rehberi (resmi liste değil)). Bu bandlar da yaklaşık ve sağlayıcıya bağlıdır.
- Hacim duyarlılığı: Kontör ve abonelik hacimle arttığı için, bir kampanya/Black-Friday zirvesi kontör tüketimini doğrudan yükseltir ve hacim/limit sınırlarına yaklaştırabilir.
Özel köprü bu tekrarlayan modeli, peşin geliştirme + süregelen bakımla takas eder: API sürüm değişiklikleri, retry/kuyruk mantığı ve senkron sapması gibi kalemler zamanla maliyet üretir. Odak noktanız birim fiyatı ezberlemek değil, mekanizmayı anlamak olmalı: belge hacminiz büyük ve öngörülebilirse tekrarlayan kontör kalemi zamanla peşin dev+bakım maliyetini geçebilir; hacminiz düşük veya platformunuz zaten destekliyse hazır entegratör açık ara ekonomiktir. Genel çerçeveyi özel vs hazır yazılım yazımızdaki mantıkla birlikte değerlendirmek, bu takası netleştirir.
Partnerfy'ın B2B / white-label yaklaşımı
Sakarya merkezli bir B2B / white-label yazılım mühendisliği firması olarak bu kararı bir "vaat" değil, bir süreç olarak veriyoruz: önce mağazanızın hangi kutuya düştüğünü teşhis ederiz (listelenmiş SaaS mı, özel/kod tabanlı mı, kendine özgü iş kuralları var mı), sonra beş akışı (stok/fiyat/sipariş/fatura/iade) haritalar, ardından ya bir hazır entegratörü doğru konumlandırır ya da idempotency ve iade akışı doğru kurulmuş bir özel API köprüsü yazarız. Ajanslar için white-label modelde bu köprüyü sizin markanız altında teslim eder; kurumsal alıcılar için e-ticaret sistemleri ile CRM/ERP çözümlerini tek gözlemlenebilir hat üzerinde birleştiririz.
Dürüst olmak gerekirse: hiçbir köprü, kontörü sıfırlamayı ya da GİB mevzuatının hiç değişmemesini garanti edemez — bunlar dış değişkenlerdir. Bizim sözümüz garanti değil, zemin: tam-olarak-bir-kez fatura kesen, iadeyi ayrı belgeyle modelleyen, token yenileme ve retry'ı ihmal etmeyen, hacim zirvelerini kaldıran bir mimari. Kod tabanı, özel iş kuralı veya beklenmedik ERP hattı olan işleri de özel web yazılımı tarafında karşılarız.
Sonuç
E-ticaret ↔ ERP ↔ e-fatura köprüsünde doğru soru "hangisi daha iyi" değil, "mağazam hangi kutuya düşüyor"dur. Listelenmiş bir SaaS platformdaysanız ve akışlarınız standartsa, hazır entegratör çoğu zaman yeter — tekrarlayan abonelik + kontör bedeline razı olmak koşuluyla. Özel/kod tabanlı bir mağazanız ya da kendine özgü iş kurallarınız varsa, özel API köprüsü bir lüks değil gerekliliktir. Her iki durumda da e-fatura bir OCR işi değil, UBL-TR XML işidir; idempotency ve iade akışını doğru modellemek pazarlık konusu değildir. Nereden başlayacağınızdan emin değilseniz, bizimle iletişime geçin; mağazanızı sınıflandırıp size özel bir "hazır entegratör mü, özel köprü mü" kararı ve maliyet-biçimi karşılaştırması çıkaralım.
Kaynaklar
- GİB — Özel Entegratörlük (üç e-Fatura yöntemi ve resmi tanım)
- GİB — e-Belge (e-Fatura/e-Arşiv) portalı ve e-Fatura paketi (UBL-TR şemaları)
- Paraşüt — Resmi API dokümanı (OAuth2, v4, e_invoices/e_archives, PDF uçları, durum enum'u)
- Logo — Netsis uyarlama araçları / NetOpenX Rest API
- Entegra — e-ticaret entegrasyonu (ERP hedefleri + platform listesi)
- Sentos — B2C e-ticaret entegrasyonu (sabit platform listesi)
- İkas — ön muhasebe/ERP entegrasyonları
- IdeaSoft — Mikro entegrasyonu (~15 dk polling, web-servis katmanı)
- Faturaport — 2026 kontör fiyatları (pazar karşılaştırması, resmi liste değil)
- Faturaport — 2026 e-fatura maliyet rehberi (yıllık abonelik bandları, resmi liste değil)
- Paraşüt — e-Arşiv iptal vs iade faturası (kavramsal)