WooCommerce e-Fatura ve e-Arşiv Entegrasyonu: Türkiye İçin Kurulum

Gün sonu, WooCommerce sipariş listesindesiniz. Bugün 18 sipariş gelmiş, ikisinde müşteri şirket adını "Ad Soyad" alanına yazmış ama vergi kimlik numarası hiçbir yerde yok. Muhasebeciniz bir mesaj bırakmış: "Bu iki tanesi e-Arşiv değil e-Fatura olacak, portalden manuel giremem." Sipariş detay ekranında ise fatura diye bir sekme yok; yalnızca kalemler, kargo bedeli, KDV toplamı ve sipariş numarası duruyor.

Bu, Türkiye'de WooCommerce ile satış yapan herkesin kurulumdan birkaç hafta sonra çarptığı duvardır. Sorun WooCommerce'in eksikliği değil mimarisidir: WooCommerce bir sipariş sistemi, e-belge ise ayrı bir yasal katmandır ve ikisini birbirine bağlamak için üç şeye ihtiyacınız vardır — alıcının vergi kimliği, belge tipine karar veren bir mantık ve belgeyi GİB'e ileten bir entegratör.

Bu rehberde üç katmanı sırayla kuracağız: ödeme formuna VKN/TCKN ve vergi dairesi alanının eklenmesi, mükellef sorgusuyla belge tipi kararının otomatikleşmesi, faturanın hangi sipariş durumunda tetikleneceği, iade ve iptal senaryoları, ve entegratör sözleşmesini imzalamadan önce sormanız gereken teknik sorular.

WooCommerce Neden Kendi Başına Fatura Kesemez#

WooCommerce'in ürettiği şey bir sipariş kaydıdır: satır kalemleri, kargo bedeli, indirim, vergi tutarı ve toplam. Bu kayıt muhasebe açısından bir belge değildir. Hiçbir yerde tescil edilmez, resmi bir numara serisine girmez, GİB'in ondan haberi olmaz. "PDF fatura" üreten eklentilerin bastığı çıktı da aynı kategoridedir — biçimsel olarak faturaya benzeyen bir sepet dökümüdür, hukuken fatura değildir.

Türkiye'de geçerli olan belge e-Fatura veya e-Arşiv Faturadır; ikisinin farkını ve hangi durumda hangisinin kesileceğini e-Fatura ve e-Arşiv arasındaki fark yazısında ayrıntılı ele aldık. Burada odağımız bu kararın WooCommerce içinde nasıl otomatikleşeceği.

Çalışan bir kurulum üç katmandan oluşur ve her katmanın ayrı bir sahibi vardır:

Bu üçünden biri eksikse zincir kopar ve en sık kopan halka ilkidir: eklenti kurulmuş, sözleşme imzalanmıştır, ama checkout'ta VKN alanı olmadığı için kurumsal siparişlerde belge tipi yanlış seçilir.

Checkout'a VKN/TCKN ve Vergi Dairesi Alanı Nasıl Eklenir#

Belge tipini belirleyen tek veri alıcının vergi kimliğidir. Bunu ödeme adımında toplamıyorsanız, kararı sipariş sonrasında telefonla veya e-postayla tamamlamak zorunda kalırsınız — ki bu, otomasyonun tamamen dışına düşmek demektir.

Doğru yaklaşım, önce bir fatura tipi seçimi sunup VKN ve vergi dairesi alanlarını buna bağlamaktır. Bireysel alıcıyı VKN girmeye zorlamak dönüşümü düşürür; kurumsal alıcıyı boş geçirmek ise faturayı yanlış tipte kestirir.

Alanları Klasik Checkout'a Eklemek#

Aşağıdaki kod, tema functions.php dosyanıza değil, siteye özel küçük bir eklentiye konmalıdır; tema değiştirdiğinizde fatura alanlarınızın kaybolmasını istemezsiniz.

add_filter( 'woocommerce_billing_fields', 'magaza_fatura_alanlari' );

function magaza_fatura_alanlari( $fields ) {
    $fields['billing_fatura_tipi'] = array(
        'type'     => 'select',
        'label'    => 'Fatura tipi',
        'required' => true,
        'class'    => array( 'form-row-wide' ),
        'priority' => 25,
        'options'  => array(
            'bireysel' => 'Bireysel',
            'kurumsal' => 'Kurumsal (şirket)',
        ),
    );

    $fields['billing_vkn_tckn'] = array(
        'type'        => 'text',
        'label'       => 'VKN / TCKN',
        'required'    => false,
        'class'       => array( 'form-row-wide' ),
        'placeholder' => '10 haneli VKN veya 11 haneli TCKN',
        'priority'    => 26,
    );

    $fields['billing_vergi_dairesi'] = array(
        'type'     => 'text',
        'label'    => 'Vergi dairesi',
        'required' => false,
        'class'    => array( 'form-row-wide' ),
        'priority' => 27,
    );

    return $fields;
}

Alanları required => false bırakıp doğrulamayı ayrı yapmamızın nedeni koşulluluktur: zorunluluk yalnızca "Kurumsal" seçildiğinde geçerlidir. Alanları gizleyip göstermek için küçük bir JavaScript yazabilirsiniz, ama asıl kontrol sunucuda olmalıdır.

Doğrulamayı Sunucu Tarafında Yapmak#

add_action( 'woocommerce_after_checkout_validation', 'magaza_fatura_alani_dogrula', 10, 2 );

function magaza_fatura_alani_dogrula( $data, $errors ) {
    if ( empty( $data['billing_fatura_tipi'] ) || 'kurumsal' !== $data['billing_fatura_tipi'] ) {
        return;
    }

    $vkn = preg_replace( '/\D/', '', $data['billing_vkn_tckn'] ?? '' );

    if ( 10 !== strlen( $vkn ) ) {
        $errors->add( 'billing', 'Kurumsal fatura için 10 haneli vergi kimlik numarası girmelisiniz.' );
    }

    if ( '' === trim( $data['billing_vergi_dairesi'] ?? '' ) ) {
        $errors->add( 'billing', 'Kurumsal fatura için vergi dairesi bilgisi zorunludur.' );
    }
}

Numarayı preg_replace ile rakamlara indirgemek önemlidir; müşteriler numarayı boşluklu, tireli veya başında "VKN:" yazarak girer. Bu temizlik yapılmazsa entegratöre gönderilen değer reddedilir.

Blok Tabanlı Checkout Kullanıyorsanız#

WooCommerce'in blok tabanlı ödeme sayfasında yukarıdaki klasik kancalar çalışmaz. Blok checkout için ayrı bir API vardır ve alanlar woocommerce_register_additional_checkout_field ile kaydedilir; doğrulama da o API'nin kendi validate_callback mekanizmasıyla yapılır. Mağazanız blok checkout kullanıyorsa entegratör eklentisinin bunu desteklediğini kurulumdan önce doğrulayın — birçok Türk entegratör eklentisi hâlâ yalnızca klasik forma alan ekler ve blok checkout'ta VKN alanı hiç görünmez.

Mağazanız yeni kuruluyorsa ve ödeme akışı henüz oturmadıysa, önce WooCommerce kurulum adımlarını tamamlayıp ödeme yöntemlerini netleştirmeniz, fatura katmanını en son eklemeniz işinizi kolaylaştırır.

e-Fatura mı e-Arşiv mi? Kararı Otomatikleştirmek#

Bu karar mağaza sahibinin yorumuna bırakılacak bir şey değildir. Kural nettir: alıcı e-Fatura mükellefiyse belge e-Fatura olarak, GİB sistemi üzerinden alıcının posta kutusuna gönderilir. Değilse e-Arşiv Fatura düzenlenir ve alıcıya e-postayla iletilir.

Zorluk şurada: alıcının mükellef olup olmadığını sipariş anında bilmiyorsunuz. Bunun için GİB'in mükellef listesi sorgulanır. Neyse ki bu sorguyu tek tek yapmanız gerekmez — her ciddi entegratörün "mükellef sorgulama" uç noktası vardır ve VKN'yi gönderip alıcının posta kutusu etiketini geri alırsınız.

Kritik nokta, bu sorgunun üç sonucu olabileceğidir ve kodunuz üçünü de ayrı ele almalıdır:

Üçüncü satır en çok atlanan ve en pahalıya patlayan durumdur. Ağ hatasını "mükellef değil" olarak yorumlayan bir kurulum, e-Fatura mükellefi bir müşteriye e-Arşiv keser. Bu hatanın düzeltilmesi iptal + yeniden düzenleme demektir ve e-Fatura tarafında iptal, e-Arşiv kadar kolay değildir. Kural şu olmalı: karar verilemiyorsa belge kesilmez, iş kuyrukta bekler ve tekrar denenir.

Sorgu sonucunu önbelleğe almak da hem hız hem kota açısından şarttır; aynı kurumsal müşteri ayda beş sipariş verdiğinde beş kez sorgu atmanın anlamı yoktur:

function magaza_efatura_mukellefi_mi( $vkn ) {
    $vkn = preg_replace( '/\D/', '', $vkn );

    if ( 10 !== strlen( $vkn ) && 11 !== strlen( $vkn ) ) {
        return false; // geçersiz numara: e-Arşiv yolundan devam
    }

    $cache_key = 'efatura_mukellef_' . $vkn;
    $cached    = get_transient( $cache_key );

    if ( false !== $cached ) {
        return 'evet' === $cached;
    }

    $sonuc = magaza_entegrator_mukellef_sorgula( $vkn ); // entegratörün SDK / REST çağrısı

    if ( is_wp_error( $sonuc ) ) {
        return null; // karar verilemedi
    }

    set_transient( $cache_key, $sonuc ? 'evet' : 'hayir', DAY_IN_SECONDS );

    return $sonuc;
}

Önbellek süresini bir günden uzun tutmayın: mükellefiyet değişebilir ve ay ortasında kapsama giren bir firmaya bir hafta boyunca e-Arşiv kesmek istemezsiniz. Bireysel alıcılarda ise sorgu hiç gerekmez; TCKN ile satın alan son tüketiciye her durumda e-Arşiv düzenlenir. Fatura tipi seçimi bu yüzden yalnızca bir form alanı değil, sorgu maliyetini de düşüren bir filtredir.

Faturayı Hangi Sipariş Durumunda Kesmeli#

En sık yapılan hata, faturayı sipariş oluşur oluşmaz kesmektir. WooCommerce'te sipariş oluşması ödeme alındığı anlamına gelmez; havale/EFT ile verilen bir sipariş günlerce on-hold durumunda bekleyebilir, iptal edilebilir. Ödenmemiş bir siparişe belge düzenlerseniz, o belgeyi iptal etmek zorunda kalırsınız.

Doğru tetikleyici ödemenin doğrulandığı andır. WooCommerce'te bu, ödeme yöntemine göre iki duruma karşılık gelir:

Fiziksel ürün satan mağazaların büyük çoğunluğu için doğru nokta processing'dir: para hesaba geçmiştir, mal sevk edilecektir. Sanal/indirilebilir ürünlerde WooCommerce siparişi doğrudan completed yapar, dolayısıyla iki durumu da dinlemek gerekir.

Belge oluşturma işini istek içinde senkron yapmayın. Entegratör API'si yavaşladığında müşteriniz teşekkür sayfasında bekler ve ödeme sonrası akış tıkanır. WooCommerce ile birlikte gelen Action Scheduler bu iş için hazırdır:

add_action( 'woocommerce_order_status_processing', 'magaza_faturayi_kuyruga_al' );
add_action( 'woocommerce_order_status_completed',  'magaza_faturayi_kuyruga_al' );

function magaza_faturayi_kuyruga_al( $order_id ) {
    $order = wc_get_order( $order_id );

    if ( ! $order ) {
        return;
    }

    // Aynı siparişe ikinci belge kesilmesin
    if ( $order->get_meta( '_efatura_belge_no' ) ) {
        return;
    }

    if ( ! $order->is_paid() ) {
        return;
    }

    as_enqueue_async_action( 'magaza_fatura_kes', array( 'order_id' => $order_id ), 'fatura' );
}

_efatura_belge_no kontrolü tesadüfi değildir: processing ve completed kancalarının ikisi de aynı sipariş için sırayla çalışır, ayrıca bir yönetici siparişi elle completed'a çekerse kanca tekrar tetiklenir. Bu kontrol olmadan aynı satışa iki fatura kesilir. Aynı mantığı entegratör eklentinizde de arayın: siparişe belge numarası kaydediliyor mu, ediliyorsa tekrar kesmeyi engelliyor mu?

Fatura Tutarını Sipariş Tutarına Kuruşuna Kadar Eşitlemek#

Belge kesilmeye başladıktan sonra ortaya çıkan ikinci sorun kalemler ve tutarlar arasındaki uyuşmazlıktır. Muhasebeciniz "sipariş 1.249,90 TL ama fatura 1.249,88 TL kesilmiş" dediğinde bakılacak dört yer vardır.

KDV yuvarlama. WooCommerce vergiyi satır satır hesaplayıp toplar; entegratör ise çoğu zaman toplam üzerinden ters hesap yapar. İki yöntem kuruş düzeyinde ayrışabilir. WooCommerce vergi ayarlarındaki alt toplam düzeyinde yuvarlama seçeneğiyle entegratörün mantığını hizalamanız gerekir. Fiyatları KDV dahil mi hariç mi girdiğiniz de bu hesabı doğrudan etkiler; ayrıntılar için WooCommerce KDV ve vergi ayarları yazısına bakın.

Kargo bedeli. Kargo faturada ayrı bir satır olarak yer almalı ve kendi KDV oranını taşımalıdır. Kargoyu ürün fiyatına gömen veya faturada hiç göstermeyen kurulumlar, ücretsiz kargo eşiği devreye girdiğinde tutarsızlık üretir. Kargo yapılandırmanız oturmadıysa WooCommerce kargo ayarları tarafını önce netleştirin.

Kupon ve indirimler. İndirimin faturada nasıl görüneceği bir tercihtir: ya her satırın birim fiyatına dağıtılır, ya da toplam üzerinden iskonto satırı olarak yazılır. İkisi de geçerlidir ama entegratör eklentinizin hangisini yaptığını bilmelisiniz, çünkü satır bazlı KDV oranları farklıysa (örneğin sepette hem %20 hem %10 ürün varsa) iskontonun oransal dağıtılması gerekir. Tek satıra yazılan indirim, karışık oranlı sepetlerde KDV tutarını bozar.

Negatif satırlar ve ek ücretler. Bazı eklentiler "hizmet bedeli" veya "kapıda ödeme farkı" gibi kalemleri sıfır ya da negatif tutarlı satır olarak ekler; bu satırlar GİB tarafında sorun çıkarır, faturaya taşımadan önce test siparişiyle doğrulayın.

Doğrulamanın en pratik yolu, aynı sipariş için WooCommerce'teki üç sayıyı entegratör panelindeki belgeyle karşılaştırmaktır: mal/hizmet toplamı, KDV toplamı, genel toplam. Üçü de tutuyorsa satır dağılımı da doğrudur.

İade, İptal ve Kısmi İade Senaryolarında Ne Olur#

Fatura kesildikten sonra müşteri iade talep ettiğinde, WooCommerce'te "İade Et" düğmesine basmak belge tarafında hiçbir şey değiştirmez. Sipariş refunded olur, para geri gider, ama ortada hâlâ geçerli bir fatura vardır.

Belge tipine göre yol ayrılır:

e-Arşiv Fatura düzenlediyseniz, belge henüz GİB'e raporlanmadan önceki süre içinde iptal edilebilir. Bu süre sınırlıdır ve raporlama günlük yapıldığı için pratikte çok kısadır. Süre geçtiyse iptal değil, iade süreci işletilir: alıcı vergi mükellefiyse karşı taraftan iade faturası istenir, mükellef değilse iade/gider pusulası veya iade belgesi düzenlenir. Uygulamadaki en yaygın pratik, e-ticaret iadelerinde ürünle birlikte gönderilen iade formunun imzalı olarak geri alınmasıdır.

e-Fatura düzenlediyseniz durum daha katıdır. Gönderilmiş bir e-Faturayı tek taraflı iptal edemezsiniz. Senaryo "Temel Fatura" ise alıcı sistem üzerinden itiraz edemez, harici yollarla (KEP, noter, iadeli taahhütlü) itiraz etmesi gerekir; "Ticari Fatura" ise alıcı belirli bir süre içinde sistem üzerinden ret cevabı gönderebilir. Bu yüzden e-ticaret mağazalarında senaryo seçimi bir tercih değil, iade politikanızın teknik karşılığıdır.

Kısmi iade en çok atlanan durumdur. Üç ürünlük siparişin birini iade eden müşteri için faturanın tamamını iptal edemezsiniz; iade edilen kalem kadar belge düzenlenir. WooCommerce'in kısmi iade ekranında girdiğiniz tutarın KDV'yi de içerdiğine dikkat edin — yalnızca ürün bedelini girip KDV'yi unutmak, aylar sonra fark edilen bir açık bırakır.

Pratik öneri: iade akışını otomatikleştirmeyin. woocommerce_order_refunded kancasına bağlanıp otomatik iptal denemek, e-Fatura tarafında başarısız olur ve tutarsız bir durum bırakır. Kanca yalnızca bir bildirim üretsin, kararı insan versin.

Entegratör Seçerken Sorulacak Teknik Sorular#

Türkiye'de onlarca özel entegratör var ve hepsinin WordPress eklentisi olduğunu söylüyor. Ticari karşılaştırmayı bir yana bırakıp yalnızca teknik tarafa bakarsanız, ayrımı yapan sorular şunlardır:

1. Blok checkout desteği var mı? WooCommerce'in yeni ödeme sayfasında VKN alanı görünüyor mu, yoksa yalnızca klasik forma mı alan ekliyor?
2. Mükellef sorgusu eklentiye dahil mi? Sorgu önbellekleniyor mu ve başarısız olduğunda ne yapıyor — belge kesmiyor mu, sessizce e-Arşiv'e mi düşüyor?
3. Tekrar deneme mantığı nasıl? API cevap vermezse sipariş belgesiz mi kalır, kuyruğa mı alınır, kaç kez denenir?
4. Aynı siparişe iki belge kesmeyi engelleyen bir kilit var mı? Sipariş meta'sına belge numarası yazılıyor mu?
5. Test ortamı sunuluyor mu? Canlıya geçmeden akışı gerçek belge kesmeden deneyebilmelisiniz.
6. Kalem eşlemesi yapılandırılabilir mi? Kargo, kupon ve ek ücretlerin faturaya nasıl yansıyacağını siz belirleyebiliyor musunuz?
7. Belge çıktısı sipariş kaydına ekleniyor mu? Müşteri hesabında ve sipariş e-postasında faturaya erişim var mı?
8. Log tutuluyor mu? API yanıtlarını ve hata kodlarını görebileceğiniz bir kayıt ekranı yoksa sorun ayıklamak imkânsızdır.

Bu sekiz sorunun cevabını satış öncesi görüşmede net alamıyorsanız, aynı soruları canlıya çıktıktan sonra çok daha pahalı şekilde sorarsınız. Mükellefiyet ve zorunluluk hadleri gibi belge kesmeye başlamadan önce netleşmesi gereken konular içinse e-ticarette vergi ve şirket kurulumu yazısı iyi bir başlangıç noktasıdır.

Canlıya Almadan Önce Doğrulama Turu#

Entegrasyonu açtığınız gün test siparişleriyle şu senaryoları sırayla geçin. Her biri gerçek hayatta karşınıza çıkacak durumlardır:

İlk hafta boyunca günde bir kez entegratör panelindeki belge sayısı ile WooCommerce'teki ödenmiş sipariş sayısını karşılaştırın. Fark varsa kuyrukta takılmış bir iş vardır; bunu iki gün içinde fark etmek, ay sonunda fark etmekten çok daha ucuzdur.

Kurulum bir kez oturduğunda fatura tarafı gerçekten arka planda çalışır. Buraya ulaşmanın yolu sihirli bir eklentiden değil, checkout'taki üç alanın doğru toplanmasından, kararın karar-verilemedi durumunda duracak şekilde kurgulanmasından ve tetikleyicinin ödeme anına bağlanmasından geçer.

Sıkça Sorulan Sorular#

WooCommerce tek başına e-Fatura kesebilir mi?#

Kesemez. WooCommerce yalnızca siparişi, kalemleri ve KDV tutarını hesaplar; ürettiği çıktı hukuken fatura yerine geçmez. Türkiye'de geçerli bir e-Fatura veya e-Arşiv Fatura düzenlemek için GİB'e bağlı bir entegratörle çalışmanız ve bu entegratörün WordPress eklentisini kurmanız gerekir. WooCommerce bu zincirde veri kaynağıdır, belge üreticisi değil.

Checkout'ta VKN alanı olmadan fatura kesilebilir mi?#

Bireysel alıcılara TCKN ile e-Arşiv Fatura kesilebilir, ancak kurumsal alıcılar için vergi kimlik numarası zorunludur. VKN alanı olmayan bir mağazada kurumsal siparişler mükellef sorgusu yapılamadan e-Arşiv olarak kesilir ve bu, alıcı e-Fatura mükellefiyse yanlış belge tipidir. Düzeltmesi iptal ve yeniden düzenleme gerektirdiği için alanı baştan eklemek çok daha ucuzdur.

Fatura hangi sipariş durumunda otomatik kesilmeli?#

Ödemenin doğrulandığı durumda. Fiziksel ürün satan mağazalarda bu genellikle processing, sanal veya indirilebilir ürünlerde completed durumudur. Siparişin oluştuğu an olan pending veya havale beklenen on-hold durumunda belge kesmeyin; ödeme gerçekleşmeyebilir ve kesilmiş bir belgeyi iptal etmek, kesmemekten çok daha zahmetlidir.

Müşteri siparişi iade ettiğinde fatura otomatik iptal olur mu?#

Olmaz ve otomatikleştirmeye çalışmak da doğru değildir. e-Arşiv faturalar GİB'e raporlanmadan önceki kısa süre içinde iptal edilebilir; bu süre geçtikten sonra veya belge e-Fatura ise iptal yerine iade süreci işletilir, karşı taraftan iade faturası istenir ya da iade belgesi düzenlenir. WooCommerce'teki iade işlemi yalnızca bir bildirim üretmeli, kararı muhasebe vermelidir.

Aynı siparişe iki fatura kesildi, neden olur?#

Genellikle sipariş durumu kancasının birden fazla kez tetiklenmesinden kaynaklanır: sipariş önce processing, sonra completed durumuna geçer ve iki kanca da belge oluşturur. Bir yöneticinin siparişi elle tekrar kaydetmesi de aynı sonucu doğurur. Çözüm, belge kesildikten sonra sipariş meta verisine belge numarasını yazmak ve kanca çalıştığında bu değer doluysa işlemi atlamaktır.

Mükellef sorgusu başarısız olursa ne yapmalı?#

Belgeyi kesmeyin. Sorgu hatasını "mükellef değil" olarak yorumlayan bir kurulum, e-Fatura mükellefi bir alıcıya e-Arşiv keser ve bu yanlış belgenin düzeltilmesi zordur. Doğru davranış işi kuyrukta bırakıp birkaç dakika sonra tekrar denemek, belirli sayıda denemeden sonra hâlâ sonuç alınamıyorsa yöneticiye bildirim düşürmektir.