Senaryolar

Kullanım Senaryoları

Oluşturma, güncelleme ve iptal akışı için karar ağacı ve senaryolar.

Genel Bakış

e-Adisyon tek bir oluşturma akışı etrafında şekillenir: entegratör, alıcı bilgileriyle birlikte kalemleri, vergi toplamlarını ve toplam tutarları içeren bir JSON gönderir. Bu modülde karar noktaları alıcının kimlik tipi (gerçek/tüzel kişi), kalem sayısı ve iptal uygunluğu üzerinden ilerler. Doğrudan entegrasyonlarda SMS/iade kodu gibi bir doğrulama adımı yoktur.

Karar Ağacı

e-Adisyon akışı, alıcı kimlik tipinin ve kalem sayısının belge yapısına etkisini iptal uygunluğu kararıyla birlikte ele alır.

Alan Zorunluluk Matrisi

Alan	Zorunlu mu?	Not
`DocumentExternalId`	Evet	Boşsa `BLL0020` hatası; aynı firma için tekrar kullanılamaz (`BLL0028`)
`ProfileId`	Evet	`EARSIVBELGE` olmalı
`BillTypeCode`	Evet	`ADISYON` olmalı
`UUId`	Hayır	Gönderilmezse VBT üretir; gönderilirse geçerli GUID ve tekil olmalı
`AccountingSupplierParty`	Göndermeyin	VBT firma profilinden otomatik doldurur
`AccountingCustomerParty`	Evet	VKN veya TCKN kimliği zorunlu
`BillLine[]`	Evet	En az bir kalem

Ana Senaryo Grupları

Senaryo grupları, adisyonun hangi iş durumunda hangi request alanlarıyla ayrıştığını konumlandırır.

Grup	Ne Zaman Kullanılır?	Ayırt Edici Alan
Tüzel kişi alıcı	Alıcı bir firma ise	`PartyIdentifications.SchemeId=VKN`
Gerçek kişi alıcı	Alıcı bir birey ise	`PartyIdentifications.SchemeId=TCKN`
Çok kalemli adisyon	Aynı adisyonda birden fazla ürün/hizmet varsa	`BillLine[]`
İptal	Belge `Signed` durumundayken iptal edilecekse	`BillCancelRequestModel`

Oluşturma Senaryoları

Tüzel Kişi Alıcı

Alıcı bir firma; kimlik VKN (10 hane) ile taşınır.

Alan	Değer
`PartyIdentifications[0].SchemeId`	`VKN`
`PartyIdentifications[0].Value`	10 haneli VKN

Gerçek Kişi Alıcı

Alıcı bir birey; kimlik TCKN (11 hane) ile taşınır.

Alan	Değer
`PartyIdentifications[0].SchemeId`	`TCKN`
`PartyIdentifications[0].Value`	11 haneli TCKN

Çok Kalemli Adisyon

BillLine[] birden fazla kalem taşıyabilir; her kalemin kendi KDV/tevkifat bilgisi olabilir. Kalem toplamları üst toplamlarla (LegalMonetaryTotal) tutarlı olmalıdır.

İptal Senaryosu

Bir belge yalnızca Signed durumundaysa iptal edilebilir; akış şeması için e-Adisyon Nedir? — İptal Akışı bölümüne bakın. İptal isteği POST /api/BillApi/CancelOutgoingBill endpointine BillCancelRequestModel ile gönderilir (bkz. Request Örnekleri). Güncelleme öncesi de aynı şekilde belge önce detay endpointinden (GetOutgoingBill) okunmalı; Id ve UUId dahil güncel OutgoingBillRequestModel tam olarak gönderilmelidir.

Edge-Case Tablosu

Durum	Beklenen davranış
Aynı `DocumentExternalId` ile tekrar çağrı (zaman aşımı sonrası retry)	Önce `GetOutgoingBillList` ile kayıt sorgulanmalı; bulunamadan yeni externalId ile tekrar göndermek mükerrer belge riski oluşturur.
Gönderilen `UUId` geçerli GUID formatında değil	`COM0017` hatası döner.
İmzalanmamış belge iptali	`BLL0024` — iptal reddedilir.