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

API çağrıları, firmanın yetki bağlamı ve oturum token'ı üzerinden ilerler.

💡 Tüm istekler VbtAuthorization header'ı gerektirir. Token almak için POST /api/Account/Token kullanın.

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	Zorunluluk	Not
`ProfileId`	Z	e-Arşiv Fatura için `EARSIVFATURA`
`IssueDate`	Z	Gelecek tarih olamaz
`AccountingSupplierParty`	Z	Satıcı VKN'si
`AccountingCustomerParty`	Z	Alıcı VKN (tüzel) veya TCKN (gerçek kişi)
`InvoiceLine`	Z	En az 1 kalem
`LegalMonetaryTotal`	Z	Satır toplamı, KDV hariç/dahil ve ödenecek tutar
`WithholdingTaxTotal`	O	Tevkifat varsa doldurulur
`BillingReference`	O	Mükerrer/iade veya ÖKC referansı varsa doldurulur
`EArchiveMailTo`	O	Birden fazla adres `;` ile ayrılır

Z Zorunlu · O Opsiyonel

Ekleme

Yeni fatura oluşturma çağrıları, belge içeriğini ve taraf bilgilerini platforma teslim eder; farklı giriş yöntemleri aynı belge yaşam döngüsüne bağlanır.

POST/api/VbtApi/AddOutgoingInvoice

Yeni bir e-Arşiv Fatura oluşturur ve sisteme kaydeder.

Request	`OutgoingInvoiceRequestModel`
Response	`ResponseModel<OutgoingInvoiceAddResponseModel>` — `{ InvoiceNumber, Ettn, PdfUrl, XmlUrl }`

POST/api/VbtApi/AddOutgoingInvoiceByUbl

Hazır UBL Invoice XML'i ile fatura oluşturur.

Request	`InvoiceUblRequestModel`
Response	`ResponseModel<OutgoingInvoiceAddResponseModel>`

POST/api/VbtApi/AddOutgoingInvoiceByXml

Hazır XML gövdesiyle fatura oluşturur (Ubl dışı XML akışı).

Request	`XmlRequestModel`
Response	`ResponseModel<XmlResponseModel>`

POST/api/VbtApi/AddOutgoingInvoiceByExcel

Excel dosyasındaki birden fazla satırı toplu olarak işler.

Request	`ExcelFileRequestModel`
Response	`ResponseModel<List<OutgoingInvoiceAddExcelResponseModel>>` — satır başına ayrı sonuç

POST/api/VbtApi/AddOutgoingReturnedInvoice

Mükerrer/iade referanslı fatura ekler.

Request	`OutgoingInvoiceRequestModel` (`BillingReference.InvoiceDocumentReference` ile)
Response	`ResponseModel<OutgoingInvoiceAddResponseModel>`

POST/api/VbtApi/OutgoingInvoicePreview

Faturayı kaydetmeden önce önizleme yapar.

Request	`OutgoingInvoiceRequestModel`
Response	`ResponseModel<OutgoingInvoicePreviewResponseModel>`

Güncelleme

POST/api/VbtApi/UpdateOutgoingInvoice

Mevcut bir faturayı JSON model ile günceller.

Request	`OutgoingInvoiceRequestModel`
Response	`ResponseModel<OutgoingInvoiceUpdateResponseModel>`

POST/api/VbtApi/UpdateOutgoingInvoiceByUbl

Mevcut bir faturayı UBL Invoice XML ile günceller.

Request	`InvoiceUblRequestModel`
Response	`ResponseModel<OutgoingInvoiceUpdateResponseModel>`

İptal ve İtiraz

Ayrıntılı durum modeli: Bu iki endpointin durum akışı, GİB Portal senkronizasyonu ve yasal süreler için İptal ve İtiraz Durum Takibi sayfasına bakın.

POST/api/VbtApi/CancelOutgoingEArchiveInvoice

e-Arşiv Fatura'yı iptal eder.

Request	`EArchiveCancelRequestModel`
Response	`ResponseModel<bool>`

POST/api/VbtApi/CancelOutgoingEArchiveInvoiceByXml

XML gövdesiyle e-Arşiv Fatura iptali.

Request	`XmlRequestModel`
Response	`ResponseModel<bool>`

POST/api/VbtApi/ObjectOutgoingEArchiveInvoice

Alıcının TTK md. 18/3 kapsamında yaptığı itirazı kayda geçirir.

Request	`DocumentObjectionRequestModel`
Response	`ResponseModel<bool>`

Sorgulama & Görüntüleme

GET/api/VbtApi/GetOutgoingInvoice?id={ETTN}

ETTN ile tek bir faturanın detayını getirir.

Request	`id` — string, ETTN/GUID
Response	`ResponseModel<OutgoingInvoiceResponseModel>`

POST/api/VbtApi/GetOutgoingInvoiceList

Fatura özet listesini döner.

Request	`SearchRequestModel<OutgoingInvoiceGetRequestModel>`
Response	`ResponseModel<SearchResponseModel<OutgoingInvoiceSummaryResponseModel>>`

POST/api/VbtApi/GetOutgoingInvoiceView

Belgenin HTML görüntüsünü döner.

Request	`InvoiceViewRequestModel`
Response	`ResponseModel<InvoiceViewResponseModel>`

Alt Modeller

BillingReference

Mükerrer/iade ve ÖKC referansı bu model üzerinden taşınır (BillingReferenceRequestModel).

Alan	Tip	Açıklama
`InvoiceDocumentReference`	object	Mükerrer/iade — `InvoiceTypeCode` IADE/TEVKIFATIADE/YTBIADE/YTBTEVKIFATIADE ise zorunlu; `DocumentTypeCode=IADE`, `Id` tam 16 karakter olmalı, aynı istekte tekrarlanan `Id` mükerrer sayılır
`AdditionalDocumentReference`	object	ÖKC fiş bilgisi — `DocumentTypeCode=OKCBF` ile tetiklenir; bu durumda `DocumentType=OKCBilgiFisi`, `Id`, `IssueDate`, `DocumentDescription[]`, `Attachment.ExternalReference` (string), `IssuerParty.EndpointId` ve `ValidityPeriod.StartDate` (=`IssueDate` ile aynı gün) hepsi zorunlu

InternetPayment

İnternet satışı bilgisi (InternetPaymentRequestModel) — yalnızca JSON (AddOutgoingInvoice) veya platformun düz XML modeli (AddOutgoingInvoiceByXml) ile gönderilebilir; gerçek UBL Invoice belgesinde (AddOutgoingInvoiceByUbl) karşılığı yoktur (bkz. Request → UBL XML Mapping).

Alan	Tip	Açıklama
`WebAdresi`	string	Zorunlu, en az 2 karakter (`INV0043`/`INV0263`)
`OdemeSekli`	string	GİB kod listesinde tanımlı olmalı (`INV0168`); `ODEMEARACISI` ise `OdemeAracisiAdi`, `DIGER` ise `OdemeSekliAciklama` ek zorunlu olur
`OdemeTarihi`	DateTime	Zorunlu (`INV0038`)
`GonderiTasiyanVknTckn` / `GonderiTasiyanUnvan`	string	İkisi de zorunlu (`INV0041`/`INV0040`)
`GonderimTarihi`	DateTime	Zorunlu (`INV0039`)
`Gonderilen`	string	Opsiyonel

WithholdingTaxTotal

Tevkifat bilgisi — belge seviyesinde doldurulabilen bir dizidir; yalnızca InvoiceTypeCode TEVKIFAT/YTBTEVKIFAT/IADE/YTBIADE/SGK/SARJ/SARJANLIK olduğunda kabul edilir.

Alan	Tip	Açıklama
`TaxAmount`	decimal	Toplam tevkifat tutarı
`TaxSubtotal[].TaxableAmount`	decimal	Tevkifata tabi matrah
`TaxSubtotal[].Percent`	decimal	Tevkifat oranı (%) — platformun tanımlı kod/oran eşleşmelerinden biri olmalı, aksi hâlde "Uyumsuz vergi tipi yüzdesi" hatası döner
`TaxSubtotal[].TaxCategory.TaxScheme.TaxTypeCode`	string	Tevkifat kodu (örn. `0003` GV STOPAJI)

TEKNOLOJIDESTEK

Yalnızca ProfileId=EARSIVFATURA ile birlikte geçerlidir. Alıcı PartyIdentifications içinde SchemeId=TCKN ile gönderilmeli; her InvoiceLine.Item.AdditionalItemIdentification, SchemeId'si TELEFON veya TABLET_PC olan en az bir kayıt içermelidir.

Enum Değerleri

API modellerinde kullanılan sabit değerler burada kısa bağlamıyla yer alır; ayrıntılı liste Teknik Referans sayfasındadır.

Enum	Bu rehberde geçerli değer
`InvoiceProfile`	`EARSIVFATURA`
`DocumentObjectionType`	`KEP`, `NOTER`, `TELGRAF`, `TAAHHUTLU_MEKTUP`
`EArchiveMailStatus`	`1`=Mail Gönderilmedi, `2`=Mail Gönderildi

Response — Belge Detay

GetOutgoingInvoice yanıtındaki (OutgoingInvoiceResponseModel) başlıca alanlar:

Alan	Tip	Açıklama
`Ettn`	string	Belge ETTN'i
`InvoiceNumber`	string	Belge no
`ProfileId`	string	`EARSIVFATURA`
`EArchiveMailTo`	string	e-Posta bildirim adresi (varsa)
`PayableAmount`	decimal	Ödenecek tutar

Başarı kararı: Ekleme/güncelleme yanıtlarında başarı ResponseModel.Data.HasError=false üzerinden değerlendirilmelidir; HTTP çağrısının tamamlanmış olması yeterli değildir.

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

{
  "RefreshToken": "",
  "Data": {
    "HasError": false,
    "Errors": [],
    "InvoiceNumber": "FGH2026000000001",
    "Ettn": "7dc52246-5750-496e-8bf2-bd27bc0764dc",
    "PdfUrl": "https://.../FGH2026000000001.pdf",
    "XmlUrl": "https://.../FGH2026000000001.xml"
  }
}

Alıcı uygunluk hatası yanıtı

{
  "RefreshToken": "",
  "Data": {
    "HasError": true,
    "Errors": [
      { "ErrorCode": "INV0221", "ErrorMessage": "Alıcı bilgisindeki VKN GİB e-Fatura mükelleflerinde kayıtlı olduğundan e-Arşiv Fatura kesilemez." }
    ],
    "InvoiceNumber": null,
    "Ettn": null,
    "PdfUrl": null,
    "XmlUrl": null
  }
}