e-Müstahsil Makbuzu

Referans

Sıkça Sorulan Sorular

Belge kullanımı, kesintiler, çıktı, API ve 30 Haziran 2027 SMS doğrulama geçişi hakkında sık sorulan sorular.

KonuKaynak bölüm
Belge kapsamıİlgili sayfayı açın
Kesinti senaryolarıİlgili sayfayı açın
API işlemleriİlgili sayfayı açın
30 Haziran 2027 SMS değişikliğiİlgili sayfayı açın

Kullanım ve Operasyon

e-Müstahsil Makbuzu ne zaman düzenlenir?

KDV mükellefi olmayan bir çiftçiden tarımsal ürün (sebze, meyve, tahıl vb.) satın alındığında düzenlenir. GİB e-Arşiv Belgesi kategorisinde, teknik olarak UBL CreditNote tipiyle oluşturulur.

Makbuzda stopaj (vergi kesintisi) nasıl gösterilir?

Kesinti tutarları ihtiyaca göre TaxTotal.TaxSubtotal altında kod bazında veya tevkifat için WithholdingTaxTotal altında taşınır. GV stopajı için 0003, borsa tescil için 8001, SGK prim için SGK_PRIM, mera fonu için 9040 kodları kullanılır; ödenecek tutar (PayableAmount) bu hesabın net sonucunu yansıtır.

Yakında zorunlu olacak bir SMS doğrulaması var mı?

Evet. Çalışma sınırı olarak hem işlemin yapıldığı tarih hem belge tarihi (IssueDate) 30 Haziran 2027 ve sonrası olduğunda SMS doğrulama bilgileri zorunlu kabul edilir. Bu tarihten önce SMS bilgisi isteğe bağlı olarak UBL'ye eklenebilir. Ayrıntılar için 30 Haziran 2027 SMS Doğrulaması sayfasına bakın.

SMS doğrulamalı gönderim şu anda zorunlu mu?

30 Haziran 2027 öncesinde SMS alanları tamamen boş bırakılabilir veya tamamı eksiksiz gönderilebilir; kısmi paket reddedilir. Erken kullanım VBT canlı ortamında SMS desteği açıldığında mümkündür.

SMS alanları GİB raporuna nasıl yansır?

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.

SMS'i VBT mi, entegratör mü gönderecek?

Kullanılan kanala göre değişir. Doğrudan JSON veya UBL entegrasyonunda SMS'i entegratör kendi sağlayıcısıyla gönderir, kodu kendi uygulamasında doğrular ve doğrulama bilgilerini belge requestiyle birlikte iletir; VBT'nin Portal SMS endpointlerini çağırmaz. VBT Portal kullanan firmalarda ise kullanıcı telefon numarasını kontrol edip gönderimi belge ekranından başlatır, SMS'i VBT Platform gönderir ve ekrana girilen kodu doğrular. Ayrıntılı ayrım için 30 Haziran 2027 sözleşme özetine bakın.

e-Müstahsil Makbuzunda SMS doğrulaması neden isteniyor?

SMS doğrulaması, makbuzun üretici tarafından doğrulandığını belgelemek için GİB'in 30 Haziran 2027 ve sonrası tarihli belgelerde istediği yöntem, kod, telefon ve sağlayıcı bilgisini üretir. Bu bilgiler UBL belgesine ve e-Arşiv raporuna taşınır.

Portalda SMS kodu kendiliğinden mi gönderilir?

Hayır. Belge WaitingForVerification durumunda kaydedilir; kullanıcı üreticinin telefon numarasını kontrol edip SMS gönderimini belge ekranından başlatır. VBT'nin mevcut akışı 6 haneli sayısal kod üretir; Portal API'si sağlayıcı uyumluluğu için boşluk veya kontrol karakteri içermeyen 4–6 karakterli kodu kabul eder. Gönderim başarılı olduğunda belge WaitingForSmsCode durumuna geçer ve üreticinin ilettiği kod aynı ekranda doğrulanır.

VBT Portal için ayrıca entegrasyon geliştirmek gerekir mi?

Hayır. Telefon girişi, SMS gönderimini başlatma, kod doğrulama, süre ve tekrar yönetimi VBT Portal ekranlarında hazır sunulur. Yalnız Portal UI geliştiren ekipler Portal endpoint sözleşmelerini uygular; dış ERP entegratörleri bu endpointleri çağırmaz.

SMS kodunu bekleyen makbuz iptal edilebilir mi?

Hayır. WaitingForVerification, WaitingForSmsCode ve CreditNoteAndXmlCreated durumlarındaki belge henüz imzalanmamıştır. İptal işlemi yalnız belge Signed durumuna geçtikten sonra kullanılabilir.

Excel ile yüklenen makbuzlar topluca doğrulanabilir mi?

Hayır. Portal üzerinden Excel ile oluşturulan her e-Müstahsil Makbuzu ayrı bir üretici doğrulaması taşır; SMS gönderme ve kod doğrulama adımı belge bazında tamamlanır.

Gönderilmiş SMS kodunun süresi dolarsa ne olur?

Geçersiz veya süresi dolmuş kod kabul edilmez. Deneme ve bekleme kuralları uygunsa kullanıcı aynı belge ekranından yeni SMS gönderimini başlatır; eski kodla doğrulamaya devam edilmez.

Makbuzun XML veya PDF çıktısına nasıl ulaşırım?

Belge kimliğiyle kullanılabilen çıktı işlemleri API sorgulama bölümünde yer alır.

Aynı makbuzda birden fazla ürün kalemi olabilir mi?

Evet. CreditNoteLine alanı bir listedir; aynı çiftçiden alınan birden fazla ürün tek makbuzda ayrı satırlar olarak gönderilebilir. Detay için Kullanım Senaryoları sayfasına bakın.

Bir makbuzu ne zaman iptal edebilirim?

Yalnızca Signed durumundaki makbuzlar iptal edilebilir. İmzalama bekleyen (CreditNoteAndXmlCreated) bir makbuz iptal edilmeye çalışılırsa EMM0024 hatası döner; zaten iptal edilmiş bir makbuz tekrar iptal edilemez (EMM0025).

Teknik Entegrasyon

UUId ve CreditNoteExternalId arasındaki fark nedir?

CreditNoteExternalId sizin kendi sisteminizdeki referans numaranızdır (serbest metin, zorunlu ve benzersiz olmalı). UUId ise GİB'in beklediği ETTN değeridir — göndermezseniz platform sizin için bir GUID üretir; kendiniz göndermek isterseniz geçerli ve benzersiz olmalıdır.

Taraf VKN/TCKN aktiflik kontrolü var mı?

GİB bu kontrolü henüz zorunlu kılmamıştır; şu an için entegratörün bu konuda ek bir işlem yapması gerekmez. GİB ileride bu kontrolü zorunlu hale getirirse platform tarafımızca otomatik olarak devreye alınacak ve entegratöre ayrıca duyurulacaktır.

API'ye nasıl bağlanırım, kimlik doğrulama nasıl çalışır?

Tüm istekler VbtAuthorization header'ı gerektirir. Önce POST /api/Account/Token endpointine Email/Password ile istek atıp bir token alınır; bu token diğer tüm endpointlerde VbtAuthorization header'ında gönderilir. Detay için Entegratör API Endpoint Referansı sayfasına bakın.

Test ortamı var mı?

Evet. Test/Swagger adresi ve GİB kaynak bağlantıları için GİB Referansı sayfasına bakın.

Hazır, kopyalayıp deneyebileceğim örnek request var mı?

Evet. Normal oluşturma, tevkifatlı işlem, GV stopajı, borsa tescil, SGK prim, mera fonu, çoklu kesinti, çok kalemli makbuz ve iptal için doğrudan kullanılabilir JSON örnekleri Request Örnekleri sayfasında yer alır.

Planlanan SMS doğrulamasında yöntem ve UBL alanları nasıl gönderilecek?

SMS doğrulaması kullanıldığında JSON requestinde VerificationMethod = SMS gönderilir; VerificationInfo ve VerificationProvider içinde ayrıca ChannelCode veya Type bulunmaz. Platform, model requesti için GİB'in istediği SMS ve SMS_PROVIDER UBL değerlerini üretir. Hazır UBL gönderen entegratör ise bu standart değerleri XML içinde kendisi sağlamalıdır. Tam örnek için entegratör SMS rehberine bakın.

SMS gönderme ve kod doğrulama endpointlerini entegratör mü çağıracak?

Hayır. SendCreditNoteSmsCode ve CompleteCreditNoteSmsVerification VBT Portalın hazır kullanıcı akışına aittir; Portal dışındaki çağrılar EMM0057 ile reddedilir. Doğrudan entegrasyon, kendi sürecinde tamamladığı SMS doğrulamasının yöntem, kod, telefon, sağlayıcı adı ve VKN bilgisini mevcut Add/Update requestinde gönderir.

Preview requestinde SMS doğrulama alanları gerekir mi?

Hayır. PreviewOutgoingCreditNote belgeyi kaydetmediği veya imza sürecine sokmadığı için SMS doğrulama alanlarını zorunlu tutmaz. Bu nedenle başarılı bir önizleme, 30 Haziran 2027 ve sonrası tarihli gerçek Add/Update requestinin eksik doğrulama verisiyle kabul edileceği anlamına gelmez.

VerificationProvider alanına hangi SMS sağlayıcısının bilgileri yazılmalıdır?

VerificationProvider, SMS kodunu fiilen gönderen hizmet sağlayıcının resmî bilgileridir. Kendi SMS sağlayıcınızı kullanıyorsanız ApplicationName alanına resmî unvanını, Vkn alanına 10 haneli VKN'sini gönderin. SMS VBT Portal üzerinden gönderiliyorsa VerificationProvider göndermeyin; sağlayıcı bilgisi platform tarafından eklenir.

İmzalı hazır UBL'deki telefon numarasını platform düzeltebilir mi?

Hayır. IsSigned = true ile gönderilen UBL değiştirilmeden saklanır; XML içindeki Contact/Telephone değeri imzadan önce doğrudan 5XXXXXXXXX biçiminde hazırlanmalıdır. 05XXXXXXXXX veya +905XXXXXXXXX gibi normalizasyon gerektiren değerler EMM0061 ile reddedilir. Düzeltme gerekiyorsa UBL entegratör tarafından düzeltilip yeniden imzalanarak gönderilmelidir. Ayrı e-Arşiv raporundaki 05XXXXXXXXX değeri rapor oluşturulurken ve rapor imzalanmadan önce üretilir; kaynak UBL'e uygulanmaz.

Bir istek başarısız olursa nasıl anlarım?

Oluşturma/güncelleme yanıtları HasError ve Errors[] alanlarını taşır; HasError = true ise Errors dizisindeki her öğe bir hata kodu ve açıklaması içerir (örn. EMM0020, EMM0028). Hata kodlarının rehberde geçen listesi için Teknik Referans sayfasına bakın.

Timeout sonrasında aynı makbuz yeniden oluşturulmalı mı?

Önce CreditNoteExternalId ve varsa UUID ile mevcut kayıt sorgulanmalıdır. Kayıt yokluğu doğrulanmadan yeni dış referansla tekrar gönderim yapılmamalıdır.

ERP’de hangi kimlikler birlikte saklanmalıdır?

Dış referans, UUID, makbuz numarası ve son gözlenen durum birlikte saklanmalıdır.

Birden fazla kesinti nasıl gönderilir?

Her kesinti ayrı TaxSubtotal satırı olarak gönderilir; üst vergi toplamı ve ödenecek tutar bu satırların toplamıyla uyumlu olmalıdır.

İptal isteği hangi kontrolden sonra gönderilmelidir?

Önce güncel belge durumu sorgulanmalı; yalnızca API’nin iptale izin verdiği durumda iptal çağrısı yapılmalıdır.

Canlıya geçmeden önce hangi senaryolar test edilmelidir?

Normal alım, stopaj, borsa tescil, SGK primi, mera fonu, çoklu kesinti, çok kalemli makbuz, çıktı alma, timeout mutabakatı ve iptal ayrı ayrı doğrulanmalıdır.