API

Entegratör API Endpoint Referansı

Kimlik doğrulama, belge işlemleri, sorgulama, alt modeller ve response alanları.

API Endpointlerini detaylı bir şekilde incelemek için swagger dokümantasyonuna ulaşabilirsiniz

https://edonusumtestmmapi.vbt.com.tr/swagger/docs/v1

Kimlik Doğrulama

API çağrıları, firmanın yetki bağlamı ve oturum token'ı üzerinden ilerler; bu alanda kullanılacak header ve token akışı netleştirilir.

💡 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

Request modeli, zorunlu alanlar ile koşula bağlı alanları birlikte taşır; matris entegrasyon öncesi alan kapsamını netleştirir.

Alan	Zorunluluk	Not
`CreditNoteExternalId`	Z	Dış sistem referansı, benzersiz olmalı
`IssueDate`	Z	Gelecek tarih olamaz, saat bileşeni dolu olmalı
`AccountingSupplierParty`	Z	Çiftçi bilgisi
`AccountingCustomerParty`	Z	Alıcı firma bilgisi
`CreditNoteLine`	Z	En az 1 kalem
`LegalMonetaryTotal`	Z	Satır toplamı, KDV hariç/dahil ve ödenecek tutar
`TaxTotal`	Z	KDV ve belge seviyesinde izlenen vergi/kesinti alt toplamları
`WithholdingTaxTotal`	O	UBL tevkifat alanı kullanılacaksa doldurulur
`UUId`	O	Boş bırakılırsa platform tarafından üretilir
`CreditNoteNumber`	Ş	Firma ayarına (numara kaynağı ERP mi platform mu) bağlıdır: ayar ERP ise siz sağlarsınız ve formatı doğrulanır, değilse platform üretip alanın üzerine yazar
`CopyIndicator`	O	Belirtilmezse `false` kabul edilir

Z Zorunlu · O Opsiyonel · Ş Şartlı

Ekleme

Yeni makbuz 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/CreditNoteApi/AddOutgoingCreditNote

Yeni bir e-Müstahsil Makbuzu oluşturur ve sisteme kaydeder.

Request	`OutgoingCreditNoteRequestModel`
Response	`OutgoingCreditNoteAddResponseModel` — `{ CreditNoteNumber, Ettn, HasError, Errors[] }`

POST/api/CreditNoteApi/AddOutgoingCreditNoteByUbl

Hazır UBL CreditNote XML'i ile makbuz oluşturur.

Request	`CreditNoteUblRequestModel`
Response	`OutgoingCreditNoteAddResponseModel`

POST/api/CreditNoteApi/AddOutgoingCreditNoteByExcel

Excel dosyasındaki birden fazla satırı toplu olarak işler; bu modüle özgüdür.

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

POST/api/CreditNoteApi/PreviewOutgoingCreditNote

Makbuzu kaydetmeden önce önizleme yapar. Doğrulama ve format kontrollerini içerir.

Request	`OutgoingCreditNoteRequestModel`
Response	`OutgoingCreditNotePreviewResponseModel` — `{ CreditNotePdfFileBytes, HasError, Errors[] }`

Güncelleme

Güncelleme işlemleri, belge kesinleşmeden önceki düzeltme ihtiyacını karşılar; imza ve rapor durumu bu işlemin doğal sınırını belirler.

POST/api/CreditNoteApi/UpdateOutgoingCreditNote

Mevcut bir makbuzu JSON model ile günceller.

Request	`OutgoingCreditNoteRequestModel` (`Id` veya `UUId` zorunlu)
Response	`OutgoingCreditNoteUpdateResponseModel` — `{ CreditNoteNumber, Ettn, HasError, Errors[] }`

POST/api/CreditNoteApi/UpdateOutgoingCreditNoteByUbl

Mevcut bir makbuzu UBL XML ile günceller.

Request	`CreditNoteUblRequestModel`
Response	`OutgoingCreditNoteUpdateResponseModel` — `{ CreditNoteNumber, Ettn, HasError, Errors[] }`

İptal

İptal çağrısı, düzenlenmiş makbuzun durumuna göre değerlendirilir; platform yalnızca iptal için uygun belgelerde süreci başlatır.

POST/api/CreditNoteApi/CancelOutgoingCreditNote

Yalnızca Signed durumundaki bir makbuzu iptal eder.

Ön-koşul	Belge `Signed` durumunda olmalı
Request	`CreditNoteCancelRequestModel` — `{ Id, CreditNoteExternalId, Ettn, CreditNoteNumber, EArchiveStatus, EArchiveCancelDescription }`
Response	`bool`

Sorgulama & Görüntüleme

Sorgulama uçları, oluşturulmuş belgelerin durumunu, görüntüleme çıktısını ve teknik paket bilgisini aynı referans altında toplar.

GET/api/CreditNoteApi/GetOutgoingCreditNote?id={ETTN}

ETTN (UUId) ile tek bir makbuzun detayını getirir. Belgenin tüm alanları döner.

Request	`id` — string, ETTN/GUID
Response	`OutgoingCreditNoteResponseModel`

POST/api/CreditNoteApi/GetCreditNoteGridList

UI grid ekranı için sayfalanmış makbuz listesi döner.

Request	`SearchUIRequestModel<OutgoingCreditNoteListRequestModel>`
Response	`SearchResponseModel<OutgoingCreditNoteGridResponseModel>`

POST/api/CreditNoteApi/GetGlobalSearchCreditNoteList

Global arama ekranı için makbuz listesi döner.

Request	`SearchUIRequestModel<GlobalSearchRequestModel>`
Response	`SearchResponseModel<OutgoingCreditNoteGridResponseModel>`

POST/api/CreditNoteApi/GetOutgoingCreditNoteList

Makbuz özet bilgilerini içeren liste. Entegratör sorgusu için uygundur.

Request	`SearchRequestModel<OutgoingCreditNoteGetRequestModel>`
Response	`SearchResponseModel<OutgoingCreditNoteSummaryResponseModel>`

POST/api/CreditNoteApi/GetOutgoingCreditNoteLog

Belge üzerindeki işlem geçmişini (log kayıtlarını) listeler.

Request	`SearchRequestModel<CreditNoteLogRequestModel>`
Response	`SearchResponseModel<CreditNoteLogResponseModel>`

POST/api/CreditNoteApi/GetOutgoingCreditNoteView

Belgenin HTML görüntüsünü döner (iframe içinde gösterim için).

Request	`CreditNoteViewRequestModel` — `{ Ettn, IsRead }`
Response	`CreditNoteViewResponseModel` — `{ CreditNoteHtmlView }`

POST/api/CreditNoteApi/OutgoingCreditNoteIsRead

Belgeyi okundu olarak işaretler.

Request	`CreditNoteViewRequestModel` — `{ Ettn, IsRead }`
Response	`bool`

POST/api/CreditNoteApi/GetOutgoingCreditNotePdf

Belgenin PDF formatındaki görselini döner.

Request	`CreditNotePdfRequestModel` — `{ CreditNoteEttns: ["ettn1", "ettn2"...] }`
Response	`CreditNotePdfResponseModel` — `{ CreditNotePdfFileBytes }` (base64)

POST/api/CreditNoteApi/GetOutgoingCreditNoteDocumentPackage

Belge paketini (XML/PDF) getirir.

Request	`GlobalDocumentPreviewRequestModel`
Response	`DocumentPreviewResponseModel`

POST/api/CreditNoteApi/GetOutgoingCreditNoteXmlList

Ham UBL XML listesini getirir.

Request	`OutgoingCreditNoteXmlRequestModel`
Response	`OutgoingCreditNoteXmlResponseModel`

POST/api/CreditNoteApi/GetOutgingCreditNotePrefixList

Belge numarası önek listesini getirir.

Request	`NumberPrefixRequestModel`
Response	`IList<NumberPrefixResponseModel>`

Alt Modeller

Ekleme ve güncelleme çağrılarında geçen ürün kalemi, vergi/kesinti ve taraf alt modelleri burada tek başlık altında toplanır.

CreditNoteLine

Ürün kalemi bilgisi — makbuzda satın alınan her tarımsal ürün için tek bir satır oluşturulur. En az bir kalem zorunludur; birden fazla ürün aynı makbuzda ayrı satırlar olarak gönderilebilir.

Alan	Tip	Açıklama
`InvoiceLineExternalId`	string	Satırın dış sistemdeki referansı
`CreditedQuantity`	object	Miktar + birim kodu
`LineExtensionAmount`	decimal	Satır toplamı
`Item`	object	Ürün/hizmet adı
`Price`	decimal	Birim fiyat
`TaxTotal`	object	Satır vergi/kesinti bilgisi
`WithholdingTaxTotal`	array	Satır tevkifat bilgisi (varsa)

TaxTotal Kesinti Kodları

TaxTotal, standart vergi alt toplamlarının yanında e-Müstahsil Makbuzu'na özgü kesinti kodlarını da taşıyabilir. Excel ile içe aktarma ve barkod üretimi, GV stopajı, borsa tescil, SGK prim ve mera fonu tutarlarını TaxSubtotal[].TaxCategory.TaxScheme.TaxTypeCode değerinden ayrıştırır.

TaxTypeCode	Name	Kullanım
`0003`	`GV STOPAJI`	Gelir vergisi stopajı
`8001`	`BORSA TES.ÜC.`	Borsa tescil kesintisi
`SGK_PRIM`	`SGK PRIM KESINTISI`	SGK prim kesintisi
`9040`	`MERA FONU`	Mera fonu kesintisi

WithholdingTaxTotal

Tevkifat bilgisi — hem belge (OutgoingCreditNoteRequestModel.WithholdingTaxTotal) hem satır (CreditNoteLineRequestModel.WithholdingTaxTotal) seviyesinde doldurulabilen, tekrar eden bir dizidir. Bu alan kullanıldığında PayableAmount tevkifat etkisini yansıtacak şekilde hesaplanmalıdır.

Alan	Tip	Açıklama
`TaxAmount`	decimal	Toplam tevkifat tutarı
`TaxSubtotal[].TaxableAmount`	decimal	Tevkifata tabi matrah
`TaxSubtotal[].TaxAmount`	decimal	Alt kalem tevkifat tutarı
`TaxSubtotal[].Percent`	decimal	Tevkifat oranı (%)
`TaxSubtotal[].TaxCategory.TaxScheme.Name`	string	Örn. `GV STOPAJI`
`TaxSubtotal[].TaxCategory.TaxScheme.TaxTypeCode`	string	Örn. `0003`

Taraflar

AccountingSupplierParty (çiftçi) ve AccountingCustomerParty (alıcı firma) aynı genel Party modelini paylaşır; ayırt edici alan PartyIdentifications içindeki SchemeId'dir.

Taraf	SchemeId	Kimlik Alanı	Ad Alanı
`AccountingSupplierParty` (çiftçi)	`TCKN`	`PartyIdentifications[].Id`	`Person` (gerçek kişi ad/soyad)
`AccountingCustomerParty` (alıcı)	`VKN`	`PartyIdentifications[].Id`	`PartyName` (tüzel kişi unvanı)

Enum Değerleri

API modellerinde kullanılan sabit değerler burada kısa bağlamıyla yer alır; enumların business anlamı, hata kodlarıyla ilişkisi ve validasyon referansları Teknik Referans sayfasında takip edilir.

Response — Belge Detay

GetOutgoingCreditNote yanıtındaki (OutgoingCreditNoteResponseModel) başlıca alanlar:

Alan	Tip	Açıklama
`Id`	int	Belge Id
`UUId`	string	ETTN
`CreditNoteExternalId`	string	Dış sistem referansı
`CreditNoteNumber`	string	Belge no
`ProfileId` / `CreditNoteTypeCode`	string / string	Sabit: `EARSIVBELGE` / `MUSTAHSILMAKBUZ`
`DocumentCurrencyCode`	string	Para birimi
`IssueDate`	DateTime	Düzenleme tarihi
`AccountingSupplierPartyName` / `AccountingSupplierVknTckn`	string / string	Çiftçi adı ve kimlik no
`AccountingCustomerPartyName` / `AccountingCustomerVknTckn`	string / string	Alıcı firma adı ve VKN
`PayableAmount`	decimal	Ödenecek tutar
`TaxExclusiveAmount` / `TaxInclusiveAmount`	decimal / decimal	KDV hariç/dahil tutar
`TaxTotalAmount`	decimal	Toplam vergi/kesinti
`WithholdingTaxTotalAmount`	decimal	Toplam tevkifat
`TaxTotal`	array	Vergi ve kesinti detayı
`WithholdingTaxTotal`	array	Tevkifat detayı (varsa)
`CreditNoteLine`	array	Ürün kalemleri
`OutgoingCreditNoteStatus`	string	Belge durumu
`EArchiveStatus`	int	1=Valid, 2=Cancelled
`SigningTime`	DateTime?	İmza zamanı
`EArchiveReportStatus` / `EArchiveReportDescription`	int / string	GİB rapor durumu ve açıklaması
`EArchiveCancelDate` / `EArchiveCancelDescription`	DateTime? / string	İptal bilgileri (varsa)
`IsRead` / `IsReadDate`	bool / DateTime?	Okundu bilgisi