e-Arşiv Fatura

API

Request → UBL XML Mapping

Entegratörün gönderdiği JSON alanlarının UBL Invoice XML'deki karşılığını gösteren referans tablo.

Mapping Kapsamı

Kısa kural: Entegratör üç farklı gövde formatından birini gönderebilir: JSON (AddOutgoingInvoice), platformun düz XML modeli (AddOutgoingInvoiceByXml) veya UBL-TR Invoice belgesi (AddOutgoingInvoiceByUbl). Bir model alanının UBL standardında tanımlanması ile platformun UBL girişinde o alanı okuması ayrı sözleşmelerdir; aşağıdaki tablo platformun gözlenebilir dönüşümünü gösterir.

Referans Tablo

JSON/Model AlanıGerçek UBL Invoice XML KarşılığıNot
ProfileIdcbc:ProfileIDBelgenin e-Arşiv profilini taşır.
InvoiceTypeCodecbc:InvoiceTypeCodeSatış, iade veya istisna gibi fatura tipini taşır.
IssueDatecbc:IssueDate ve cbc:IssueTimeRequest tarih-zamanı UBL'de tarih ve saat olarak ayrılır.
InvoicePeriod.StartDate / EndDatecac:InvoicePeriod altındaki tarih ve saat çiftleriSARJ ve SARJANLIK tiplerinde birlikte zorunludur; her iki tarih de 01.01.2005 veya sonrası olmalıdır.
AdditionalDocumentReference[]
SchemeId=ESURaporID
cac:AdditionalDocumentReference/cbc:ID + cbc:IssueDateSARJ için en az bir kayıt bulunur. Her Id GUID biçiminde, her IssueDate 2000–2099 aralığında olmalıdır; geçerli kayıtların tamamı request sırasıyla ayrı elemanlara aktarılır. DocumentDescription zorunlu değildir.
ContractDocumentReference[]
SchemeId=YTBNO
cac:ContractDocumentReference/cbc:ID + cbc:IssueDateYTBTEVKIFAT ve YTBTEVKIFATIADE için tam bir kayıt bulunur; Id yalnız rakamlardan oluşan 6 hane, IssueDate dolu olmalıdır. DocumentDescription zorunlu değildir.
DocumentCurrencyCodecbc:DocumentCurrencyCodeBelge tutarlarının para birimini belirler.
AccountingSupplierPartycac:AccountingSupplierPartyFaturayı düzenleyen tarafın kimlik ve adres bilgilerini taşır.
AccountingCustomerPartycac:AccountingCustomerPartyAlıcının kimlik, ad ve adres bilgilerini taşır.
AccountingCustomerParty.Party.PartyIdentifications[]cac:PartyIdentification/cbc:IDTam olarak bir VKN (10 rakam) veya TCKN (11 rakam) kaydı alıcı tipini belirler; PASAPORTNO ve TESISATNO gibi diğer şemalar genel senaryolarda korunabilir ve bu sayıma katılmaz. TEKNOLOJIDESTEK tipinin yalnız TCKN kabul eden daha dar kuralı ayrıca uygulanır.
AccountingCustomerParty...PartyIdentifications[]
SchemeId=PLAKA
cac:AccountingCustomerParty/.../cbc:ID[@schemeID='PLAKA']SARJ ve SARJANLIK tiplerinde tam bir kayıt bulunur; değer 1–50 karakterdir ve yalnız büyük harf, rakam, _ veya - içerir.
AccountingCustomerParty.Party.PartyNamecac:PartyName/cbc:NameVKN'li tüzel alıcının unvanıdır.
AccountingCustomerParty.Party.Person.FirstName / FamilyNamecac:Person/cbc:FirstName / cbc:FamilyNameTCKN'li gerçek alıcının ad ve soyadıdır.
AllowanceCharge[]cac:AllowanceChargeBelge seviyesindeki indirim ve artırımları taşır.
TaxTotal[]cac:TaxTotalBelge seviyesindeki vergi toplamlarını taşır.
LegalMonetaryTotalcac:LegalMonetaryTotalVergi hariç, vergi dahil ve ödenecek toplamları taşır.
InvoiceLine[]cac:InvoiceLineHer fatura kalemi kendi miktar, fiyat, vergi ve mal/hizmet bilgisiyle aktarılır. SARJ/SARJANLIK için Item.Name, InvoicedQuantity.Value/UnitCode ve en az bir TaxTotal.TaxSubtotal zorunludur.
InvoiceLine[].Price
InvoiceLine[].InvoicedQuantity.Value
cac:Price/cbc:PriceAmount
cbc:InvoicedQuantity
SARJ/SARJANLIK için 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ıSARJ/SARJANLIK için vergi matrahı ve tutarları en fazla 2, vergi oranı en fazla 3 ondalık basamak içerebilir.
InvoiceLine[].Item.ItemInstance[].SerialIdcac:Item/cac:ItemInstance/cbc:SerialIDSARJANLIK tipinde tam bir kalemde tam bir boş olmayan seri numarası bulunur.
InvoiceLine[].Item.AdditionalItemIdentification[]
SchemeId=TELEFON / TABLET_PC
cac:Item/cac:AdditionalItemIdentification/cbc:IDTEKNOLOJIDESTEK tipinde her kalemde bu iki büyük harfli şema değerinden en az biri bulunur.
BillingReference[]cac:BillingReferenceÖKC, iade ve önceki belge referanslarını taşır. YTBTEVKIFATIADE dahil iade tiplerinde InvoiceDocumentReference altında DocumentTypeCode=IADE, tam 16 karakterli Id ve kaynak belge IssueDate değeri gönderilir.
Delivery[]cac:DeliveryTeslim tarihi, adresi, tarafı ve teslim koşullarını taşır.
PaymentMeans[]cac:PaymentMeansÖdeme yöntemini ve ilgili ödeme bilgilerini taşır.
WithholdingTaxTotal[]cac:WithholdingTaxTotalTevkifat toplamlarını belge seviyesinde taşır.
InternetPaymentPlatformun UBL girişinden request modeline aktarılmaz.İnternet satışı alanları JSON veya platformun düz XML modeliyle gönderilmelidir.
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.
İnternet satışı alanlarının giriş biçimi: Platformun UBL giriş işlemi InternetPayment alanını request modeline aktarmaz. Bu bilgileri gönderecek entegratörler JSON (AddOutgoingInvoice) veya platformun düz XML modelini (AddOutgoingInvoiceByXml) kullanmalıdır. Düz XML biçimi platform model alanlarını kullanır; UBL cac:/cbc: isim alanlarıyla karıştırılmamalıdır.
Alıcı ad alanı: TCKN'li alıcıda PartyName gerçek kişi adı yerine kullanılmamalıdır; Person.FirstName ve Person.FamilyName gönderilmelidir. VKN'li alıcıda ise PartyName zorunludur.

Uygulama Notları

ÖKC referansı gönderilirken DocumentTypeCode alanının literal olarak OKCBF, DocumentType alanının literal olarak OKCBilgiFisi değerini taşıması zorunludur; bu ikisi ve Id/IssueDate/DocumentDescription/Attachment.ExternalReference/IssuerParty.EndpointId/ValidityPeriod.StartDate alanlarından herhangi biri eksik veya uyumsuzsa istek "SCHEME" koduyla reddedilir (bkz. Teknik Referans — Katman A). İnternet satışı senaryosunda faturanın Note alanına "Bu satış internet üzerinden yapılmıştır." ibaresinin eklenmesi VUK 509 md. IV.2.4.5 gereğidir; bu ibare için UBL tarafında ayrı bir zorunlu eleman yoktur, serbest metin olarak cbc:Note'a taşınır.