Referans
Teknik Referans
Enum değerleri, hata/mesaj kodları, alan kuralları ve sözleşme bakım notları.
Enumlar
Bu rehber, EARSIVFATURA dışında desteklenen 10 e-Fatura profilini kapsar. InvoiceTypeCode değerleri profile göre sınırlandırılır; geçerli değer kümesi ve profile özgü koşullar için güncel GİB teknik kılavuzu esas alınır.
InvoiceProfile (değer) | GİB kodu | Rehber kapsamında mı? |
|---|---|---|
TemelFatura (1) | TEMELFATURA | Evet |
TicariFatura (2) | TICARIFATURA | Evet |
YolcuBeraberFatura (3) | YOLCUBERABERFATURA | Evet |
Ihracat (4) | IHRACAT | Evet |
EarsivFatura (5) | EARSIVFATURA | Hayır — ayrı e-Arşiv Fatura rehberinde |
Kamu (6) | KAMU | Evet |
HalKayitSistemi (7) | HKS | Evet |
YatirimTesvik (10) | YATIRIMTESVIK | Evet |
Idis (11) | IDIS | Evet |
IlacTibbiCihaz (15) | ILAC_TIBBICIHAZ | Evet |
Enerji (99) | ENERJI | Evet |
InvoiceTypeCode (tam liste — 21 değer, hepsi ortak enum üzerinden tüm profillerde paylaşılır):
InvoiceTypeCode | GİB kodu |
|---|---|
Satis | SATIS |
Iade | IADE |
Tevkifat | TEVKIFAT |
Istisna | ISTISNA |
OzelMatrah | OZELMATRAH |
IhracKayitli | IHRACKAYITLI |
Sgk | SGK |
Komisyoncu | KOMISYONCU |
HksSatis | HKSSATIS |
HksKomisyoncu | HKSKOMISYONCU |
TevkifatIade | TEVKIFATIADE |
KonaklamaVergisi | KONAKLAMAVERGISI |
IlacTibbiCihaz | ILAC_TIBBICIHAZ |
YtbSatis | YTBSATIS |
YtbIade | YTBIADE |
YtbIstisna | YTBISTISNA |
YtbTevkifat | YTBTEVKIFAT |
YtbTevkifatIade | YTBTEVKIFATIADE |
Sarj | SARJ |
SarjAnlik | SARJANLIK |
TeknolojiDestek | TEKNOLOJIDESTEK |
Dikkat —
TeknolojiDestek bu rehberin profillerinde geçersizdir: InvoiceTypeCode=TEKNOLOJIDESTEK gönderildiğinde ProfileID'nin yalnızca EARSIVFATURA olmasına izin verilir. Bu rehberin kapsadığı 10 profilden hiçbiriyle birlikte gönderilemez. Belge Durum Kodları
Durum yanıtları iki alanı birlikte taşır: ayrıntılı teknik süreç durumu ve kullanıcıya gösterilmeye uygun özet durum. Entegratör otomasyon kararını teknik alanla, kullanıcı mesajını ise *StatusForUser alanıyla vermelidir; ekranda teknik enum adı gösterilmemelidir. Bu bölüm enum sözlüğüdür; durumların hangi sırayla ilerlediği Giden Fatura Akışı ve Gelen Fatura Akışı sayfalarında gösterilir.
Giden Fatura Teknik Durumları
| Değer | Kod | Dışarıdan gözlenebilir anlam | Entegratör aksiyonu |
|---|---|---|---|
InvoiceAndXmlCreated | 20 | Fatura ve UBL oluşturuldu. | ETTN'yi saklayın; gönderim otomatik değilse gönderim işlemini başlatın. |
Signed | 30 | Belge imzalandı ve gönderime hazır. | Durum sorgulamaya devam edin. |
WaitingForSendingToGib | 35 | GİB'e gönderim sırasına alındı. | Yeni belge oluşturmayın veya aynı ETTN'yi tekrar göndermeyin. |
CouldNotSentToGib | 45 | GİB'e gönderim tamamlanamadı. | Hata detayını ve yeniden gönderim politikasını değerlendirin. |
SentToGib | 50 | GİB'e gönderildi; sistem yanıtı bekleniyor. | Bekleyin ve aynı ETTN ile sorgulayın. |
GibFailed | 55 | GİB faturayı hata ile sonuçlandırdı. | GİB hata bilgisini inceleyin; yeni işlemden önce nedeni düzeltin. |
GibReceived | 60 | GİB belgeyi aldı ve alıcıya iletiyor. | Nihai teslim veya alıcı yanıtını bekleyin. |
GibCouldNotSendToParty | 65 | GİB belgeyi alıcıya ulaştıramadı. | Durumu izleyin; otomatik tekrar sürerken yeni fatura üretmeyin. |
SentToParty | 75 | Belge alıcıya iletildi; gerekiyorsa yanıt bekleniyor. | Profilin tek veya iki taraflı akışına göre sonucu izleyin. |
PartyReturnedError | 80 | Alıcı sistem hata yanıtı verdi. | Yanıt ayrıntısını inceleyin ve iş sürecini hata olarak kapatın. |
PartyReceivedAndWaitingForApproval | 85 | Alıcı kabul veya red kararı verecek. | Uygulama yanıtı gelene kadar sorgulamayı sürdürün. |
Rejected | 90 | Fatura reddedildi. | Red açıklamasını işleyin; aynı belgeyi tekrar göndermeyin. |
Approved | 95 | Fatura onaylandı. | İş akışını başarılı ve nihai olarak kapatın. |
Cancelled | 100 | GİB Portal iptali platforma yansıdı. | Yerel durumu iptal olarak güncelleyin. |
Objected | 105 | Fatura için itiraz kaydı bulundu. | Yerel itiraz sürecini ve belge ilişkisini saklayın. |
Gelen Fatura Kullanıcı Durumları
| Değer | Kod | Anlam | Beklenen davranış |
|---|---|---|---|
ApproveOrRejectNotStarted | 3 | Onay/red süreci henüz başlamadı. | Profilin yanıt gerektirip gerektirmediğini belirleyin. |
WaitingForApproveOrReject | 5 | Kullanıcı veya ERP kararı bekleniyor. | Gerekli profilde kabul/red çağrısı yapın. |
Approving | 6 | Kabul yanıtı işleniyor. | İkinci kez yanıt göndermeden sonucu izleyin. |
Rejecting | 7 | Red yanıtı işleniyor. | İkinci kez yanıt göndermeden sonucu izleyin. |
ApproveOrRejectSentWithError | 11 | Uygulama yanıtı hata ile sonuçlandı. | Hata ayrıntısını değerlendirin; kör tekrar yapmayın. |
Approved | 12 | Kabul işlemi tamamlandı. | ERP iş sürecini başarılı kapatın. |
Rejected | 13 | Red işlemi tamamlandı. | Red nedenini ve belge durumunu saklayın. |
Cancelled | 14 | GİB Portal iptali yansıdı. | Yerel faturayı iptal durumuna alın. |
Objected | 15 | İtiraz kaydı yansıdı. | İtiraz belgesi ve tarihini yerel kayıtla ilişkilendirin. |
Polling kuralı: Bekleyen veya işlemde olan durumlarda aynı ETTN ile durum sorgulanır. Zaman aşımı, ağ hatası veya belirsiz HTTP sonucu yeni fatura oluşturma gerekçesi değildir; önce mevcut ETTN'nin platformdaki sonucu sorgulanmalıdır.
Hata ve Mesaj Kodları
Hata davranışları üç grupta ele alınır: senaryo kurallarında ortak SCHEME kodu, genel belge kurallarında paylaşımlı kodlar ve belirli alanlara ait özel kodlar. Entegratör, işlem sonucunda dönen ErrorCode ile ErrorMessage alanlarını birlikte değerlendirmelidir.
Üç ayrı hata kodu katmanı: Bu modülde dönen
ErrorCode alanı üç farklı kaynaktan gelir.
- Katman A — literal
"SCHEME": Profil/tip uyumluluğu, HKS, İDİS, YTB, İhracat, Kamu, iade ve tevkifat kurallarının büyük kısmıErrorCode="SCHEME"döner — hepsi aynı kodu taşır, ayrım yalnızcaErrorMessagemetnindedir. Bu kurallar için programatik switch/case yapılamaz. - Katman B — genel
SCM00xx/DOC00xxkodları: Para birimi, vergi tipi, istisna kodu gibi GİB kod listesi kontrollerinde ve kardinalite hatalarında kullanılan paylaşımlı kodlardır; tek bir kod birden fazla farklı alanı kapsayabilir. - Katman C — gerçek, alana özel kodlar:
INVxxxx/COMxxxx/SGKxxxxöneki taşıyan, her biri tek bir kurala karşılık gelen kodlardır.
Katman C — Alana Özel Kodlar (bu rehberin 10 profiline uygulanan alt küme)
Aşağıdaki tablo yalnızca bu rehberin profillerinde dönebilen alan özel hata kodlarını listeler. InternetPayment ve ÖKC (OKCBF) ile ilgili INV0036–INV0043, INV0168, INV0263, INV0221 ve PTY0003 kodları e-Arşiv Fatura kapsamındadır; ayrıntıları e-Arşiv Fatura rehberinin teknik referansında yer alır.
| Kod | Mesaj (birebir) | Koşul |
|---|---|---|
INV0220 | Alıcı bilgisindeki VKN GİB e-Fatura mükelleflerinde kayıtlı değildir! | Bu rehberdeki profillerden biri gönderilmiş ancak alıcı GİB e-Fatura kullanıcı listesinde bulunamamıştır. |
INV0229 | Alıcı fatura tarihinden sonraki saatlerde/günlerde e-fatura mükellefi olmuştur! | Alıcının e-Fatura mükellefiyet başlangıcı, faturanın düzenleme tarihinden sonradır. |
COM0030 | Alıcı için gönderilen etiket bilgisi ilgili mükellef için mevcut değildir! | ReceiverIdentifier ile gönderilen etiket alıcıya ait değildir. Kontrol TemelFatura, TicariFatura ve Kamu profillerinde uygulanır. |
SGK0001 | SgkAdditionalDocumentReferenceRequired | InvoiceTypeCode=SGK iken AdditionalDocumentReference gönderilmemiştir. |
SGK0002 | SgkAdditionalDocumentTypeCodeError | Sağlık harcama tipleri için MukellefKodu, MukellefAdi veya DosyaNo referanslarından biri eksiktir. |
SGK0003 | SgkAdditionalDocumentTypeCodeFileNumberError | Abonelik veya MalHizmet harcama tipinde DosyaNo referansı eksiktir. |
SGK0004 | SgkAdditionalDocumentPeriodError | Sağlık veya abonelik harcama tipinde InvoicePeriod gönderilmemiştir. |
Katman A — Senaryo Kuralları (hepsi ErrorCode="SCHEME")
Aşağıdaki mesajlar ayrı bir koda sahip değildir; ayrım ErrorMessage metnine bakılarak yapılmalıdır.
| Senaryo | Gözlenebilir mesaj veya kural |
|---|---|
| Tip/profil uyumu — IADE | "Fatura tipi IADE iken fatura profili sadece TEMELFATURA, EARSIVFATURA, ILAC_TIBBICIHAZ, YATIRIMTESVIK veya IDIS olabilir" |
| Tip/profil uyumu — İDİS | "IDIS fatura senaryosunda fatura tipi SATIS, ISTISNA, IADE, TEVKIFAT, TEVKIFATIADE veya IHRACKAYITLI tiplerinden biri olmalıdır." |
| Tip/profil uyumu — SGK | "Fatura profili SGK iken fatura tipi sadece TEMELFATURA olabilir" (mesaj metni böyledir; kastedilen: InvoiceTypeCode=SGK iken ProfileID yalnızca TEMELFATURA olabilir) |
| Tip/profil uyumu — İHRACAT | "Fatura profili IHRACAT iken fatura tipi sadece ISTISNA olabilir" |
| Tip/profil uyumu — YOLCUBERABERFATURA | "Fatura profili YOLCUBERABERFATURA iken fatura tipi sadece ISTISNA olabilir" |
| Tip/profil uyumu — ENERJI | "cbc:ProfileID değeri ENERJI olduğu durumda cbc:InvoiceTypeCode değeri SARJ veya SARJANLIK olmalıdır." |
| Tip/profil uyumu — ILAC_TIBBICIHAZ | "ILAC_TIBBICIHAZ Fatura senaryosunda fatura tipi SATIS, ISTISNA, TEVKIFAT, TEVKIFATIADE, IADE ve IHRACKAYITLI tiplerinden biri olmalıdır." |
| Tip/profil uyumu — YATIRIMTESVIK | GİB'e gönderilecek e-Faturada SATIS, ISTISNA veya IADE kullanılır; güncel GİB kılavuzu esas alınır. |
| HKS kalem kimliği | "ProfileID elemanının değeri HKS iken her InvoiceLine elemanı 19 karakterli KUNYENO içermelidir" |
| ILAC_TIBBICIHAZ kalem kimliği | "ProfileID elemanının değeri ILAC_TIBBICIHAZ iken her InvoiceLine elemanı Item.AdditionalItemIdentification.SchemeID'si ILAC veya TIBBICIHAZ olan bilgi içermelidir" |
| İDİS sevkiyat no | "IDIS türündeki faturalarda IdisSevkiyatNo alanı 'SE-' ile başlayıp ardından 7 haneli sayı içermelidir." |
| İDİS kalem etiket no | "...schemeId değeri ETIKETNO olan bilgilerin İlk 2 karakteri harf, sonraki 7 karakter rakam olmak üzere toplam 9 karakter alfanumerik olmak üzere üretilmelidir." |
| YTB — YTBNO zorunluluğu | "YTB Türündeki faturalarda YTB Numarasının bulunacağı ContractDocumentReference alanı dolu olmalıdır." / "6 haneli Yatırım Teşvik Belgesi Numarası zorunludur." |
| YTB — harcama tip kodu/tip uyumu | "YTB Türündeki faturalarda CommodityClassification.ItemClassificationCode alanı 01 ise fatura tipi yalnızca satış veya istisna olmalıdır." (02/03/04 kodları için benzer, farklı izinli tip listeleriyle) |
| İhracat — teslimat/Incoterm/GTİP | "...Invoice ve InvoiceLine elemanlarından en az bir tanesi Delivery.DeliveryAddress elemanı içermelidir" / "...schemeID niteliği değeri 'INCOTERMS' olan en az bir ID elemanı içermelidir" / "GTİP kodu 12 haneli numaralardan oluşmalıdır..." |
| İhracat — alıcı/vergi dairesi | "...BuyerCustomerParty.Party.PartyLegalEntity.RegistrationName elamanı dolu olmalıdır" / "AccountingSupplierParty.Party.PartyTaxScheme.TaxScheme.Name elamanı dolu olmalıdır" |
| İhracat/Yolcu Beraber — sabit alıcı adresi | "Receiver.Identifier elemanının değeri urn:mail:ihracatpk@gtb.gov.tr iken Invoice.ProfileID elemanının değeri IHRACAT olmalıdır" (Yolcu Beraber için urn:mail:yolcuberaberpk@gtb.gov.tr ile aynı desen) |
| Yolcu Beraber — TaxRepresentativeParty | "...TaxRepresentativeParty.PartyIdentification elemanı schemeID niteliği değeri 'ARACIKURUMVKN' olan ve değeri geçerli bir vkn/tckn olan bir tane ID elemanı içermelidir." (aynı desen ARACIKURUMETIKET için de geçerlidir) |
| Kamu — IBAN/para birimi | "ProfileID elemanının değeri KAMU iken PaymentMeans.PayeeFinancialAccount.ID alanına geçerli bir Türkiye IBAN numarası yazılmalıdır" / "Kamu faturalarında PayeeFinancialAccount.CurrencyCode alanı boş geçilemez" |
| Tevkifat (belge seviyesi) | "WithholdingTaxTotal elamanı varken fatura tipi TEVKIFAT, YTBTEVKIFAT, IADE, YTBIADE, SGK, SARJ veya SARJANLIK olabilir" / "TaxTypeCode değeri 4171 ise fatura tipi TEVKIFAT, IADE, YTBIADE veya SGK olabilir" |
| Mükerrer/iade — eksik referans | "IADE, TEVKIFATIADE, YTBIADE ve YTBTEVKIFATIADE fatura tiplerinde iade bilgilerini içeren BillingReference/InvoiceDocumentReference elemanı zorunludur." |
| Mükerrer/iade — DocumentTypeCode/ID/tekillik | "...DocumentTypeCode değeri 'IADE' olmalıdır..." / "...ID 16 haneli olmalıdır..." / "Mükerrer iade fatura numarası mevcut. Mükerrer Belge Numaraları: {csv}" |
Katman B — Genel Kodlar
| Kod | Mesaj |
|---|---|
SCM0001 | {0} için girilen kod geçerli değildir! (GİB kod listesinde bulunmayan değer — para birimi, vergi tipi, istisna kodu, ödeme aracı vb.) |
SCM0002 | {0} zorunlu bir elemandır boş geçilemez! |
SCM0005 | CopyIndicator false olmalıdır! |
SCM0006–SCM0008 | IssueDate zorunlu/gelecek olamaz/saat bileşeni zorunlu |
SCM0011 | Kalem detay ID bilgileri mükerrer olmamalıdır! |
DOC0006 | Ampersand (&) karakter içeren veri bulundu! |
Doğrulama Kapsamı
Hata kataloğu yalnızca profil kurallarından oluşmaz. Aşağıdaki tablo, e-Fatura oluşturma sırasında uygulanan doğrulama ailelerinin tamamını ve hatanın hangi katmanda gözlenebileceğini gösterir. Alan adı içeren genel mesajlarda entegratör, dönen ErrorCode ile ErrorMessage değerini birlikte kaydetmelidir.
| Doğrulama ailesi | Kontrol edilen sözleşme | Hata katmanı |
|---|---|---|
| Belge kimliği ve tarih | UUID, fatura numarası, IssueDate, IssueTime ve CopyIndicator | SCM00xx / DOC00xx |
| Kod listeleri ve para birimi | Para birimi, vergi, istisna, ödeme aracı ve diğer GİB kod listeleri | SCM0001 ve alan mesajı |
| Taraflar ve mükellefiyet | Gönderici/alıcı kimliği, GİB mükellefiyeti, mükellefiyet tarihi ve alıcı etiketi | INV0220, INV0229, COM0030 |
| Belge toplamları | Vergi hariç/dahil tutar, indirim/artırım, yuvarlama ve ödenecek tutar dengesi | SCHEME / SCM00xx |
| Vergi ve tevkifat | TaxTotal, TaxSubtotal, istisna nedeni, WithholdingTaxTotal ve TaxTypeCode=4171 | SCHEME / SCM00xx |
| Fatura kalemleri | Miktar, birim, fiyat, kalem tutarı, kalem kimliği ve mükerrer satır kimliği | SCHEME / SCM0011 |
| İndirim ve artırımlar | Belge/kalem seviyesinde AllowanceCharge, oran, temel tutar ve sıra | SCHEME / SCM00xx |
| Ödeme ve referanslar | PaymentMeans, sipariş/irsaliye referansı ve iade için BillingReference | SCHEME / SCM00xx |
| Profil ve fatura tipi | ProfileID ile InvoiceTypeCode uyumu | SCHEME |
| İhracat ve yolcu beraber | GTİP, Incoterm, teslimat, ihracat alıcısı, pasaport ve aracı kurum bilgileri | SCHEME |
| Kamu | TR IBAN, hesap para birimi ve alıcı taraf alanları | SCHEME |
| SGK | Ek belge, dosya numarası ve fatura dönemi | SGK0001–SGK0004 |
| HKS, İDİS ve İlaç/Tıbbi Cihaz | Künye, sevkiyat/etiket ve ürün izlenebilirlik kimlikleri | SCHEME |
| Yatırım teşvik | YTB numarası/tarihi, harcama tipi ve güncel GİB fatura tipi kümesi | SCHEME |
Bilinen doğrulama davranışı: İstisna kodu grubu kullanılan ve fatura tipi doğru seçilmiş bir istekte de "Vergi istisna muhafiyet kodu : {code} için fatura tipi ISTISNA, IADE, IHRACKAYITLI veya SGK olabilir." hatası alınabilir. Alanlar bu kurala uygun olduğu hâlde hata sürüyorsa request'i değiştirmeden destek ekibine hata yanıtıyla birlikte iletin.
Validasyon Referansları
Senaryo bazlı anlatım için Giden Fatura Senaryoları ile Gelen Fatura Senaryoları sayfalarına bakın. Operasyonel görevler de yön bazında giden ve gelen fatura sorumlulukları sayfalarında açıklanır; aşağıdaki tablo alanlarla gözlenebilir hata davranışlarını eşleştirir.
| Konu | Kural |
|---|---|
Profil → izinli InvoiceTypeCode kümesi | Seçilen profile göre izinli türler Alan Zorunluluk Matrisi'nde listelenir. |
| Alıcının GİB e-Fatura mükellefi olması | Tüm 10 profil için zorunlu (INV0220); mükellefiyet tarihi fatura tarihinden sonra ise INV0229 |
Etiket (ReceiverIdentifier) doğrulaması | Yalnızca TemelFatura/TicariFatura/Kamu profillerinde (COM0030) |
| SGK ek belge/dönem kuralları | Yalnızca InvoiceTypeCode=SGK (dolayısıyla ProfileID=TEMELFATURA) için (SGK0001–SGK0004) |
WithholdingTaxTotal / TaxTypeCode=4171 kısıtı | WithholdingTaxTotal yalnızca izin verilen fatura tiplerinde gönderilir; 4171 kodu yalnızca TEVKIFAT, IADE, YTBIADE veya SGK tiplerinde kabul edilir. |
| İade fatura referans bütünlüğü | IADE, TEVKIFATIADE, YTBIADE ve YTBTEVKIFATIADE tiplerinde iade edilen belgeyi gösteren BillingReference/InvoiceDocumentReference zorunludur. |
| Vergi istisna kodu grupları | Alanlar kurala uygun olduğu hâlde tip uyumsuzluğu hatası alınırsa yukarıdaki bilinen doğrulama davranışı uygulanır. |
Sözleşme Bakımı
Profil, fatura tipi, alan zorunluluğu veya hata kodu değiştiğinde bu referans API sözleşmesiyle birlikte güncellenmelidir. Entegratör yalnızca bu sayfada yayımlanan alan ve hata davranışlarına bağımlı olmalıdır.