e-Fatura

Giden Fatura

Giden Fatura Senaryoları

On e-Fatura profili için ProfileId, InvoiceTypeCode, zorunlu alan, oluşturma, iptal ve itiraz senaryoları.

Genel Bakış

Giden e-Fatura, tek bir OutgoingInvoiceRequestModel gövdesi üzerinden 10 farklı ProfileId değerini kapsar (e-Arşiv Fatura ayrı bir rehberde ele alınır). Karar noktası, ProfileId ile InvoiceTypeCode alanlarının birlikte belirlediği kombinasyondur: her profil, belge tipini belirli bir alt kümeyle sınırlar ve profile özgü ek alanlar zorunlu kılar. Bu sayfa giden belgenin profil, alan ve oluşturma kararlarını açıklar; belge oluşturulduktan sonraki geçişler Giden Fatura Akışı, tarafların görev sınırları Giden Fatura Sorumlulukları sayfasındadır.

Karar Ağacı

İlk düğüm ProfileId seçimidir; bu seçim hem izin verilen InvoiceTypeCode alt kümesini hem de profile özgü zorunlu alanları belirler.

Profil kümesiTemel davranışEk sözleşme
TEMELFATURAAlıcı uygulama yanıtı beklenmeden temel teslim akışı izlenir.Kamuya özgü kurallar seçilen tipe göre ayrıca uygulanır.
TICARIFATURAAlıcının kabul, red veya itiraz yanıtı izlenir.Yanıt bekleme ve terminal durumlar giden fatura akışında takip edilir.
KAMUKamu faturası kuralları uygulanır.Geçerli TR IBAN ve kamuya özgü zorunlu alanlar gönderilir.
IHRACAT / YOLCUBERABERFATURAİhracat veya yolcu beraberi satış sözleşmesi uygulanır.Gümrük ve taraf alanları seçilen profile göre tamamlanır.
HKS / ENERJI / ILAC_TIBBICIHAZSektörel kimlik ve satır alanları doğrulanır.İlgili şema değerleri her fatura kaleminde taşınır.
YATIRIMTESVIK / IDISTeşvik veya sevkiyat sözleşmesi uygulanır.YTBNO, IdisSevkiyatNo ve ETIKETNO gibi profile özgü alanlar doldurulur.

Alan Zorunluluk Matrisi

Ortak belge alanları her profilde aynı kalır; profile özgü alanlar yalnızca ilgili ProfileId gönderildiğinde devreye girer.

Profil (ProfileId)İzin Verilen InvoiceTypeCodeProfile Özgü Zorunlu Alan
TEMELFATURAProfile özgü ek kısıt yok—
TICARIFATURAProfile özgü ek kısıt yokAlıcı etiketi (ReceiverIdentifier) gönderildiyse GİB kullanıcı listesinde doğrulanır
YOLCUBERABERFATURAYalnızca ISTISNABuyerCustomerParty'de PARTYTYPE=TAXFREE kimliği, Person.NationalityID, Person.IdentityDocumentReference.ID, TaxRepresentativeParty altında ARACIKURUMVKN/ARACIKURUMETIKET
IHRACATYalnızca ISTISNABuyerCustomerParty'de PARTYTYPE=EXPORT kimliği, PartyLegalEntity.RegistrationName, AccountingSupplierParty.PartyTaxScheme.TaxScheme.Name, satırda GTİP (Delivery.Shipment.GoodsItem.RequiredCustomsID), Incoterm, teslimat adresi, taşıma modu, InvoicedQuantity/Price > 0
KAMUProfile özgü ek kısıt yok; IADE kabul edilirPaymentMeans.PayeeFinancialAccount.ID geçerli TR IBAN, PayeeFinancialAccount.CurrencyCode dolu, BuyerCustomerParty zorunlu; IADE tipinde iade belge referansı da zorunlu
HKSProfile özgü ek kısıt yokHer InvoiceLine.Item.AdditionalItemIdentification içinde SchemeId=KUNYENO, değer tam 19 karakter
ENERJIYalnızca SARJ veya SARJANLIK—
ILAC_TIBBICIHAZSATIS, ISTISNA, TEVKIFAT, TEVKIFATIADE, IADE, IHRACKAYITLIHer InvoiceLine.Item.AdditionalItemIdentification içinde SchemeId değeri TIBBICIHAZ, ILAC veya DIGER
YATIRIMTESVIKSATIS, ISTISNA, IADEContractDocumentReference içinde SchemeId=YTBNO, 6 haneli değer ve dolu IssueDate; güncel GİB kılavuzundaki üçlü tip kümesi esas alınır
IDISSATIS, ISTISNA, IADE, TEVKIFAT, TEVKIFATIADE, IHRACKAYITLIIdisSevkiyatNo ile eşleşmeli; her InvoiceLine.Item.AdditionalItemIdentification içinde SchemeId=ETIKETNO, değer ile eşleşmeli
İade kuralları: Literal InvoiceTypeCode=IADE yalnızca TEMELFATURA, EARSIVFATURA, ILAC_TIBBICIHAZ, YATIRIMTESVIK, IDIS veya KAMU profilleriyle kullanılabilir. IADE, TEVKIFATIADE, YTBIADE ve YTBTEVKIFATIADE tiplerinin tamamında BillingReference/InvoiceDocumentReference altında DocumentTypeCode=IADE ve tam 16 karakterli Id zorunludur. Profil kısıtı yalnız IADE tipine aittir; diğer üç tipe genellenmez.

Ana Senaryo Grupları

Senaryo grupları, faturanın hangi profil altında hangi ek alanlarla ayrıştığını konumlandırır.

GrupNe Zaman Kullanılır?Ayırt Edici Alan
Temel FaturaAlıcı GİB mükellefi ve özel bir profil gerekmiyorsaEk alan yok
Ticari FaturaAlıcının ApplicationResponse ile kabul/red bildirmesi beklenecekseKabul/red uygulama yanıtı beklenir
Yolcu Beraberinde EşyaYurt dışında yerleşik yolcuya (Tax-Free) satış yapılıyorsaPARTYTYPE=TAXFREE, TaxRepresentativeParty
İhracatGümrük Ticaret Bakanlığı ihracat listesine (PARTYTYPE=EXPORT) fatura kesiliyorsaGTİP, Incoterm, teslimat alanları
KamuAlıcı kamu tüzel kişiliğiyse (veya TEMELFATURA olarak gönderilip alıcı kamu mükellefiyse)PaymentMeans.PayeeFinancialAccount.ID (TR IBAN)
Hal Kayıt SistemiSebze/meyve toptan satışında HKS künyesi izlenecekseAdditionalItemIdentification.SchemeId=KUNYENO
EnerjiŞarj hizmeti faturası kesiliyorsaInvoiceTypeCode=SARJ/SARJANLIK
İlaç/Tıbbi Cihazİlaç veya tıbbi cihaz teslimlerinde GİB izlenebilirliği gerekiyorsaAdditionalItemIdentification.SchemeId=ILAC/TIBBICIHAZ/DIGER
Yatırım TeşvikYTB kapsamındaki mal/hizmet teslimlerinde teşvik numarası izlenecekseContractDocumentReference.SchemeId=YTBNO
İDİSİhracatta dahilde işleme rejimi sevkiyatı izlenecekseIdisSevkiyatNo, AdditionalItemIdentification.SchemeId=ETIKETNO

Oluşturma Senaryoları

Aşağıdaki kartlar her profil için entegratörün göndermesi gereken alanları ve işlem sonucunu gösterir.

Temel Fatura (TEMELFATURA)

Varsayılan profildir; özel bir senaryo gerekmiyorsa kullanılır. Profile özgü ek bir InvoiceTypeCode sınırlaması yoktur; genel e-Fatura kuralları uygulanır.

AlanDeğer
ProfileIdTEMELFATURA
Alıcı yanıtıKabul/red uygulama yanıtı beklenmez; belge otomatik sonuçlandırılır
Dikkat: Alıcı GİB nezdinde kamu tüzel kişisiyse KAMU profiline ait IBAN ve taraf kuralları da uygulanır. Ayrıntı için aşağıdaki Kamu senaryosuna ve edge-case tablosuna bakın.

Ticari Fatura (TICARIFATURA)

Alıcının faturayı ApplicationResponse ile kabul veya red etmesi beklenen iki taraflı akışta kullanılır. Profile özgü ek zorunlu alan yoktur; ayırt edici unsur iki taraflı onay akışıdır.

AlanDeğer
ProfileIdTICARIFATURA
Alıcı yanıtıWaitingForApproveOrReject durumunda kabul veya red uygulama yanıtı beklenir

Yolcu Beraberinde Eşya (YOLCUBERABERFATURA)

Tax-Free satışlarında kullanılır; fatura tipi yalnızca ISTISNA olabilir, alıcı tarafı PARTYTYPE=TAXFREE kimliği taşımalı ve aracı kurum bilgisi TaxRepresentativeParty altında doldurulmalıdır.

AlanDeğer
InvoiceTypeCodeISTISNA (zorunlu, tek seçenek)
BuyerCustomerParty.PartyIdentificationsSchemeId=PARTYTYPE, Value=TAXFREE
BuyerCustomerParty.Party.Person.NationalityIDDolu olmalı
BuyerCustomerParty.Party.Person.IdentityDocumentReference.IDDolu olmalı (pasaport no)
TaxRepresentativeParty.PartyIdentificationsARACIKURUMVKN (10/11 haneli), ARACIKURUMETIKET — her biri tam bir adet

İhracat (IHRACAT)

Fatura tipi yalnızca ISTISNA olabilir; alıcı PARTYTYPE=EXPORT kimliği taşımalı ve satır/teslimat alanları gümrük izlenebilirliği için doldurulmalıdır.

AlanDeğer
InvoiceTypeCodeISTISNA (zorunlu, tek seçenek)
BuyerCustomerParty.PartyIdentificationsSchemeId=PARTYTYPE, Value=EXPORT
BuyerCustomerParty.Party.PartyLegalEntity.RegistrationNameDolu olmalı
AccountingSupplierParty.Party.PartyTaxScheme.TaxScheme.NameDolu olmalı
InvoiceLine.Delivery.Shipment.GoodsItem.RequiredCustomsID12 haneli GTİP )
Delivery.DeliveryTerms (satır veya belge seviyesi)SchemeId=INCOTERMS içeren en az bir ID
Delivery.DeliveryAddress (satır veya belge seviyesi)En az bir tanesinde dolu olmalı
Delivery.Shipment.ShipmentStage.TransportModeCode (satır veya belge seviyesi)En az bir tanesinde dolu olmalı
InvoiceLine.InvoicedQuantity / Price> 0

Kamu (KAMU)

Alıcı kamu tüzel kişiliğiyse kullanılır; ödeme aracının Türkiye IBAN'ı olması zorunludur. Kamuya ait bir satışın iadesi aynı profil altında InvoiceTypeCode=IADE ile gönderilebilir.

AlanDeğer
PaymentMeans.PayeeFinancialAccount.ID ile eşleşen TR IBAN
PaymentMeans.PayeeFinancialAccount.CurrencyCodeDolu olmalı
BuyerCustomerPartyVBT e-Fatura API sözleşmesinde zorunludur
KAMU iadesiInvoiceTypeCode=IADE; BillingReference[].InvoiceDocumentReference içinde DocumentTypeCode=IADE, tam 16 karakterli Id ve kaynak belge IssueDate değeri

Tam gövde için KAMU iade request örneğine bakın.

Hal Kayıt Sistemi (HKS)

Sebze/meyve toptan satışında her satırın HKS künye numarasını taşıması gerekir.

AlanDeğer
InvoiceLine.Item.AdditionalItemIdentification.SchemeIdKUNYENO
AdditionalItemIdentification.Value uzunluğuTam 19 karakter

Enerji (ENERJI)

Şarj hizmeti faturalarında kullanılır; fatura tipi iki değerle sınırlıdır. Her iki tipte hizmet dönemi ile alıcı plakası zorunludur.

AlanDeğer
InvoiceTypeCodeSARJ veya SARJANLIK
InvoicePeriodBaşlangıç ve bitiş tarih/saatleri birlikte; tarihler 01.01.2005 veya sonrası
AccountingCustomerParty kimliğiTam bir PLAKA; 1–50 karakter, büyük harf/rakam/_/-
Her InvoiceLineHizmet adı, miktar/birim ve en az bir vergi detayı zorunlu
Fiyat ve miktarEn fazla 8 ondalık basamak
Vergi matrahı/tutarı ve oranıMatrah ve tutar en fazla 2; oran en fazla 3 ondalık basamak
SARJEn az bir GUID/tarih taşıyan ESURaporID referansı
SARJANLIKHer kalemde en az bir boş olmayan ItemInstance.SerialId

Örnek kullanım için ENERJİ request örneğine, alan karşılıkları için Giden Fatura JSON → UBL Mapping sayfasına bakın.

İlaç/Tıbbi Cihaz (ILAC_TIBBICIHAZ)

İlaç veya tıbbi cihaz teslimlerinde her satırın GİB izlenebilirlik kodunu taşıması gerekir.

AlanDeğer
InvoiceTypeCodeSATIS, ISTISNA, TEVKIFAT, TEVKIFATIADE, IADE veya IHRACKAYITLI
InvoiceLine.Item.AdditionalItemIdentification.SchemeIdTIBBICIHAZ, ILAC veya DIGER (en az biri her satırda)

Yatırım Teşvik (YATIRIMTESVIK)

YTB kapsamındaki teslimlerde teşvik belge numarası ve harcama tipi kodu birlikte doğrulanır. Geçerli tip kümesi ve vergi koşulları için güncel GİB e-Fatura kılavuzu esas alınır.

AlanDeğer
InvoiceTypeCodeSATIS, ISTISNA veya IADE
ContractDocumentReference.SchemeIdYTBNO, değer tam 6 hane
ContractDocumentReference.IssueDateDolu olmalı
InvoiceLine.Item.CommodityClassification.ItemClassificationCode01/02/03/04; seçilen kod için güncel GİB kılavuzundaki vergi koşulları uygulanır
ISTISNA + harcama tipi 01Aynı kalemin 0015 KDV kırılımında TaxExemptionReasonCode=308
ISTISNA + harcama tipi 02Aynı kalemin 0015 KDV kırılımında TaxExemptionReasonCode=339

İDİS (IDIS)

Dahilde işleme rejimi sevkiyatlarında sevkiyat numarası ve satır etiket numarası zorunludur.

AlanDeğer
InvoiceTypeCodeSATIS, ISTISNA, IADE, TEVKIFAT, TEVKIFATIADE veya IHRACKAYITLI
IdisSevkiyatNoSE- veya ES- ön eki + tam 7 rakam
InvoiceLine.Item.AdditionalItemIdentification.SchemeIdETIKETNO, değer ile eşleşmeli (yorum: 2 harf + 7 rakam)

İptal ve İtiraz Senaryosu

Giden faturada iptal yalnızca TEMELFATURA ve ILAC_TIBBICIHAZ profillerinde desteklenir. İtiraz ise belge kimliğiyle birlikte itiraz belgesi, tarihi, numarası, türü ve açıklaması gönderilerek kaydedilir.

İşlemÖn koşulEndpoint
İptalProfil TEMELFATURA veya ILAC_TIBBICIHAZCancelOutgoingInvoice
İtirazİtiraz belgesi bilgileri eksiksizObjectOutgoingInvoice
İtiraz ve iptal kapsamı farklıdır: ObjectOutgoingInvoice işlemi ProfileId değerine göre sınırlandırılmaz. CancelOutgoingInvoice ise yalnızca yukarıda belirtilen profilleri kabul eder.

Sınır Durumları

Sınır durumlar, profil seçiminin veya doğrulamanın beklenmeyen kombinasyonlarda nasıl davrandığını önceden görmek için ayrı ele alınır.

#DurumSonuçNeden
E1ProfileId=TEMELFATURA gönderilir ve alıcı GİB nezdinde kamu tüzel kişisi olarak bulunursa⚠️KAMU profiline özgü IBAN ve BuyerCustomerParty kontrolleri uygulanır.
E2InvoiceTypeCode=IADE iken ProfileId değeri TICARIFATURA, IHRACAT, YOLCUBERABERFATURA, HKS veya ENERJI gibi izin verilmeyen bir profil ise❌SCHEME hatası — yalnız TEMELFATURA, EARSIVFATURA, ILAC_TIBBICIHAZ, YATIRIMTESVIK, IDIS veya KAMU kabul edilir. Bu profil kısıtı diğer iade tiplerine genellenmez.
E3InvoiceTypeCode=SGK iken ProfileId TEMELFATURA dışında bir değerse❌SCHEME hatası
E4InvoiceTypeCode=TEKNOLOJIDESTEK iken ProfileId EARSIVFATURA dışında bir değerse❌SCHEME hatası — bu tip zaten e-Fatura kapsamı dışına düşer
E5ReceiverIdentifier = urn:mail:yolcuberaberpk@gtb.gov.tr iken ProfileId YOLCUBERABERFATURA değilse❌SCHEME hatası
E6ReceiverIdentifier = urn:mail:ihracatpk@gtb.gov.tr iken ProfileId IHRACAT değilse❌SCHEME hatası
E7WithholdingTaxTotal dolu iken InvoiceTypeCode izin verilen kümenin dışındaysa❌SCHEME hatası. İzin verilen tipler: TEVKIFAT, YTBTEVKIFAT, IADE, YTBIADE, SGK, SARJ, SARJANLIK.
E8TaxTypeCode=4171 (Petrol/Doğalgaz ÖTV Tevkifatı) kullanılırken InvoiceTypeCode TEVKIFAT/IADE/YTBIADE/SGK dışındaysa❌SCHEME hatası