Uygulama
Kullanım Senaryoları
Normal, GV stopajı, borsa tescil, SGK prim, mera fonu, çoklu kesinti, tevkifat, çok kalemli oluşturma ve iptal akışları için karar ağacı.
Genel Bakış
e-Müstahsil Makbuzu tek bir oluşturma akışı etrafında şekillenir: entegratör, çiftçi ve alıcı firma bilgileriyle birlikte ürün kalemlerini, vergi toplamlarını ve varsa kesinti tutarlarını içeren bir JSON gönderir. Bu modülde karar noktaları kesinti uygulanıp uygulanmayacağı, kesintinin hangi teknik alanda taşındığı, satır sayısı ve iptal uygunluğu üzerinden ilerler.
Karar Ağacı
Müstahsil akışı, vergi/kesinti toplamlarının belge yapısına etkisini satır sayısı ve iptal uygunluğu kararlarıyla birlikte ele alır.
Alan Zorunluluk Matrisi
Senaryo seçildikten sonra zorunluluk, ortak belge alanları ile senaryoya özgü kesinti alanlarının birlikte tamamlanmasıyla netleşir.
| Senaryo | Her Zaman Zorunlu | Senaryoda Zorunlu | Boş Kalabilecek Alan |
|---|---|---|---|
| Normal oluşturma | CreditNoteExternalId, taraflar, CreditNoteLine[], LegalMonetaryTotal | Ek kesinti alanı yok | WithholdingTaxTotal |
| GV stopajı | Ortak belge alanları | TaxTotal.TaxSubtotal içinde 0003, matrah, oran, tutar | WithholdingTaxTotal, tevkifat kullanılmıyorsa |
| Borsa tescil | Ortak belge alanları | TaxTotal.TaxSubtotal içinde 8001, matrah, oran, tutar | WithholdingTaxTotal |
| SGK prim | Ortak belge alanları | TaxTotal.TaxSubtotal içinde SGK_PRIM, matrah, oran, tutar | WithholdingTaxTotal |
| Mera fonu | Ortak belge alanları | TaxTotal.TaxSubtotal içinde 9040, matrah, oran, tutar | WithholdingTaxTotal |
| Çoklu kesinti | Ortak belge alanları | Her kod için ayrı TaxSubtotal; TaxTotal.TaxAmount alt satır toplamıyla uyumlu | Senaryoda kullanılmayan kesinti kodları |
| Tevkifat | Ortak belge alanları | WithholdingTaxTotal ve net PayableAmount | TaxTotal altında aynı ekonomik tutarın ikinci kez düşülmesi |
| İptal | CreditNoteExternalId, Ettn, CreditNoteNumber, EArchiveStatus | Belgenin Signed durumda olması | Belge satır ve tutar modeli |
Ana Senaryo Grupları
Senaryo grupları, makbuzun hangi iş durumunda hangi request alanlarıyla ayrıştığını konumlandırır.
| Grup | Ne Zaman Kullanılır? | Ayırt Edici Alan |
|---|---|---|
| Normal oluşturma | Tek ürün kalemi ve ek kesinti yoksa | CreditNoteLine, LegalMonetaryTotal |
| Vergi/kesinti toplamlı işlem | GV stopajı, borsa tescil, SGK prim veya mera fonu tutarı belge toplamında izlenecekse | TaxTotal[].TaxSubtotal |
| Tevkifatlı işlem | UBL tevkifat alanı ayrıca doldurulacaksa | WithholdingTaxTotal |
| Çok kalemli makbuz | Aynı çiftçiden birden fazla ürün alınıyorsa | CreditNoteLine[] |
| İptal | Belge Signed durumundayken iptal edilecekse | CreditNoteCancelRequestModel |
Oluşturma Senaryoları
Aşağıdaki kartlar en sık karşılaşılan varyasyonları gösterir.
Normal Oluşturma
Tek kalemli bir tarımsal ürün alımı; ek kesinti yoksa belge toplamı satır ve vergi toplamlarıyla kapanır.
| Alan | Değer |
|---|---|
| CreditNoteTypeCode | MUSTAHSILMAKBUZ |
| AccountingSupplierParty.SchemeId | TCKN (çiftçi) |
| AccountingCustomerParty.SchemeId | VKN (alıcı firma) |
| CreditNoteLine | 1 kalem |
Vergi/Kesinti Toplamlı İşlem
Excel ile içe aktarma ve barkod üretimi, GV stopajı, borsa tescil, SGK prim ve mera fonu tutarlarını TaxTotal.TaxSubtotal içindeki kodlardan okur; bu kodlar belge seviyesinde ve gerekiyorsa satır seviyesinde aynı ekonomik hesabı yansıtmalıdır.
| Kod | Ad | Kapsam |
|---|---|---|
0003 | GV STOPAJI | Gelir vergisi stopajı |
8001 | BORSA TES.ÜC. | Borsa tescil kesintisi |
SGK_PRIM | SGK PRIM KESINTISI | SGK prim kesintisi |
9040 | MERA FONU | Mera fonu kesintisi |
PayableAmount, belge üzerinde taşınan kesinti ve tevkifatların etkisini yansıtacak net ödenecek tutar olmalıdır.Tevkifatlı İşlem
UBL tevkifat alanı kullanılacaksa WithholdingTaxTotal hem belge hem satır seviyesinde doldurulur; bu alan GİB raporundaki tevkifat bölümüne karşılık gelir.
| Alan | Değer |
|---|---|
| WithholdingTaxTotal.TaxCategory.TaxScheme.Name | GV STOPAJI |
| WithholdingTaxTotal.TaxCategory.TaxScheme.TaxTypeCode | 0003 |
Çok Kalemli Makbuz
Aynı çiftçiden birden fazla ürün kalemi tek makbuzda toplanabilir; CreditNoteLine alanı bir liste olduğundan her kalem ayrı bir satır olarak eklenir.
| Alan | Değer |
|---|---|
| CreditNoteLine | 2+ kalem, her biri kendi Item/Price/CreditedQuantity bilgisiyle |
İptal Senaryosu
Bir makbuz yalnızca Signed durumundaysa iptal edilebilir; akış şeması için e-Müstahsil Makbuzu Nedir? — İptal Akışı bölümüne bakın. İptal isteği POST /api/CreditNoteApi/CancelOutgoingCreditNote endpointine CreditNoteCancelRequestModel ile gönderilir (bkz. Request Örnekleri).
Edge-Case Tablosu
Sınır durumlar, entegrasyonun beklenmeyen kombinasyonlarda nasıl davranacağını önceden görmek için ayrı ele alınır.
| # | Durum | Sonuç | Neden |
|---|---|---|---|
| E1 | UUId geçersiz GUID formatında gönderilirse | ❌ | COM0017 |
| E2 | CreditNoteExternalId tekrar gönderilirse | ❌ | EMM0028 |
| E3 | UUId tekrar gönderilirse | ❌ | EMM0035 |
| E4 | CreditNoteNumber regex formatına uymazsa | ❌ | Format hatası |
| E5 | IssueDate gelecek bir tarih olarak gönderilirse | ❌ | UBL kardinalite hatası |
| E6 | IssueDate'de saat bileşeni boşsa (00:00:00) | ❌ | UBL kardinalite hatası |
| E7 | CreditNoteAndXmlCreated durumunda iptal denenirse | ❌ | EMM0024 |
| E8 | Zaten iptal edilmiş bir belge tekrar iptal edilirse | ❌ | EMM0025 |
| E9 | UUId boş gönderilirse | ✅ | Platform otomatik GUID üretir |
| E10 | CreditNoteNumber boş gönderilirse (firma ayarı platform kaynaklıysa) | ✅ | Platform üretir |