Uygulama
Entegratör Sorumlulukları
Entegratörün veri hazırlama, doğrulama ve belge oluşturma sürecindeki sorumlulukları.
İ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.
- Token alınmalı ve sonraki çağrılarda
VbtAuthorizationheader'ı gönderilmelidir. - 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.
- Üreticinin telefon numarası kendi uygulamanızda kontrol edilmeli ve SMS kendi sağlayıcınız üzerinden gönderilmelidir.
- Ü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.
- JSON çağrısında
VerificationMethod=SMS,VerificationInfoveVerificationProvideraynı Add/Update requestine eklenmelidir. Hazır UBL çağrısında karşılık gelenSMSveSMS_PROVIDERalanları XML içinde tamamlanmalıdır. - 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.
- Başarılı yanıttan sonra
OutgoingCreditNoteStatusForUserizlenmeli;WaitingForVerificationveWaitingForSmsCodedurumları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:
| # | Veri | Kim Üretir | Entegratör Ne Yapmalı | Hata |
|---|---|---|---|---|
| 1 | CreditNoteExternalId | Entegratör | Kendi sisteminde benzersiz bir referans üret ve gönder | EMM0020 / EMM0028 |
| 2 | UUId | Platform (opsiyonel) | Boş bırakılırsa platform bir GUID üretir; kendiniz göndermek isterseniz geçerli ve benzersiz olmalı | COM0017 / EMM0035 |
| 3 | CreditNoteNumber | Firma ayarına göre | Numara kaynağı ERP ise üretip regex formatına uydur; platform kaynaklıysa boş bırakılabilir | Format hatası |
| 4 | AccountingSupplierParty | Entegratör veya platform | Makbuzu düzenleyen/alıcı firmanın kimlik ve unvan bilgisini gönder; Portal akışında platform oturum firmasından doldurabilir. | Taraf/kimlik validasyonu |
| 5 | AccountingCustomerParty | Entegratör | SMS 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 |
| 6 | CreditNoteLine[] | Entegratör | Her tarımsal ürün için miktar, birim, ürün adı, fiyat ve satır toplamını hesapla | UBL kardinalite hatası |
| 7 | TaxTotal | Entegratör | KDV ve varsa GV stopajı, borsa tescil, SGK prim, mera fonu alt toplamlarını kodlarıyla hesapla | Validasyon veya rapor uyumsuzluğu |
| 8 | WithholdingTaxTotal | Entegratör | Tevkifat alanı kullanılacaksa belge ve satır seviyesinde tutarlı hesapla | Validasyon hatası |
| 9 | SMS doğrulama kodu ve telefon | Entegratörün doğrulama süreci | SMS 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 |
| 10 | SMS 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 |
| 11 | VerificationMethod | Entegratör | e-Müstahsil Makbuzu için SMS gönderin; Portal Send/Complete endpointlerini çağırmayın. | EMM0057 / EMM0060 |
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.
| Senaryo | Entegratörün Hesaplayacağı Alanlar | Zorunlu Kod/Alan | Gönderim Öncesi Kontrol |
|---|---|---|---|
| Normal oluşturma | Taraflar, ürün satırları, belge toplamları | CreditNoteLine[], LegalMonetaryTotal | Ek kesinti yoksa PayableAmount satır toplamlarıyla kapanır |
| GV stopajı | Stopaj matrahı, oranı ve tutarı | TaxSubtotal.TaxScheme.TaxTypeCode=0003 | TaxAmount, TaxableAmount ve Percent aynı hesabı göstermeli |
| Borsa tescil | Borsa tescil matrahı, oranı ve tutarı | TaxSubtotal.TaxScheme.TaxTypeCode=8001 | Kod adı BORSA TES.ÜC. ile uyumlu olmalı |
| SGK prim | SGK prim matrahı, oranı ve tutarı | TaxSubtotal.TaxScheme.TaxTypeCode=SGK_PRIM | Kod adı SGK PRIM KESINTISI ile uyumlu olmalı |
| Mera fonu | Mera fonu matrahı, oranı ve tutarı | TaxSubtotal.TaxScheme.TaxTypeCode=9040 | Kod adı MERA FONU ile uyumlu olmalı |
| Çoklu kesinti | Her kesinti için ayrı alt toplam | TaxTotal.TaxSubtotal[] | TaxTotal.TaxAmount, alt satır TaxAmount toplamına eşit olmalı |
| Tevkifat | Tevkifat matrahı, oranı ve tutarı | WithholdingTaxTotal | Aynı tutar TaxTotal altında tekrar düşülmemeli |
| İptal | İptal edilecek belgenin kimliği ve durum bilgisi | CreditNoteCancelRequestModel | Belge 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.
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.
| Kontrol | Beklenen | Neden |
|---|---|---|
| Belge kimliği | CreditNoteExternalId tekil, UUId boş veya geçerli GUID | Mükerrer ve format hatalarını önler |
| Taraflar | SMS 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önderilir | UBL taraf rolü ve GİB raporundaki gerçek/tüzel kişi seçimi aynı kimliğe dayanır |
| Satırlar | En az bir CreditNoteLine; miktar, birim, ürün adı ve fiyat dolu | Makbuzun ekonomik içeriği satır seviyesinde taşınır |
| GV stopajı | TaxTotal.TaxSubtotal içinde 0003, GV STOPAJI, matrah, oran ve tutar dolu | Gelir vergisi stopajı kod bazında raporlanabilir |
| Borsa tescil | TaxTotal.TaxSubtotal içinde 8001, BORSA TES.ÜC., matrah, oran ve tutar dolu | Borsa tescil tutarı diğer kesintilerden ayrı izlenir |
| SGK prim | TaxTotal.TaxSubtotal içinde SGK_PRIM, SGK PRIM KESINTISI, matrah, oran ve tutar dolu | SGK prim kesintisi kendi koduyla raporlanır |
| Mera fonu | TaxTotal.TaxSubtotal içinde 9040, MERA FONU, matrah, oran ve tutar dolu | Mera fonu kesintisi kendi koduyla raporlanır |
| Çoklu kesinti | Her kesinti için ayrı TaxSubtotal; TaxTotal.TaxAmount alt satırların toplamı | Tek belge içinde birden fazla kesinti karışmadan izlenir |
| Tevkifat | WithholdingTaxTotal kullanılıyorsa toplamlar PayableAmount ile uyumlu | Net ödenecek tutarın aynı kesintiyi iki kez düşmesini engeller |
| Tutarlar | LegalMonetaryTotal ve satır toplamları aynı para biriminde | UBL ve GİB rapor tutarları arasında fark oluşmasını engeller |