Teknik Temel
GİB Referansı
GİB paketi, kullanım yöntemi, teknik gereksinimler ve resmi kaynaklar.
GİB Paketi
GİB'in yayımladığı teknik kılavuz; UBL-TR 1.2.1 şema tanımlarını, e-Müstahsil Makbuzu'na özgü CreditNoteTypeCode/ProfileID değerlerini ve örnek XML yapısını içerir.
Kullanım Yöntemi
e-Fatura uygulamasına dahil olan mükellefler, e-Müstahsil Makbuzu sistemini GİB tarafından yetkilendirilmiş Özel Entegratörler aracılığıyla kullanabilir. VBT Yazılım bu süreçte Özel Entegratör konumundadır.
Teknik Gereksinimler
Teknik gereksinimler, UBL üretimi ile GİB raporlamasının aynı veri setinden tutarlı şekilde beslenmesini sağlar.
UBL Belge Standardı
e-Müstahsil Makbuzu UBL 2.1 CreditNote doküman tipi üzerinden ifade edilir; üretilen XML'de aşağıdaki sabit sürüm ve belge kimliği bilgileri kullanılır:
| Alan | Değer |
|---|---|
UBLVersionID | 2.1 |
CustomizationID | TR1.2.1 |
ProfileID | EARSIVBELGE |
CreditNoteTypeCode | MUSTAHSILMAKBUZ |
CreditNote tipidir; belgeyi Müstahsil yapan ayırt edici alan CreditNoteTypeCode=MUSTAHSILMAKBUZ değeridir.Taraf Kimlik Tipleri
UBL-TR'nin PartyIdentification şema kodları bu belgede şu şekilde kullanılır:
| Taraf | SchemeId | Açıklama |
|---|---|---|
Makbuzu düzenleyen/alıcı firma (AccountingSupplierParty) | VKN veya TCKN | Makbuzu düzenleyen tarafın kimliği |
Üretici/çiftçi (AccountingCustomerParty) | TCKN veya SMS isteğe bağlıyken SMS’siz tüzel kişi makbuzunda VKN | SMS ile doğrulanan makbuzda 11 haneli TCKN zorunludur ve doğrulama bilgileri bu tarafın Contact alanında taşınır. |
AccountingCustomerParty altında 11 haneli TCKN ile gönderilmelidir.Vergi ve Kesinti Kodları
e-Müstahsil Makbuzu'nda vergi ve kesinti kalemleri UBL TaxTotal/TaxSubtotal yapısıyla taşınabilir. Platformun barkod ve Excel dönüşüm akışında GV stopajı, borsa tescil, SGK prim ve mera fonu tutarları bu kodlar üzerinden ayrıştırılır.
| TaxTypeCode | Name | Kapsam |
|---|---|---|
0003 | GV STOPAJI | Gelir vergisi stopajı |
8001 | BORSA TES.ÜC. | Borsa tescil kesintisi |
SGK_PRIM | SGK PRIM KESINTISI | SGK prim kesintisi |
9040 | MERA FONU | Mera fonu kesintisi |
Senaryo Bazlı Alan Kapsamı
Kesinti türü değiştiğinde belge iskeleti aynı kalır; zorunlu alan farkı, ilgili tutarın TaxTotal.TaxSubtotal veya WithholdingTaxTotal altında kod bazında taşınmasından doğar.
| Senaryo | Zorunlu UBL Alanı | Kod/Ad | GİB Rapor Karşılığı | Net Tutar Etkisi |
|---|---|---|---|---|
| Normal oluşturma | CreditNoteLine, LegalMonetaryTotal | Ek kesinti kodu yok | vergiBilgisi.vergi[] temel vergi bilgileriyle kapanır | PayableAmount satır toplamlarıyla uyumludur |
| GV stopajı | TaxTotal.TaxSubtotal | 0003 / GV STOPAJI | vergiBilgisi.vergi[] içinde kod bazında izlenir | Stopaj tutarı net ödenecek tutara yansır |
| Borsa tescil | TaxTotal.TaxSubtotal | 8001 / BORSA TES.ÜC. | vergiBilgisi.vergi[] içinde ayrı satır olarak izlenir | Kesinti tutarı net ödenecek tutara yansır |
| SGK prim | TaxTotal.TaxSubtotal | SGK_PRIM / SGK PRIM KESINTISI | vergiBilgisi.vergi[] içinde ayrı satır olarak izlenir | Kesinti tutarı net ödenecek tutara yansır |
| Mera fonu | TaxTotal.TaxSubtotal | 9040 / MERA FONU | vergiBilgisi.vergi[] içinde ayrı satır olarak izlenir | Kesinti tutarı net ödenecek tutara yansır |
| Çoklu kesinti | TaxTotal.TaxSubtotal[] | Her kesinti için ayrı kod satırı | vergiBilgisi.vergi[] her kodu ayrı taşır | TaxTotal.TaxAmount alt satırların toplamıyla uyumlu olmalıdır |
| Tevkifat | WithholdingTaxTotal | Tevkifat kodu ve oranı | vergiBilgisi.tevkifat[] | Aynı ekonomik tutar TaxTotal altında tekrar düşülmemelidir |
Tevkifat (Withholding Tax)
UBL şemasındaki WithholdingTaxTotal alanı, belge ve satır seviyesinde ayrıca tevkifat bilgisi taşınması gereken durumlarda kullanılır. Bu alan doldurulduğunda toplamlar, LegalMonetaryTotal/PayableAmount değerindeki net ödenecek tutarla uyumlu kalmalıdır.
TaxTotal altında, tevkifat ise WithholdingTaxTotal altında taşındığında aynı ekonomik tutar iki kez düşülmemelidir; PayableAmount tek net sonucu göstermelidir.Belge Toplamları
Belge toplamları, ürün satırları, vergi/kesinti alt toplamları ve varsa tevkifat alanlarının tek net ödenecek tutara bağlandığı noktadır. Brüt tutar ile ödenecek tutar arasındaki fark, request içinde taşınan kesinti ve tevkifat toplamlarıyla uyumlu olmalıdır.
Üretici SMS Doğrulaması — 30 Haziran 2027
30 Haziran 2027 öncesinde SMS bilgisi bulunmayan UBL ile eksiksiz SMS doğrulama bilgisi taşıyan UBL birlikte desteklenir. SMS alanlarından herhangi biri gönderildiğinde yöntem, kod, telefon ve sağlayıcı bilgilerinin tamamı belgeyle birlikte bulunmalıdır; eksik paket kabul edilmez. SMS zorunluluğu, hem işlemin yapıldığı tarih hem belge tarihi (IssueDate) 30 Haziran 2027 ve sonrasındayken başlar.
| Gereksinim | UBL karşılığı | Sorumluluk |
|---|---|---|
| Üretici kimliği | AccountingCustomerParty altında 11 haneli TCKN ve Person ad/soyadı | Doğrudan entegrasyonda entegratör; Portalda kullanıcı girdisi ve platform kontrolleri |
| Doğrulama yöntemi | Üretici Contact/Name = SMS | JSON requestinde VerificationMethod=SMS; hazır UBL'de sabit değer entegratör tarafından yazılır |
| Kod ve telefon | Üretici Contact/ID ve Contact/Telephone | Doğrudan entegrasyonda SMS'i gönderen ve kodu doğrulayan entegratör; Portalda VBT Platform |
| Sağlayıcı adı ve VKN | Düzenleyen tarafın Contact/OtherCommunication alanında SMS_PROVIDER, sağlayıcı adı ve VKN | SMS'i fiilen gönderen sağlayıcının resmî bilgisi kullanılır |
GİB Rapor Alanları
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. 4 Kasım 2026 testinde GİB, SMS’li, SMS’siz ve her iki türü içeren karma raporu kabul etti (sonuç kodu 30). Yayımlanan GİB rapor şeması SMS’siz satırı zorunlu alan kontrolünde reddediyor. Canlı ortam için GİB teyidi bekleniyor.
| Alan | Açıklama | |
|---|---|---|
makbuzNo | Z | Belge no |
ozetDeger | Z | İmza hash |
duzenlenmeTarihi + duzenlenmeZamani | Z | Tarih/saat |
paraBirimi | Z | ISO 4217 |
toplamTutar / odenecekTutar | Z | Tutarlar |
vergiBilgisi.vergi[] | Z | matrah + vergiKodu + vergiOrani + vergiTutari; kesinti kodları bu listede kod bazında izlenebilir |
vergiBilgisi.tevkifat[] | Ş | Tevkifat kullanılan işlemlerde: tevkifatKodu + tevkifatOrani + tevkifatTutari |
mustahsilBilgileri | Ş | Üretici kimliği korunur. SMS varsa gercekKisi altında adiSoyadi, tckn ve bilgiDetay içindeki kod/telefon |
operatorUygulamaBilgi | Ş | SMS bilgisi varsa SMS sağlayıcısının unvan ve vkn bilgisi; operatorKullanimType request alanı değil XSD tip adıdır. SMS yoksa eklenmez. |
mustahsilMakbuzUrl / imzaZamani | Z | — |
İptal Raporu
İptal edilen bir makbuz için GİB raporuna ayrı bir eArsivRaporuMustahsilMakbuzIptal elemanı eklenir:
Resmi Kaynaklar
Resmi kaynaklar, teknik yorumun dayandığı GİB paketini, kılavuzları ve mevzuat bağlantılarını birlikte takip etmeyi sağlar.
| Kaynak | URL |
|---|---|
| e-Müstahsil Makbuzu Teknik Kılavuzu V1.1 (PDF) | e-Mustahsil_Makbuzu_Teknik_Kilavuzu_V1.1.pdf |
| 28 Ekim 2026 e-Müstahsil Makbuzu Süre Uzatım Duyurusu | e-Mustahsil_Makbuzu_Sure_Uzatim_Duyurusu.pdf |
| GİB Duyurular Sayfası | ebelge.gib.gov.tr/duyurular.html |
| UBL-TR 1.2.1 Paketi | UBL-TR1.2.1_Paketi.zip |
| VUK 509 Sıra No.lu Genel Tebliğ | Resmi Gazete |