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 |
|---|---|---|
ProfileId | cbc:ProfileID | Belgenin e-Arşiv profilini taşır. |
InvoiceTypeCode | cbc:InvoiceTypeCode | Satış, iade veya istisna gibi fatura tipini taşır. |
IssueDate | cbc:IssueDate ve cbc:IssueTime | Request tarih-zamanı UBL'de tarih ve saat olarak ayrılır. |
InvoicePeriod.StartDate / EndDate | cac:InvoicePeriod altındaki tarih ve saat çiftleri | SARJ 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:IssueDate | SARJ 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:IssueDate | YTBTEVKIFAT 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. |
DocumentCurrencyCode | cbc:DocumentCurrencyCode | Belge tutarlarının para birimini belirler. |
AccountingSupplierParty | cac:AccountingSupplierParty | Faturayı düzenleyen tarafın kimlik ve adres bilgilerini taşır. |
AccountingCustomerParty | cac:AccountingCustomerParty | Alıcının kimlik, ad ve adres bilgilerini taşır. |
AccountingCustomerParty.Party.PartyIdentifications[] | cac:PartyIdentification/cbc:ID | Tam 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.PartyName | cac:PartyName/cbc:Name | VKN'li tüzel alıcının unvanıdır. |
AccountingCustomerParty.Party.Person.FirstName / FamilyName | cac:Person/cbc:FirstName / cbc:FamilyName | TCKN'li gerçek alıcının ad ve soyadıdır. |
AllowanceCharge[] | cac:AllowanceCharge | Belge seviyesindeki indirim ve artırımları taşır. |
TaxTotal[] | cac:TaxTotal | Belge seviyesindeki vergi toplamlarını taşır. |
LegalMonetaryTotal | cac:LegalMonetaryTotal | Vergi hariç, vergi dahil ve ödenecek toplamları taşır. |
InvoiceLine[] | cac:InvoiceLine | Her 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[].PriceInvoiceLine[].InvoicedQuantity.Value | cac:Price/cbc:PriceAmountcbc:InvoicedQuantity | SARJ/SARJANLIK için her iki değer de en fazla 8 ondalık basamak içerebilir. |
InvoiceLine[].TaxTotal.TaxAmountTaxSubtotal[].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[].SerialId | cac:Item/cac:ItemInstance/cbc:SerialID | SARJANLIK tipinde tam bir kalemde tam bir boş olmayan seri numarası bulunur. |
InvoiceLine[].Item.AdditionalItemIdentification[]SchemeId=TELEFON / TABLET_PC | cac:Item/cac:AdditionalItemIdentification/cbc:ID | TEKNOLOJIDESTEK 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:Delivery | Teslim tarihi, adresi, tarafı ve teslim koşullarını taşır. |
PaymentMeans[] | cac:PaymentMeans | Ödeme yöntemini ve ilgili ödeme bilgilerini taşır. |
WithholdingTaxTotal[] | cac:WithholdingTaxTotal | Tevkifat toplamlarını belge seviyesinde taşır. |
InternetPayment | Platformun 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./IssuerParty./ValidityPeriod. 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.