Türkiye'de e-fatura, e-arşiv ve ön muhasebe entegrasyonu geliştirirken API seçimi doğrudan operasyonel sorumluluk yaratır. Fatura oluşturma, belge gönderimi, mükellef sorgulama, PDF üretimi, müşteri kaydı, ürün yönetimi ve finans hareketleri aynı teknik sınıfa girmeyebilir.
Bu rehber, API Deposu'ndaki Nilvera, EDM ve Paraşüt API V4 kayıtlarını kullanım alanına göre ayırır. Amaç "hangi API daha iyi" demek değil; hangi ürün akışında hangi API türünün daha doğru olduğunu netleştirmektir.
Hızlı karşılaştırma
| API | En iyi kullanım | Kimlik doğrulama | Not |
|---|---|---|---|
| Nilvera | E-fatura, e-arşiv, mükellef sorgulama | Bearer Token | Test ortamı sinyali var |
| EDM | E-belge ve kurumsal belge süreçleri | OAuth 2.0 | E-fatura, e-arşiv, e-irsaliye kapsamı |
| Paraşüt API V4 | Ön muhasebe ve fatura yönetimi | OAuth 2.0 | Müşteri, ürün, hesap ve fatura iş akışları |
Önce kapsamı ayırın
E-fatura entegrasyonu ile ön muhasebe entegrasyonu aynı şey değildir. Sadece belge gönderimi ve yasal e-belge süreçleri gerekiyorsa Nilvera veya EDM gibi e-belge odaklı sağlayıcılar daha doğal adaydır. Müşteri, ürün, kasa, banka, satış faturası ve finans hareketi yönetmek istiyorsanız Paraşüt API V4 daha geniş bir uygulama API'si olarak değerlendirilir.
Kapsamı yanlış seçmek sonradan büyük refaktör doğurur. E-fatura sağlayıcısını CRM gibi kullanmaya çalışmak da, ön muhasebe API'sini yasal belge entegratörü gibi görmek de hatalı sınırlar yaratabilir.
Backend sınırı şart
Bu API'ler kişisel veri, ticari belge, vergi numarası ve finansal kayıtlarla çalışır. Bu yüzden token ve belge işlemleri frontend koduna taşınmamalıdır. Backend tarafında sağlayıcı adaptörü, yetki kontrolü, audit kaydı ve hata normalizasyonu olmalıdır.
Belge oluşturma gibi mutasyonlarda idempotency özellikle önemlidir. Aynı faturanın ağ hatası nedeniyle iki kez gönderilmesi ciddi operasyonel sorun yaratabilir. Sağlayıcıdan gelen belge ID'si, uygulamadaki sipariş veya fatura kaydıyla tekil bağlanmalıdır.
Test ve canlıya geçiş
E-belge süreçlerinde sadece başarılı senaryo yeterli değildir. Hatalı VKN/TCKN, eksik adres, belge iptali, PDF alma, durum sorgulama, alıcı e-fatura mükellefi mi kontrolü ve sağlayıcı tarafı geçici hata gibi senaryolar test edilmelidir.
Canlıya geçmeden önce küçük hacimli pilot yapılmalıdır. Gerçek muhasebe operasyonu, API yanıtı kadar panel kullanımı, destek süreci ve mutabakat raporlarına da bağlıdır. Bu nedenle teknik PoC ile operasyonel pilot ayrı düşünülmelidir.
İçerik ve ürün kalitesi
E-fatura API içerikleri reklam ve arama kalitesi açısından yüzeysel olmamalıdır. Okuyucuya sağlayıcı listesi değil; kapsam ayrımı, veri güvenliği, test süreci, hata yönetimi ve üretim sorumluluğu anlatılmalıdır. Bu alan Türkiye'de yüksek niyetli arama trafiği taşır, ancak yanlış bilgi ciddi zarar verebilir.
API dokümantasyonu değişebileceği için fiyat, sandbox, endpoint ve yetki iddiaları resmi kaynaklardan düzenli kontrol edilmelidir. Bilinmeyen alanlar kesin bilgi gibi yazılmamalıdır.
Veri modeli ve audit ihtiyacı
E-fatura ve muhasebe entegrasyonlarında audit kaydı sonradan eklenebilecek küçük bir özellik değildir. Hangi kullanıcı hangi belgeyi oluşturdu, sağlayıcıya hangi payload gönderildi, sağlayıcı hangi yanıtı verdi ve belge durumu ne zaman değişti gibi bilgiler sistemde izlenebilir olmalıdır.
Bu kayıtlar hem müşteri desteği hem de hatalı işlem analizi için gereklidir. Ancak raw payload saklarken kişisel veri ve ticari sır riskleri düşünülmelidir. Gerekli alanları maskelemek, belirli süre sonunda arşivlemek ve erişimi rol bazlı sınırlamak daha güvenli bir modeldir.
Sağlayıcı bağımlılığını azaltmak için kendi belge durum modelinizi oluşturun. Örneğin draft, submitted, accepted, rejected, cancelled gibi durumları uygulama içinde standartlaştırmak, Nilvera veya EDM gibi sağlayıcılardan gelen farklı yanıtları daha yönetilebilir hale getirir.
İlgili API Deposu kayıtları
Kaynaklar
Sik Sorulan Sorular
›E-fatura API'si seçerken ilk kriter ne olmalı?
Önce ürünün e-fatura/e-arşiv gönderimi mi, mükellef sorgulama mı, ön muhasebe mi yoksa belge arşivleme mi yapacağını netleştirin. Her sağlayıcı aynı kapsam ve operasyon modelini sunmaz.
›Nilvera, EDM ve Paraşüt aynı ihtiyacı mı çözer?
Hayır. Nilvera ve EDM e-belge entegrasyonu tarafında öne çıkar; Paraşüt ise ön muhasebe, fatura, müşteri, ürün ve finans iş akışları için daha geniş bir uygulama API'si sunar.
›Bu API'ler test ortamı sağlar mı?
Katalogda Nilvera için test ortamı sinyali bulunur. Diğer sağlayıcılar için güncel sandbox, demo ve yetkilendirme koşulları resmi dokümantasyondan kontrol edilmelidir.
›E-fatura entegrasyonu frontend'den yapılabilir mi?
Hayır, bu tip entegrasyonlar backend servis sınırında tutulmalıdır. Token, belge imzalama, müşteri verisi ve audit kayıtları frontend'e taşınmamalıdır.