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.
Üretici kimliği: Erken kullanım dahil SMS doğrulaması gönderildiğinde üretici 11 haneli TCKN ve gerçek kişi bilgileriyle tanımlanır. Geçiş öncesindeki SMS’siz belgelerde mevcut gerçek/tüzel kişi ayrımı uygulanır.
Mapping Kapsamı
Request modeli, UBL 2.1 CreditNote XML'e çiftçi/alıcı tarafları, SMS doğrulama bilgileri, ürün kalemleri, belge toplamları, vergi/kesinti toplamları ve tevkifat alanları üzerinden yansır.
UBL bütünlüğü: SMS yöntem, bilgi ve sağlayıcı düğümlerinin tamamı boş veya tamamı dolu olmalıdır. SMS alanlarının yalnız bir kısmı gönderilirse istek reddedilir. Planlanan sürümde tam SMS paketi UBL ve rapora yazılır. SMS kullanılmadığında raporda kod, telefon ve operatör bölümü oluşturulmaz.
Kısa kural: Request tarafındaki ekonomik veri
CreditNoteLine, TaxTotal, WithholdingTaxTotal ve LegalMonetaryTotal alanlarında; kimlik ve doğrulama verisi ise AccountingSupplierParty ile AccountingCustomerParty altında UBL'e yansır. Doğrudan JSON entegrasyonunda platform SMS/SMS_PROVIDER sabitlerini üretir; hazır UBL entegratörü aynı sabitleri XML içinde kendisi sağlar.Hazır ve imzalı UBL:
CreditNoteUblRequestModel.IsSigned = true kullanılıyorsa Contact/Telephone doğrudan 5XXXXXXXXX biçiminde, diğer alanlar da nihai ve GİB'e uygun hazırlanmalıdır. Platform imzalı XML'i normalize etmez veya yeniden yazmaz; canonical olmayan telefon EMM0061 ile reddedilir. Değişiklik gereken UBL entegratör tarafından düzeltilip yeniden imzalanmalıdır. IsSigned yalnız imzası entegratör tarafından doğrulanmış UBL için true gönderilmelidir.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 | ETTN — evrensel tekil belge kimliği |
CreditNoteNumber | cbc:ID | Belge numarası (16 karakter) |
ProfileId | cbc:ProfileID | Sabit: EARSIVBELGE |
CreditNoteTypeCode | cbc:CreditNoteTypeCode | Sabit: MUSTAHSILMAKBUZ |
DocumentCurrencyCode | cbc:DocumentCurrencyCode | ISO 4217 para birimi |
IssueDate | cbc:IssueDate + cbc:IssueTime | Tarih ve saat ayrı yazılır |
Note[] | cbc:Note (tekrarlanabilir) | Genel açıklamalar |
| Taraflar | ||
AccountingSupplierParty | cac:AccountingSupplierParty/cac:Party | Makbuzu düzenleyen/alıcı firma |
AccountingCustomerParty | cac:AccountingCustomerParty/cac:Party | Üretici/çiftçi; SMS doğrulamalı belgede SchemeId=TCKN |
AccountingCustomerParty.Party.PartyName | cac:PartyName/cbc:Name | Üretici/çiftçi ad soyadı |
AccountingCustomerParty.Party.Person.FirstName / FamilyName | cac:Person/cbc:FirstName / cbc:FamilyName | Üretici/çiftçinin adı ve soyadı |
| SMS Doğrulaması | ||
VerificationMethod | cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Name | Hazır UBL değeri SMS |
VerificationInfo.Code | cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ID | Üreticinin doğruladığı SMS kodu |
VerificationInfo.PhoneNumber | cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Telephone | Kodun gönderildiği telefon; imzalı hazır UBL'de 5XXXXXXXXX |
VerificationMethod | cac:AccountingSupplierParty/cac:Party/cac:Contact/cac:OtherCommunication/cbc:ChannelCode/@name | Hazır UBL değeri SMS_PROVIDER |
VerificationProvider.ApplicationName | cac:AccountingSupplierParty/cac:Party/cac:Contact/cac:OtherCommunication/cbc:ChannelCode | SMS sağlayıcısının resmî adı |
VerificationProvider.Vkn | cac:AccountingSupplierParty/cac:Party/cac:Contact/cac:OtherCommunication/cbc:Value | SMS sağlayıcısının 10 haneli VKN'si |
| LegalMonetaryTotal → cac:LegalMonetaryTotal | ||
LegalMonetaryTotal. | cbc:LineExtensionAmount[@currencyID] | Satır toplamı |
LegalMonetaryTotal. | cbc:TaxExclusiveAmount[@currencyID] | KDV hariç tutar |
LegalMonetaryTotal. | cbc:TaxInclusiveAmount[@currencyID] | KDV dahil tutar |
LegalMonetaryTotal. | cbc:PayableAmount[@currencyID] | Ödenecek tutar (kesinti/tevkifat etkisi yansıtılmış) |
| TaxTotal[] → cac:TaxTotal | ||
TaxTotal[]. | cbc:TaxAmount[@currencyID] | Vergi/kesinti toplam tutarı |
TaxTotal[]. | cac:TaxSubtotal/cbc:TaxableAmount | Matrah |
TaxTotal[]. | cbc:Percent | KDV oranı (%) |
TaxTotal[].TaxSubtotal. | cac:TaxScheme/cbc:TaxTypeCode | Vergi/kesinti kodu: 0015, 0003, 8001, SGK_PRIM, 9040 |
TaxTotal[].TaxSubtotal. | cac:TaxScheme/cbc:Name | Kesinti adı: GV STOPAJI, BORSA TES.ÜC., SGK PRIM KESINTISI, MERA FONU |
| WithholdingTaxTotal[] → cac:WithholdingTaxTotal | ||
WithholdingTaxTotal[]. | cbc:TaxAmount[@currencyID] | Tevkifat tutarı |
WithholdingTaxTotal[].TaxSubtotal. | cbc:Percent | Tevkifat oranı (%) |
WithholdingTaxTotal[].TaxSubtotal. | cac:TaxScheme/cbc:TaxTypeCode | Tevkifat kodu; GV stopajı için 0003 |
| CreditNoteLine[] → cac:CreditNoteLine | ||
CreditNoteLine[]. | cbc:ID | Satır no (1'den başlar) |
CreditNoteLine[].CreditedQuantity / UnitCode | cbc:CreditedQuantity[@unitCode] | Miktar + birim |
CreditNoteLine[]. | cbc:LineExtensionAmount[@currencyID] | Satır toplamı |
CreditNoteLine[]. | cac:Item/cbc:Name | Ürün adı |
CreditNoteLine[]. | cac:Price/cbc:PriceAmount[@currencyID] | Birim fiyat |
CreditNoteLine[]. | cac:TaxTotal (satır altında) | Satır seviyesi vergi/kesinti alt toplamları |
CreditNoteLine[]. | cac:WithholdingTaxTotal (satır altında) | Satır seviyesi tevkifat (varsa) |
Uygulama Notları
Mapping notları, platformun otomatik tamamladığı alanlar ile entegratörün göndermesi gereken alanlar arasındaki sınırı netleştirir.
| Konu | Kontrol | Sonuç |
|---|---|---|
| Taraf kimliği | SMS ile doğrulamada üreticinin TCKN bilgisi gerekir. SMS isteğe bağlıyken SMS’siz makbuzda gerçek kişi TCKN, tüzel kişi VKN ile tanımlanır. Alıcı tam olarak bir VKN veya TCKN ile gönderilir | UBL taraf rolleri ve GİB raporundaki gerçek/tüzel kişi seçimi aynı kimliği kullanır |
| SMS doğrulaması | VerificationMethod=SMS, kod, telefon, sağlayıcı adı ve VKN aynı doğrulama kaydı olarak gönderilir | Üretici Contact ve sağlayıcı OtherCommunication alanları birlikte oluşur; kısmi veri reddedilir |
| Vergi/kesinti kodları | TaxTotal. içinde 0003, 8001, SGK_PRIM, 9040 kodları gerektiği kadar taşınır | Barkod ve rapor üretimi kesinti tutarlarını kod bazında okuyabilir |
| Tevkifat | WithholdingTaxTotal belge ve satır seviyesinde uyumlu hesaplanır | GİB raporundaki tevkifat alanları beslenir |
| Satır kalemleri | Her ürün ayrı CreditNoteLine olarak yazılır | Çok kalemli makbuzlarda her ürün kendi miktar/fiyat bilgisini taşır |
| Sabit değerler | ProfileID=EARSIVBELGE, CreditNoteTypeCode=MUSTAHSILMAKBUZ | Belgenin GİB tarafında e-Müstahsil Makbuzu olarak sınıflanmasını sağlar |