e-Müstahsil Makbuzu

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.

RequestTokenRequestModel — { Email, Password }
ResponseTokenResponseModel — { 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.

AlanZorunlulukNot
CreditNoteExternalIdZDış sistem referansı, benzersiz olmalı
IssueDateZGelecek tarih olamaz, saat bileşeni dolu olmalı
AccountingSupplierPartyZMakbuzu düzenleyen alıcı firma bilgisi
AccountingCustomerPartyZÜretici/çiftçi bilgisi; SMS zorunlu olduğunda veya erken kullanımda SMS paketi gönderildiğinde 11 haneli TCKN ve Person ad/soyadı zorunludur
CreditNoteLineZEn az 1 kalem
LegalMonetaryTotalZSatır toplamı, KDV hariç/dahil ve ödenecek tutar
TaxTotalZKDV ve belge seviyesinde izlenen vergi/kesinti alt toplamları
WithholdingTaxTotalOUBL tevkifat alanı kullanılacaksa doldurulur
UUIdOBoş 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
CopyIndicatorOBelirtilmezse false kabul edilir
VerificationMethodŞİşlem tarihi ve IssueDate 30 Haziran 2027 ve sonrasındayken doğrudan JSON/UBL entegrasyonlarında SMS zorunludur
VerificationInfoŞDoğrudan entegrasyonda doğrulanmış Code ve kodun gönderildiği PhoneNumber birlikte gönderilir
VerificationProviderŞSMS'i fiilen gönderen sağlayıcının ApplicationName ve 10 haneli Vkn bilgisi birlikte gönderilir

Z Zorunlu · O Opsiyonel · Ş Şartlı

SMS kanal sınırı: Doğrudan JSON veya hazır UBL entegrasyonunda SMS'i entegratör gönderir, kodu kendi uygulamasında doğrular ve tam doğrulama verisini Add/Update requestinde iletir. Portalın SendCreditNoteSmsCode ve CompleteCreditNoteSmsVerification endpointleri dış entegrasyon için değildir. Portalda kullanıcı gönderimi ekrandan başlatır; SMS gönderimi ve kod doğrulaması VBT Platform tarafından yürütülür.
Preview farkı: PreviewOutgoingCreditNote belgeyi kaydetmediği ve imza sürecine sokmadığı için SMS doğrulama alanlarını zorunlu tutmaz. Preview başarısı, 30 Haziran 2027 ve sonrası tarihli gerçek Add/Update requestinin doğrulama alanları olmadan kabul edileceği anlamına gelmez.

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.

RequestOutgoingCreditNoteRequestModel
ResponseOutgoingCreditNoteAddResponseModel — { CreditNoteNumber, Ettn, HasError, Errors[] }
POST/api/CreditNoteApi/AddOutgoingCreditNoteByUbl

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

RequestCreditNoteUblRequestModel
ResponseOutgoingCreditNoteAddResponseModel
POST/api/CreditNoteApi/AddOutgoingCreditNoteByExcel

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

RequestExcelFileRequestModel
ResponseList<OutgoingCreditNoteAddExcelResponseModel> — satır başına ayrı sonuç
POST/api/CreditNoteApi/PreviewOutgoingCreditNote

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

RequestOutgoingCreditNoteRequestModel
ResponseOutgoingCreditNotePreviewResponseModel — { 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.

RequestOutgoingCreditNoteRequestModel (Id veya UUId zorunlu)
ResponseOutgoingCreditNoteUpdateResponseModel — { CreditNoteNumber, Ettn, HasError, Errors[] }
POST/api/CreditNoteApi/UpdateOutgoingCreditNoteByUbl

Mevcut bir makbuzu UBL XML ile günceller.

RequestCreditNoteUblRequestModel
ResponseOutgoingCreditNoteUpdateResponseModel — { CreditNoteNumber, Ettn, HasError, Errors[] }
İmzalı UBL sorumluluğu: AddOutgoingCreditNoteByUbl veya UpdateOutgoingCreditNoteByUbl çağrısında IsSigned = true gönderildiğinde XML değiştirilmeden saklanır. Telefon ve diğer SMS doğrulama alanları imzadan önce nihai ve GİB'e uygun olmalıdır; canonical olmayan telefon EMM0061 ile reddedilir. Düzeltme gerekiyorsa UBL yeniden imzalanarak gönderilmelidir. IsSigned kriptografik doğrulama sonucu değil çağıranın beyanıdır ve yalnız imzası entegratör tarafından doğrulanmış UBL için true kullanılmalıdır.

İ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şulBelge Signed durumunda olmalı
RequestCreditNoteCancelRequestModel — { Id, CreditNoteExternalId, Ettn, CreditNoteNumber, EArchiveStatus, EArchiveCancelDescription }
Responsebool

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.

Requestid — string, ETTN/GUID
ResponseOutgoingCreditNoteResponseModel
POST/api/CreditNoteApi/GetCreditNoteGridList

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

RequestSearchUIRequestModel<OutgoingCreditNoteListRequestModel>
ResponseSearchResponseModel<OutgoingCreditNoteGridResponseModel>
POST/api/CreditNoteApi/GetGlobalSearchCreditNoteList

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

RequestSearchUIRequestModel<GlobalSearchRequestModel>
ResponseSearchResponseModel<OutgoingCreditNoteGridResponseModel>
POST/api/CreditNoteApi/GetOutgoingCreditNoteList

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

RequestSearchRequestModel<OutgoingCreditNoteGetRequestModel>
ResponseSearchResponseModel<OutgoingCreditNoteSummaryResponseModel>
POST/api/CreditNoteApi/GetOutgoingCreditNoteLog

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

RequestSearchRequestModel<CreditNoteLogRequestModel>
ResponseSearchResponseModel<CreditNoteLogResponseModel>
POST/api/CreditNoteApi/GetOutgoingCreditNoteView

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

RequestCreditNoteViewRequestModel — { Ettn, IsRead }
ResponseCreditNoteViewResponseModel — { CreditNoteHtmlView }
POST/api/CreditNoteApi/OutgoingCreditNoteIsRead

Belgeyi okundu olarak işaretler.

RequestCreditNoteViewRequestModel — { Ettn, IsRead }
Responsebool
POST/api/CreditNoteApi/GetOutgoingCreditNotePdf

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

RequestCreditNotePdfRequestModel — { CreditNoteEttns: ["ettn1", "ettn2"...] }
ResponseCreditNotePdfResponseModel — { CreditNotePdfFileBytes } (base64)
POST/api/CreditNoteApi/GetOutgoingCreditNoteDocumentPackage

Belge paketini (XML/PDF) getirir.

RequestGlobalDocumentPreviewRequestModel
ResponseDocumentPreviewResponseModel
POST/api/CreditNoteApi/GetOutgoingCreditNoteXmlList

Ham UBL XML listesini getirir.

RequestOutgoingCreditNoteXmlRequestModel
ResponseOutgoingCreditNoteXmlResponseModel
POST/api/CreditNoteApi/GetOutgingCreditNotePrefixList

Belge numarası önek listesini getirir.

RequestNumberPrefixRequestModel
ResponseIList<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.

AlanTipAçıklama
InvoiceLineExternalIdstringSatırın dış sistemdeki referansı
CreditedQuantityobjectMiktar + birim kodu
LineExtensionAmountdecimalSatır toplamı
ItemobjectÜrün/hizmet adı
PricedecimalBirim fiyat
TaxTotalobjectSatır vergi/kesinti bilgisi
WithholdingTaxTotalarraySatır tevkifat bilgisi (varsa)

SMS Doğrulama Modelleri

Doğrudan entegrasyon requestlerinde yöntem ve dört alt alan tek doğrulama kaydı olarak taşınır. Geçiş öncesinde alanların tamamı boş olabilir veya tamamı birlikte gönderilebilir; kısmi paket validasyon hatasıyla reddedilir. Planlanan sürümde tam SMS paketi UBL ve rapora yazılır. SMS kullanılmadığında raporda kod, telefon ve operatör bölümü oluşturulmaz.

AlanTip / DeğerAçıklama
VerificationMethodSMSe-Müstahsil Makbuzu için desteklenen tek doğrulama yöntemi
VerificationInfo.CodestringÜreticinin doğruladığı 4–6 karakterli kod; boşluk veya kontrol karakteri içermez
VerificationInfo.PhoneNumberstringKodun gönderildiği Türkiye mobil numarası
VerificationProvider.ApplicationNamestringSMS'i fiilen gönderen hizmet sağlayıcının resmî adı
VerificationProvider.Vkn10 haneSMS sağlayıcısının yalnız rakamlardan oluşan VKN'si

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.

TaxTypeCodeNameKullanım
0003GV STOPAJIGelir vergisi stopajı
8001BORSA TES.ÜC.Borsa tescil kesintisi
SGK_PRIMSGK PRIM KESINTISISGK prim kesintisi
9040MERA FONUMera 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.

AlanTipAçıklama
TaxAmountdecimalToplam tevkifat tutarı
TaxSubtotal[].TaxableAmountdecimalTevkifata tabi matrah
TaxSubtotal[].TaxAmountdecimalAlt kalem tevkifat tutarı
TaxSubtotal[].PercentdecimalTevkifat oranı (%)
TaxSubtotal[].TaxCategory.TaxScheme.NamestringÖrn. GV STOPAJI
TaxSubtotal[].TaxCategory.TaxScheme.TaxTypeCodestringÖrn. 0003

Taraflar

AccountingSupplierParty makbuzu düzenleyen alıcı firmayı, AccountingCustomerParty ise üretici/çiftçiyi taşır. İki taraf aynı genel Party modelini paylaşır; kimlik değeri PartyIdentifications[].Value, kimlik türü aynı kaydın SchemeId alanıdır.

TarafSchemeIdKimlik AlanıAd Alanı
AccountingSupplierParty (makbuzu düzenleyen/alıcı firma)VKN veya TCKNPartyIdentifications[].ValuePartyName veya Person
AccountingCustomerParty (üretici/çiftçi; işlem tarihi ve IssueDate 30 Haziran 2027 ve sonrası)TCKNPartyIdentifications[].Value (11 hane)Person.FirstName + Person.FamilyName
30 Haziran 2027 kuralı: İşlem tarihi ve IssueDate birlikte yürürlük sınırına ulaştığında üretici/çiftçi, AccountingCustomerParty altında 11 haneli TCKN ve Person ad/soyadıyla gönderilmelidir. Tarihlerden biri daha erkense mevcut taraf sözleşmesi değişmez.

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.

OutgoingCreditNoteStatusForUserAnlamıKanal
WaitingForVerificationBelge kaydedildi; SMS gönderiminin kullanıcı tarafından başlatılması beklenirYalnız Portal
WaitingForSmsCodeSMS gönderildi; üreticinin kod girişi beklenirYalnız Portal
CreditNoteAndXmlCreatedDoğrulama verisi kabul edildi; belge ve XML oluşturulduDoğrudan entegrasyon veya tamamlanmış Portal doğrulaması
SignedBelge imzalandı ve gönderime hazırTüm kanallar

Response — Belge Detay

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

AlanTipAçıklama
IdintBelge Id
UUIdstringETTN
CreditNoteExternalIdstringDış sistem referansı
CreditNoteNumberstringBelge no
ProfileId / CreditNoteTypeCodestring / stringSabit: EARSIVBELGE / MUSTAHSILMAKBUZ
DocumentCurrencyCodestringPara birimi
IssueDateDateTimeDüzenleme tarihi
AccountingSupplierPartyName / AccountingSupplierVknTcknstring / stringMakbuzu düzenleyen/alıcı firma adı ve kimlik no
AccountingCustomerPartyName / AccountingCustomerVknTcknstring / stringÜretici/çiftçi adı ve kimliği; işlem tarihi ve IssueDate 30 Haziran 2027 ve sonrasındayken ad/soyad ve TCKN
PayableAmountdecimalÖdenecek tutar
TaxExclusiveAmount / TaxInclusiveAmountdecimal / decimalKDV hariç/dahil tutar
TaxTotalAmountdecimalToplam vergi/kesinti
WithholdingTaxTotalAmountdecimalToplam tevkifat
TaxTotalarrayVergi ve kesinti detayı
WithholdingTaxTotalarrayTevkifat detayı (varsa)
CreditNoteLinearrayÜrün kalemleri
OutgoingCreditNoteStatusstringBelge durumu
OutgoingCreditNoteStatusForUserstringPortal SMS bekleme adımları dahil kullanıcıya yönelik süreç durumu
VerificationMethodstringBelge detay ve geçmiş response'unda doğrulama yöntemi; grid response'unda bulunmaz
EArchiveStatusint1=Valid, 2=Cancelled
SigningTimeDateTime?İmza zamanı
EArchiveReportStatus / EArchiveReportDescriptionint / stringGİB rapor durumu ve açıklaması
EArchiveCancelDate / EArchiveCancelDescriptionDateTime? / stringİptal bilgileri (varsa)
IsRead / IsReadDatebool / DateTime?Okundu bilgisi