Teknik Temel

GİB Referansı

GİB paketi, kullanım yöntemi, teknik gereksinimler ve resmi kaynaklar.

📦 Referans: Entegrasyon, GİB'in UBL-TR 1.2 temel standardını ve yayımlanan güncel şema paketi ile profile özgü teknik kılavuzları birlikte esas alır.

GİB Paketi

GİB e-Fatura paketi; UBL-TR 1.2 temel standardını, desteklenen ProfileID değerlerini ve Schematron doğrulama kurallarını içerir. Paket dosyasının yayın sürümü ile UBL belgesindeki CustomizationID=TR1.2 değeri farklı kavramlardır; gönderilen belge güncel şema ve profile özgü kılavuzlarla birlikte doğrulanmalıdır.

Kullanım Yöntemi

Mükellefler e-Fatura uygulamasına GİB Portal veya yetkilendirilmiş özel entegratör üzerinden dahil olabilir. VBT Yazılım özel entegratör olarak ERP API ve VBT Portal üzerinden oluşturulan faturaları aynı dış sözleşme kurallarına göre işler.

Teknik Gereksinimler

Teknik gereksinimler, UBL üretimi ile GİB'e iletilen zarf (envelope) tabanlı gönderimin aynı veri setinden tutarlı şekilde beslenmesini sağlar. e-Fatura profilleri, e-Arşiv Fatura'nın aksine GİB'e doğrudan e-Arşiv API'si üzerinden değil, zarf (envelope) tabanlı bir hat üzerinden iletilir (bkz. GİB Rapor Alanları).

UBL Belge Standardı

e-Fatura, UBL 2.1 Invoice doküman tipi üzerinden ifade edilir. Belge kimliği alanları tüm fatura profilleri için platform tarafından aşağıdaki sabit değerlerle oluşturulur:

Alan	Değer
`UBLVersionID`	`2.1`
`CustomizationID`	`TR1.2`
`ProfileID`	Aşağıdaki 10 değerden biri

Dikkat — sabit değer: Bu entegrasyonda CustomizationID değeri TR1.2 olarak gönderilir. e-İrsaliye belgelerinde kullanılan TR1.2.1 değeriyle karıştırmayın.

Taraf Kimlik Tipleri

UBL-TR'nin PartyIdentification şema kodları, e-Fatura'da her iki tarafta da mükellef kimliğini taşır:

Taraf	SchemeId	Açıklama
Satıcı (`AccountingSupplierParty`)	`VKN` veya `TCKN`	e-Fatura uygulamasına kayıtlı mükellef; VKN veya TCKN taşıyabilir
Alıcı (`AccountingCustomerParty`)	`VKN` veya `TCKN`	e-Fatura uygulamasına kayıtlı mükellef; VKN veya TCKN taşıyabilir

e-Fatura alıcısı ve satıcısı GİB e-Fatura uygulamasına kayıtlı olmalı; taraf kimlikleri VKN veya TCKN ile gönderilmelidir. e-Arşiv Fatura alıcısı için farklı mükellefiyet kuralı uygulanır.

Fatura Profili — InvoiceTypeCode Kısıtları

Bu rehberin kapsadığı 10 ProfileID değeri için izin verilen InvoiceTypeCode kombinasyonları aşağıdadır.

ProfileID	İzin verilen InvoiceTypeCode
`TEMELFATURA`	Profile özgü ek kısıt yoktur; genel `IADE` ve `SGK` kuralları geçerlidir
`TICARIFATURA`	Profile özgü ek kısıt yoktur; ancak `IADE` tipi bu profilde kullanılamaz
`YOLCUBERABERFATURA`	Yalnızca `ISTISNA`
`IHRACAT`	Yalnızca `ISTISNA`
`KAMU`	Profile özgü `InvoiceTypeCode` kısıtı yoktur; `PaymentMeans.PayeeFinancialAccount.Id` alanında Türkiye IBAN formatı zorunludur
`HKS`	Profile özgü `InvoiceTypeCode` kısıtı yoktur; her `InvoiceLine` 19 karakterli `KUNYENO` içermelidir
`ENERJI`	`SARJ` veya `SARJANLIK`
`ILAC_TIBBICIHAZ`	`SATIS`, `ISTISNA`, `TEVKIFAT`, `TEVKIFATIADE`, `IADE`, `IHRACKAYITLI`
`YATIRIMTESVIK`	`SATIS`, `ISTISNA`, `IADE`
`IDIS`	`SATIS`, `ISTISNA`, `IADE`, `TEVKIFAT`, `TEVKIFATIADE`, `IHRACKAYITLI`

Kesişen genel kurallar: InvoiceTypeCode=IADE yalnızca TEMELFATURA, EARSIVFATURA, ILAC_TIBBICIHAZ, YATIRIMTESVIK veya IDIS profillerinde kullanılabilir — bu, TICARIFATURA, YOLCUBERABERFATURA, IHRACAT, KAMU, HKS ve ENERJI profillerinde IADE tipinin reddedileceği anlamına gelir. Ayrıca InvoiceTypeCode=SGK yalnızca TEMELFATURA profilinde kullanılabilir ve InvoiceTypeCode=TEKNOLOJIDESTEK yalnızca EARSIVFATURA profilinde kullanılabilir , kapsam dışı profil).

Belge Toplamları

Belge toplamları, ürün satırları, vergi alt toplamları ve varsa tevkifat alanlarının tek net ödenecek tutara bağlandığı noktadır. WithholdingTaxTotal alanı dolduğunda, aynı ekonomik tutar TaxTotal altında tekrar düşülmemelidir; LegalMonetaryTotal/PayableAmount tek net sonucu göstermelidir.

GİB Rapor Alanları

Bu rehberin kapsadığı profiller zarf tabanlı hat üzerinden GİB'e iletilir. Request kabul edildikten sonra aynı belge yeniden gönderilmemeli; sonuç belge kimliğiyle durum sorgulama endpointlerinden izlenmelidir. TICARIFATURA, YOLCUBERABERFATURA ve IHRACAT profillerinde alıcı yanıtı ayrıca izlenir.

e-Arşiv Fatura kapsam dışı: EARSIVFATURA profili, GİB'e e-Arşiv raporu (eArsivRaporu) ile ayrı bir API üzerinden iletilir; bu akış bu rehberin kapsamı dışındadır, ayrıntı için e-Arşiv Fatura rehberine bakın.

İptal Raporu

Bu 10 profil için, e-Arşiv Fatura'daki gibi ayrı bir GİB "iptal raporu" API çağrısı (faturaIptal/faturaitiraz elemanı) yoktur. Sonlandırma, GİB zarf hattı üzerinden gelen alıcı yanıtıyla ifade edilir:

Aksiyon	Geçerli önceki durum	Yeni durum
`Cancel`	`Approved`	`Cancelled`
`Object`	`Approved` veya `Rejected`	`Objected`

CancelOutgoingInvoice yalnızca TEMELFATURA ve ILAC_TIBBICIHAZ profillerinde kullanılabilir; diğer profillerde InvalidOutgoingInvoiceProfileIdForCancelOperation hatası döner. İtiraz ve iptal sonucu response ile alınır ve daha sonra durum sorgulama endpointlerinden izlenir.

Resmi Kaynaklar

Resmi kaynaklar, teknik yorumun dayandığı GİB paketini ve mevzuat bağlantılarını birlikte takip etmeyi sağlar.

Kaynak	URL
GİB e-Fatura Uygulaması	e-Fatura ana sayfası
GİB Duyurular Sayfası	Güncel duyurular
UBL-TR şema paketi	Yayımlanan paket dosyası
Yatırım Teşvik Teknik Kılavuzu	Kasım 2025, sürüm 1.0
İDİS Teknik Kılavuzu	Sürüm 1.0
Gümrük İşlemleri Kılavuzu	İhracat ve yolcu beraberi eşya