e-Fatura

Giden Fatura

Giden Fatura JSON → UBL Mapping

Giden fatura JSON alanlarının üretilen UBL Invoice XML içindeki karşılıkları.

Mapping Kapsamı

Kısa kural: Aşağıdaki tablo, AddOutgoingInvoice isteğinin ortak alanlarıyla profile özgü alanlarının UBL Invoice belgesindeki karşılığını birlikte gösterir. Düz XML için AddOutgoingInvoiceByXml, hazır UBL belgesi için AddOutgoingInvoiceByUbl kullanılır. EARSIVFATURA bu rehberin kapsamı dışındadır.

Referans Tablo

JSON AlanıUBL Invoice KarşılığıKural
ProfileIdcbc:ProfileIDTüm e-Fatura isteklerinde zorunludur.
InvoiceTypeCodecbc:InvoiceTypeCodeSeçilen profile ve güncel GİB kılavuzuna uygun olmalıdır.
IssueDatecbc:IssueDate + cbc:IssueTimeTarih ve saat bileşenleri UBL belgesine ayrı yazılır.
InvoicePeriod.StartDate / EndDatecac:InvoicePeriod/cbc:StartDate + StartTime / EndDate + EndTimeENERJI profilindeki SARJ ve SARJANLIK faturalarında tarih ve saat çiftleri birlikte zorunludur.
DocumentCurrencyCodecbc:DocumentCurrencyCodeBelge toplamları ve satır tutarları bu para birimiyle tutarlı olmalıdır.
AccountingSupplierPartycac:AccountingSupplierPartySatıcı tarafının kimlik, unvan ve adres bilgilerini taşır.
AccountingCustomerPartycac:AccountingCustomerPartyAlıcı tarafının kimlik, unvan ve adres bilgilerini taşır.
AccountingCustomerParty.Party.PartyIdentifications[]
SchemeId=PLAKA
cac:AccountingCustomerParty/cac:Party/cac:PartyIdentification/cbc:ID
schemeID="PLAKA"
ENERJI profilinde tam bir plaka kaydı bulunur.
AdditionalDocumentReference[]
SchemeId=ESURaporID
cac:AdditionalDocumentReference/cbc:ID + cbc:IssueDateSARJ faturasında en az bir kayıt bulunur; her Id GUID biçiminde, her IssueDate 2000–2099 aralığında olmalıdır.
InvoiceLine[].Item.ItemInstance[].SerialIdcac:InvoiceLine/cac:Item/cac:ItemInstance/cbc:SerialIDSARJANLIK faturasında her satır en az bir boş olmayan seri numarası taşır.
BillingReference[].InvoiceDocumentReferencecac:BillingReference/cac:InvoiceDocumentReferenceIADE, TEVKIFATIADE, YTBIADE ve YTBTEVKIFATIADE tiplerinde cbc:DocumentTypeCode=IADE, tam 16 karakterli cbc:ID ve kaynak belge tarihi taşır; KAMU iadesinde de aynı yapı kullanılır.
Delivery[]cac:DeliveryTeslim tarihi, adresi, taşıma bilgisi ve ihracat teslim koşullarını taşır.
PaymentMeans[]cac:PaymentMeansÖdeme aracı, vade ve alacaklı hesap bilgilerini taşır; KAMU profilinde TR IBAN kontrolü uygulanır.
AllowanceCharge[]cac:AllowanceChargeBelge seviyesindeki indirim ve artırımlar tutar, oran ve temel tutarla birlikte aktarılır.
TaxTotal[]cac:TaxTotalVergi toplamı ve alt vergi kırılımları birlikte aktarılır.
TaxTotal[].TaxSubtotal[].TaxCategory.TaxExemptionReasonCodecac:TaxTotal/cac:TaxSubtotal/cac:TaxCategory/cbc:TaxExemptionReasonCode233 kamulaştırma istisnasıdır. 555 yalnız izin verilen profil/tiplerde ve sıfır olmayan 0015 KDV ile kullanılır. 308/339 yalnız yatırım teşvik bağlamındadır.
LegalMonetaryTotalcac:LegalMonetaryTotalVergi hariç, vergi dahil ve ödenecek toplamları taşır.
InvoiceLine[]cac:InvoiceLineHer kalemin miktar, fiyat, vergi ve ürün bilgilerini taşır. ENERJI profilinde Item.Name, InvoicedQuantity.Value/UnitCode ve en az bir TaxTotal.TaxSubtotal zorunludur.
InvoiceLine[].Price
InvoiceLine[].InvoicedQuantity.Value
cac:Price/cbc:PriceAmount
cbc:InvoicedQuantity
ENERJI profilindeki SARJ/SARJANLIK faturalarında her iki değer de en fazla 8 ondalık basamak içerebilir.
InvoiceLine[].TaxTotal.TaxAmount
TaxSubtotal[].TaxableAmount / TaxAmount / Percent
cac:TaxTotal ve cac:TaxSubtotal altındaki tutar/oran alanlarıENERJI profilindeki SARJ/SARJANLIK faturalarında vergi matrahı ve tutarları en fazla 2, vergi oranı en fazla 3 ondalık basamak içerebilir.
InvoiceLine[].Item.CommodityClassification[].Valuecac:InvoiceLine/cac:Item/cac:CommodityClassification/cbc:ItemClassificationCodeYATIRIMTESVIK profilinde zorunludur. JSON request alanı Value'dur; değer 01, 02, 03 veya 04 olmalıdır.
ContractDocumentReference[]
SchemeId=YTBNO
cac:ContractDocumentReference/cbc:ID
+ cbc:IssueDate
YATIRIMTESVIK profilinde zorunludur. ID 6 haneli, IssueDate dolu olmalıdır.
InvoiceLine[].Delivery[].Shipment.GoodsItem[].RequiredCustomsIdcac:InvoiceLine/cac:Delivery/cac:Shipment/cac:GoodsItem/cbc:RequiredCustomsIDIHRACAT profilinde her kalemde zorunludur. GTİP değeri 12 haneli ve yalnızca rakam olmalıdır.
InvoiceLine[].Item.AdditionalItemIdentification[]
SchemeId=KUNYENO
cac:InvoiceLine/cac:Item/cac:AdditionalItemIdentification/cbc:ID
schemeID="KUNYENO"
HKS profilinde her kalemde zorunludur. Değer tam 19 karakter olmalıdır.
InvoiceLine[].Item.AdditionalItemIdentification[]
SchemeId=ILACSchemeId=TIBBICIHAZSchemeId=DIGER
cac:InvoiceLine/cac:Item/cac:AdditionalItemIdentification/cbc:IDILAC_TIBBICIHAZ profilinde her kalem bu üç şema değerinden birini taşımalıdır.
InvoiceLine[].Item.AdditionalItemIdentification[]
SchemeId=ETIKETNO
cac:InvoiceLine/cac:Item/cac:AdditionalItemIdentification/cbc:ID
schemeID="ETIKETNO"
IDIS profilinde her kalemde zorunludur. Değer 2 harf ve ardından 7 rakam içermelidir.
IdisSevkiyatNocac:AccountingSupplierParty/cac:Party/cac:PartyIdentification/cbc:ID
schemeID="SEVKIYATNO"
IDIS profilinde zorunludur. Değer SE- veya ES- ön eki ve ardından tam 7 rakam içermelidir. Hazır UBL’de bu değer AccountingSupplierParty altındaki SEVKIYATNO kimliğinde taşınır. Hedef ortamda İDİS UBL giriş desteği teyit edilmediyse JSON veya platform XML’i kullanın.
PricingCurrencyCodecbc:PricingCurrencyCodeUBL Invoice içinde opsiyoneldir. AddOutgoingInvoice isteğinden üretilen UBL'ye aktarılmaz; AddOutgoingInvoiceByUbl ile verilen hazır UBL'de kullanılabilir.
TaxCurrencyCodecbc:TaxCurrencyCodeUBL Invoice içinde opsiyoneldir. AddOutgoingInvoice isteğinden üretilen UBL'ye aktarılmaz; AddOutgoingInvoiceByUbl ile verilen hazır UBL'de kullanılabilir.
PaymentAlternativeCurrencyCodecbc:PaymentAlternativeCurrencyCodeUBL Invoice içinde opsiyoneldir. AddOutgoingInvoice isteğinden üretilen UBL'ye aktarılmaz; AddOutgoingInvoiceByUbl ile verilen hazır UBL'de kullanılabilir.
Ayrıntı ve güncelleme çevrimi: UBL'den üretilen ayrıntı yanıtında AdditionalDocumentReference[] ve ContractDocumentReference[] kayıtlarının Id ile SchemeId alanları birlikte korunur. InvoiceLine[].Item.AdditionalItemIdentification[] değerleri düz metin dizisi değil, her biri SchemeId ve Value taşıyan nesneler olarak döner. SARJ ve SARJANLIK tiplerinde UBL'deki StartDate/StartTime ile EndDate/EndTime çiftleri ayrıntı ve güncelleme modellerindeki InvoicePeriod.StartDate/EndDate tarih-saat değerlerine yeniden birleştirilir; diğer fatura tiplerinin ortak dönem dönüşümü tarih bileşeniyle kalır. Bu alanları ayrıntı yanıtından güncelleme isteğine taşırken nesne yapısı ve SchemeId değerleri kaybedilmemelidir.

Uygulama Notları

Yatırım Teşvik Fatura Tipi Kümeleri

ItemClassificationCodeİzin Verilen InvoiceTypeCode DeğerleriEk Kural
01 veya 02SATIS, ISTISNA veya IADEGüncel GİB e-Fatura kılavuzundaki tip kümesi kullanılır.
03 veya 04SATIS veya IADEISTISNA kullanılamaz; KDV oranı sıfır olamaz.
İstisna kodu eşleşmesi: YATIRIMTESVIK + ISTISNA bağlamında ItemClassificationCode=01 olan kalemin 0015 KDV kırılımında TaxExemptionReasonCode=308; ItemClassificationCode=02 olan kalemde 339 bulunmalıdır.

Profil Bazlı Alan Kontrolleri

ProfilZorunlu DeğerKoşulHata
IHRACATGTİPHer kalemde 12 haneli sayısal değerSCHEME
HKSKUNYENOHer InvoiceLine içinde bulunmalıdırSCHEME
ILAC_TIBBICIHAZILAC, TIBBICIHAZ veya DIGERHer InvoiceLine bu değerlerden birini taşımalıdırSCHEME
IDISETIKETNOHer InvoiceLine içinde bulunmalıdırSCHEME