Sorumluluklar

Entegratör Sorumlulukları

Entegratörün veri hazırlama, kimlik, tutar, vergi ve sonuç yönetimi sorumlulukları.

İlk Başarılı Belge İçin Uçtan Uca Akış

Sağlıklı bir entegrasyon yalnız endpoint çağrısından ibaret değildir. Token yönetimi, veri hazırlığı, toplam kontrolü, iş sonucu ve sonradan sorgulama tek bir bütün olarak ele alınmalıdır.

Veri Sorumluluk Tablosu

Veri grubu	Entegratör sorumluluğu	VBT’nin sağladığı davranış	Doğrulama sinyali
Kimlik ve oturum	Doğru firma ve kanal için token almak, yenilenen tokenı saklamak	Token üretir ve standart zarf içinde yenileme bilgisini döner.	HTTP başarı + geçerli `Token`/`RefreshToken`
Dış referans	Her yeni işlem için benzersiz `SmmExternalId` üretmek	Belgeyi dış referansla ilişkilendirir.	Oluşturma sonucunda `HasError = false`
Alıcı	Kimlik tipine uygun ad/unvan, vergi dairesi ve adresi göndermek	Veriyi belge ve raporlama kaydına taşır.	Detay sorgusunda taraf alanları
Hizmet satırları	Her satırın açıklama, brüt, oran, vergi ve kesinti tutarlarını hesaplamak	Gönderilen iş verisinden belge görünümünü üretir.	PDF ve detay response’u
Belge toplamları	Satır toplamlarıyla üst toplamları uzlaştırmak	İş kurallarını doğrular ve sonucu döner.	`Data.Errors[]` boş olmalı
Teslim	Gönderim şeklini ve elektronik teslim adresini doğru belirlemek	PDF üretir; Portal e-posta gönderim işlevlerini sunar.	Liste/detay e-posta durumu
İptal	Doğru UUID ile iptal çağrısı yapmak ve sonucu ERP’ye işlemek	Belgeyi iptal eder ve GİB bildirimini raporlama sürecinde yönetir.	`Data = true`, liste/detay durumu

Senaryo Bazlı Hazırlık Matrisi

Karar	Gönderilmesi gereken	Gönderim öncesi kontrol
VKN alıcı	`Unvan`, `VergiDaire`, adres	VKN 10 hane ve yalnız rakam
TCKN alıcı	`Ad`, `Soyad`, adres	TCKN 11 hane ve yalnız rakam
TRY	`DocumentCurrencyCode = TRY`, `CalculationRate = 1`	Döviz karşılığı yanlışlıkla gönderilmemiş olmalı
Döviz	ISO 4217 kodu, işlem kuru, gerekiyorsa `Kur`	Kur sıfırdan büyük ve toplam karşılıkları tutarlı
Stopaj	Oran, stopaj tutarı, net ücret	Stopaj tutarı brüt üzerinden hesaplanmış olmalı
Tevkifat	Oran, kod, tevkifat tutarı, ödenecek KDV	Tevkifat hesaplanan KDV üzerinden hesaplanmış olmalı
Elektronik teslim	`GonderimSekli`, kullanılacak e-posta adresi	Adres biçimi ve çoklu adres ayırıcıları
Güncelleme	Mevcut `Id`, `UUId` ve tam güncel model	Güncel belge önce sorgulanmış olmalı

Hesaplama ve Yuvarlama Kuralları

VBT request’i ekonomik işlemin hazır sonucu olarak kabul eder. Entegratör, kalem ve belge düzeyindeki tutarları aynı hesaplama politikasıyla üretmelidir.

Alan	Hesaplama ilişkisi	Kontrol
`HesaplananKdv`	`TotalAmount × KdvOran / 100`	Satır ve üst toplam KDV toplamı aynı olmalı
`TaxStopajTotalAmount`	`TotalAmount × StopajOran / 100`	Stopaj yoksa oran ve tutar sıfır
`WithholdingTaxTotalAmount`	`HesaplananKdv × TevkifatOran / 100`	Tevkifat varsa kod da gönderilmeli
`TaxKdvTotalAmount`	`HesaplananKdv − WithholdingTaxTotalAmount`	Negatif olamaz
`NetUcret`	`TotalAmount − TaxStopajTotalAmount`	Brüt ücretle stopaj uyumlu olmalı
`PayableAmount`	`NetUcret + TaxKdvTotalAmount`	Nihai tahsilat/ödeme tutarıyla eşleşmeli

Yuvarlama: Oranlardan hesaplanan değerleri ve belge toplamlarını farklı adımlarda farklı hassasiyetle yuvarlamayın. ERP’de kullanılan yuvarlama politikası satır ve üst toplamda aynı olmalıdır.

Kimlik ve Tekrar Çağrı Yönetimi

SmmExternalId entegratörün idempotency anahtarıdır. Ağ hatası veya zaman aşımı sonrasında çağrının sonucu belirsizse aynı ekonomik işlemi yeni bir dış referansla tekrar göndermek mükerrer belge riski oluşturur.

Oluşturma request’i gönderilmeden dış referansı kalıcı olarak ayırın.
Yanıt başarıyla geldiyse SmmNumber ve UUId ile birlikte saklayın.
Yanıt alınamadıysa önce liste sorgusunda SmmExternalId filtresiyle kontrol edin.
Kayıt bulunduysa sonucu uzlaştırın; bulunmadıysa aynı dış referansla kontrollü tekrar deneyin.

Token ve Header Yönetimi

Account/Token dışındaki çağrılarda VbtAuthorization header’ı gönderilmelidir. Her standart yanıttaki RefreshToken boş değilse istemcinin sakladığı token atomik biçimde güncellenmelidir.

POST /api/Smm/AddOutgoingSmm HTTP/1.1
Content-Type: application/json
VbtAuthorization: <token>

Paralel istekler: Aynı firma için eşzamanlı çağrılar varsa token yenileme yarışını önlemek üzere en son geçerli token merkezi ve güvenli biçimde saklanmalıdır.

Yanıt ve Hata Yönetimi

HTTP isteğinin tamamlanmış olması belge iş sonucunun başarılı olduğu anlamına gelmez. Oluşturma, güncelleme ve önizleme sonuçlarında içteki Data.HasError ve Data.Errors[] birlikte değerlendirilmelidir.

Sinyal	Anlam	İstemci davranışı
HTTP 2xx + `Data.HasError = false`	İşlem kabul edildi.	Kimlikleri sakla; gerekirse detay/PDF ile doğrula.
HTTP 2xx + `Data.HasError = true`	İş kuralı veya içerik doğrulaması başarısız.	`Errors[]` listesini kullanıcıya göster; veri düzeltilmeden otomatik tekrar yapma.
HTTP 401/403	Oturum veya yetki geçersiz.	Tokenı yenile; aynı iş emrini kontrollü tekrar gönder.
HTTP 5xx / zaman aşımı	Sonuç belirsiz olabilir.	Dış referansla sorgulamadan yeni belge oluşturma.
`RefreshToken` dolu	Yeni oturum tokenı sağlandı.	Bir sonraki istekten önce güvenli biçimde sakla.

Gönderim Öncesi Kontrol Listesi

Kimlik ve taraf kontrolü

SmmExternalId boş değil ve bu işleme özgü.
VKN/TCKN yalnız rakam ve doğru uzunlukta.
VKN’de unvan/vergi dairesi; TCKN’de ad/soyad tamam.
Alıcı adresinde ülke, ilçe/semt ve şehir bilgileri var.

Hizmet ve toplam kontrolü

En az bir MalHizmetler satırı var ve satır kimlikleri benzersiz.
KDV, stopaj ve tevkifat oranları 0–100 aralığında.
Satır tutarlarının toplamı üst toplamlarla eşleşiyor.
PayableAmount net ücret ve ödenecek KDV ile uyumlu.

Teslim ve sonuç kontrolü

GonderimSekli iş senaryosuna uygun.
Elektronik teslim adresi geçerli ve çoklu adresler noktalı virgülle ayrılmış.
Başarı kararı HasError üzerinden veriliyor.
UUId, SmmNumber ve yenilenen token saklanıyor.