Teknik Temel
GİB Referansı
GİB paketi, kullanım yöntemi, teknik gereksinimler ve resmi e-SMM kaynakları.
GİB Paketi
e-SMM, e-Arşiv uygulaması kapsamında elektronik olarak düzenlenen serbest meslek makbuzudur. Tekil makbuzun oluşturulması ve alıcıya teslimi ile belgelerin GİB’e dönemsel olarak raporlanması birbirini tamamlayan iki ayrı süreçtir.
| Kapsam | Tekil makbuz | GİB raporu |
|---|---|---|
| Amaç | Hizmet ve tahsilatın alıcıya verilen belgesi | Düzenlenen ve iptal edilen belgelerin dönemsel bildirimi |
| Temel içerik | Taraflar, hizmet kalemleri, vergi/kesinti ve toplamlar | Belge kimlikleri, taraf kimliği, tarih, para birimi, tutarlar ve durum |
| İşlem zamanı | Oluşturma veya güncelleme çağrısı sırasında | VBT’nin raporlama takviminde |
| Entegratör erişimi | Detay, PDF ve belge paketi uçları | Rapor işlemleri entegratöre açılmaz; VBT tarafından yönetilir. |
Kullanım Yöntemi
Entegratör makbuzun iş verisini JSON request ile iletir. VBT, doğrulanan veriden tekil belgeyi ve imzalı PDF’i üretir. Kabul edilen belgeler daha sonra VBT tarafından mevzuata uygun GİB raporlama sürecine alınır.
Teknik Gereksinimler
Makbuzun iş verisi, belge üzerindeki görünüm ve GİB raporundaki karşılık aynı ekonomik işlemi anlatmalıdır. Entegratör özellikle aşağıdaki bütünlük kurallarını sağlamalıdır.
| Konu | Gereksinim | İlgili request alanları |
|---|---|---|
| Belge kimliği | Her yeni belge ERP tarafında benzersiz bir dış referansla gönderilmelidir. | SmmExternalId |
| Düzenleme zamanı | Belge tarihi gerçek işlem zamanını göstermeli ve geçerli tarih biçiminde olmalıdır. | IssueDate, BelgeZamanSpecified |
| Taraf kimliği | VKN 10, TCKN 11 haneli ve sayısal olmalıdır; kişi/kurum alanları kimlik tipine uygun tamamlanmalıdır. | Alici.VknTckn, Unvan, Ad, Soyad |
| Adres | Ülke, ilçe/semt ve şehir başta olmak üzere alıcı adresi belgeyi tanımlayacak yeterlilikte olmalıdır. | Alici.Adres |
| Para birimi | ISO 4217 kodu kullanılmalı; TRY dışındaki belgede kur sıfırdan büyük olmalıdır. | DocumentCurrencyCode, CalculationRate |
| Vergi ve kesinti | KDV, stopaj ve tevkifat oran/tutarları hem satır hem belge toplamlarıyla uyumlu olmalıdır. | MalHizmetler[], üst toplam alanları |
| Teslim | Elektronik veya kâğıt teslim seçimi doğru gönderilmeli; elektronik teslimde e-posta adresi doğrulanmalıdır. | GonderimSekli, EArchiveMailTo |
| Karekod | Belge üzerindeki karekod, yürürlükteki GİB karekod standardındaki zorunlu bilgileri taşımalıdır. | QrCode veya VBT tarafından oluşturulan belge verisi |
Taraf Kimlikleri
| Alıcı türü | Kimlik | Zorunlu ad alanları | Ek bilgi |
|---|---|---|---|
| Tüzel kişi | 10 haneli VKN | Unvan | VergiDaire ve adres tamamlanır. |
| Gerçek kişi | 11 haneli TCKN | Ad ve Soyad | Adres tamamlanır; unvan/vergi dairesi kullanılmaz. |
Vergi ve Kesinti Yapısı
e-SMM’de brüt hizmet bedelinden gelir vergisi stopajı düşülebilir; hesaplanan KDV’ye ayrıca tevkifat uygulanabilir. Bu iki kesinti farklı matrah ve amaçlara sahiptir.
| Unsurlar | Matrah | Request alanları | Toplama etkisi |
|---|---|---|---|
| KDV | Brüt hizmet bedeli | KdvOran, HesaplananKdv | Hesaplanan KDV’yi oluşturur. |
| Gelir vergisi stopajı | Brüt hizmet bedeli | StopajOran, TaxStopajTotalAmount | NetUcret hesabında brüt ücretten düşülür. |
| KDV tevkifatı | Hesaplanan KDV | TevkifatOran, TevkifatKodu, WithholdingTaxTotalAmount | TaxKdvTotalAmount hesabında KDV’den düşülür. |
| Ödenecek tutar | Net ücret + ödenecek KDV | PayableAmount | Makbuzdaki tahsil edilen/ödenecek nihai tutardır. |
Belge Toplamları
Hesaplama sırası, örnek bir kalem için aşağıdaki zihinsel modelle kurulabilir. Yuvarlama politikası ERP ile VBT arasında aynı hassasiyetle uygulanmalıdır.
| Adım | Formül | Örnek: brüt 1.000, KDV %20, stopaj %20, tevkifat %50 |
|---|---|---|
| Hesaplanan KDV | Brüt × KDV oranı | 200 |
| Stopaj | Brüt × stopaj oranı | 200 |
| Tevkifat | Hesaplanan KDV × tevkifat oranı | 100 |
| Net ücret | Brüt − stopaj | 800 |
| Ödenecek KDV | Hesaplanan KDV − tevkifat | 100 |
| Ödenecek tutar | Net ücret + ödenecek KDV | 900 |
Para Birimi ve Kur
| Senaryo | DocumentCurrencyCode | CalculationRate | Kur modeli |
|---|---|---|---|
| TRY belge | TRY | 1 | Yabancı para karşılıkları gerekmiyorsa boş bırakılabilir. |
| Dövizli belge | Geçerli ISO 4217 kodu, ör. USD veya EUR | İşlem tarihindeki kullanılan kur; sıfır olamaz. | Belge toplamlarının TRY karşılıklarını taşır. |
GİB Rapor Alanları
Raporlama sırasında tekil belge kaydından GİB’in beklediği iş alanları oluşturulur. Entegratörün görevi request verisini doğru sağlamaktır; rapor şemasını veya gönderim paketini üretmez.
| İş alanı | Kaynak request bilgisi | Rapor anlamı |
|---|---|---|
| Belge numarası ve UUID | Oluşturma sonucu üretilen SmmNumber, UUId | Raporlanan makbuzun tekil kimliği |
| Düzenleme tarihi | IssueDate | Makbuz tarihi |
| Gönderici ve alıcı | Firma kaydı, Alici | VKN/TCKN ve taraf adı |
| Para birimi ve kur | DocumentCurrencyCode, CalculationRate | Belgenin döviz bilgisi |
| Brüt, vergi, kesinti ve net | Belge toplam alanları | Makbuzun ekonomik özeti |
| İptal | Belgenin iptal kaydı ve tarihi | İptal raporunda ilgili belge referansı |
İptal Bildirimi
Entegratör iptal talebini belge UUID’siyle iletir. İptal edilen belgenin GİB’e bildirilmesi, belgenin raporlama durumuna göre VBT tarafından uygun rapor döneminde yönetilir.
Data = true sonucunu saklayın ve belgeyi yeniden düzenlenecekse yeni bir SmmExternalId kullanın. GİB rapor uçlarını ayrıca çağırmayın.Resmi Kaynaklar
- e-Arşiv Teknik Kılavuzu V1.18 — rapor paketleri, belge türleri ve teknik bildirim çerçevesi.
- 509 Sıra No.lu VUK Genel Tebliği — güncel metin — e-Belge uygulamalarının yasal kapsamı.
- Karekod veya Barkod Standardı Kılavuzu V1.0 — belge üzerindeki karekod içeriği.