e-Müstahsil Makbuzu

Uygulama

Entegratör Sorumlulukları

Entegratörün veri hazırlama, doğrulama ve belge oluşturma sürecindeki sorumlulukları.

Ü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.
Doğrudan entegrasyon: SMS doğrulaması kullanılacaksa entegratör SMS'i kendi sağlayıcısı üzerinden göndermeli, kodu kendi uygulamasında doğrulamalı ve kod, telefon, yöntem, sağlayıcı adı ile sağlayıcı VKN'sini aynı Add/Update requestinde eksiksiz göndermelidir. Portalın SMS endpointleri doğrudan entegrasyon sözleşmesinin parçası değildir. 30 Haziran 2027 öncesinde SMS alanları tamamen boş bırakılabilir veya eksiksiz gönderilebilir; kısmi ERP/UBL isteği beklemeye alınmaz, 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.

İlk Başarılı Belge İçin Uçtan Uca Akış

Aşağıdaki sıra SMS doğrulamasının uçtan uca sorumluluğunu gösterir. 30 Haziran 2027 öncesinde SMS doğrulaması kullanılmıyorsa bu adımlar uygulanmaz; erken kullanım varsa SMS paketi eksiksiz tamamlanır ve rapora aktarılır.

  1. Token alınmalı ve sonraki çağrılarda VbtAuthorization header'ı gönderilmelidir.
  2. JSON veya hazır UBL yöntemi seçilmelidir; iki yöntemin doğrulama alanlarını taşıma kuralları karıştırılmamalıdır.
  3. Üreticinin telefon numarası kendi uygulamanızda kontrol edilmeli ve SMS kendi sağlayıcınız üzerinden gönderilmelidir.
  4. Üreticinin ilettiği kod kendi uygulamanızda doğrulanmalı; kod, telefon, yöntem, sağlayıcı adı ve sağlayıcı VKN'si aynı doğrulama kaydından hazırlanmalıdır.
  5. JSON çağrısında VerificationMethod=SMS, VerificationInfo ve VerificationProvider aynı Add/Update requestine eklenmelidir. Hazır UBL çağrısında karşılık gelen SMS ve SMS_PROVIDER alanları XML içinde tamamlanmalıdır.
  6. Belge Add/Update endpointine gönderilmeli; eksik doğrulama verisiyle gelen doğrudan entegrasyon isteğinin beklemeye alınmayacağı, reddedileceği dikkate alınmalıdır.
  7. Başarılı yanıttan sonra OutgoingCreditNoteStatusForUser izlenmeli; WaitingForVerification ve WaitingForSmsCode durumlarının Portal akışına ait olduğu bilinmelidir.

Veri Sorumluluk Tablosu

Entegratörün (ERP/muhasebe sistemi) API çağırmadan önce sağlaması gerekenler:

#VeriKim ÜretirEntegratör Ne YapmalıHata
1CreditNoteExternalIdEntegratörKendi sisteminde benzersiz bir referans üret ve gönderEMM0020 / EMM0028
2UUIdPlatform (opsiyonel)Boş bırakılırsa platform bir GUID üretir; kendiniz göndermek isterseniz geçerli ve benzersiz olmalıCOM0017 / EMM0035
3CreditNoteNumberFirma ayarına göreNumara kaynağı ERP ise üretip regex formatına uydur; platform kaynaklıysa boş bırakılabilirFormat hatası
4AccountingSupplierPartyEntegratör veya platformMakbuzu düzenleyen/alıcı firmanın kimlik ve unvan bilgisini gönder; Portal akışında platform oturum firmasından doldurabilir.Taraf/kimlik validasyonu
5AccountingCustomerPartyEntegratörSMS kullanıyorsanız üreticinin 11 haneli TCKN ve ad/soyad bilgisini gönderin. SMS isteğe bağlıyken SMS’siz makbuzda gerçek kişi için TCKN, tüzel kişi için VKN kullanın.Taraf/kimlik validasyonu
6CreditNoteLine[]EntegratörHer tarımsal ürün için miktar, birim, ürün adı, fiyat ve satır toplamını hesaplaUBL kardinalite hatası
7TaxTotalEntegratörKDV ve varsa GV stopajı, borsa tescil, SGK prim, mera fonu alt toplamlarını kodlarıyla hesaplaValidasyon veya rapor uyumsuzluğu
8WithholdingTaxTotalEntegratörTevkifat alanı kullanılacaksa belge ve satır seviyesinde tutarlı hesaplaValidasyon hatası
9SMS doğrulama kodu ve telefonEntegratörün doğrulama süreciSMS ile doğrulanan makbuzda kendi sağlayıcınızla SMS gönderip doğruladığınız kodu ve ilişkili telefonu VerificationInfo içinde gönderin.Eksik veya kısmi doğrulama verisi reddedilir
10SMS sağlayıcısıEntegratörün SMS sağlayıcısıSağlayıcının resmî uygulama adını ve 10 haneli VKN'sini VerificationProvider içinde gönderin.EMM0058
11VerificationMethodEntegratöre-Müstahsil Makbuzu için SMS gönderin; Portal Send/Complete endpointlerini çağırmayın.EMM0057 / EMM0060
Bilgi: GİB, taraf VKN/TCKN'nin belge tarihinde aktif mükellef olup olmadığına yönelik canlı doğrulamayı henüz zorunlu kılmamıştır. Bu kontrol GİB tarafından zorunlu hale getirildiğinde platform tarafımızca otomatik olarak devreye alınacaktır; entegratörün bu konuda şu an için ek bir işlem yapması gerekmez.

Senaryo Bazlı Hazırlık Matrisi

Ortak belge alanları hazırlandıktan sonra entegratörün asıl ayrımı, kesinti türünü doğru kodla ve doğru toplam ilişkisiyle göndermesidir.

SenaryoEntegratörün Hesaplayacağı AlanlarZorunlu Kod/AlanGönderim Öncesi Kontrol
Normal oluşturmaTaraflar, ürün satırları, belge toplamlarıCreditNoteLine[], LegalMonetaryTotalEk kesinti yoksa PayableAmount satır toplamlarıyla kapanır
GV stopajıStopaj matrahı, oranı ve tutarıTaxSubtotal.TaxScheme.TaxTypeCode=0003TaxAmount, TaxableAmount ve Percent aynı hesabı göstermeli
Borsa tescilBorsa tescil matrahı, oranı ve tutarıTaxSubtotal.TaxScheme.TaxTypeCode=8001Kod adı BORSA TES.ÜC. ile uyumlu olmalı
SGK primSGK prim matrahı, oranı ve tutarıTaxSubtotal.TaxScheme.TaxTypeCode=SGK_PRIMKod adı SGK PRIM KESINTISI ile uyumlu olmalı
Mera fonuMera fonu matrahı, oranı ve tutarıTaxSubtotal.TaxScheme.TaxTypeCode=9040Kod adı MERA FONU ile uyumlu olmalı
Çoklu kesintiHer kesinti için ayrı alt toplamTaxTotal.TaxSubtotal[]TaxTotal.TaxAmount, alt satır TaxAmount toplamına eşit olmalı
TevkifatTevkifat matrahı, oranı ve tutarıWithholdingTaxTotalAynı tutar TaxTotal altında tekrar düşülmemeli
İptalİptal edilecek belgenin kimliği ve durum bilgisiCreditNoteCancelRequestModelBelge Signed durumda olmalı

Adım Süreci

Doğrudan entegrasyonda SMS gönderimi ve kod doğrulaması VBT Platform çağrısından önce entegratör tarafından tamamlanır; belge requesti doğrulanmış sonucu taşır.

e-Müstahsil Makbuzu doğrudan entegrasyon SMS adımlarıEntegratör üretici telefonunu kontrol eder, kendi sağlayıcısıyla SMS gönderir, kodu kendi uygulamasında doğrular ve doğrulama bilgilerini belgeyle birlikte Add veya Update requestine ekler.Telefonu kontrol etÜretici / çiftçiSMS'i gönderEntegratörün sağlayıcısıKodu doğrulaEntegratörün uygulamasıDoğrulama verisinibelgeye ekleSMS + kod + telefon + sağlayıcıAdd / UpdateTam veriyle gönderVBT Platform doğrudan entegrasyonda SMS göndermez ve kodun gerçekliğini doğrulamaz.Eksik doğrulama verisi Portal bekleme akışına alınmaz; request reddedilir.
Belge tabanıtaraf + satır + toplamSenaryo kararınormal / kesinti / iptalTaxTotal kesintileri0003, 8001, SGK_PRIM, 9040Withholdingyalnızca tevkifat varsaİptal modeliSigned ön koşuluÖn kontrolAPI öncesi

Doğrulama Öncesi Kontrol Listesi

Request gönderilmeden önce yapılan son kontrol, teknik hata dönüşlerini azaltır ve belge üretimini daha öngörülebilir hale getirir.

KontrolBeklenenNeden
Belge kimliğiCreditNoteExternalId tekil, UUId boş veya geçerli GUIDMükerrer ve format hatalarını önler
TaraflarSMS 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 rolü ve GİB raporundaki gerçek/tüzel kişi seçimi aynı kimliğe dayanır
SatırlarEn az bir CreditNoteLine; miktar, birim, ürün adı ve fiyat doluMakbuzun ekonomik içeriği satır seviyesinde taşınır
GV stopajıTaxTotal.TaxSubtotal içinde 0003, GV STOPAJI, matrah, oran ve tutar doluGelir vergisi stopajı kod bazında raporlanabilir
Borsa tescilTaxTotal.TaxSubtotal içinde 8001, BORSA TES.ÜC., matrah, oran ve tutar doluBorsa tescil tutarı diğer kesintilerden ayrı izlenir
SGK primTaxTotal.TaxSubtotal içinde SGK_PRIM, SGK PRIM KESINTISI, matrah, oran ve tutar doluSGK prim kesintisi kendi koduyla raporlanır
Mera fonuTaxTotal.TaxSubtotal içinde 9040, MERA FONU, matrah, oran ve tutar doluMera fonu kesintisi kendi koduyla raporlanır
Çoklu kesintiHer kesinti için ayrı TaxSubtotal; TaxTotal.TaxAmount alt satırların toplamıTek belge içinde birden fazla kesinti karışmadan izlenir
TevkifatWithholdingTaxTotal kullanılıyorsa toplamlar PayableAmount ile uyumluNet ödenecek tutarın aynı kesintiyi iki kez düşmesini engeller
TutarlarLegalMonetaryTotal ve satır toplamları aynı para birimindeUBL ve GİB rapor tutarları arasında fark oluşmasını engeller
30 Haziran 2027 SMS doğrulaması: Doğrudan entegrasyonda VBT Platform SMS göndermez ve kod doğrulamaz. Entegratör kendi SMS sürecinde tamamladığı doğrulamanın sonucunu belge requestiyle birlikte gönderir. Alan ve örnek sözleşmeleri için bkz. SMS Doğrulamalı Gönderim — Entegratörler İçin.