API

Entegratör API Endpoint Referansı

Entegratörün doğrudan ERP/API entegrasyonunda kullandığı belge endpointleri, alan sözleşmeleri ve yanıt örnekleri.

Kimlik Doğrulama

POST/api/Account/Token

Oturum token'ı alır. Tüm diğer endpointler bu token'ı VbtAuthorization header'ında bekler.

Request	`TokenRequestModel` — `{ Email, Password }`
Response	`TokenResponseModel` — `{ Token }`

Alan Zorunluluk Matrisi

Alan	Zorunlu mu?	Not
`DocumentExternalId`	Evet	Benzersiz, ERP referansı
`ProfileId`	Evet	`EARSIVBELGE`
`BillTypeCode`	Evet	`ADISYON`
`IssueDate`	Evet	ISO 8601
`AccountingSupplierParty`	Göndermeyin	VBT doldurur
`AccountingCustomerParty`	Evet	VKN veya TCKN kimliği
`BillLine[]`	Evet	En az bir kalem
`LegalMonetaryTotal`	Evet	Kalem toplamlarıyla tutarlı

Ekleme

POST/api/BillApi/AddOutgoingBill

JSON model ile e-Adisyon oluşturur.

Request	`OutgoingBillRequestModel`
Response	`OutgoingBillAddResponseModel` — `Data.{ HasError, Errors, BillNumber, Ettn }`

POST/api/BillApi/AddOutgoingBillByUbl

Hazır UBL XML ile e-Adisyon oluşturur.

Request	`BillUblRequestModel`
Response	`OutgoingBillAddResponseModel`

POST/api/BillApi/PreviewOutgoingBill

Kayıt oluşturmadan taslak PDF üretir (dummy UUId/DocumentNumber ile).

Request	`OutgoingBillRequestModel`
Response	`OutgoingBillPreviewResponseModel.BillPdfFileBytes` (doğrudan bu adla tanımlı, override yok)

Güncelleme

POST/api/BillApi/UpdateOutgoingBill

Mevcut belgeyi günceller.

Ön koşul	Belge önce detay endpointinden okunmalı; request içinde mevcut `Id` ve `UUId` bulunmalıdır.
Request	`OutgoingBillRequestModel`
Response	`OutgoingBillUpdateResponseModel` — `Data.{ HasError, Errors, BillNumber, Ettn }`

POST/api/BillApi/UpdateOutgoingBillByUbl

Hazır UBL XML ile günceller.

Request BillUblRequestModel

İptal

POST/api/BillApi/CancelOutgoingBill

Belgeyi iptal eder. Yalnızca Signed durumdaki belgeler iptal edilebilir.

Request	`BillCancelRequestModel` — `{ Id, BillExternalId, Ettn, BillNumber, EArchiveStatus, EArchiveCancelDescription }` (kayıt `Id`/`BillExternalId`/`Ettn`/`BillNumber`'dan ilk eşleşenle bulunur)
Response	`bool`
Not	İmzalanmamış belge iptali `BLL0024`, zaten iptal edilmiş belge `BLL0025` döner. Bildirim e-postası gönderilmez.

{
  "Ettn": "6b60c576-7ed9-4bf1-9f90-3c97747b7470",
  "EArchiveStatus": 2
}

Sorgulama & Görüntüleme

GET/api/BillApi/GetOutgoingBill?id={ettn}

ETTN ile belge detayını getirir.

Response OutgoingBillResponseModel

POST/api/BillApi/GetOutgoingBillList

Özet liste sorgular.

Request	`SearchRequestModel<OutgoingBillGetRequestModel>`
Filtreler	ETTN, taraf VKN/TCKN/adı, belge no, dış referans, tarih, e-Arşiv/mail/rapor/iptal-rapor durumları
Response	`SearchResponseModel<OutgoingBillSummaryResponseModel>`

POST/api/BillApi/GetOutgoingBillPdf

Bir veya daha fazla e-Adisyon'un PDF çıktısını getirir.

Request	`BillPdfRequestModel` — `Ettns[]` (JSON alanı `BillEttns`)
Response	`BillPdfResponseModel.BillPdfFileBytes` — JSON içinde base64 olarak taşınır. (C# property adı `FileBytes`'tır, `JsonProperty` ile tel adı `BillPdfFileBytes`'a zorlanır.)

{
  "BillEttns": ["6b60c576-7ed9-4bf1-9f90-3c97747b7470"]
}

POST/api/BillApi/GetOutgoingBillDocumentPackage

Portal görüntüleme/indirme senaryosunda kullanılan belge paketini döner.

Request	`GlobalDocumentPreviewRequestModel`
Response	`DocumentPreviewResponseModel`

POST/api/BillApi/GetOutgoingBillXmlList

Belgelerin UBL XML çıktılarını toplu olarak getirir (Excel değil, XML).

Request	`OutgoingBillXmlRequestModel` — `{ BillEttns: [] }`
Response	`OutgoingBillXmlResponseModel`

Alt Modeller

OutgoingBillRequestModel

Alan	Tip	Not
`Id`	int	Güncellemede kullanılır
`DocumentExternalId`	string	ERP dış referansı, zorunlu
`DocumentNumber`	string	Belge no; boşsa VBT üretir
`ProfileId`	string	`EARSIVBELGE`
`BillTypeCode`	string	`ADISYON`
`UUId`	string	ETTN; boşsa VBT üretir
`DocumentCurrencyCode`	string	ISO 4217
`IssueDate`	DateTime	ISO 8601
`LineCountNumeric`	decimal	Kalem sayısı
`AccountingSupplierParty`	SupplierPartyRequestModel	VBT doldurur, göndermeyin
`AccountingCustomerParty`	CustomerPartyRequestModel	Alıcı taraf
`TaxTotal`	List<TaxTotalRequestModel>	Belge seviyesi vergi toplamları
`WithholdingTaxTotal`	List<TaxTotalRequestModel>	Tevkifat bilgileri
`LegalMonetaryTotal`	MonetaryTotalRequestModel	Belge parasal toplamları
`BillLine`	List<OutgoingBillLineRequestModel>	Kalemler
`EArchiveMailTo`	string	Çoklu adres `;` ile ayrılır
`ChannelCode`	string	Uygulama kodu

Not: Yukarıdaki tablo sık kullanılan alanları kapsar; model ayrıca AllowanceCharge, OrderReference, BillingReference, DespatchDocumentReference, ReceiptDocumentReference, OriginatorDocumentReference, ContractDocumentReference, BuyerCustomerParty, SellerSupplierParty, TaxRepresentativeParty, Delivery, PaymentMeans, PaymentTerms, döviz kuru alanları ve Barcode gibi UBL uyumlu opsiyonel alanlar da taşır.

OutgoingBillLineRequestModel

Alan	Tip	Not
`Id`	string	Kalem sıra no
`CreditedQuantity`	QuantityRequestModel	Miktar + birim kodu
`LineExtensionAmount`	decimal	Kalem tutarı
`TaxTotal`	TaxTotalRequestModel	Kalem vergi bilgisi
`WithholdingTaxTotal`	List<TaxTotalRequestModel>	Kalem tevkifatı
`Item`	ItemRequestModel	Mal/hizmet adı
`Price`	decimal	Birim fiyat

AccountingCustomerParty / AccountingSupplierParty

Ortak Vbt.Core.Ubl taraf modeli kullanılır: Party.PartyIdentifications[] (SchemeId: VKN|TCKN, Value), Party.PartyName, Party.PostalAddress (CityName, Country.Name vb.).

Enum Değerleri

Alan	Değer	Anlam
`OutgoingBillStatus`	`BillAndXmlCreated`	Belge ve UBL XML oluşturuldu, imzalama bekliyor
`OutgoingBillStatus`	`Signed`	İmzalandı; GİB gönderimine ve iptale hazır
`ProfileId`	`EARSIVBELGE`	GİB e-Arşiv belge profili
`BillTypeCode`	`ADISYON`	e-Adisyon belge tipi

Response — Belge Detay

İşlem	Model	Önemli alanlar
Ekleme	`OutgoingBillAddResponseModel`	`HasError`, `Errors[]`, `BillNumber`, `Ettn`
Güncelleme	`OutgoingBillUpdateResponseModel`	`HasError`, `Errors[]`, `BillNumber`, `Ettn`
Detay	`OutgoingBillResponseModel`	Belgenin tüm alanları
Liste	`SearchResponseModel<OutgoingBillSummaryResponseModel>`	UUID, taraf, tarih, tutarlar, durumlar
PDF	`BillPdfResponseModel`	`BillPdfFileBytes`

Başarılı oluşturma yanıtı

{
  "RefreshToken": "",
  "Data": {
    "HasError": false,
    "Errors": [],
    "BillNumber": "ADS2026000000001",
    "Ettn": "6b60c576-7ed9-4bf1-9f90-3c97747b7470"
  }
}

İçerik doğrulama yanıtı

{
  "RefreshToken": "",
  "Data": {
    "HasError": true,
    "Errors": [
      { "ErrorCode": "BLL0020", "ErrorMessage": "ExternalId zorunludur." }
    ],
    "BillNumber": null,
    "Ettn": null
  }
}