e-Müstahsil Makbuzu

Uygulama

Platform Sorumlulukları

Platformun otomatik işlemleri, validasyon kuralları, hata yanıtları ve iptal ön koşulları.

VBT Portal: SMS ile doğrulama yaparken Portal kullanıcısı üreticinin telefonunu kontrol eder ve SMS gönderimini belge ekranından başlatır. SMS'i VBT Platform gönderir; kullanıcı üreticinin ilettiği kodu ekrana girer, platform kodu doğrular ve başarılı sonuçtan sonra belgeyi imza akışına alır. SMS otomatik olarak gönderilmez. 30 Haziran 2027 öncesinde SMS’siz belge düzenlenebilir.

Portal UI Geliştiricisi — Uçtan Uca Belge Akışı

  1. Portal kullanıcısı üreticinin telefon numarasını kontrol eder ve makbuzu kaydeder.
  2. SMS bilgisi boş olan imzasız Portal belgesi WaitingForVerification durumunda tutulur; bu aşamada imza kuyruğu oluşturulmaz.
  3. Kullanıcı belge ekranındaki SMS gönderme adımını başlatır. Portal, SendCreditNoteSmsCode çağrısını yapar; SMS'i VBT Platform gönderir ve belge WaitingForSmsCode durumuna geçer.
  4. Kullanıcı üreticinin ilettiği kodu ekrana girer. Portal, gönderimden dönen doğrulama tokenı ve kodla CompleteCreditNoteSmsVerification çağrısını yapar.
  5. Platform kodu doğrular, doğrulama bilgilerini belgeye ekler, UBL'i yeniden üretir ve belgeyi CreditNoteAndXmlCreated durumuyla imza kuyruğuna alır.
  6. Belge detayı yeniden sorgulanır; CreditNoteAndXmlCreated veya Signed durumunda SMS ekranı kapatılır, hata oluşursa kullanıcıya yeniden gönderim veya kod düzeltme adımı gösterilir.

Otomatik İşlemler

Platform, entegratörün gönderdiği request'i doğruladıktan sonra e-Müstahsil Makbuzu'na özgü UBL XML üretimi, imza kuyruğu, GİB raporu ve belge görüntüleme adımlarını yönetir. Entegratör belge içeriğini sağlar; platform teknik yaşam döngüsünü işletir.

#İşlemAçıklama
1ValidasyonAlan zorunluluk, format, kombinasyon kontrolleri
2Portal SMS doğrulamasıKullanıcının başlattığı gönderimde SMS'i iletir; kod, süre ve tekrar kontrollerini yönetir; başarılı doğrulamadan sonra belgeyi imza akışına geçirir.
3UBL XML ÜretimiUBL 2.1 CreditNote standardında XML
4Numara/UUID AtamaEntegratör göndermezse otomatik
5İmzalamaya HazırlamaCreditNoteAndXmlCreated durumuna kaydedilir
6e-İmzalamaBelge imzalama akışına alınır; işlem tamamlandığında durum Signed'e geçer.
7Belge kaydıKalıcı saklama
8GİB RaporPlanlanan 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.
9GİB GönderimRapor iletimi + yanıt işleme
10İptal RaporuSonraki döngüde bildirim
11PDFYazdırılabilir çıktı
12E-postaBildirim (yapılandırıldıysa)

Validasyon Kuralları

Validasyonlar, e-Müstahsil Makbuzu request'inin teknik olarak üretilebilir ve GİB raporuna taşınabilir olmasını kontrol eder; ana odak çiftçi/alıcı tarafları, ürün kalemleri ve stopaj hesaplarıdır.

KontrolKodAçıklama
CreditNoteExternalId doluEMM0020Her belgede zorunlu
CreditNoteExternalId tekilEMM0028Mükerrer engeli
UUId geçerli GUIDCOM0017Gönderilirse format kontrolü
UUId tekilEMM0035Mükerrer engeli
CreditNoteNumber formatı—16 karakter, Seri+Sıra regex'i
IssueDate gelecek olamaz—UBL kardinalite kontrolü
IssueDate saat bileşeni dolu—Zaman damgası zorunlu
En az bir CreditNoteLine—Makbuz satırsız oluşturulamaz
Vergi/kesinti toplam uyumu—TaxTotal, WithholdingTaxTotal ve PayableAmount aynı ekonomik hesabı yansıtmalı
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.
Portal kullanıcıları: Makbuzu düzenleyen/alıcı firma AccountingSupplierParty, üretici/çiftçi ise AccountingCustomerParty olarak oluşturulur. SMS doğrulaması tamamlandığında üretici TCKN'si, SMS kodu ve telefon ile sağlayıcı bilgisi kayıtlı doğrulama bilgilerinden GİB raporuna otomatik aktarılır; kullanıcı ayrı bir rapor nesnesi hazırlamaz.

Portal SMS Doğrulama Akışı

Portal, SMS gönderme ve kod doğrulama adımlarını belge ekranında hazır sunar; kullanıcı teknik endpoint, token veya sağlayıcı bilgisi yönetmez.

AdımPortal kullanıcısıVBT Platform
Belge kaydıMakbuz bilgilerini kaydeder.Belgeyi WaitingForVerification durumunda tutar; imza kuyruğu oluşturmaz.
SMS gönderimiÜreticinin telefonunu kontrol eder ve gönderimi başlatır.SMS'i gönderir; başarılı gönderimde belgeyi WaitingForSmsCode durumuna geçirir.
Kod doğrulamaÜreticinin ilettiği kodu ekrana girer.Kodu doğrular; başarılı sonuçta doğrulama bilgilerini belgeye ekler ve imza kuyruğunu oluşturur.
Hata veya süre aşımıEkrandaki yönlendirmeye göre yeniden dener.Süre, yeniden gönderim ve deneme sınırlarını yönetir; başarısız sonucu doğrulanmış göstermez.

Portal Durumları

Teknik değerPortal açıklamasıKullanıcı aksiyonu
WaitingForVerificationSMS gönderimi bekleniyor.Üreticinin telefonu kontrol edilerek gönderim başlatılır.
WaitingForSmsCodeSMS onayı bekleniyor.Üreticinin ilettiği kod girilir; gerekirse telefon düzeltilerek yeniden gönderim yapılır.
CreditNoteAndXmlCreatedDoğrulama tamamlandı; belge imzalama bekliyor.Belge durumu takip edilir.
SignedBelge imzalandı ve GİB raporuna hazır.Ek SMS işlemi yapılmaz.

SMS Doğrulama Akışı

OutgoingCreditNoteStatusForUser, doğrudan entegrasyon ile Portalın etkileşimli SMS akışını ayırır. Doğrudan entegrasyon tam SMS verisini Add/Update requestinde gönderir ve bekleme durumlarına girmez. Portalda ise kullanıcı gönderimi başlatır; VBT Platform SMS'i gönderip kodu doğruladıktan sonra iki kanal aynı imza kuyruğunda birleşir.

e-Müstahsil Makbuzu SMS doğrulama ve imza durum akışıDoğrudan entegrasyon tam SMS verisiyle imza kuyruğuna ilerler; Portal belgesi kullanıcının başlattığı SMS gönderimi ve kod doğrulaması tamamlandıktan sonra aynı kuyruğa ulaşır.Add / Updatemakbuz kaydıDoğrudan entegrasyon: tam ve önceden doğrulanmış SMS verisiSMS'i entegratör gönderir; kodu entegratör doğrularPortal: SMS bilgisi boş başlangıçSMS otomatik gönderilmezWaitingForVerificationkullanıcı gönderimi başlatırVBT SMS gönderirWaitingForSmsCodekullanıcı kodu girerVBT kodu doğrulardoğrulama bilgileri UBL'e eklenirCreditNoteAndXmlCreatedimzalama bekliyorOtomatik imzalamaSignedrapora hazır

Hata Yanıtı

Hata yanıtı, tüm Müstahsil endpointlerinde aynı temel şekli izler. MessageCode alanı, validasyon tablosundaki hata koduyla eşleştirilir.

{
  "IsSuccess": false,
  "Message": "Açıklama",
  "MessageCode": "EMM0020",
  "Data": null
}
AlanAnlamı
IsSuccessİşlemin başarılı olup olmadığını gösterir
MessageKullanıcıya veya log'a yazılabilecek açıklama
MessageCodeValidasyon veya iş kuralı hata kodu
DataBaşarılı işlemlerde response modeli; hatada çoğu durumda boş

İptal Ön-Koşulları

İptal isteği, yalnızca belge durumu uygun olduğunda ilerler; bu koşullar çağrı öncesi beklenen teknik zemini belirler.

  • Belge Signed durumunda olmalı (CreditNoteAndXmlCreated durumunda iptal edilemez — EMM0024)
  • İptal requestinde EArchiveStatus=2 (Cancelled) gönderilmeli
  • Daha önce iptal edilmiş bir belge tekrar iptal edilemez (EMM0025)
30 Haziran 2027 SMS doğrulaması: Yeni kullanıcı durumları iptal ön koşulunu değiştirmez. WaitingForVerification ve WaitingForSmsCode dahil imzalanmamış makbuzlar iptal edilemez. Bkz. SMS Doğrulamalı Gönderim — Portal Kullanıcıları İçin.