Uygulama
Entegratör Sorumlulukları
Entegratörün veri hazırlama, doğrulama ve belge oluşturma sürecindeki sorumlulukları.
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 | Çiftçinin TCKN ve ad/soyad bilgisini gerçek kişi olarak gönder | Taraf/kimlik validasyonu |
| 5 | AccountingCustomerParty | Entegratör | Alıcı firmanın VKN ve unvan bilgisini tüzel kişi olarak gönder | 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ı |
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.
| 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
Entegratör tarafındaki hazırlık süreci, taraf ve kalem bilgisinin doğru kurulmasıyla başlar; akış bu hazırlığın API gönderimine nasıl bağlandığını gösterir.
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 | Çiftçi TCKN, alıcı firma VKN ile gönderilir | UBL taraf rolü ve GİB raporu aynı kimlik tipine 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 |
Planlanan değişiklik: Aktivasyon sonrasında bu sorumluluk tablosuna SMS doğrulama alanları eklenecektir. Aktivasyon öncesi hazırlık gereken sözleşme değişiklikleri için bkz. SMS Doğrulamalı Gönderim — Entegratörler İçin.