API
Request → UBL XML Mapping
Entegratörün gönderdiği JSON alanlarının UBL XML'deki karşılığını gösteren referans tablo.
Mapping Kapsamı
Request modeli, UBL 2.1 CreditNote XML'e doğrulama sağlayıcısı, alıcı/vekil bilgileri, iade referansı, kargo ve belge satırları üzerinden yansır.
Kısa kural: Entegratör iş kararlarını request alanlarıyla gönderir; platform bu alanları UBL XML node'larına ve GİB rapor alanlarına dönüştürür. Kargo şirketi bilgilerinin tamamlanacağı akışlarda entegratör yalnızca kargo şirketi kodunu gönderir.
Request Alanı → UBL XML Path
Mapping tablosu, request modelindeki iş kararlarının UBL XML'de hangi node'lara taşındığını izlenebilir hale getirir.
| Request Alanı | UBL XML Path | Açıklama |
|---|---|---|
| Root Alanlar | ||
UUId | cbc:UUID | Evrensel tekil belge kimliği |
ExpenseVoucherNumber | cbc:ID | Belge numarası |
ProfileId | cbc:ProfileID | Sabit: GIDERPUSULASI |
ExpenseVoucherTypeCode | cbc:CreditNoteTypeCode | SATIS / IADE |
DocumentCurrencyCode | cbc:DocumentCurrencyCode | ISO 4217 para birimi |
IssueDate | cbc:IssueDate + cbc:IssueTime | Tarih ve saat ayrı olarak yazılır |
Note[] | cbc:Note (tekrarlanabilir) | Genel açıklamalar |
| VerificationMethod → GİB doğrulama alanları | ||
VerificationMethod | Contact/Name ve cbc:ChannelCode[@name] | SMS → SMS/SMS_PROVIDER; IADEKODU → IADEKODU/IADE_PROVIDER |
| VerificationProvider → AccountingSupplierParty/Party/Contact/OtherCommunication | ||
VerificationProvider. | cbc:ChannelCode[text()] | Sağlayıcı uygulama adı |
VerificationProvider. | cbc:Value | Sağlayıcı VKN (10 hane) |
| AccountingCustomerParty → cac:AccountingCustomerParty/cac:Party | ||
AccountingCustomerParty. | cac:PartyIdentification/cbc:ID | Kimlik no (TCKN/Pasaport değeri) |
AccountingCustomerParty. | cbc:ID/@schemeID | TCKN / PASAPORTNO |
AccountingCustomerParty. | cac:PartyName/cbc:Name | Alıcı adı soyadı |
| VerificationInfo → ilgili tarafın Party/Contact alanı (normal işlemde AccountingCustomerParty; vekâleten iadede BuyerCustomerParty) | ||
VerificationInfo. | cbc:ID | SMS veya iade kodu |
VerificationInfo. | cbc:Name | SMS / IADEKODU |
VerificationInfo. | cbc:Telephone | 0XXXXXXXXXX format |
| DelegateReceiver → cac:BuyerCustomerParty/cac:Party | ||
DelegateReceiver. | cac:PartyIdentification/cbc:ID[value] | DelegateReceiver yalnız IADE'de kullanılabilir; SATIS'te reddedilir. Nesne gönderildiğinde Identification, IdentificationType (TCKN/PASAPORTNO) ve Name alanlarının üçü de zorunludur — kısmi doldurma kabul edilmez. |
DelegateReceiver. | cbc:ID/@schemeID | |
DelegateReceiver. | cac:Person/cbc:FirstName | |
| ReturnedDocumentReference → cac:BillingReference/cac:InvoiceDocumentReference | ||
ReturnedDocumentReference. | cbc:ID/@schemeID | EARSIV_FATURA / SATIS_FISI / BELGESIZ |
ReturnedDocumentReference. | cbc:ID[value] | Belge numarası |
ReturnedDocumentReference. | cbc:IssueDate | yyyy-MM-dd |
| Kargo şirketi → cac:Delivery/cac:DeliveryParty | ||
CargoCompanyCode | cac:DeliveryParty/cac:PartyIdentification/cbc:ID[@schemeID="VKN"] | JSON endpointleri: Entegratör yalnız CargoCompanyCode gönderir; platform kendi ürettiği UBL'de kargo şirketi bilgilerini tamamlar.Hazır UBL endpointleri: Entegratör önce CargoCompanies/ kaydını almalı; VKN, unvan, yetki belge numarası, şehir, ilçe ve ülke değerlerini değiştirmeden DeliveryParty içine yazmalıdır. Platform UBL'yi tamamlamaz veya değiştirmez; uyumsuz içeriği EGP0087 ile reddeder. |
| (DB: VKN) | cbc:ID[value] | |
| (DB: Title) | cac:PartyName/cbc:Name | |
| (DB: ClassificationCode) | cbc:IndustryClassificationCode | |
| (DB: CityName / CitySubdivisionName / CountryName) | cac:PostalAddress/... | |
| LegalMonetaryTotal → cac:LegalMonetaryTotal | ||
LegalMonetaryTotal. | cbc:PayableAmount[@currencyID] | Ödenecek tutar |
LegalMonetaryTotal. | cbc:TaxExclusiveAmount[@currencyID] | Vergisiz toplam |
LegalMonetaryTotal. | cbc:TaxInclusiveAmount[@currencyID] | Vergili toplam |
LegalMonetaryTotal. | cbc:LineExtensionAmount[@currencyID] | Satır toplamı |
| TaxTotal[] → cac:TaxTotal | ||
TaxTotal[]. | cbc:TaxAmount[@currencyID] | Vergi tutarı |
TaxTotal[]. | cac:TaxSubtotal/cbc:TaxableAmount | Matrah |
TaxTotal[]. | cbc:CalculationSequenceNumeric | Hesaplama sırası (birden fazla vergi kalemi olduğunda) |
TaxTotal[]. | cbc:TransactionCurrencyTaxAmount | İşlem para birimindeki vergi tutarı |
TaxTotal[]. | cbc:PerUnitAmount | Birim başına vergi tutarı |
TaxTotal[]. | cac:TaxScheme/cbc:TaxTypeCode | Vergi kodu (0015 KDV, 0003 GV Stopajı vb.) |
TaxTotal[]. | cac:TaxScheme/cbc:Name | Vergi adı (örn. "KDV GERCEK", "GV STOPAJI") |
TaxTotal[]. | cbc:Percent | Vergi oranı (%) |
| ExpenseVoucherLine[] → cac:CreditNoteLine | ||
ExpenseVoucherLine[]. | cbc:ID | Satır no (1'den başlar) |
ExpenseVoucherLine[].Quantity / UnitCode | cbc:CreditedQuantity[@unitCode] | Miktar + birim |
ExpenseVoucherLine[]. | cbc:LineExtensionAmount[@currencyID] | Satır toplamı |
ExpenseVoucherLine[]. | cac:Item/cbc:Name | Ürün/hizmet adı |
ExpenseVoucherLine[]. | cac:Price/cbc:PriceAmount[@currencyID] | Birim fiyat |
Entegratör sorumluluğu: Hazır UBL endpointlerinde gönderilmesi gereken alanlar, Add/Update özel durumları ve başarılı/başarısız örnekler Entegratör Sorumlulukları sayfasında yer alır. Bu sayfadaki tablo, request alanlarının UBL path karşılıkları için kanonik referanstır.
Uygulama Notları
Mapping notları, platformun otomatik tamamladığı alanlar ile entegratörün göndermesi gereken alanlar arasındaki sınırı netleştirir.
Vekâletli UBL uyarısı: Vekâleten yapılan iadelerde doğrulama bilgisinin gönderileceği
Contact konumu değişir. Asıl alıcı AccountingCustomerParty içinde korunmalı; vekil ve doğrulama bilgileri BuyerCustomerParty altında gönderilmelidir. Tam kural ve XML örneği için Entegratör Sorumlulukları bölümünü inceleyin.Note[] hakkında: Platform, entegratörün gönderdiği listeye kendi ürettiği bir cbc:Note ekler (tutarın yazıyla karşılığı). Bu nedenle UBL çıktısındaki Note sayısı, request'te gönderilenden bir fazla olabilir.