e-Müstahsil Makbuzu

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 PathAçıklama
Root Alanlar
UUIdcbc:UUIDETTN — evrensel tekil belge kimliği
CreditNoteNumbercbc:IDBelge numarası (16 karakter)
ProfileIdcbc:ProfileIDSabit: EARSIVBELGE
CreditNoteTypeCodecbc:CreditNoteTypeCodeSabit: MUSTAHSILMAKBUZ
DocumentCurrencyCodecbc:DocumentCurrencyCodeISO 4217 para birimi
IssueDatecbc:IssueDate + cbc:IssueTimeTarih ve saat ayrı yazılır
Note[]cbc:Note (tekrarlanabilir)Genel açıklamalar
Taraflar
AccountingSupplierPartycac:AccountingSupplierParty/cac:PartyMakbuzu düzenleyen/alıcı firma
AccountingCustomerPartycac:AccountingCustomerParty/cac:PartyÜretici/çiftçi; SMS doğrulamalı belgede SchemeId=TCKN
AccountingCustomerParty.Party.PartyNamecac:PartyName/cbc:NameÜretici/çiftçi ad soyadı
AccountingCustomerParty.Party.Person.FirstName / FamilyNamecac:Person/cbc:FirstName / cbc:FamilyNameÜretici/çiftçinin adı ve soyadı
SMS Doğrulaması
VerificationMethodcac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:NameHazır UBL değeri SMS
VerificationInfo.Codecac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:IDÜreticinin doğruladığı SMS kodu
VerificationInfo.PhoneNumbercac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:TelephoneKodun gönderildiği telefon; imzalı hazır UBL'de 5XXXXXXXXX
VerificationMethodcac:AccountingSupplierParty/cac:Party/cac:Contact/cac:OtherCommunication/cbc:ChannelCode/@nameHazır UBL değeri SMS_PROVIDER
VerificationProvider.ApplicationNamecac:AccountingSupplierParty/cac:Party/cac:Contact/cac:OtherCommunication/cbc:ChannelCodeSMS sağlayıcısının resmî adı
VerificationProvider.Vkncac:AccountingSupplierParty/cac:Party/cac:Contact/cac:OtherCommunication/cbc:ValueSMS sağlayıcısının 10 haneli VKN'si
LegalMonetaryTotal → cac:LegalMonetaryTotal
LegalMonetaryTotal.LineExtensionAmountcbc:LineExtensionAmount[@currencyID]Satır toplamı
LegalMonetaryTotal.TaxExclusiveAmountcbc:TaxExclusiveAmount[@currencyID]KDV hariç tutar
LegalMonetaryTotal.TaxInclusiveAmountcbc:TaxInclusiveAmount[@currencyID]KDV dahil tutar
LegalMonetaryTotal.PayableAmountcbc:PayableAmount[@currencyID]Ödenecek tutar (kesinti/tevkifat etkisi yansıtılmış)
TaxTotal[] → cac:TaxTotal
TaxTotal[].TaxAmountcbc:TaxAmount[@currencyID]Vergi/kesinti toplam tutarı
TaxTotal[].TaxSubtotal.TaxableAmountcac:TaxSubtotal/cbc:TaxableAmountMatrah
TaxTotal[].TaxSubtotal.Percentcbc:PercentKDV oranı (%)
TaxTotal[].TaxSubtotal.TaxCategory.TaxScheme.TaxTypeCodecac:TaxScheme/cbc:TaxTypeCodeVergi/kesinti kodu: 0015, 0003, 8001, SGK_PRIM, 9040
TaxTotal[].TaxSubtotal.TaxCategory.TaxScheme.Namecac:TaxScheme/cbc:NameKesinti adı: GV STOPAJI, BORSA TES.ÜC., SGK PRIM KESINTISI, MERA FONU
WithholdingTaxTotal[] → cac:WithholdingTaxTotal
WithholdingTaxTotal[].TaxAmountcbc:TaxAmount[@currencyID]Tevkifat tutarı
WithholdingTaxTotal[].TaxSubtotal.Percentcbc:PercentTevkifat oranı (%)
WithholdingTaxTotal[].TaxSubtotal.TaxCategory.TaxScheme.TaxTypeCodecac:TaxScheme/cbc:TaxTypeCodeTevkifat kodu; GV stopajı için 0003
CreditNoteLine[] → cac:CreditNoteLine
CreditNoteLine[].Idcbc:IDSatır no (1'den başlar)
CreditNoteLine[].CreditedQuantity / UnitCodecbc:CreditedQuantity[@unitCode]Miktar + birim
CreditNoteLine[].LineExtensionAmountcbc:LineExtensionAmount[@currencyID]Satır toplamı
CreditNoteLine[].Item.Namecac:Item/cbc:NameÜrün adı
CreditNoteLine[].Pricecac:Price/cbc:PriceAmount[@currencyID]Birim fiyat
CreditNoteLine[].TaxTotalcac:TaxTotal (satır altında)Satır seviyesi vergi/kesinti alt toplamları
CreditNoteLine[].WithholdingTaxTotalcac: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.

KonuKontrolSonuç
Taraf kimliğiSMS 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önderilirUBL 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.TaxSubtotal içinde 0003, 8001, SGK_PRIM, 9040 kodları gerektiği kadar taşınırBarkod ve rapor üretimi kesinti tutarlarını kod bazında okuyabilir
TevkifatWithholdingTaxTotal belge ve satır seviyesinde uyumlu hesaplanırGİB raporundaki tevkifat alanları beslenir
Satır kalemleriHer ürün ayrı CreditNoteLine olarak yazılırÇok kalemli makbuzlarda her ürün kendi miktar/fiyat bilgisini taşır
Sabit değerlerProfileID=EARSIVBELGE, CreditNoteTypeCode=MUSTAHSILMAKBUZBelgenin GİB tarafında e-Müstahsil Makbuzu olarak sınıflanmasını sağlar