Senaryolar
Kullanım Senaryoları
Gerçek ve tüzel alıcı, para birimi, vergi, gönderim ve iptal senaryoları.
Genel Bakış
e-SMM oluşturma akışı tek bir request modeli kullanır; senaryolar alıcının kimlik tipi, para birimi, vergi/kesinti yapısı, teslim şekli ve işlem türüne göre ayrışır. Doğru senaryo seçimi, hangi alanların doldurulacağını ve toplamların nasıl hesaplanacağını belirler.
Karar Ağacı
Önce alıcı ve para birimi belirlenir; ardından stopaj ve tevkifat kararları toplam modelini, teslim seçimi ise iletişim alanlarını şekillendirir.
Alan Zorunluluk Matrisi
| Senaryo | Her zaman gerekli | Senaryoya özgü | Kullanılmayan alan |
|---|---|---|---|
| Tüzel kişi / TRY | IssueDate, SmmExternalId, alıcı adresi, hizmet ve toplamlar | Alici.Unvan, 10 haneli VknTckn, VergiDaire, kur 1 | Alici.Ad, Alici.Soyad, döviz karşılıkları |
| Gerçek kişi / TRY | Ortak belge alanları | Alici.Ad, Alici.Soyad, 11 haneli TCKN | Unvan, VergiDaire |
| Dövizli | Ortak belge alanları | ISO 4217 DocumentCurrencyCode, sıfırdan büyük CalculationRate, gerekiyorsa Kur | TRY için ayrıca döviz karşılıkları |
| Stopajlı | Brüt, KDV ve ortak toplamlar | StopajOran, TaxStopajTotalAmount, NetUcret | Tevkifat yoksa tevkifat alanları 0/boş |
| Tevkifatlı | Brüt, KDV ve ortak toplamlar | TevkifatOran, TevkifatKodu, WithholdingTaxTotalAmount, TaxKdvTotalAmount | Stopaj yoksa stopaj alanları 0 |
| Elektronik teslim | Ortak belge alanları | GonderimSekli = Elektronik, kullanılacaksa EArchiveMailTo | Kâğıt teslim bilgisi |
| Kâğıt teslim | Ortak belge alanları | GonderimSekli = Kagit | EArchiveMailTo zorunlu değildir. |
| Güncelleme | Oluşturma modelinin güncel tam hali | Id ve UUId | Yeni dış referans üretilmez; mevcut belgeyle eşleştirilir. |
| İptal | Geçerli token | UUId | Belge satır ve toplam modeli gönderilmez. |
Ana Senaryo Grupları
| Grup | Ne zaman kullanılır? | Ayırt edici alanlar | İlgili örnek |
|---|---|---|---|
| Standart TRY | Belge ve ödeme Türk lirasıysa | DocumentCurrencyCode = TRY, CalculationRate = 1 | Örnek 1 |
| Gerçek kişi alıcı | Hizmeti alan kişi TCKN ile tanımlanıyorsa | Ad, Soyad, 11 haneli TCKN | Örnek 2 |
| Döviz | Belge USD, EUR veya başka bir ISO 4217 para birimindeyse | DocumentCurrencyCode, CalculationRate, Kur | Örnek 3 |
| Stopaj | Hizmet bedelinden gelir vergisi kesintisi yapılıyorsa | StopajOran, TaxStopajTotalAmount | Örnek 4 |
| KDV tevkifatı | Hesaplanan KDV’nin bir bölümü alıcı tarafından sorumlu sıfatıyla beyan ediliyorsa | TevkifatOran, TevkifatKodu, tevkifat tutarı | Örnek 5 |
| Çok kalem | Aynı makbuzda birden fazla hizmet satırı varsa | MalHizmetler[], benzersiz LineId | Örnek 7 |
Oluşturma Senaryoları
Aşağıdaki kartlar, request hazırlarken hangi kararların değiştiğini özetler.
Tüzel Kişi — TRY
Alıcı 10 haneli VKN ile tanımlanır. Unvan, VergiDaire ve adres gönderilir. Para birimi TRY, kur 1 olur. Bu, kurumsal alıcılar için temel senaryodur.
Gerçek Kişi — TRY
Alıcı 11 haneli TCKN ile tanımlanır; Ad ve Soyad birlikte gönderilir. Kurum alanlarıyla kişi alanları karıştırılmaz.
Dövizli Makbuz
Belge para birimi ISO 4217 koduyla gönderilir. CalculationRate sıfır olamaz. Belge toplamları belge para biriminde, Kur alanları ise gerektiğinde TRY karşılıklarıyla tutarlı hazırlanır.
Stopajlı Makbuz
Stopaj, brüt hizmet bedeli üzerinden hesaplanır. TaxStopajTotalAmount hem satırda hem belge toplamında oranla uyumlu olmalı; NetUcret = TotalAmount − TaxStopajTotalAmount ilişkisi korunmalıdır.
KDV Tevkifatlı Makbuz
Tevkifat, hesaplanan KDV üzerinden hesaplanır. Oranla birlikte ilgili TevkifatKodu gönderilir. TaxKdvTotalAmount = HesaplananKdv − WithholdingTaxTotalAmount ilişkisi korunur.
Stopaj + Tevkifat
İki kesinti birlikte uygulanabilir; stopaj brüt ücret üzerinde, tevkifat KDV üzerinde ayrı hesaplanır. PayableAmount, net ücret ile tevkifat sonrası ödenecek KDV’nin toplamıdır.
Çok Kalemli Makbuz
Her hizmet satırı benzersiz LineId ve Id ile gönderilir. Üst toplamlar tüm satırların tutar, vergi ve kesinti toplamlarına eşit olmalıdır.
Elektronik veya Kâğıt Teslim
Elektronik teslimde e-posta adresi doğrulanır ve Portal’dan yeniden gönderim yapılabilir. Kâğıt teslimde imzalı PDF üretimi devam eder; çıktı alınıp fiziksel olarak verilebilir.
Güncelleme Senaryosu
Güncelleme, mevcut belgenin tam request modelinin düzeltilmiş haliyle yapılır. Id ve UUId mevcut kaydı tanımlar; başarılı güncellemede PDF yeniden üretilip imzalanır.
GetOutgoingSmm ile güncel belgeyi okuyun, yalnız değiştireceğiniz alanı değil tam modeli hazırlayın ve UpdateOutgoingSmm sonucundaki HasError değerini kontrol edin.İptal Senaryosu
İptal için belge UUID’si gönderilir. Başarılı Data = true sonucu ERP kaydına işlenir. Aynı ekonomik işlem yeniden belgelenecekse yeni belge, yeni bir SmmExternalId ile oluşturulur.
Edge-Case Tablosu
| Durum | Beklenen yaklaşım | Kaçınılacak davranış |
|---|---|---|
| VKN ile ad-soyad gönderilmesi | VKN’de unvan ve vergi dairesi kullanılır. | Kişi ve kurum alanlarını aynı alıcıda karıştırmak |
| TRY dışı para biriminde kur yok | Geçerli işlem kuru sıfırdan büyük gönderilir. | CalculationRate = 0 |
| Birden fazla e-posta | Adresler noktalı virgülle ayrılır. | Virgül veya serbest metin kullanmak |
| Tekrar eden ERP çağrısı | Önce dış referansla mevcut kayıt sorgulanır. | Aynı işlem için yeni SmmExternalId üretip mükerrer belge oluşturmak |
| Satır toplamı üst toplamla farklı | Gönderimden önce tüm satırlar yeniden toplanır. | Üst toplamları bağımsız elle girmek |
| Uzun işlem sonrası yanıt alınamadı | Aynı request’i körlemesine tekrarlamadan önce dış referans veya UUID ile sorgulama yapılır. | Ağ zaman aşımını kesin başarısızlık saymak |
| İptal sonrası yeniden düzenleme | Yeni dış referans ve yeni belge oluşturulur. | İptal edilen UUID üzerinde güncelleme denemek |