e-Fatura Entegrasyonu: Kendi Yazılımınızdan API ile Fatura Kesmek

e-Fatura entegrasyonunda kim neyi yapar?

e-Fatura entegrasyonunda dört taraf vardır ve her birinin işi ayrıdır: işletme faturanın içeriğinden sorumludur, yazılım veriyi üretir, özel entegratör belgeyi GİB'e taşır, GİB sistemi ise belgeyi alıcıya ulaştırır. Sorun çıktığında hangi tarafa bakılacağını bilmek için bu ayrımı baştan yazmak gerekir.

GİB'in e-Belge sitesine göre e-Fatura üç yöntemle kullanılabilir: GİB'in e-Fatura Portalı, işletmenin kendi bilgi işlem sistemini GİB'e doğrudan bağlaması ve GİB'den özel entegrasyon izni almış kurumların sistemi. Kendi yazılımından fatura kesmek isteyen işletmelerin çoğu üçüncü yolu, yani özel entegratörü kullanır. GİB'in özel entegratör listesi e-Belge sitesinde yayımlanır; bu yazıda tek tek firma adı vermiyor, sıralama yapmıyoruz.

Burada bir ayrımı açıkça yazalım: D'Cloud Software GİB özel entegratörü değildir ve e-belge düzenleme hizmeti satmaz. Bizim işimiz, yazılımınız ile seçtiğiniz entegratörün API'si arasındaki katmandır. Bu, bir ERP entegrasyonu ya da muhasebe programı entegrasyonu ile aynı mantıkla kurulur: kayıt, işi yapmaya yetkili sistemin resmî arayüzünden oluşur.

İki teknik not daha var. GİB'in Özel Entegrasyon Kılavuzu'na (sürüm 1.7) göre özel entegratörle sözleşme yapan mükellef, isterse faturalarının entegratörün mali mührüyle onaylanarak iletilmesini talep edebilir. Aynı kılavuz, portal kullanan bir mükellef özel entegratöre geçtiğinde GİB portal hesabının kapatıldığını yazar. Yani portal ve entegratör yöntemi aynı anda kullanılmaz.

e-Fatura mı e-Arşiv mi: alıcının mükellef sorgusu

e-Fatura'ya kayıtlı bir satıcıda hangi belgenin kesileceğine işletme değil alıcının durumu karar verir: alıcı GİB'in e-Fatura kayıtlı kullanıcı listesindeyse e-Fatura, değilse e-Arşiv Fatura kesilir. 509 Sıra No.lu VUK Genel Tebliği'nin 2026 itibarıyla yürürlükteki metnine göre satıcı ve alıcının ikisi de e-Fatura'ya kayıtlıysa aralarındaki faturaların tamamı e-Fatura olmak zorundadır.

Bu nedenle e-Fatura API entegrasyonunun ilk çağrısı fatura göndermek değil, mükellef sorgusudur. GİB'in Kullanıcı Listesi (User List) kılavuzu, listede mükellefin kimlik numarasının, unvanının, kullandığı yöntemin ve etiket (posta kutusu) bilgilerinin yer aldığını; etiketlerin açılış ve silinme tarihlerinin de tutulduğunu anlatır. Bir alıcının birden fazla etiketi olabilir. Sorgunun entegratörün API'sinde hangi uç noktayla ve hangi alanlarla sunulduğu, entegratörün belgesinden kontrol edilir.

Sorgu bir kez değil, her faturada yapılmalıdır. GİB'in sıkça sorulan sorularında, alıcının sisteme kayıtlı olmadığı bir tarihe düzenlenen e-Faturanın teknik olarak sistemden geçse bile Vergi Usul Kanunu bakımından geçersiz olduğu belirtiliyor. Cari kartında bir yıl önce "e-Arşiv" yazan bir müşteri bugün kayıtlı kullanıcı olabilir.

Zorunluluk tarafını kısa geçelim; ayrıntısı e-Fatura'ya geçiş yazımızda var. 509 Sıra No.lu Tebliğ'in güncel metnine göre brüt satış hasılatı 2022 veya sonraki bir hesap döneminde 3 milyon TL ve üzeri olan mükellefler, izleyen yılın yedinci ayının başından itibaren e-Fatura'ya geçer. Aynı tebliğe göre e-Arşiv'e dahil olmayan mükelleflerin faturaları, tebliğde sayılan istisnalar dışında, 1 Ocak 2026'dan itibaren tutarına bakılmaksızın e-Arşiv Fatura olarak düzenlenir; basit usul ve işletme hesabı esasına göre defter tutanlar için bu tarih 1 Ocak 2027'dir. Bu tarihlerin sizin için ne anlama geldiğini mali müşaviriniz belirler.

Belge nasıl üretilir ve gönderilir?

Fatura, GİB'in yayımladığı UBL-TR formatında bir XML belgesidir; yazılımınız ya bu belgeyi kendisi üretir ya da entegratörün kabul ettiği daha sade bir veri modelini gönderir ve UBL-TR'yi entegratör oluşturur.

UBL-TR ve GİB'in teknik kılavuzları

UBL-TR'nin resmî kaynağı GİB'in e-Belge sitesidir. Orada UBL-TR Fatura kılavuzu, kod listeleri, ortak elemanlar ve senaryo kılavuzları birlikte bir paket olarak yayımlanır; kod listeleri düzenli güncellenir, en son sürüme oradan bakılır. Bir yazılımcının ilk okuması gereken alanlar şunlardır:

• CustomizationID: UBL-TR Fatura kılavuzuna göre TR1.2 değerini alır.
• ProfileID: Senaryodur. Kod listesinde TEMELFATURA, TICARIFATURA, EARSIVFATURA, IHRACAT, KAMU gibi değerler yer alır.
• ID: Fatura numarasıdır. Kılavuza göre üç haneli alfanümerik birim kod ile 13 haneli müteselsil numaradan oluşur; müteselsil kısmın ilk dört hanesi yıl, kalan dokuz hanesi sıra numarasıdır. Aynı numara bir kez kullanılabilir.
• UUID: Evrensel Tekil Tanımlama Numarası (ETTN). Kılavuza göre faturayı düzenleyen tarafından GUID biçiminde üretilir.
• InvoiceTypeCode: Fatura tipidir; kod listesinde SATIS, IADE, TEVKIFAT, ISTISNA gibi değerler bulunur.

Kendi UBL-TR üretiminizi yazmak her faturayı tam kontrol etmenizi sağlar, ama şema doğrulaması, kod listesi güncellemeleri ve tevkifat ya da istisna gibi özel durumlar da sizin sorumluluğunuza geçer. Entegratörün sade veri modeli işi kolaylaştırır, karşılığında o modelin desteklemediği bir alanı ihtiyaç duyduğunuz gün ekleyemeyebilirsiniz. Fatura tipiniz az ve sabitse sade model çoğu zaman yeter.

e-Arşiv tarafında bir ek kural var: GİB'in e-Arşiv Kılavuzu, internet üzerinden yapılan satışlar için diğer satışlardan ayrı bir birim kodu (fatura numarasının ilk üç hanesi) kullanılmasını ister. Web sitenizden gelen siparişler için ayrı seri açılması bu yüzden kurulumun başında konuşulur.

Gönderim akışı adım adım

Sağlıklı bir akış altı adımdan oluşur ve her adımın sonucu yazılımın kendi veritabanına kaydedilir:

1. Mükellef sorgusu: Alıcının vergi ya da kimlik numarasıyla kayıtlı kullanıcı durumu ve etiketi okunur.
2. Taslak: Sipariş verisinden fatura taslağı oluşur; ETTN bu anda üretilir ve kaydedilir.
3. Doğrulama: Zorunlu alanlar, birim kodları, toplamlar ve vergi satırları gönderimden önce kontrol edilir.
4. Gönderim: Taslak entegratöre iletilir; dönen kimlik ya da numara kayda yazılır.
5. Durum takibi: Belgenin GİB'e iletilip iletilmediği ve alıcıya ulaşıp ulaşmadığı okunur.
6. Belge ve arşiv: PDF ya da HTML görüntüsü ile XML dosyası alınır, siparişin yanına bağlanır.

Aşağıdaki PHP iskeleti yalnızca akışın biçimini göstermek içindir. Uç nokta ve alan adları uydurmadır; hiçbir gerçek entegratörün API'sini temsil etmez. Gerçek kurulumda alan adları, kimlik doğrulama yöntemi ve hata kodları seçtiğiniz entegratörün belgesinden alınır.

<?php
// Örnek iskelet. entegrator.example gerçek bir servis değildir.
$base  = 'https://entegrator.example/api/v1';
$token = getenv('ENTEGRATOR_TOKEN'); // anahtar koda yazılmaz

function api(string $method, string $url, string $token, ?array $body = null): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $token, 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
    ]);
    $raw  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return ['code' => $code, 'body' => $raw === false ? null : json_decode($raw, true)];
}

// 1) Mükellef sorgusu
$alici = api('GET', "$base/mukellef?vkn=1234567890", $token);
$tur   = ($alici['body']['kayitli'] ?? false) ? 'EFATURA' : 'EARSIV';

// 2) ETTN gönderimden ÖNCE üretilir ve siparişe kaydedilir
$ettn = $siparis['ettn'] ?? uuidV4();   // uuidV4(): projedeki yardımcı fonksiyon
kaydetEttn($siparis['id'], $ettn);

// 4) Gönderim: aynı ETTN ile ikinci istek yeni fatura doğurmamalı
$sonuc = api('POST', "$base/faturalar", $token, [
    'ettn'  => $ettn,
    'tur'   => $tur,
    'alici' => $siparis['alici'],
    'satir' => $siparis['satirlar'],
]);

if ($sonuc['code'] === 0 || $sonuc['code'] >= 500) {
    // Sonuç belirsiz: tekrar göndermeden önce ETTN ile durumu sorgula
    $durum = api('GET', "$base/faturalar/$ettn/durum", $token);
}

Bu iskeletteki tek önemli fikir şudur: ETTN istekten önce üretilir ve saklanır. Geri kalan her şey entegratöre göre değişir.

Durum takibi ve tekrar gönderim: aynı fatura iki kez gitmemeli

Bir fatura için "gönderildi" tek bir an değil, bir dizi durumdur ve yazılım her birini ayrı kaydetmelidir. Entegratöre ulaşan belge henüz GİB'e iletilmemiş olabilir, GİB'e ulaşan belge alıcıya teslim edilmemiş olabilir, ticari senaryoda alıcı belgeyi reddedebilir.

Neden iki kez gidebilir?

En sık sebep zaman aşımıdır. Yazılım isteği gönderir, entegratör belgeyi işler ama cevap yolda kaybolur; yazılım "gitmedi" sanıp yeniden gönderir. Eğer her denemede yeni ETTN ve yeni numara üretiliyorsa, aynı sipariş için iki geçerli fatura oluşur. Düzeltmesi iade ya da iptal süreciyle ve mali müşavirle yapılır.

Koruma üç katmandan oluşur. ETTN sipariş başına bir kez üretilir ve veritabanında saklanır. Belirsiz sonuçta tekrar göndermeden önce o ETTN ile entegratörden durum sorgulanır. Aynı siparişe ikinci fatura oluşturmayı engelleyen bir kontrol veritabanında tutulur. Entegratörün aynı ETTN ile gelen ikinci isteği reddedip reddetmediği ayrıca sorulur, çünkü bu davranış her API'de aynı değildir.

Numara tarafında da dikkat gerekir. GİB'in sıkça sorulan sorularına göre her seri kendi içinde müteselsil olmalıdır; numara atlanırsa yazılımın imkân vermesi hâlinde atlanan numaralara iptal kaydı düşülmesi ve bağlı vergi dairesine dilekçeyle açıklama yapılması gerekir. Numarayı kimin verdiğini, yani sizin yazılımınızın mı yoksa entegratörün mü verdiğini baştan netleştirmek bu riski azaltır.

Ticari senaryo yanıtı ve e-Arşiv raporu

Ticari senaryoyla gönderilen e-Faturada alıcı sistem içinden kabul ya da red yanıtı verebilir. GİB'in sıkça sorulan sorularına göre alıcı, belge posta kutusuna düştüğü andan itibaren 8 gün içinde reddetmezse kabul etmiş sayılır. Yazılımınız bu yanıtı entegratörden okuyup siparişin yanına yazmazsa, reddedilen bir fatura muhasebede açık alacak gibi görünmeye devam eder.

e-Arşiv tarafında raporu, entegratör kullanan mükellef için teknik olarak özel entegratör gönderir. GİB'in e-Arşiv Kılavuzu'na göre portal dışındaki yöntemlerle e-Arşiv'e dahil olan mükellefler ve izinli özel entegratörler, e-Arşiv raporlarını günlük dönemler hâlinde ve en geç izleyen günün sonuna kadar Başkanlığa gönderir. Entegratör kullanıyorsanız bu raporu sizin yazılımınız üretmez; raporu hangi tarafın gönderdiği sözleşmede yazılı olmalı ve iptal edilen e-Arşiv faturaların bu rapora nasıl yansıdığını entegratöre sormak gerekir.

Belge, görüntü ve arşiv

Fatura kesildikten sonra yazılımın elinde XML ve bir görüntü dosyası olmalıdır. GİB'in e-Arşiv Kılavuzu, alıcıya elektronik iletimde belgenin nasıl görüntüleneceği ve imzanın nasıl doğrulanacağı hakkında bilgi verilmesini ister. Kılavuz, raporların Başkanlığa aktarılmasının muhafaza ve ibraz ödevlerini ortadan kaldırmadığını da yazar. Belgeleri entegratörün mü sakladığı, ne kadar süre sakladığı ve dışa aktarmanın nasıl yapıldığı sözleşmede yazılı olmalıdır.

Özel entegratör API'si seçerken 8 teknik soru

Entegratör seçimi çoğu zaman fiyat ve tanıdıklıkla yapılır; yazılım bağlanacaksa API'nin kendisi de en az o kadar önemlidir. Aşağıdaki sekiz soru, teklif aşamasında yazılı cevap istenmesi gerekenlerdir:

Bu soruların cevabı entegratörden entegratöre değişir. Biz bir entegratör önermiyoruz ve hiçbirinin bayisi ya da çözüm ortağı değiliz; seçimi siz yaparsınız, biz seçilen API'ye bağlanırız. Cevapların yazılı olması, ileride bir sorun çıktığında hangi tarafın neyi taahhüt ettiğini gösterir.

Hazır ön muhasebe programı yetiyorsa ayrı entegrasyon gerekmez

Faturalarınızı bir ön muhasebe ya da muhasebe programından kesiyorsanız ve program e-Fatura ile e-Arşiv'i kendi ekranından düzenliyorsa, ayrı bir e-Fatura API entegrasyonu yazmak çoğu zaman gereksizdir. Bu durumda doğru soru "programım e-faturayı nasıl keser?" değil, "sipariş verisi programa nasıl girer?" sorusudur.

Ayrı entegrasyon üç durumda anlamlı olur. Birincisi, fatura muhasebe programından değil, sizin geliştirdiğiniz bir sistemden doğuyorsa: abonelik paneli, sipariş portalı ya da sahadan gelen kayıt. İkincisi, siparişin kapanmasıyla faturanın kesilmesi arasında insan beklemesi istenmiyorsa. Üçüncüsü, toplu fatura kesme ve fatura otomasyonu gibi işler tek akışta birleşecekse.

Bir ara yol da vardır: faturayı muhasebe programınız kesmeye devam eder, sizin yazılımınız sipariş verisini programın resmî arayüzünden ona aktarır. Böylece e-belge süreci hiç değişmez, yalnızca elle yazma kalkar. Hangi yolun uygun olduğu kullandığınız programa, fatura sayınıza ve fatura tiplerinizin çeşitliliğine göre keşifte netleşir.

Sıkça Sorulan Sorular

e-Fatura entegrasyonu için GİB'e başvurmam gerekir mi?

Özel entegratör kullanıyorsanız GİB'e ayrıca doğrudan bağlanmazsınız; başvuru ve hesap süreci entegratörle yapılan sözleşme üzerinden yürür. GİB'in Özel Entegrasyon Kılavuzu'na göre e-Fatura'ya kayıtlı olmayan mükellef önce mali mühür sertifikası ürettirir, sonra özel entegratörle anlaşır; 509 Sıra No.lu Tebliğ ise mükellefin isterse belgelerini entegratörün mali mührüyle onaylatabileceğini yazar. Güncel başvuru adımlarını entegratörünüz ve GİB'in e-Belge sitesindeki başvuru sayfası gösterir. Kendi sisteminizi GİB'e doğrudan bağlamak ayrı bir izin ve test süreci gerektirir.

e-Fatura entegrasyonu PHP ile yapılabilir mi?

Evet. Entegratörün API'si HTTP tabanlıysa (REST ya da SOAP) hangi dili kullandığınız belirleyici değildir; PHP, .NET, Java ya da Node.js aynı akışı kurabilir. Belirleyici olan dil değil, mükellef sorgusu, ETTN yönetimi, durum takibi ve hata kayıtlarının doğru kurulmasıdır.

D'Cloud Software e-Fatura kesiyor mu?

Hayır. D'Cloud Software GİB özel entegratörü değildir ve e-belge düzenleme hizmeti vermez. Faturanız sizin seçtiğiniz entegratör üzerinden GİB'e gider; biz yazılımınızı o entegratörün API'sine bağlar, durum takibini ve arşiv akışını kurarız.

e-Arşiv faturayı alıcıya nasıl ulaştırırım?

509 Sıra No.lu Tebliğ'e göre e-Arşiv Fatura, e-Fatura'ya kayıtlı olmayan alıcıya talebine göre kâğıt olarak ya da elektronik ortamda iletilir. Yazılımınız entegratörden aldığı PDF'i ya da görüntüleme bağlantısını siparişle birlikte e-postayla gönderebilir. Hangi kanalın kullanılacağı ve kişisel verinin nasıl işleneceği işletmenizin aydınlatma metniyle uyumlu olmalıdır.

Entegratörümü değiştirirsem yazılımım çöper mi?

Akış entegratöre özgü kodlarla doğrudan sipariş ekranına gömülmüşse değişiklik zahmetli olur. API çağrıları ayrı bir katmanda toplanır ve fatura verisi yazılımın kendi modelinde tutulursa, yeni entegratör için yalnızca o katman yeniden yazılır. Eski belgelerin arşivini toplu dışa aktarma imkânı da sözleşme aşamasında sorulmalıdır.

Toplu fatura kesme ile bu entegrasyon aynı şey mi?

Değil. Toplu fatura kesme, tekrar eden faturaların listeden hazırlanıp onaylanması işidir; e-Fatura entegrasyonu ise onaylanan belgenin entegratöre ulaştırılmasıdır. İkisi aynı akışta birleşebilir: liste hazırlanır, onaylanır, her fatura ayrı ETTN ile gönderilir ve sonucu ayrı görünür.

Kendi yazılımınızı e-Fatura'ya bağlamak için ilk adım

Başlamadan önce üç bilgiyi hazırlayın: faturanın bugün hangi sistemden doğduğu, ayda yaklaşık kaç fatura kestiğiniz ve kullandığınız ya da düşündüğünüz özel entegratör. Mevcut programınız bu işi zaten yapıyorsa bunu açıkça söyleriz ve ayrı geliştirme önermeyiz.

Mersin merkezli yazılım ekibimizle ücretsiz online keşif görüşmesinde akışınıza birlikte bakabiliriz. Kapsam netleşince sabit fiyatlı ve yazılı kapsamlı teklif verilir; teslim sonrası 15 gün ücretsiz hata düzeltme sunulur. Akışınızı konuşmak için iletişime geçin: iletişim formunu kullanabilir ya da WhatsApp'tan yazabilirsiniz. En geç 24 saat içinde dönüş yaparız.