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/v1Kimlik 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.
VbtAuthorization header'ı gerektirir. Token almak için POST /api/Account/Token kullanın.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 | Makbuzu düzenleyen alıcı firma bilgisi |
AccountingCustomerParty | Z | Ü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 |
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 |
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ı
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.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.
Yeni bir e-Müstahsil Makbuzu oluşturur ve sisteme kaydeder.
| Request | OutgoingCreditNoteRequestModel |
| Response | OutgoingCreditNoteAddResponseModel — { CreditNoteNumber, Ettn, HasError, Errors[] } |
Hazır UBL CreditNote XML'i ile makbuz oluşturur.
| Request | CreditNoteUblRequestModel |
| Response | OutgoingCreditNoteAddResponseModel |
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ç |
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.
Mevcut bir makbuzu JSON model ile günceller.
| Request | OutgoingCreditNoteRequestModel (Id veya UUId zorunlu) |
| Response | OutgoingCreditNoteUpdateResponseModel — { CreditNoteNumber, Ettn, HasError, Errors[] } |
Mevcut bir makbuzu UBL XML ile günceller.
| Request | CreditNoteUblRequestModel |
| Response | OutgoingCreditNoteUpdateResponseModel — { CreditNoteNumber, Ettn, HasError, Errors[] } |
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.
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.
ETTN (UUId) ile tek bir makbuzun detayını getirir. Belgenin tüm alanları döner.
| Request | id — string, ETTN/GUID |
| Response | OutgoingCreditNoteResponseModel |
UI grid ekranı için sayfalanmış makbuz listesi döner.
| Request | SearchUIRequestModel<OutgoingCreditNoteListRequestModel> |
| Response | SearchResponseModel<OutgoingCreditNoteGridResponseModel> |
Global arama ekranı için makbuz listesi döner.
| Request | SearchUIRequestModel<GlobalSearchRequestModel> |
| Response | SearchResponseModel<OutgoingCreditNoteGridResponseModel> |
Makbuz özet bilgilerini içeren liste. Entegratör sorgusu için uygundur.
| Request | SearchRequestModel<OutgoingCreditNoteGetRequestModel> |
| Response | SearchResponseModel<OutgoingCreditNoteSummaryResponseModel> |
Belge üzerindeki işlem geçmişini (log kayıtlarını) listeler.
| Request | SearchRequestModel<CreditNoteLogRequestModel> |
| Response | SearchResponseModel<CreditNoteLogResponseModel> |
Belgenin HTML görüntüsünü döner (iframe içinde gösterim için).
| Request | CreditNoteViewRequestModel — { Ettn, IsRead } |
| Response | CreditNoteViewResponseModel — { CreditNoteHtmlView } |
Belgeyi okundu olarak işaretler.
| Request | CreditNoteViewRequestModel — { Ettn, IsRead } |
| Response | bool |
Belgenin PDF formatındaki görselini döner.
| Request | CreditNotePdfRequestModel — { CreditNoteEttns: ["ettn1", "ettn2"...] } |
| Response | CreditNotePdfResponseModel — { CreditNotePdfFileBytes } (base64) |
Belge paketini (XML/PDF) getirir.
| Request | GlobalDocumentPreviewRequestModel |
| Response | DocumentPreviewResponseModel |
Ham UBL XML listesini getirir.
| Request | OutgoingCreditNoteXmlRequestModel |
| Response | OutgoingCreditNoteXmlResponseModel |
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) |
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.
| Alan | Tip / Değer | Açıklama |
|---|---|---|
VerificationMethod | SMS | e-Müstahsil Makbuzu için desteklenen tek doğrulama yöntemi |
VerificationInfo.Code | string | Üreticinin doğruladığı 4–6 karakterli kod; boşluk veya kontrol karakteri içermez |
VerificationInfo.PhoneNumber | string | Kodun gönderildiği Türkiye mobil numarası |
VerificationProvider.ApplicationName | string | SMS'i fiilen gönderen hizmet sağlayıcının resmî adı |
VerificationProvider.Vkn | 10 hane | SMS 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.
| 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 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.
| Taraf | SchemeId | Kimlik Alanı | Ad Alanı |
|---|---|---|---|
AccountingSupplierParty (makbuzu düzenleyen/alıcı firma) | VKN veya TCKN | PartyIdentifications[].Value | PartyName veya Person |
AccountingCustomerParty (üretici/çiftçi; işlem tarihi ve IssueDate 30 Haziran 2027 ve sonrası) | TCKN | PartyIdentifications[].Value (11 hane) | Person.FirstName + Person.FamilyName |
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.
OutgoingCreditNoteStatusForUser | Anlamı | Kanal |
|---|---|---|
WaitingForVerification | Belge kaydedildi; SMS gönderiminin kullanıcı tarafından başlatılması beklenir | Yalnız Portal |
WaitingForSmsCode | SMS gönderildi; üreticinin kod girişi beklenir | Yalnız Portal |
CreditNoteAndXmlCreated | Doğrulama verisi kabul edildi; belge ve XML oluşturuldu | Doğrudan entegrasyon veya tamamlanmış Portal doğrulaması |
Signed | Belge imzalandı ve gönderime hazır | Tüm kanallar |
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 | Makbuzu düzenleyen/alıcı firma adı ve kimlik no |
AccountingCustomerPartyName / AccountingCustomerVknTckn | string / string | Üretici/çiftçi adı ve kimliği; işlem tarihi ve IssueDate 30 Haziran 2027 ve sonrasındayken ad/soyad ve TCKN |
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 |
OutgoingCreditNoteStatusForUser | string | Portal SMS bekleme adımları dahil kullanıcıya yönelik süreç durumu |
VerificationMethod | string | Belge detay ve geçmiş response'unda doğrulama yöntemi; grid response'unda bulunmaz |
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 |