Entegratör API Endpoint Referansı

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

https://edonusumtestgpapi.vbt.com.tr/swagger/ui/index

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.

Alan Zorunluluk Matrisi

Request modeli, zorunlu alanlar ile senaryoya bağlı alanları birlikte taşır. Aşağıdaki matris GİB belge sözleşmesini gösterir. VerificationInfo ve VerificationProvider doğrudan entegrasyonlarda eksiksiz gönderilmelidir.

Z Zorunlu · O Opsiyonel · Ş Şartlı

Ekleme

Yeni e-Gider Pusulası oluşturma çağrıları, belge içeriğini, doğrulama bilgisini ve senaryo detaylarını platforma teslim eder.

{
  "ExpenseVoucherExternalId": "ERP-GP-2026-145",
  "FileBytes": "BASE64_ENCODED_UBL_XML",
  "IsZipped": false,
  "IsSigned": false,
  "EArchiveMailTo": "muhasebe@example.com"
}

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.

{
  "ExpenseVoucherExternalId": "ERP-GP-2026-145",
  "FileBytes": "BASE64_ENCODED_CURRENT_UBL_XML_OR_ZIP",
  "IsZipped": true,
  "IsSigned": false,
  "EArchiveMailTo": "muhasebe@example.com"
}

İptal

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

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.

Kargo Şirketi

Kargo iadelerinde kullanılacak şirket bilgisi platform referanslarından seçilir; bu uç, geçerli kargo kayıtlarını entegrasyon tarafına açar.

Alt Modeller

Ekleme ve güncelleme çağrılarında geçen doğrulama, vekalet, iade ve kargo alt modelleri burada tek başlık altında toplanır.

VerificationProvider

SMS veya iade kodu gönderimi için kullanılan üçüncü parti doğrulama sağlayıcısının bilgileri. Entegratörün adı değil, doğrulama hizmetini sağlayan uygulamanın adı ve VKN'si yazılır. UBL'de AccountingSupplierParty/Party/Contact/OtherCommunication altına, GİB raporunda operatorUygulamaBilgi alanına taşınır. Doğrudan entegrasyonlarda eksiksiz gönderilmelidir.

VerificationInfo

Muhataba iletilen doğrulama bilgisi — SMS kodu veya iade kodu ile bu kodun ilişkilendirildiği telefon. Doğrudan entegrasyonlarda VerificationProvider ile birlikte eksiksiz gönderilmelidir. UBL'de AccountingCustomerParty/Party/Contact altına yazılır (vekalet varsa BuyerCustomerParty/Party/Contact); GİB raporunda aliciBilgileri/bilgiDetay alanına yansır.

DelegateReceiver (doluysa 3 alan zorunlu)

Vekil kişi bilgisi — iade edilecek ürünü orijinal alıcı yerine teslim eden kişi. Yalnızca IADE belgelerinde kullanılır. Kimlik tipi, kimlik değeri ve ad birlikte gönderilmelidir. Doğrulama kodu, tipi ve telefon bu modelde tekrarlanmaz; ayrı VerificationInfo modelinde taşınır.

ReturnedDocumentReference (IADE'de zorunlu)

İadeye konu olan orijinal belgenin referansı — hangi belgeye karşılık iade yapıldığını tanımlar. IADE belgelerinde zorunlu, SATIS'te kullanılmaz. UBL'de BillingReference/InvoiceDocumentReference olarak, GİB raporunda iadeDetay alanına yazılır. BELGESIZ iadede DocumentNumber boş bırakılabilir ancak alıcının gerçek kimliği zorunludur.

CargoCompany (kargo iadede zorunlu)

Kargo ile yapılan iadelerde kullanılan kargo şirketi bilgisi. Entegratör bu modeli doğrudan doldurmaz — sadece CargoCompanyCode alanına kargo firmasının kodunu yazar. Platform, bu koda karşılık gelen aşağıdaki bilgileri tamamlar ve UBL'de Delivery/DeliveryParty alanına yazar:

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

Belge detay response'u, teknik durum bilgisiyle iş verisini birlikte döner; alan açıklamaları bu ayrımı görünür kılar.

Belge Detay ve Liste Yanıtları

Belge detay ve liste yanıtlarına OutgoingExpenseVoucherStatusForUser alanını içerir. Bu alan SMS ve iade kodu bekleme adımlarını kullanıcıya açıklar; OutgoingExpenseVoucherStatus teknik belge durumunu taşımaya devam eder.

Yanıt Örnekleri

Oluşturma ve güncelleme endpointlerinde iş sonucu Data.HasError üzerinden değerlendirilmelidir. HTTP çağrısının tamamlanması tek başına belgenin kabul edildiği anlamına gelmez.

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

{
  "RefreshToken": "",
  "Data": {
    "HasError": false,
    "Errors": [],
    "ExpenseVoucherNumber": "GIP2026000000145",
    "Ettn": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Başarısız oluşturma yanıtı

Doğrudan entegrasyonda doğrulama alanlarından biri eksik veya uyumsuz gönderilirse oluşturma ya da güncelleme sonucu aşağıdaki biçimde döner.

{
  "RefreshToken": "",
  "Data": {
    "HasError": true,
    "Errors": [
      {
        "ErrorCode": "SCM0002",
        "ErrorMessage": "VerificationProvider.Vkn zorunlu bir elemandır boş geçilemez!"
      }
    ],
    "ExpenseVoucherNumber": null,
    "Ettn": null
  }
}

Portal doğrulama endpointi hata yanıtı

Portal işlemleri mevcut API hata zarfını kullanır. Entegrasyon bu endpointleri çağırmamalı; hata ayrımında HTTP durumuyla birlikte ErrorCode dikkate alınmalıdır. Portal endpointlerinin tam sözleşmesi Portal API Endpoint Referansı sayfasındadır.

{
  "Type": 2,
  "Type_Desc": "Business",
  "ErrorCode": "EGP0072",
  "Message": "Telefon numarası geçerli formatta değildir.",
  "Detail": null
}