API

Portal API Endpoint Referansı

Portal UI'ın belge oluşturma, doğrulama ve gerçek kişi cari akışlarında kullandığı endpoint sözleşmeleri.

Entegratör mü arıyorsunuz? Bu sayfa yalnızca VBT Portal uygulamasının kendi kullanımı içindir. Doğrudan ERP/API entegrasyonu için Entegratör API Endpoint Referansı sayfasına bakın.

Belge Oluşturma ve Güncelleme

Portal UI, entegratörlerle aynı AddOutgoingExpenseVoucher ve UpdateOutgoingExpenseVoucher endpointlerini kullanır. SMS sonradan Portal endpointleriyle tamamlanabilir; İADEKODU ise belge Add/Update modeli içinde gönderilir.

Adım	Portal UI davranışı
1. Cari seçimi	Alıcı ve varsa vekil PersonParty endpointleriyle aranır veya kaydedilir.
2. Belge kaydı	Seçilen alıcı `AccountingCustomerParty.Party.Id`, varsa vekil `DelegateReceiver.PartyId` ile Add/Update request'ine taşınır. Kullanıcının seçtiği tek TCKN veya PASAPORTNO belge kimliği olarak gönderilir.
3. İlk yanıt	Yalnız unsigned SMS akışında `VerificationInfo` ve `VerificationProvider` tamamen boş olabilir. İADEKODU seçildiyse iki model ilk Add/Update isteğinde tamdır. UI, response içindeki `OutgoingExpenseVoucherStatusForUser` değerini esas alır.
4. Doğrulama	`WaitingForVerification` yalnız SMS gönderiminin beklendiğini gösterir; Send ve Complete çağrıları kullanılır. İADEKODU için ayrı Portal endpointi yoktur.
5. Güncel durum	Başarılı işlemden sonra belge yeniden sorgulanır; imzaya hazır veya bekleyen güncel durum gösterilir.

Portal Add/Update alan özeti

{
  "AccountingCustomerParty": {
    "Party": {
      "Id": 12345,
      "PartyIdentifications": [
        { "SchemeId": "PASAPORTNO", "Value": "U12345678" }
      ]
    }
  },
  "DelegateReceiver": {
    "PartyId": 67890
  },
  "VerificationInfo": null,
  "VerificationProvider": null
}

Bu parça tam belge request'i değildir; yalnız Portalın cari ve doğrulama sınırını gösterir. Belgenin diğer zorunlu alanları aynı Add/Update sözleşmesinde gönderilmelidir.

Doğrulama Endpointleri

Portal kullanıcısına hazır sunulan doğrulama ekranları, aşağıdaki endpoint sözleşmeleri üzerinden ilerler. Bu endpointler VBT Portal uygulamasının kullanımı içindir; dış entegratörlerin belge oluşturma ve güncelleme sözleşmelerinin yerini almaz.

Görünürlük: UI, doğrulama kontrollerini belgenin dönen durumu ve senaryosuna göre gösterir. WaitingForVerification SMS gönderme ekranını, WaitingForSmsCode SMS kodu girişini açar.

POST/api/ExpenseVoucherApi/SendExpenseVoucherSmsCode

Satış veya SMS seçilmiş yüz yüze iade senaryosunda doğrulama kodunu gönderir.

Çağrı koşulu	Belge `WaitingForVerification` veya telefon düzeltme/yeniden gönderim için `WaitingForSmsCode` durumundadır; senaryo SMS doğrulamasına izin verir.
Request	`SendExpenseVoucherSmsCodeRequestModel` — belge kimliği alanlarından en az biri ve `PhoneNumber`
Response	`SendExpenseVoucherSmsCodeResponseModel` — `MaskedPhoneNumber`, `VerificationToken`, `ExpiresInSeconds`
UI davranışı	Maskeli telefon ve kalan süre gösterilir; token kullanıcıya gösterilmeden kod doğrulama çağrısına taşınır.

POST/api/ExpenseVoucherApi/CompleteExpenseVoucherSmsVerification

SMS gönderiminden dönen token ile kullanıcının girdiği kodu doğrular.

Çağrı koşulu	Belge `WaitingForSmsCode` durumundadır.
Request	`VerifyExpenseVoucherSmsCodeRequestModel` — aynı belge kimliği, `VerificationToken` ve `Code`
Response	`ResponseModel<bool>`
UI davranışı	Başarılı sonuçta belge yeniden okunur ve güncel state gösterilir; hata halinde doğrulanmış görünümü verilmez.

İADEKODU akışı: Ayrı bir Portal submit endpointi yoktur. UI, VerificationProvider ve VerificationInfo alanlarını tam belge modeliyle birlikte AddOutgoingExpenseVoucher veya UpdateOutgoingExpenseVoucher çağrısında gönderir. Geçerli İADEKODU verisi belgeyi SMS adımlarına sokmadan imza kuyruğuna taşır; kargolu IADE bu alanlar olmadan kaydedilemez.

İstemci davranışı: Devam eden çağrı sırasında aynı aksiyon yeniden tetiklenmez. İş kuralı hatasında API'nin kullanıcıya dönük mesajı gösterilir ve belge başarılı yanıt alınmadan bir sonraki state'e geçirilmez. Güncel durum için işlem sonrasında belge yeniden sorgulanır.

Gerçek Kişi Cari Endpointleri

İşlem sırası: Portal önce ad, TCKN veya PASAPORTNO ile arama yapmalıdır. Kayıt bulunursa response içindeki gerçek Party.Id ile Update; bulunamazsa Add çağrılmalıdır. Public cari API'sinde Save/upsert endpointi yoktur.

GET/api/PersonParty/GetPartyListByNameAndType?partyName={partyName}

Ad, TCKN veya pasaport numarasıyla gerçek kişi carilerini arar.

Request	Query string içinde `partyName` değeri — ad, TCKN veya PASAPORTNO içerebilir
Response	`ResponseModel<IList<PartyResponseModel>>`
UI davranışı	Yalnız `Customer`, `Supplier` ve `CustomerAndSupplier` rollerindeki gerçek kişiler gösterilir. Arama carinin rolünü değiştirmez.

Çağrı ve seçim örneği

GET /api/PersonParty/GetPartyListByNameAndType?partyName=U12345678

Kayıt bulunursa Data[].Id, Update request'ine ve belge request'indeki ilgili cari Id alanına taşınır.

GET/api/PersonParty/Get?id={id}

Firma kapsamındaki gerçek kişi cari detayını getirir.

Request	Query string içinde cari `id` değeri
Response	`ResponseModel<PartyResponseModel>`
UI davranışı	`Person`, `Contact`, `PostalAddress` ve `PartyIdentifications` alanları forma taşınır.

POST/api/PersonParty/Add

Customer rolünde yeni gerçek kişi carisi oluşturur.

Çağrı koşulu	TCKN veya PASAPORTNO ile yapılan aramada mevcut cari bulunamamıştır.
Request	`PartyRequestModel` — `PartyName`, `Person`, `Contact`, `PostalAddress` ve `PartyIdentifications`
Response	`ResponseModel<PartyResponseModel>`
Kural	En az bir TCKN veya PASAPORTNO bulunmalıdır. Add mevcut kimliği otomatik güncellemez.

Yeni gerçek kişi request'i

{
  "Id": 0,
  "PartyName": "ÖRNEK KİŞİ",
  "PartyIdentifications": [
    { "SchemeId": "PASAPORTNO", "Value": "U12345678" }
  ],
  "Person": {
    "FirstName": "ÖRNEK",
    "FamilyName": "KİŞİ",
    "NationalityId": "TR"
  },
  "Contact": {
    "Telephone": "05551112233",
    "ElectronicMail": "ornek.kisi@example.com"
  },
  "PostalAddress": {
    "StreetName": "Örnek Caddesi",
    "BuildingNumber": "12",
    "CitySubdivisionName": "Kadıköy",
    "CityName": "İstanbul",
    "Country": { "Name": "Türkiye" }
  }
}

POST/api/PersonParty/Update

Arama veya detay response'undan seçilen gerçek kişi carisini günceller.

Çağrı koşulu	Mevcut cari seçilmiştir ve response'taki `Id` korunmuştur.
Request	`PartyRequestModel` — geçerli `Id` ve güncel cari modeli
Response	`ResponseModel<PartyResponseModel>`
UI davranışı	Update bir patch değildir. Form, Get veya Search response'undan alınan korunacak alanlarla birlikte güncel modeli göndermelidir.

GET/api/PersonParty/Delete?id={id}

Firma kapsamındaki gerçek kişi carisini ve bağlı kimlik kayıtlarını siler.

Request	Query string içinde cari `id` değeri
Response	`ResponseModel<bool>`
Sonuç	Cari ve bağlı TCKN/PASAPORTNO kayıtları aynı işlem içinde silinir.

Gerçek Kişi Kimlik Endpointleri

İlk kimlikler cari Add/Update request'indeki PartyIdentifications alanıyla taşınır. Kayıtlı carinin kimliklerini sonradan ayrı yönetmek için aşağıdaki endpointler kullanılır.

GET/api/PersonPartyIdentification/Get?partyId={id}

Carinin aktif TCKN ve PASAPORTNO kayıtlarını, kimlik kayıt Id'leriyle birlikte getirir. Update veya Delete öncesinde kullanılacak kimlik Id'si bu response'tan alınmalıdır.

POST/api/PersonPartyIdentification/Add

Mevcut gerçek kişi carisine yeni bir TCKN veya PASAPORTNO ekler.

Request	`PartyIdentificationRequestModel` — `PartyId`, `SchemeId`, `Value`
Response	`ResponseModel<PartyIdentificationResponseModel>`

POST/api/PersonPartyIdentification/Update

Mevcut kimlik kaydını günceller.

Request	`PartyIdentificationRequestModel` — mevcut kimliğin `Id` değeri, `PartyId`, `SchemeId`, `Value`
Response	`ResponseModel<PartyIdentificationResponseModel>`

GET/api/PersonPartyIdentification/Delete?id={id}

Seçilen kimlik kaydını siler. Carinin son aktif kişi kimliği silinemez.

Request	Query string içinde kimlik kaydının `id` değeri
Response	`ResponseModel<bool>`

Kimlik özeti: Kimlik Add, Update veya Delete işleminden sonra carinin IdentityOrTaxNumber değeri TCKN önceliğiyle güncellenir. Cari üzerinde TCKN ve PASAPORTNO birlikte bulunabilir; aynı scheme altında iki farklı aktif değer bulunamaz. Silinen kimlik tarihçe olarak korunur; aynı SchemeId ve Value yeniden eklenirse yeni bir aktif kimlik kaydı oluşturulur.

PersonParty Hata Kodları

Kod	Karşılaşılabilecek durum
`PTY0001`	`Update` çağrısında geçerli bir cari `Id` gönderilmemiştir.
`PPY0001`	Cari adı gönderilmemiştir.
`PPY0003`	Gerçek kişi carisi için TCKN veya PASAPORTNO gönderilmemiştir.
`PPY0004`	Kimlik tipi TCKN veya PASAPORTNO değildir.
`PPY0005`	Kimlik aynı firmadaki başka bir caride aktiftir.
`PPY0006`	Carinin son aktif kişi kimliği kaldırılmak istenmiştir.
`PPY0007`	Cari rolü PersonParty kullanımına uygun değildir.
`PPY0008`	Seçilen cari gerçek kişi carisi değildir.
`PPY0009`	Pasaport numarası 9 karakter sınırını aşmıştır.
`PTYI0001`	Belirtilen kimlik kaydı bulunamamıştır (`PersonPartyIdentification/Update` veya `Delete`).
`PTYI0009`	TCKN 11 haneli sayısal değer değildir.
`PTYI0010`	Kimlik `Value` alanı boş gönderilmiştir.
`PTYI0017`	Aynı caride aynı `SchemeId` için birden fazla farklı değer gönderilmiştir.

Portal belge request'i: Alıcı cari Id'si AccountingCustomerParty.Party.Id alanına, seçilen tek TCKN veya PASAPORTNO PartyIdentifications içine yazılır. Vekil cari Id'si DelegateReceiver.PartyId alanına eklenir.

Belge sınırı: Cari bilgileri belge oluşturma veya güncelleme anında request'e kopyalanır. Cari kartında daha sonra yapılan değişiklikler mevcut belgeyi, arşiv XML'ini veya GİB raporunu değiştirmez.