Başlangıç

e-Fatura Nedir?

e-Fatura'nın kapsamı, ProfileID ayrımı, teknik kimliği ve birbirinden ayrılan giden/gelen belge yaşam döngülerine giriş.

Temel Kavram

e-Fatura, GİB e-Fatura uygulamasına kayıtlı mükelleflere düzenlenen faturaların elektronik ortamda oluşturulmasını, GİB'e iletilmesini ve alıcı tarafından teslim alınmasını kapsar. Bu kapsamda alıcı; özel sektör kuruluşu, kamu kurumu veya ihracat/gümrük alıcısı niteliğindeki GİB e-Fatura sistemine kayıtlı bir vergi mükellefidir.

e-Fatura ve e-Arşiv Fatura aynı UBL 2.1 Invoice belge tipini kullanır; ayrım ProfileId alanıyla yapılır. e-Fatura isteğinde alıcının VKN/TCKN bilgisi GİB mükellef listesinde bulunmalı ve fatura tarihi alıcının e-Fatura kayıt tarihinden önce olmamalıdır. Aksi durumda sistem GibUserListInvoiceError veya GibUserDateInvoiceError hatasını döndürür.

💡 Örnek: Bir tedarikçi, GİB e-Fatura sistemine kayıtlı bir toptancıya satış yapıyor. Toptancının VKN'si GİB kullanıcı listesinde ve kayıt tarihi fatura tarihinden önce olduğu için tedarikçi TICARIFATURA profili ile e-Fatura düzenler.

Belge Tipi

Bu rehber, desteklenen ProfileId değerlerinden EARSIVFATURA hariç 10 profili kapsar (e-Arşiv Fatura ayrı bir rehberde ele alınır). ProfileId alanı, faturanın hangi iş senaryosuna ve hangi validasyon/akış kuralına tabi olduğunu belirler.

ProfileId	İş Anlamı
`TEMELFATURA`	Genel amaçlı temel e-Fatura; tek taraflı, alıcı onayı beklenmeden otomatik kabul edilir
`TICARIFATURA`	Ticari fatura; alıcının kabul veya red uygulama yanıtı verebildiği iki taraflı akışa girer
`YOLCUBERABERFATURA`	Yolcu beraberinde eşya (tax-free) satışı; `BuyerCustomerParty` içinde `SchemeId=PARTYTYPE`, `Value=TAXFREE` kimliği zorunludur; iki taraflı onay akışına girer
`IHRACAT`	İhracat teslimine ilişkin fatura; gümrük alıcısına (`urn:mail:ihracatpk@gtb.gov.tr`) gönderilirken zorunludur; iki taraflı onay akışına girer
`KAMU`	Kamu kurumu alıcılı fatura; `PaymentMeans.PayeeFinancialAccount.Id` alanına geçerli TR IBAN ve `CurrencyCode` zorunludur; tek taraflı otomatik kabul akışına girer
`HKS`	Hal Kayıt Sistemi kapsamındaki fatura; her `InvoiceLine`'da 19 karakterli `KUNYENO` zorunludur; tek taraflı otomatik kabul akışına girer
`ENERJI`	Elektrikli araç şarj hizmeti faturası; fatura tipi yalnızca `SARJ` veya `SARJANLIK` olabilir; tek taraflı otomatik kabul akışına girer
`ILAC_TIBBICIHAZ`	İlaç/tıbbi cihaz satışı; her `InvoiceLine`'da `Item.AdditionalItemIdentification.SchemeID` değeri `ILAC`, `TIBBICIHAZ` veya `DIGER` olan bilgi zorunludur; tek taraflı otomatik kabul akışına girer
`YATIRIMTESVIK`	Yatırım teşvik belgesi kapsamındaki fatura ("teşvikli fatura"); güncel GİB e-Fatura kılavuzuna göre fatura tipi yalnızca `SATIS`, `ISTISNA` veya `IADE` olabilir; tek taraflı otomatik kabul akışına girer
`IDIS`	IDIS sevkiyat senaryolu fatura; `IdisSevkiyatNo` alanı `SE-` ile başlayıp 7 haneli sayı içermelidir, kalemlerde `ETIKETNO` şemalı `AdditionalItemIdentification` zorunludur; tek taraflı otomatik kabul akışına girer

Kamu ilişkilendirme istisnası: Kamu kurumuna kesilen bir fatura TEMELFATURA profiliyle de gönderilebilir. Alıcı kamu mükellefiyse geçerli IBAN ve CurrencyCode alanları yine zorunludur; entegratör bu alanları eksik bırakmamalıdır.

İki Ayrı XML

Belge XML'i ve rapor/zarf XML'i aynı sürecin farklı çıktılarıdır; biri belgeyi temsil eder, diğeri GİB zarf iletişimini taşır.

XML	Amaç	Standart	Üretim
UBL XML	Her fatura için — imzalanır, saklanır	UBL 2.1 Invoice	Request kabul edildiğinde üretilir
Envelope (Zarf) XML	İmzalı faturayı GİB VEDOP3'e taşıyan UBL zarfı	UBL Envelope	GİB'e gönderim sırasında üretilir

Teknik Kimlik

ProfileId, giden ve gelen fatura sözleşmelerinde faturanın iş senaryosunu belirler. Değer bu sayfadaki desteklenen 10 değerden biri olmalıdır.

Alan	Konum	Örnek Değer
`ProfileId`	`InvoiceRequestModel` (giden) / `IncomingInvoiceRequestModel` (gelen)	`TICARIFATURA`

Belge Yaşam Döngüsü

e-Fatura, giden ve gelen olmak üzere iki ayrı yönde işlenir. Giden akışta firma faturayı oluşturur, GİB'e gönderir ve teslim/alıcı sonucunu izler. Gelen akışta GİB'den alınan belge ERP'ye aktarılır; profile göre doğrudan tamamlanır veya kabul/red uygulama yanıtı bekler. Bu iki yön aynı durum makinesini paylaşmaz.

Belge yönü	Başlangıç	Temel kararlar	Kanonik sayfa
Giden e-Fatura	Önizleme ve oluşturma request'i	İmzalama, GİB, alıcı teslimi, kabul/red sonucu, hata geri dönüşü, iptal/itiraz	Giden Fatura Akışı
Gelen e-Fatura	GİB'den alınan belgenin platformda görünmesi	Tekilleştirme, ERP aktarımı, profile göre otomatik sonuç veya kabul/red yanıtı	Gelen Fatura Akışı

Okuma sırası: Önce bu sayfadaki ortak kavramları okuyun; ardından belgenin yönüne göre Giden Fatura Senaryoları veya Gelen Fatura Senaryoları ile devam edin. Her yönün durum geçişleri ve sorumlulukları kendi akışında ayrı sayfalarda açıklanır. Enum değerlerinin tam sözlüğü Teknik Referans sayfasında kalır.

Oluşturma Yöntemi

Bir e-Fatura, bu 10 profilin tamamı için ortak uç noktalarla oluşturulur: AddOutgoingInvoice (JSON gövde) — profile özel ayrı bir endpoint yoktur, ayrım yalnızca gövdedeki ProfileId alanıyla yapılır. Güncelleme için de ortak UpdateOutgoingInvoice uç noktası kullanılır. UBL/Excel ile oluşturma dahil diğer yollar (AddOutgoingInvoiceByXml, AddOutgoingInvoiceByUbl, AddOutgoingInvoiceByExcel) için Giden Fatura Entegratör API sayfasına bakabilirsiniz.

Uçtan Uca Entegrasyon Yol Haritası

Üretim entegrasyonu yalnızca fatura oluşturma çağrısından ibaret değildir. Sağlıklı bir entegrasyon şu adımların tamamını kapsar: alıcının uygunluğunu doğrulama, belgeyi önizleme, tekil kimlikleri saklama, asenkron sonucu izleme ve gelen faturaları ERP ile mutabık tutma.

Oturum aç

Account/Token sonucunu güvenli biçimde sakla ve her istekte gönder.

Alıcıyı doğrula

VKN/TCKN, fatura tarihi ve gerekiyorsa alıcı etiketini GİB kullanıcı bilgisiyle eşleştir.

Önizle

Gerçek request gövdesini OutgoingInvoicePreview ile doğrula; hata listesini kapatmadan devam etme.

Oluştur

JSON, düz XML veya hazır UBL yolundan yalnızca birini seç; dönen ETTN ve fatura numarasını kaydet.

Durumu izle

Oluşturma cevabını nihai teslim kabul etme; ETTN ile teknik ve kullanıcı durumunu sorgula.

Mutabık kal

Gelen faturaları al, yanıt gerektiren profilleri işle ve ERP işleme işaretlerini ancak yerel kayıt tamamlanınca güncelle.

Karar	Kullanılacak işlem	Sonraki kontrol
Request modeli platform tarafından oluşturulacak	`AddOutgoingInvoice`	Dönen `ETTN`'yi `GetOutgoingInvoicesStatus` çağrısında kullanarak belge durumunu sorgula
Hazır UBL Invoice gönderilecek	`AddOutgoingInvoiceByUbl`	Şema ve Schematron sonucunu kontrol et; ardından belge durumunu sorgula
Belge kaydedilmeden görsel kontrol yapılacak	`OutgoingInvoicePreview` veya `OutgoingInvoiceUblPreview`	`HasError` değerini ve `Errors[]` listesini kontrol et
Yeni gelen faturalar ERP'ye alınacak	`GetIncomingInvoiceList` veya `GetDetailedIncomingInvoiceList`	Başarılı kayıttan sonra `UpdateIncomingInvoiceErpProcessStatus` çağrısını yap
Ticari akıştaki gelen faturaya yanıt verilecek	`ApproveOrRejectIncomingInvoice`	`GetIncomingInvoicesStatus` çağrısıyla yanıt sonucunu izle
Faturanın PDF, HTML veya UBL çıktısı arşivlenecek	`GetInvoicePdf`, `GetInvoiceView` veya `Get*InvoiceXmlList`	Dosya içeriğini ETTN ve belge numarasıyla ilişkilendir