Referans
Teknik Referans
Enum değerleri, hata/mesaj kodları, validasyon referansları ve kaynak bölüm bağlantıları.
Enum Değerleri
EArchiveDocumentGIBStatusType — iptal/itiraz durum modeli:
| Değer | Ad | Açıklama |
|---|---|---|
1 | CancellingObjectingRequested | İptal / İtiraz Talebinde Bulunuldu |
3 | WaitingResponseFromReceiver | Alıcıdan Yanıt Bekleniyor |
5 | Successful | İptal / İtiraz Başarılı |
DocumentObjectionType — TTK madde 18/3 itiraz yöntemleri:
| Değer | Açıklama |
|---|---|
Kep | KEP (Kayıtlı Elektronik Posta) |
Noter | Noter kanalıyla |
Telgraf | Telgraf ile |
TaahhutluMektup | Taahhütlü mektup ile |
EArchiveMailStatus:
| Değer | Açıklama |
|---|---|
1 | Mail Gönderilmedi |
2 | Mail Gönderildi |
Hata Kodları
Üç ayrı hata kodu katmanı: Bu modülde dönen
ErrorCode alanı üç farklı kaynaktan gelir ve bu ayrım entegratörün hata ayrımı yapma biçimini doğrudan belirler.
- Katman A — literal
"SCHEME": ÖKC, mükerrer/iade, tevkifat ve TEKNOLOJIDESTEK gibi senaryolara özgü kuralları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; hata ayrımı mesaj metnine bakılarak yapılmalıdır. - 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/PTYxxxxöneki taşıyan, her biri tek bir kurala karşılık gelen kodlardır. Bu tabloda listelenenler bu katmandandır.
Katman C — Alana Özel Kodlar
| Kod | Mesaj (birebir) | Koşul |
|---|---|---|
INV0220 | Alıcı bilgisindeki VKN GİB e-Fatura mükelleflerinde kayıtlı değildir! | ProfileId≠EARSIVFATURA gönderilmiş ama alıcı GİB e-Fatura kullanıcı listesinde hiç yok |
INV0221 | Alıcı bilgisindeki VKN GİB e-Fatura mükelleflerinde kayıtlı olduğundan e-Arşiv Fatura kesilemez. | ProfileId=EARSIVFATURA gönderilmiş ama alıcı GİB e-Fatura kullanıcısı ve fatura tarihi bu kullanıcının kayıt tarihinden sonra |
INV0229 | Alıcı fatura tarihinden sonraki saatlerde/günlerde e-fatura mükellefi olmuştur! | ProfileId≠EARSIVFATURA gönderilmiş, alıcı GİB e-Fatura kullanıcısı ama bu kullanıcı olma tarihi fatura tarihinden sonra — yani fatura tarihinde alıcı henüz e-Fatura mükellefi değildi |
COM0030 | Alıcı için gönderilen etiket bilgisi ilgili mükellef için mevcut değildir! | ReceiverIdentifier (etiket) gönderilmiş ama GİB'de o mükellef için tanımlı değil — TemelFatura/TicariFatura/Kamu profillerinde kontrol edilir, EARSIVFATURA için bu kontrol devreye girmez |
PTY0003 | Alıcı adı /ünvanı en az {0} karakter olmalıdır. | Yalnızca EARSIVFATURA: AccountingCustomerParty ad/ünvanı 2 karakterden kısa |
INV0043 | Internet satışlarında WebAdresi zorunlu bir alandır, boş geçilemez! | InternetPayment gönderilmiş ama WebAdresi boş |
INV0263 | Web site bilgisi en az {0} karakter olmalıdır. | WebAdresi dolu ama 2 karakterden kısa |
INV0038 | Internet satışlarında OdemeTarihi zorunlu bir alandır, boş geçilemez! | OdemeTarihi boş |
INV0168 | Gönderilen InternetPayment değeri geçersiz. | OdemeSekli GİB kod listesinde yok |
INV0036 | Internet satışlarında Ödeme Şekli ODEMEARACISI ise OdemeAracisiAdi zorunlu bir alandır, boş geçilemez! | OdemeSekli=ODEMEARACISI ama OdemeAracisiAdi boş |
INV0037 | Internet satışlarında Ödeme Şekli DIGER ise OdemeSekliAciklama zorunlu bir alandır, boş geçilemez! | OdemeSekli=DIGER ama OdemeSekliAciklama boş |
INV0041 | Internet satışlarında Gönderi bilgisinde InternetPayment.GonderiTasiyanVknTckn zorunlu bir alandır, boş geçilemez! | GonderiTasiyanVknTckn boş |
INV0040 | Internet satışlarında Gönderi bilgisinde InternetPayment.GonderiTasiyanUnvan zorunlu bir alandır, boş geçilemez! | GonderiTasiyanUnvan boş |
INV0039 | Internet satışlarında Gönderi bilgisinde GonderimTarihi zorunlu bir alandır, boş geçilemez! | GonderimTarihi boş |
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 | Mesaj (birebir, seçili örnekler) |
|---|---|
| ÖKC referansı | "...DocumentTypeCode elemanının değeri 'OKCBF' iken...cbc:DocumentType elemanının değeri 'OKCBilgiFisi' olmaldır." (kaynaktaki yazım hatası dahil, birebir) |
| ÖKC referansı | "...bir IssueDate/ID/DocumentDescription elemanı içermelidir" (eksik alana göre değişir) |
| ÖKC referansı | "...bir Attachment.ExternalReference elemanı içermelidir" / "...bir IssuerParty.EndpointID elemanı içermelidir" / "...bir ValidityPeriod.StartDate elemanı içermelidir" |
| ÖKC referansı | "...ValidityPeriod.StartDate elemanının değeri ile...IssueDate elemanının değeri aynı olmalıdır" |
| Tevkifat (belge seviyesi) | "WithholdingTaxTotal elamanı varken fatura tipi TEVKIFAT, YTBTEVKIFAT, IADE, YTBIADE, SGK, SARJ veya SARJANLIK olabilir" |
| Tevkifat (alan bütünlüğü) | "WithholdingTaxTotal elemanı geçerli ve boş değer içermeyen TaxSubtotal.TaxCategory.TaxScheme.TaxTypeCode ve TaxSubtotal.Percent elemanlarına sahip olmalıdır." |
| Tevkifat (oran uyumsuzluğu) | "Uyumsuz vergi tipi yüzdesi: {taxTypeCode} vergi tipinin yüzdesi {percent} olamaz" |
| Mükerrer/iade — eksik referans | "IADE, TEVKIFATIADE, YTBIADE ve YTBTEVKIFATIADE fatura tiplerinde iade bilgilerini içeren BillingReference/InvoiceDocumentReference elemanı zorunludur." |
| Mükerrer/iade — DocumentTypeCode | "IADE tipli faturalarda BillingReference/InvoiceDocumentReference/DocumentTypeCode değeri 'IADE' olmalıdır. Gelen değer: '{value}'" |
| Mükerrer/iade — ID formatı | "IADE tipli faturalarda BillingReference/InvoiceDocumentReference/ID 16 haneli olmalıdır. Gelen değer: '{value}'" |
| Mükerrer belge tespiti | "Mükerrer iade fatura numarası mevcut. Mükerrer Belge Numaraları: {csv}" |
| TEKNOLOJIDESTEK — alıcı kimliği | "TEKNOLOJIDESTEK fatura tipinde alıcı kimlik numarası TCKN olmalıdır." |
| TEKNOLOJIDESTEK — kalem kimliği | "TEKNOLOJIDESTEK fatura tipinde yer alan tüm kalemler TELEFON veya TABLET_PC schemeID'li AdditionalItemIdentification içermelidir." |
| TEKNOLOJIDESTEK — profil | "cbc:InvoiceTypeCode değeri TEKNOLOJIDESTEK olduğu durumda cbc:ProfileID değeri EARSIVFATURA olmalıdır." |
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 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! |
İstisna kodu doğrulaması: Geçerli bir istisna kodu ve uyumlu fatura tipi gönderilmiş olsa bile platform "Vergi istisna muhafiyet kodu ... için fatura tipi ISTISNA, IADE, IHRACKAYITLI veya SGK olabilir." mesajını döndürebilir. Bu yanıt alındığında request alanları doğrulandıktan sonra aynı isteği döngü içinde tekrarlamak yerine VBT desteğiyle ilerlenmelidir.
Kullanılmayan (ölü) kodlar:
TicariMessages içinde tanımlı ama hiçbir AddError çağrısından referans edilmeyen bir INV0081–INV0096/INV0223–INV0225 "OkcBillingReference*" kod ailesi vardır. Bu kodlar bugün canlı davranışta hiç dönmez — gerçek ÖKC hataları yukarıdaki Katman A tablosunda listelenen "SCHEME" mesajlarıdır. Bu eski kodlara göre hata ayrımı yapmayın.Validasyon Referansları
ÖKC referansı doğrulaması, BillingReference[].AdditionalDocumentReference.DocumentTypeCode alanı literal OKCBF değerini taşıdığında devreye girer. Bu durumda aynı nesnenin DocumentType alanı literal OKCBilgiFisi değerini taşımalı; ayrıca Id, IssueDate, DocumentDescription, Attachment.ExternalReference, IssuerParty.EndpointId ve ValidityPeriod.StartDate alanlarının hepsi dolu olmalı ve ValidityPeriod.StartDate, IssueDate ile aynı takvim gününde olmalıdır. Eksik/uyumsuz her alan Katman A'daki ilgili "SCHEME" mesajını üretir.
Mükerrer/iade referansı (InvoiceTypeCode ∈ IADE/TEVKIFATIADE/YTBIADE/YTBTEVKIFATIADE) doğrulaması, BillingReference[].InvoiceDocumentReference nesnesinde DocumentTypeCode=IADE ve tam olarak 16 karakterli bir Id bekler; aynı istekte birden fazla satırın aynı Id'yi referans vermesi "mükerrer" olarak reddedilir.
Kaynak Bölümler
- VUK Genel Tebliği (Sıra No: 509) — IV.2. e-Arşiv Fatura Uygulaması
- GİB e-Arşiv Teknik Kılavuzu V1.18 — §3.3.2 fatura, §3.3.2.27 faturaIptal, §3.3.3 faturaitiraz
- 6102 sayılı Türk Ticaret Kanunu — madde 18/3 (itiraz yöntemi), madde 21 (fatura kabul karinesi)