e-Arşiv ve e-Fatura

Ödenen her siparişe resmi fatura kesilir: alıcı bireyselse ya da e-Fatura mükellefi değilse e-Arşiv fatura, e-Fatura mükellefi bir şirketse e-Fatura. Damga faturayı numaralar, GİB'in UBL-TR 1.2 biçiminde XML'ini ve okunabilir PDF'ini üretir, seçtiğiniz yolla (elle, Paraşüt ya da bir özel entegratör) gönderir ve gönderilince PDF'i alıcıya e-postayla iletir. Bu sayfa sunucuyu kuranlar ve muhasebe için yazıldı.

Yasal sorumluluk satıcıdadır. Damga bir özel entegratör değildir: faturayı mali mühürle imzalamaz, GİB'e iletmez ve e-Arşiv raporu göndermez. Bunları satıcının kayıtlı olduğu e-Arşiv ortamı (GİB e-Arşiv Portal ya da sözleşmeli entegratör) yapar. Faturanın doğruluğu, zamanında düzenlenmesi, GİB'e bildirimi ve saklanması mükellefin sorumluluğundadır. Ayarları ve ilk faturaları mali müşavirinizle birlikte denetleyin.

#Ön koşullar

• Satıcı (faturayı kesen şirket) GİB'e e-Arşiv Fatura uygulamasına kayıtlı olmalıdır: ya GİB e-Arşiv Portal kullanıcısı ya da bir özel entegratörün (Paraşüt, Uyumsoft, İzibiz, Sovos vb.) müşterisi. İnternetten satış yapan mükelleflerin e-Arşiv'e geçmesi zorunludur; eşikleri ve tarihleri güncel Vergi Usul Kanunu genel tebliğlerinden doğrulayın.
• e-Fatura mükellefi alıcılara e-Fatura kesebilmek için satıcının da e-Fatura kullanıcısı olması gerekir. Değilse invoicing.einvoice_profile hiç kullanılmaz; mükellef sorgusu yapan bir sürücü seçmeyin ya da elle kesimde türü "e-Arşiv" seçin.
• config.php → billing.seller alanlarında unvan, VKN (şahıs işletmesinde 11 haneli TCKN), vergi dairesi, adres ve il dolu olmalıdır. Eksikse fatura "Taslak"ta kalır ve yönetimde uyarı görünür.

#Akış

1. Sipariş ödenir (PayTR bildirimi ya da yönetimin havale onayı).
2. invoicing.auto_issue açıksa fatura hemen kesilir; kapalıysa yönetim sipariş sayfasında Fatura kes'e basar (türü elle de seçebilir).
3. Fatura türü belirlenir, numara verilir, XML ve PDF üretilir (durum Kuyrukta).
4. Sürücü faturayı gönderir. Başarılıysa durum Gönderildi olur, alıcının fatura e-postasına PDF ekli ileti gider, fatura numarası siparişe yazılır ve üye sipariş sayfasından PDF'i ve XML'i indirir.
5. Gönderim başarısız olursa durum Hata olur; hata yönetimde görünür ve bakım işi (/cron/<token>) 1, 2, 4, 8 … dakika arayla (en çok 12 saat) yeniden dener. invoicing.max_attempts deneme sonra bırakır. Kalıcı hatalar (ör. entegratörün reddettiği alan, eksik ayar) kendiliğinden denenmez: düzeltip Şimdi dene'ye basın.

Yönetim: Faturalar listesi duruma göre süzülür (bekleyen, hatalı, kuyrukta, gönderilen, iptal), fatura no, ETTN, ödeme kodu, alıcı ya da e-postayla aranır; her faturanın XML'i ve PDF'i indirilir.

Faturayı Damga dışında kestiyseniz eski yöntem de durur: sipariş sayfasında Elle fatura ekle ile numara ve PDF eklenir.

#Fatura türü

Mükellefiyet sürücüden sorgulanır (Paraşüt: e-Fatura posta kutusu listesi). Elle sürücü sorgulayamaz: kurumsal alıcının e-Fatura mükellefi olduğunu biliyorsanız otomatik kesmeyi kapatıp Fatura kes formunda türü seçin.

#Numara ve ETTN

Numara GİB biçimindedir: 3 karakter seri + yıl + 9 haneli sıra, ör. DMG2026000000001. Sıra seri ve yıl başına boşluksuzdur: numara, sayaç satırı kilitlenerek fatura kaydıyla aynı veritabanı işleminde verilir; işlem yarıda kalırsa numara da geri alınır. Numarası verilmiş fatura silinmez (iptal edilirse iptal kaydı olarak kalır). e-Arşiv ve e-Fatura ayrı serilerdir (invoicing.series, invoicing.einvoice_series). Yıl Türkiye saatine göredir.

Her faturanın bir ETTN'si (UUID v4) vardır. Entegratör ya da GİB portalı kendi numarasını verirse (Paraşüt kendi serisini kullanır; portala elle girilen fatura portalın numarasını alır) o numara "entegratör no" olarak saklanır; üyeye, e-postada ve siparişte o numara görünür.

#Belgeler

UBL-TR 1.2 XML. OASIS UBL 2.1 Invoice üzerine GİB alanları; öğe sırası UBL 2.1 şemasına uyar (testlerde şemayla doğrulanabilir, aşağıya bakın). İmzasızdır: XAdES imzayı (ext:UBLExtensions) entegratör ekler.

Tutarlar kuruş cinsinden tamsayıyla hesaplanır; KDV satır başına yarım kuruş yukarı yuvarlanır (siparişteki hesapla aynı), belge toplamı satırların toplamıdır. Fatura toplamı siparişle kuruşu kuruşuna tutmazsa fatura kesilmez.

Alanların entegratörünüzün beklediğiyle birebir örtüştüğünü (özellikle internet satışı ve gönderim şekli gösterimi) entegratörün test ortamında ve GİB'in şematron doğrulamasıyla denetleyin; Damga'nın çıktısı GİB doğrulayıcısıyla denenmedi.

PDF. GİB e-Arşiv görünümünde: "e-Arşiv Fatura" başlığı, satıcı ve "Sayın" alıcı blokları, özelleştirme no, senaryo, fatura no, tarih, ETTN, satırlar, KDV dökümü, ödenecek tutar, tutarın yazıyla hali, internet satışı notu ve ödeme bilgileri. Yazı tipi DejaVu Sans'tır (Türkçe harflerin hepsi; PDF'e gömülür). PDF dompdf ile üretilir (composer install kurar). Entegratör resmi PDF verirse (Paraşüt) ya da yönetim portalın PDF'ini yüklerse üyeye o gönderilir.

Dosyalar storage/invoices/<yıl>/ altında durur; web'den erişilemez, yalnız yetkili üye ve yönetim indirir. Yasal saklama süresi boyunca (VUK: 5 yıl) yedekleyin.

#İade ve iptal

Sipariş iade edildi olarak işaretlendikten sonra fatura sayfasında:

• Henüz gönderilmemiş fatura doğrudan iptal edilir; numara iptal kaydı olarak kalır.
• Gönderilmiş e-Arşiv faturası, düzenlendiği günden itibaren invoicing.cancel_days gün (varsayılan 7) içinde iptal edilebilir: Paraşüt ve UBL/HTTP sürücüsünde iptal entegratöre iletilir; elle sürücüde iptali portalda siz yaparsınız, Damga kaydı iptal olur. Sürenin güncel kuralını ve entegratörünüzün sınırını doğrulayıp ayarlayın.
• Süresi geçmiş e-Arşiv ya da e-Fatura iptal edilemez. İade, alıcı tacirse alıcının düzenleyeceği iade faturasıyla, tacir olmayan alıcıda gider pusulası / iade belgesiyle belgelenir. Bu belgenin numarasını İade notunu kaydet ile faturaya not edin. Hangi belgenin gerektiğini mali müşavirinize danışın.

Üye, iptal edilen faturayı sipariş sayfasında "iptal edildi" olarak görür; PDF indirilemez.

#Sürücüler

#manual — elle (varsayılan)

Damga numaralar, XML'i ve PDF'i üretir; fatura "Kuyrukta" bekler. Yönetimde XML'i ve PDF'i indirip faturayı kendi e-Arşiv ortamınıza işleyin (GİB e-Arşiv Portal XML yüklemez, bilgiler portalda forma girilir; entegratör panelleri çoğunlukla UBL yükler). Sonra Gönderildi olarak işaretle: portalın verdiği numarayı ve resmi PDF'i isteğe bağlı olarak girersiniz; alıcıya e-posta gider.

'invoicing' => ['driver' => 'manual', 'auto_issue' => true],

#parasut — Paraşüt API v4

Gerçek bir Paraşüt hesabıyla denenmedi. İstekler Paraşüt'ün açık API belgelerine göre yazıldı ve testlerde sahte HTTP ile biçimleri sınanır. Canlıya almadan önce Paraşüt'ün test şirketinde birkaç fatura kesip sonucu Paraşüt panelinde ve GİB tarafında denetleyin.

1. Paraşüt'ten API erişimi isteyin; client_id ve client_secret verilir. Firma numarası Paraşüt adresindeki sayıdır (https://uygulama.parasut.com/<firma_no>/…).
2. Paraşüt'te e-Arşiv (ve gerekiyorsa e-Fatura) etkin olmalıdır.
3. Ayarlar:

'invoicing' => [
    'driver' => 'parasut',
    'auto_issue' => true,
    'parasut' => [
        'client_id' => '…', 'client_secret' => '…',
        'username' => 'muhasebe@alanadiniz', 'password' => '…',
        'company_id' => '123456',
        'account_id' => '',     // tahsilatın işleneceği kasa / banka hesabı (isteğe bağlı)
    ],
],

Akış: OAuth2 parola akışıyla erişim anahtarı (POST /oauth/token) → müşteri (VKN/TCKN ile aranır, yoksa açılır) → ürün (ürün koduyla, ör. damga-standart) → satış faturası (/sales_invoices, Damga'nın seri ve sıra numarasıyla) → isteğe bağlı tahsilat → e-Arşiv (/e_archives, internet satışı bilgileriyle) ya da e-Fatura (/e_invoices, alıcının posta kutusuna). Paraşüt işi kuyruğa alır; bakım işi işin durumunu sorar (/trackable_jobs), bitince Paraşüt'ün verdiği numarayı ve resmi PDF'i alır. Bir adım hata verirse yeniden denemede önceki adımlar (müşteri, satış faturası) tekrar açılmaz. Paraşüt de alıcıya kendi e-postasını gönderebilir; ikinci e-postayı istemezseniz email_buyer değerini false yapın.

#ubl_http — özel entegratör şablonu

UBL'i HTTP ile alan bir entegratör ya da araya koyacağınız küçük bir köprü servis için şablondur; hiçbir entegratörün API'siyle birebir aynı değildir ve denenmedi. Uyumsoft, İzibiz, Sovos, Logo, QNB eSolutions gibi entegratörlerin çoğu SOAP ya da kendine özgü REST kullanır: src/Invoicing/Drivers/UblHttpDriver.php'yi entegratörün belgesine göre uyarlayın.

Varsayılan sözleşme: POST url gövdesi UBL-TR XML (başlıklarda X-Invoice-Profile, X-Invoice-Uuid, X-Invoice-Number), yanıt {"ref": "…", "status": "sent|pending|error", "number": "…", "message": "…"}; status_url ve cancel_url içinde {ref}, check_url içinde {id} (VKN/TCKN, yanıt {"einvoice": true|false}). Kimlik: token (Bearer) ya da username / password (Basic). Entegratör aynı ETTN'yi ikinci kez almayı reddetmelidir (yeniden denemelerde aynı belge gönderilir).

#Ayarlar

'invoicing' => [
    'driver' => 'manual',            // manual | parasut | ubl_http
    'auto_issue' => false,           // ödeme alınınca kendiliğinden kes
    'series' => 'DMG',               // e-Arşiv seri öneki (3 büyük harf / rakam)
    'einvoice_series' => 'DMF',      // e-Fatura seri öneki
    'einvoice_profile' => 'TEMELFATURA',  // ya da TICARIFATURA
    'website' => '',                 // internet satışı web adresi; boşsa app.url
    'payment_intermediary' => 'PayTR',
    'unit_code' => 'C62',
    'email_buyer' => true,
    'max_attempts' => 10,
    'cancel_days' => 7,
],
'billing' => [
    'seller' => [
        'name' => 'Ondiso Yazılım Ltd. Şti.', 'tax_id' => '1234567890', 'tax_office' => 'Yalova',
        'address' => '…', 'district' => 'Merkez', 'city' => 'Yalova', 'postal_code' => '77100',
        'phone' => '…', 'email' => 'fatura@alanadiniz', 'mersis' => '', 'trade_registry' => '',
    ],
],

Bakım işi her dakika çalışmalıdır (/cron/<token>, kurulum); çalışmazsa yeniden denemeler ve Paraşüt durum sorguları ancak site ziyaret edildikçe yapılır.

#Denemek

Testler gerçek servise gitmez: cd server && php vendor/bin/phpunit. UBL çıktısını OASIS UBL 2.1 şemalarıyla da doğrulamak için UBL-2.1 paketini indirip xsd klasörünü gösterin: DAMGA_UBL_XSD=/yol/UBL-2.1/xsd php vendor/bin/phpunit --filter ubl. Şemalar depoda tutulmaz.