Sorumluluklar
Entegratör Sorumlulukları
Entegratörün veri hazırlama, hesaplama ve belge oluşturma sürecindeki sorumlulukları.
Veri Sorumluluk Tablosu
Entegratörün (ERP/POS sistemi) API çağırmadan önce sağlaması gerekenler:
| # | Veri | Kim Üretir | Entegratör Ne Yapmalı | Hata |
|---|---|---|---|---|
| 1 | DocumentExternalId | Entegratör | Kendi sisteminde benzersiz bir referans üret ve gönder | BLL0020 / BLL0028 |
| 2 | UUId | Platform (opsiyonel) | Boş bırakılırsa platform bir GUID üretir; kendiniz göndermek isterseniz geçerli ve benzersiz olmalı | COM0017 / BLL0035 |
| 3 | DocumentNumber | Platform (opsiyonel) | Boş bırakılırsa VBT üretir; kendiniz göndermek isterseniz sıra/format kontrolünden geçmeli | BLL0009 |
| 4 | AccountingSupplierParty | Platform | Göndermeyin; firma profilinden otomatik doldurulur | — |
| 5 | AccountingCustomerParty | Entegratör | Alıcının VKN (tüzel) veya TCKN (gerçek kişi) kimliğini ve adresini gönder | Taraf/kimlik validasyonu |
| 6 | BillLine[] | Entegratör | Her kalem için miktar, birim, ürün/hizmet adı, fiyat ve satır toplamını hesapla | UBL kardinalite hatası |
| 7 | TaxTotal / LegalMonetaryTotal | Entegratör | KDV ve kalem toplamlarını tutarlı hesapla | Validasyon veya rapor uyumsuzluğu |
Senaryo Bazlı Hazırlık Matrisi
Ortak belge alanları hazırlandıktan sonra entegratörün asıl ayrımı, alıcı kimlik tipini doğru şema koduyla göndermesidir.
| Senaryo | Entegratörün Hesaplayacağı Alanlar | Zorunlu Kod/Alan | Gönderim Öncesi Kontrol |
|---|---|---|---|
| Tüzel kişi alıcı | Taraf, kalemler, belge toplamları | PartyIdentifications.SchemeId=VKN | VKN 10 hane |
| Gerçek kişi alıcı | Taraf, kalemler, belge toplamları | PartyIdentifications.SchemeId=TCKN | TCKN 11 hane |
| Çok kalemli adisyon | Her kalem için ayrı tutar/KDV | BillLine[] | LegalMonetaryTotal satır toplamlarıyla eşleşmeli |
| İptal | İptal edilecek belgenin kimliği ve durum bilgisi | BillCancelRequestModel | 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.
Gönderim Ö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 | DocumentExternalId tekil, UUId boş veya geçerli GUID | Mükerrer ve format hatalarını önler |
| Düzenleyen taraf | AccountingSupplierParty gönderilmiyor | Bu alan VBT tarafından firma profilinden doldurulur |
| Alıcı | VKN (tüzel) veya TCKN (gerçek kişi) doğru uzunlukta ve yalnız rakam | UBL taraf rolü ve GİB raporu aynı kimlik tipine dayanır |
| Kalemler | En az bir BillLine; miktar, birim, ürün/hizmet adı ve fiyat dolu | Adisyonun ekonomik içeriği satır seviyesinde taşınır |
| Tutarlar | Kalem toplamları LegalMonetaryTotal ile eşleşiyor | UBL ve GİB rapor tutarları arasında fark oluşmasını engeller |
| Sonuç | Başarı kararı Data.HasError üzerinden veriliyor; Data.BillNumber/Data.Ettn saklanıyor | İptal ve PDF işlemleri doğru Ettn ile çağrılabilsin |