İçeriğe geç
e-Fatura API

GİB e-Fatura ve Ön Muhasebe API Entegrasyonu

Fatura kesmek için portala girip alan doldurmak, hacim büyüdükçe sürdürülemez hale gelir. Bu rehberde yazılımınızı GİB'e veya özel entegratöre bağlayıp faturayı satış anında otomatik kestirmenin yol haritasını bulacaksınız: yöntem karşılaştırması, başvurudan canlıya geçişe süreç adımları, kuyruk ve hata yönetimi, maliyet kalemleri.

11 dk okuma 13 soru-cevap 8 ana konu Güncelleme: 9 Ağustos 2026
Kısa Cevap

e-Fatura API entegrasyonu; sipariş, satış veya ERP yazılımınızın GİB altyapısına ya da özel entegratör servislerine web servisi üzerinden bağlanarak faturayı insan eli değmeden oluşturması, göndermesi ve izlemesi demektir. Satış kaydı oluştuğu anda sistem cariyi VKN/TCKN sorgusuyla doğrular, alıcının mükellefiyet durumuna göre e-Fatura veya e-Arşiv tipini seçer, belgeyi UBL-TR formatında hazırlar ve saniyeler içinde iletir. Bu rehberde GİB Portal, doğrudan entegrasyon ve özel entegratör yöntemlerini karşılaştırıyor; mali mühür başvurusundan test ortamına ve canlıya geçişe uzanan adımları, kuyruk ve hata yönetimini, maliyet kalemlerini somut senaryolarla anlatıyoruz. Kesilen faturanın muhasebe kayıtlarına otomatik işlenmesi için Logo, Mikro ve Netsis aktarımını anlattığımız muhasebe entegrasyonu rehberiyle birlikte okumanızı öneririz. Edge Bilişim bu akışları özel web yazılım projelerinin bir modülü olarak da, mevcut sisteminize eklenen bağımsız bir servis olarak da geliştiriyor.

Rehberin Ana Konuları

e-Fatura API Entegrasyonunda Yöntem Seçiminden Canlıya Geçişe 8 Kritik Aşama

GİB Portal sınırlarından kuyruk mimarisine, sahada kurduğumuz fatura akışlarında projenin kaderini belirleyen başlıklar.

GİB Portal mı, Doğrudan Entegrasyon mu, Özel Entegratör mü?

Üç yol var: GİB Portal, doğrudan GİB entegrasyonu ve özel entegratör. Portal ücretsizdir ama her belge elle girilir, aylık fatura sınırı vardır ve API sunmadığı için otomasyona kapalıdır; yalnızca ayda birkaç belge kesenler için mantıklıdır. Doğrudan entegrasyonda kendi bilgi işlem sisteminiz GİB'e 7/24 bağlanır; mali mühür, zaman damgası, arşivleme ve kesintisiz çalışma sorumluluğu tamamen sizdedir, bu yüzden genellikle yüksek hacimli ve güçlü teknik ekibi olan kurumların tercihidir. Özel entegratör modelinde GİB onaylı bir firma bu altyapıyı üstlenir ve size REST API sunar; karşılığında belge başına kontör veya abonelik ödersiniz. Kararı üç soru belirler: aylık belge hacminiz, teknik ekip kapasiteniz ve altyapı üzerinde ne kadar kontrol istediğiniz. Portalda kalmanın sınırını gösteren pratik eşikler de bellidir: aylık belge sayısı birkaç yüze yaklaştığında, birden fazla satış kanalı oluştuğunda veya fatura girişine ayrılan personel saati belirginleştiğinde API entegrasyonu kendini hızla amorti etmeye başlar. Geçiş kararı için basit bir hesap yeterlidir: bir belgenin elle girişi tipik olarak birkaç dakika sürer; günde elli belge kesen bir işletmede bu, yalnızca veri girişine harcanan saatler ve her elle girişte tekrarlanan hata riski demektir. Entegratör modeliyle başlayıp hacim büyüdüğünde doğrudan entegrasyona geçmek de mümkündür; katmanlı kurulan bir mimaride bu geçiş, iş mantığına dokunmadan yalnızca bağlantı katmanının değişmesiyle yapılır.

Başvurudan Canlıya Geçişe Adım Adım Süreç

Süreç tipik olarak şu sırayla ilerler: mali mühür veya e-imza temini, GİB başvurusu ve yöntem bildirimi, entegratör seçimi, API anahtarının alınması ve yetki kapsamlarının tanımlanması, ardından asıl geliştirme. Analiz aşamasında hangi olayın faturayı tetikleyeceği — sipariş onayı mı, ödeme mi, sevkiyat mı — ve hangi senaryoların kapsandığı netleştirilir. Edge Bilişim olarak bu projelerde senaryo listesini (tevkifat, istisna, iade, dövizli fatura) mali müşavirinizle birlikte çıkarıyor, her birini entegratörün sandbox ortamında uçtan uca test ediyor, canlıya önce düşük hacimli bir pilotla geçiyoruz; proje sonunda kod, Git deposu ve kurulum dokümanıyla birlikte devrediliyor. Bu disiplin, canlıda reddedilen fatura oranını en baştan düşürür.

UBL-TR Formatı, Belge Tipleri ve İmza Zinciri

Fatura, GİB'in şemasını tanımladığı UBL-TR (XML) formatında üretilir; e-Fatura'da temel ve ticari senaryo, mükellef olmayan alıcıda e-Arşiv, sevkiyatta e-İrsaliye devreye girer. Gönderim öncesi şema ve kural (schematron) kontrolü yapılırsa hatalar belge GİB'e ulaşmadan yakalanır; red ve yeniden kesim döngüsü kısalır. Belgenin hukuki geçerliliği mali mühür ve zaman damgasıyla sağlanır: doğrudan entegrasyonda imzayı sizin altyapınız atar, entegratör modelinde bu adımı entegratör üstlenir. Ticari senaryoda alıcının faturayı kabul veya red edebildiğini, temel senaryoda ise böyle bir onay adımı olmadığını baştan planlamak gerekir. Sözleşme ve belgeleri dijital imzaya taşımak isterseniz e-İmza ve KEP entegrasyonu rehberimiz bu konuyu ayrıntılı işliyor. Formatla ilk kez karşılaşan ekipler için pratik bir uyarı: UBL-TR'de sorun çıkaran nokta çoğu zaman şemanın kendisi değil, kural setidir. Vergi istisna kodunun senaryoya uymaması, birim kodunun standart listeden seçilmemesi veya yuvarlama farkı yüzünden kalem toplamının belge toplamını tutmaması, şeması geçerli bir belgeyi bile reddettirir. Bu yüzden gönderim öncesi kontrol iki katmanlı kurulmalıdır: önce XML şema doğrulaması, ardından tutar toplamları ve kod listeleri gibi iş kurallarının uygulama tarafında denetimi. Arşivleme de formatın parçasıdır: imzalı XML belgeler yasal saklama süresi boyunca değiştirilemez biçimde saklanır; müşteriye gösterilen PDF yalnızca görselleştirmedir, hukuki belge XML'in kendisidir.

VKN/TCKN Doğrulama ve Doğru Belge Tipi Seçimi

Fatura kesilmeden önce alıcının VKN/TCKN'si GİB servislerinden sorgulanır; unvan, vergi dairesi ve e-Fatura mükellefiyeti anlık doğrulanır. Mükellef alıcıya e-Fatura, olmayana e-Arşiv otomatik seçilir; kullanıcı bu ayrımı düşünmek zorunda kalmaz. Bu tek adım, sahada en sık görülen iki hatayı kökünden çözer: yanlış unvanla kesilip reddedilen faturalar ve e-Arşiv kesilmesi gerekirken e-Fatura denenip sistemde takılan belgeler. Sorgu sonuçları cari karta yazıldığı için müşteri verisi her satışta kendiliğinden güncellenir; aynı müşteri için tekrar tekrar sorgu yapılmasın diye sonuçlar makul bir süre önbellekte tutulur. Toplu fatura kesiminde ise doğrulama, gönderim kuyruğunun ilk adımı olarak çalışır. Sorgulamanın akıştaki yeri de önemlidir: doğrulamayı yalnızca cari kart açılışında yapmak yetmez, çünkü mükellefiyet durumu zamanla değişir; dün e-Arşiv kesilen bir müşteri bugün e-Fatura mükellefi olabilir. Bu yüzden sorgu, fatura kesiminin hemen öncesinde bir kez daha çalıştırılır ve sonuç belgeye işlenir. Yüksek hacimli gönderimlerde GİB mükellef listesinin gün başında topluca çekilip yerelde tutulması yaygın bir optimizasyondur; tekil sorgular yalnızca listede bulunamayan kayıtlar için yapılır ve akış hızlanır. Kurgunun tamamı kullanıcıya tek bir davranış olarak yansır: doğru belge tipi her seferinde kendiliğinden seçilir.

Kuyruk, Yeniden Deneme ve Webhook ile Hata Yönetimi

GİB veya entegratör tarafında kesinti, yetki hatası (401), şema reddi (422) ya da ticari red olağan senaryolardır; entegrasyonun kalitesi bunlara verdiği tepkiyle ölçülür. Sağlam bir mimaride her fatura önce kuyruğa yazılır, gönderim başarısızsa artan aralıklarla otomatik yeniden denenir; kalıcı hatalar nedeniyle birlikte yetkiliye düşer. Aynı sipariş için ikinci gönderimi engelleyen idempotency anahtarı mükerrer faturanın önüne geçer. Durum takibi için sürekli sorgu yerine webhook kullanmak daha sağlıklıdır: entegratör, belge kabul veya reddedildiğinde sisteminize anlık bildirim gönderir, panel bu bilgiyle güncellenir. Hangi belgenin gönderildiği, beklediği veya reddedildiği tek ekrandan izlenir; hiçbir fatura sessizce kaybolmaz. Kesinti senaryosu pratikte şöyle işler: bağlantı koptuğunda oluşan satışlar kuyruğa birikmeye devam eder, bağlantı geri geldiğinde belgeler sırayla gönderilir; akış kaldığı yerden devam eder ve kesinti süresince kesilen hiçbir satış belgesiz kalmaz. Mükerrer belge tarafında idempotency anahtarı somut bir güvencedir: ağ kesintisi, çift tıklama veya tekrar çalışan bir otomasyon görevi aynı sipariş için ikinci gönderimi tetiklese bile sistem referansı tanır ve yeni belge oluşturmaz. Hata yönetiminde son adım insan faktörüdür: kalıcı redde düşen belgeler için panelde neden kodu ve önerilen düzeltme gösterilir; muhasebe ekibi XML okumak zorunda kalmadan sorunu giderir.

Satış Kanalları: E-Ticaret, Pazaryeri, ERP ve Mağaza

Entegrasyonun değeri, faturayı tetikleyen kanalların tamamını kapsamasıyla ortaya çıkar. Web sitenizde sipariş tamamlandığında fatura otomatik kesilir; bu kurgunun platform tarafını e-ticaret platform entegrasyonu rehberinde anlatıyoruz. Trendyol ve Hepsiburada gibi pazaryerlerinden siparişler API ile çekilip aynı akışta faturalanır; ERP'de sevkiyat gerçekleştiğinde belge ERP verisinden beslenir. Fiziksel mağazada yazar kasadan geçen satışlar için ÖKC entegrasyonu, restoran tarafında yemek kartı tahsilatları da aynı fatura altyapısına bağlanabilir. Her kanal için üç kural baştan tanımlanır: fatura hangi anda kesilecek, hangi seri kullanılacak ve belge kimin adına düzenlenecek. Kanal ekleme sırası da planlanmalıdır: genellikle en yüksek hacimli kanal önce bağlanır, akış birkaç hafta gözlendikten sonra diğerleri sırayla eklenir. Kanal bazlı seri kullanımı raporlamayı kolaylaştırır; hangi cironun hangi kanaldan geldiği belge serisinden bile okunur ve dönem sonu mutabakatı kanal kanal yapılabilir. Böylece kanal sayısı arttıkça kaos değil, tek bir izlenebilir akış büyür.

Raporlama, Mutabakat ve Maliyet Planı

Entegrasyon yalnızca belge kesmez; kesilen, bekleyen ve reddedilen faturaları dönem bazında raporlar, satış kayıtlarıyla karşılaştırıp eksik veya mükerrer belgeyi gün içinde yakalar. Tahsilat tarafını da kapatmak isterseniz banka hareketleriyle fatura eşleştirmesini otomatik mutabakat rehberinde ele aldık. Bütçe planında iki ayrı kalem vardır: bir kez ödenen geliştirme bedeli ve entegratöre ödenen sürekli kontör/abonelik. Geliştirme maliyetini senaryo sayısı (e-Fatura, e-Arşiv, e-İrsaliye, iade), bağlanan sistem sayısı ve çoklu şirket ihtiyacı belirler; tek senaryolu bir bağlantı ile çok şirketli uçtan uca bir akış arasında birkaç kat fark oluşabilir. Kontör maliyeti belge başınadır ve pakete göre değişir; hacim büyüdükçe doğrudan GİB modeli toplamda avantajlı hale gelebilir. Sağlıklı karar, iki kalemi birlikte hesaplamaktan geçer.

GİB Test Ortamından Canlıya Geçiş Süreci

Test aşaması bu projelerin pazarlık kabul etmeyen adımıdır, çünkü canlıda düzeltilen her hata mali belgeye dokunur. Süreç iki ortamda yürür: GİB'in test ortamı ve entegratörün sandbox'ı. Önce tüm senaryolar — temel ve ticari e-Fatura, e-Arşiv, iade, iptal, tevkifat ve dövizli belgeler — örnek verilerle uçtan uca denenir; red senaryoları da bilerek tetiklenir ki hata mesajlarının sisteme nasıl döndüğü görülsün. Test verisi gerçek verinize benzemelidir: en uzun unvanlı müşteri, en çok kalemli fatura ve en düşük tutarlı belge gibi uç örnekler mutlaka listeye alınır, çünkü sorunlar ortalama kayıtlarda değil uç kayıtlarda çıkar. Testler tamamlandığında canlıya geçiş tek günde ve tüm hacimle yapılmaz: önce düşük hacimli bir pilot başlar (örneğin tek bir satış kanalı veya tek şube), birkaç gün boyunca kesilen her belge muhasebe kayıtlarıyla karşılaştırılır, sapma sıfırlandığında kalan kanallar sırayla açılır. Geçiş haftasında eski usul yedek olarak hazır tutulur; entegrasyonda beklenmedik bir sorun çıkarsa faturalar portal üzerinden kesilerek operasyon durmaz. Canlıya geçişten sonraki ilk ay yakın izleme dönemidir: red oranı, ortalama gönderim süresi ve kuyrukta bekleyen belge sayısı günlük takip edilir; bu üç gösterge normale oturduğunda proje kapanır.

GİB e-Fatura API projenizi konuşalım — ihtiyacınızı ücretsiz analiz edelim, aynı gün dönüş yapalım.
WhatsApp
Sıkça Sorulan Sorular

e-Fatura API Entegrasyonu Hakkında Sık Sorulan Sorular

13 gerçek soruya net cevap — aradığınızı yazarak filtreleyin.

Kendi yazılımınızın — sipariş, satış, CRM veya ERP sisteminizin — GİB altyapısına ya da özel entegratör servislerine web servisiyle bağlanarak fatura oluşturma, gönderme, sorgulama ve iptal işlemlerini otomatik yapmasıdır. Portala girip elle veri girmek yerine, satış kaydı oluştuğunda fatura arka planda kesilir ve durumu sisteminize geri bildirilir.

Yardımcı olalım

GİB e-Fatura API konusunda bir projeniz ya da sorununuz mu var?

Edge Bilişim ekibi ihtiyacınızı ücretsiz analiz eder ve projeye özel net bir teklif sunar. Kaynak kodu size teslim edilen, lisans bağımlılığı olmayan çözümler; 200+ proje deneyimi ve 81 ilde uzaktan hizmet.

WhatsApp'tan Yazın Hemen Arayın

[email protected] · İstanbul (81 ile uzaktan hizmet)

Müşteri Yorumları

Müşterilerimiz Bizi Nasıl Değerlendiriyor?

5.0 3 değerlendirme Google Yorumları
5 100%
4 0%
3 0%
2 0%
1 0%
Google'da değerlendirin

Daha fazla yorum için kaydırın