Mapping
Request → Belge → GİB Raporu Mapping
Entegratör request alanlarının makbuzdaki iş anlamı ve GİB raporundaki karşılıkları.
Mapping Kapsamı
Bu sayfa, entegratör request alanının makbuz üzerindeki iş anlamını ve dönemsel GİB raporundaki karşılığını gösterir. İç model, servis veya serileştirme sınıfları sözleşmenin parçası değildir.
Okuma biçimi: “Belge karşılığı” alıcının gördüğü tekil e-SMM’yi, “GİB raporu karşılığı” ise VBT’nin dönemsel bildirimde kullandığı iş bilgisini ifade eder.
Kimlik, Tarih ve Kanal
| Request alanı | Belge karşılığı | GİB raporu karşılığı | Entegrasyon notu |
|---|
SmmExternalId | ERP ile belge arasındaki dış referans | VBT içindeki belge eşleştirmesini destekler; yasal belge numarasının yerine geçmez. | Yeni belge için firma bazında benzersiz tutulur. |
IssueDate | Düzenleme tarih-zamanı | Makbuz tarihi | İşlemin gerçek düzenleme zamanı gönderilir. |
UUId | UUID/ETTN | Raporlanan belgenin tekil elektronik kimliği | Oluşturmada VBT üretir; güncelleme, sorgu, çıktı ve iptalde kullanılır. |
SmmNumber | Makbuz numarası | Belge numarası | 16 karakterli numara VBT tarafından üretilir. |
LocationCode | Düzenleme lokasyonu/şubesi | Belgenin operasyonel kaynak bilgisi | ERP lokasyon koduyla tutarlı gönderilir. |
ChannelCode | Belgenin geldiği kanal | Platformdaki kaynak kanal kaydı | Token bağlamıyla uyumlu olmalıdır. |
Teslim ve İletişim
| Request alanı | Belge karşılığı | GİB raporu karşılığı | Entegrasyon notu |
|---|
GonderimSekli | Elektronik veya kâğıt teslim tercihi | Belgenin teslim/bildirim biçimi | Kagit veya Elektronik |
EArchiveMailTo | Elektronik teslim adresi | Belgenin elektronik teslim kaydıyla ilişkilidir. | Birden fazla adres ; ile ayrılır. |
QrCode | Belge üzerindeki karekod içeriği | Rapor alanından ziyade tekil belge görünümünün mevzuat uyumunu destekler. | GİB karekod standardıyla uyumlu olmalıdır. |
FirmLogo | Belge görünümündeki firma logosu | Raporlanmaz. | Yalnız sunum alanıdır. |
Aciklamalar[] | Makbuz notları | Raporun temel mali alanlarının yerine geçmez. | İşlem açıklaması için kullanılır. |
Düzenleyen Taraf
Düzenleyen serbest meslek erbabının bilgileri token ile seçilen VBT firma kaydından tamamlanır. Entegratör, bu bilgileri alıcı modeli içinde tekrar etmez.
| Firma bilgisi | Belge karşılığı | GİB raporu karşılığı |
|---|
| VKN/TCKN | Makbuzu düzenleyen kimliği | Gönderici kimliği |
| Unvan veya ad-soyad | Serbest meslek erbabı adı | Gönderici taraf adı |
| Vergi dairesi ve adres | Düzenleyen iletişim/vergi bilgisi | Raporlamadaki gönderici tanımı |
Alıcı Taraf
| Request alanı | Belge karşılığı | GİB raporu karşılığı | Kural |
|---|
Alici.VknTckn | Alıcı VKN veya TCKN | Alıcı kimlik numarası | 10 hane VKN, 11 hane TCKN |
Alici.Unvan | Tüzel kişi unvanı | VKN alıcının adı | VKN senaryosunda zorunlu |
Alici.Ad, Soyad | Gerçek kişi adı | TCKN alıcının ad-soyadı | TCKN senaryosunda ikisi de zorunlu |
Alici.VergiDaire | Tüzel kişinin vergi dairesi | Alıcı vergi dairesi bilgisi | VKN senaryosunda tamamlanır. |
Alici.Adres.Ulke | Ülke | Alıcı adresi ülke bilgisi | Zorunlu çekirdek adres alanı |
Alici.Adres.Semt | İlçe/semt | Alıcı adresi alt idari bölümü | Zorunlu çekirdek adres alanı |
Alici.Adres.Sehir | Şehir | Alıcı adresi şehir bilgisi | Zorunlu çekirdek adres alanı |
| Diğer adres alanları | Açık adres ve iletişim | Alıcı adresinin ayrıntıları | Belgeyi tanımlayacak yeterlilikte gönderilir. |
Hizmet Satırları
| Request alanı | Belge karşılığı | GİB raporu karşılığı | Kontrol |
|---|
MalHizmetler[].LineId | Satır sıra numarası | Belge kaleminin sırası | Belge içinde benzersiz |
Id | ERP/satır referansı | Kalem eşleştirmesini destekler. | İstemci tarafından kararlı tutulur. |
MalHizmetAd | Sunulan hizmet açıklaması | Belge kaleminin iş tanımı | Gerçek hizmeti açıklar. |
TotalAmount | Satır brüt hizmet bedeli | Rapor toplamlarının kaynağı | Üst brüt toplama dahil edilir. |
KdvOran, HesaplananKdv | Satır KDV oranı ve tutarı | Vergi toplamlarına yansır. | Brüt × oran ilişkisi |
StopajOran, TaxStopajTotalAmount | Satır gelir vergisi kesintisi | Stopaj toplamına yansır. | Brüt üzerinden hesaplanır. |
TevkifatOran, TevkifatKodu, WithholdingTaxTotalAmount | Satır KDV tevkifatı | Tevkifat kodu ve tutarına yansır. | Hesaplanan KDV üzerinden |
NetUcret | Stopaj sonrası hizmet bedeli | Net ücret toplamına yansır. | Brüt − stopaj |
TaxKdvTotalAmount | Tevkifat sonrası ödenecek KDV | Ödenecek KDV toplamına yansır. | KDV − tevkifat |
PayableAmount | Satır nihai tutarı | Nihai tutar toplamına yansır. | Net ücret + ödenecek KDV |
Belge Toplamları
| Request alanı | Makbuz üzerindeki anlam | GİB raporundaki anlam | Satırlarla ilişki |
|---|
TotalAmount | Brüt hizmet toplamı | Brüt ücret | Satır brütlerinin toplamı |
HesaplananKdv | Toplam hesaplanan KDV | KDV tutarı | Satır KDV toplamı |
TaxStopajTotalAmount | Toplam gelir vergisi stopajı | Stopaj/kesinti tutarı | Satır stopaj toplamı |
WithholdingTaxTotalAmount | Toplam KDV tevkifatı | Tevkifat tutarı | Satır tevkifat toplamı |
TaxKdvTotalAmount | Toplam ödenecek KDV | Tevkifat sonrası KDV | Satır ödenecek KDV toplamı |
NetUcret | Stopaj sonrası net ücret | Net ücret | Satır net ücret toplamı |
PayableAmount | Tahsil edilen/ödenecek nihai tutar | Ödenecek tutar | Satır nihai tutar toplamı |
ToplamVergi | Belge vergi toplamı | Vergi/kesinti özeti | Vergi gruplarıyla uyumlu |
Para Birimi ve Kur
| Request alanı | Belge karşılığı | GİB raporu karşılığı | Kural |
|---|
DocumentCurrencyCode | Belge para birimi | Para birimi kodu | ISO 4217 |
CalculationRate | TRY karşılığı işlem kuru | Döviz kuru | TRY’de 1; dövizde sıfırdan büyük |
Kur.TotalAmount | Brüt tutarın TRY karşılığı | Raporlamadaki yerel para karşılığını destekler. | Brüt × kur |
Kur.NetUcret | Net ücretin TRY karşılığı | Net tutarın yerel para karşılığı | Net × kur |
Diğer Kur alanları | KDV, stopaj, tevkifat ve nihai tutarın TRY karşılıkları | Raporlamadaki döviz/kur bütünlüğü | İlgili belge tutarı × kur |
Durum ve İptal
| API işlemi/response alanı | Belge anlamı | GİB raporlama anlamı |
|---|
OutgoingSmmStatus = PdfCreated | Belge ve PDF çıktısı oluşturulmuştur. | Belge VBT raporlama sürecine alınabilir. |
OutgoingSmmStatus = Signed | Belge imzalı çıktı durumundadır. | Raporlama için tamamlanmış tekil belge kaydıdır. |
EArchiveReportStatus | Portal/liste görünümündeki normal rapor durumu | Belgenin GİB rapor sürecindeki sonucu |
CancelOutgoingSmm | Belge iptal edilir. | İptal bilgisi VBT tarafından uygun rapor akışına alınır. |
EArchiveCancelReportStatus | Portal/liste görünümündeki iptal raporu durumu | İptal bildiriminin GİB sonucu |
Uygulama Notları
- Request alanı ile belge/GİB karşılığı aynı iş verisini anlatmalı; toplamlar ayrı kaynaklardan bağımsız üretilmemelidir.
SmmExternalId, UUId ve SmmNumber farklı kimliklerdir; ERP’de birlikte saklanmalıdır.- VKN/TCKN uzunluğu tarafın kişi/kurum alanlarını belirler.
- Dövizli belgede kur ve TRY karşılıkları aynı işlem kurundan hesaplanmalıdır.
- GİB raporu oluşturma, imzalama, paketleme ve gönderim VBT sorumluluğudur.