API

Entegratör API Endpoint Referansı

Doğrudan ERP/API entegrasyonunda kullanılan kimlik, oluşturma, güncelleme, sorgulama, iptal ve belge endpointleri.

Kimlik doğrulama: /api/Account/Token dışındaki tüm entegratör çağrılarında VbtAuthorization header’ı gönderilmelidir. Yanıttaki RefreshToken doluysa bir sonraki çağrıdan önce saklanmalıdır.

Kimlik Doğrulama

POST/api/Account/Token

Kullanıcı, firma ve kanal bağlamı için API oturum tokenı üretir.

Request	`TokenRequestModel` — `Email`, `Password`, `FirmId`, `ChannelCode`
Response	`TokenResponseModel`; sonraki çağrılarda kullanılacak token
Başarı kararı	Token alanı boş değilse oturum kullanılabilir.

Token request örneği

{
  "Email": "entegrasyon@example.com",
  "Password": "********"
}

GET/api/Account/LogOut

Geçerli API oturumunu sonlandırır.

Header	`VbtAuthorization`
Response	`ResponseModel<bool>`
Kullanım	Oturum kapatıldığında saklanan token temizlenir.

Alan Zorunluluk Matrisi

SmmRequestModel oluşturma, güncelleme ve önizleme için ortak modeldir. Zorunluluk, işlem ve senaryoya göre aşağıdaki biçimde yorumlanmalıdır.

Alan	Tip	Oluşturma	Güncelleme	Kural
`Id`	int	—	Z	Mevcut kayıt kimliği
`UUId`	string	—	Z	Mevcut belge UUID/ETTN değeri
`SmmExternalId`	string	Z	Z	Firma altında dış sistem referansı
`IssueDate`	DateTime	Z	Z	ISO 8601 tarih-zaman
`DocumentCurrencyCode`	string	Z	Z	ISO 4217 para birimi
`CalculationRate`	decimal	Ş	Ş	TRY dışındaki belgede sıfırdan büyük; TRY için `1`
`GonderimSekli`	string	İ	İ	`Kagit` veya `Elektronik`; teslim davranışının açık olması için gönderilmesi önerilir.
`Alici`	object	Z	Z	Kimlik tipine uygun kişi/kurum ve adres bilgileri
`MalHizmetler`	array	Z	Z	En az bir hizmet satırı
Belge toplamları	decimal	Z	Z	Satır toplamlarıyla uyumlu
`EArchiveMailTo`	string	Ş	Ş	Elektronik teslimde kullanılacak adresler; çoklu değerler `;` ile ayrılır.
`QrCode`, `FirmLogo`	string	Opsiyonel	Opsiyonel	Belge görünümüne yönelik içerik
`ChannelCode`	string	Önerilir	Önerilir	Belgenin geldiği kanal; token bağlamıyla uyumlu olmalıdır.

Ekleme

POST/api/Smm/AddOutgoingSmm

Yeni e-SMM oluşturur; belge PDF’i aynı işlem sırasında üretilip imzalanır.

Ön koşul	Geçerli token, benzersiz `SmmExternalId`, tam alıcı/adres, en az bir hizmet satırı ve tutarlı toplamlar
Request	`SmmRequestModel`
Response	`ResponseModel<OutgoingAddSmmReponseModel>` — `Data.{ HasError, Errors, SmmNumber, UUId }`
Başarı kararı	`Data.HasError = false`; belge numarası ve UUID saklanır.

Zaman aşımı: Yanıt alınamadıysa aynı ekonomik işlemi yeni dış referansla tekrar göndermeyin. Önce GetOutgoingSmmList üzerinden SmmExternalId ile uzlaştırın.

POST/api/Smm/PreviewOutgoingSmm

Belgeyi kaydetmeden taslak PDF önizlemesi üretir.

Request	`SmmRequestModel`
Response	`OutgoingSmmPreviewResponseModel.SmmPdfFileBytes` ve iş sonucu
Not	Önizleme belge numarası veya kalıcı kayıt oluştuğu anlamına gelmez.

Güncelleme

POST/api/Smm/UpdateOutgoingSmm

Mevcut e-SMM’yi tam güncel modelle değiştirir ve imzalı PDF çıktısını yeniden üretir.

Ön koşul	Belge önce detay endpointinden okunmalı; request içinde mevcut `Id` ve `UUId` bulunmalıdır.
Request	`SmmRequestModel`; yalnız değişen alanlar değil tam belge modeli
Response	`Data.{ HasError, Errors, SmmNumber, UUId }`
Başarı kararı	`Data.HasError = false`; yeni çıktı istenirse PDF endpointinden alınır.

İptal

POST/api/Smm/CancelOutgoingSmm

UUID ile belirtilen e-SMM’yi iptal eder.

Request	`SmmCancelRequestModel` — `{ "UUId": "6b60c576-7ed9-4bf1-9f90-3c97747b7470" }`
Response	`ResponseModel<bool>`
Başarı kararı	`Data = true`
Sonraki adım	ERP kaydı iptal durumuna alınır; yeniden düzenleme yeni dış referansla yapılır.

{
  "UUId": "6b60c576-7ed9-4bf1-9f90-3c97747b7470"
}

Sorgulama & Görüntüleme

GET/api/Smm/GetOutgoingSmm?id={uuid}

UUID ile tek belgenin başlık, taraf, hizmet, vergi ve toplam detayını getirir.

Parametre	`id` — belge UUID/ETTN değeri
Response	`ResponseModel<OutgoingSmmReponseModel>`
Kullanım	Güncelleme öncesi güncel modeli okuma ve sonuç uzlaştırma

POST/api/Smm/GetOutgoingSmmList

Entegrasyon sorguları için sayfalı e-SMM özet listesini getirir.

Request	`SearchRequestModel<OutgoingSmmGetUiRequestModel>` — `Query`, `Skip`, `Take`, `OrderByName`, `OrderByType`
Filtreler	`UUId`, `VknTckn`, `Unvan`, `IssueDate`, `SmmNumber`, `SmmExternalId`, durum ve e-posta alanları
Response	`SearchResponseModel<OutgoingSmmSummaryResponseModel>`
Sayfalama	`Take` 0–100 aralığında olmalıdır.

Dış referansla liste sorgusu

{
  "Query": {
    "SmmExternalId": "ERP-SMM-2026-00001"
  },
  "Skip": 0,
  "Take": 20,
  "OrderByName": "IssueDate",
  "OrderByType": "DESC"
}

POST/api/Smm/GetOutgoingSmmPdf

Bir veya daha fazla e-SMM’nin PDF çıktısını getirir.

Request	`SmmPdfRequestModel` — `Ettns[]`, opsiyonel `DisplayPdf` ve `FirmId`
Response	`OutgoingSmmPdfResponseModel.SmmPdfFileBytes` — JSON içinde base64 olarak taşınır.
Kullanım	Arşivleme, kullanıcıya gösterim veya dosyaya yazma

{
  "Ettns": ["6b60c576-7ed9-4bf1-9f90-3c97747b7470"],
  "DisplayPdf": true
}

POST/api/Smm/GetOutgoingSmmDocumentPackage

Seçilen belge için Portal görüntüleme/indirme senaryosunda kullanılan belge paketini döner.

Request	`GlobalDocumentPreviewRequestModel`
Response	`DocumentPreviewResponseModel`; dosya içeriği ve görüntüleme bilgileri
Tercih	ERP yalnız PDF byte dizisine ihtiyaç duyuyorsa `GetOutgoingSmmPdf` daha doğrudan sözleşmedir.

Alt Modeller

SmmRequestModel

Model, belge başlığı ve toplamlarını taşır; alıcı, hizmet, vergi ve kur alt modelleri aşağıdaki bölümlerde ayrıştırılmıştır.

Alan	Tip	İş anlamı	Not
`LocationCode`	string	Belgenin düzenlendiği lokasyon	ERP şube/lokasyon koduyla eşleştirilebilir.
`IssueDate`	DateTime	Düzenleme tarih-zamanı	ISO 8601 gönderilmesi önerilir.
`BelgeZamanSpecified`	bool	Zaman bilgisinin ayrıca belirtildiğini gösterir.	Tarih-zaman kullanan entegrasyonlarda tutarlı gönderilir.
`UUId`	string	Belge UUID/ETTN	Güncellemede kullanılır; oluşturmada VBT üretir.
`SmmNumber`	string	16 karakterli belge numarası	Oluşturmada VBT üretir.
`FileName`	string	Belge dosya adı	VBT tarafından çıktı kaydında üretilir; oluşturma girdisi olarak kullanılmaz.
`DocumentCurrencyCode`	string	Belge para birimi	ISO 4217
`CalculationRate`	decimal	TRY karşılığı kur	TRY dışındaki belgede zorunlu
`Alici`	object	Hizmeti alan kişi/kurum	Kimlik ve adres
`Gonderen`	object	Serbest meslek erbabı	VBT firma kaydından tamamlanır.
`MalHizmetler`	array	Hizmet satırları	Satır toplamları üst toplamla eşleşir.
`BaslikVergi`	object	Belge düzeyi vergi/tevkifat grubu	Vergi ve tevkifat listeleri
`Aciklamalar`	string[]	Belge notları	Birden fazla açıklama gönderilebilir.
`TotalAmount`	decimal	Brüt hizmet toplamı	Satır brüt toplamı
`HesaplananKdv`	decimal	Hesaplanan KDV	KDV satır toplamı
`StopajOran`	int	Belge stopaj oranı	0–100
`TaxStopajTotalAmount`	decimal	Toplam stopaj	Brüt üzerinden hesaplanır.
`TevkifatOran`	int	Belge tevkifat oranı	0–100
`TevkifatKodu`	int	Belge tevkifat kodu	Senaryoya uygun kod
`WithholdingTaxTotalAmount`	decimal	Toplam KDV tevkifatı	Hesaplanan KDV üzerinden
`TaxKdvTotalAmount`	decimal	Tevkifat sonrası KDV	Ödenecek KDV
`NetUcret`	decimal	Stopaj sonrası net ücret	Brüt − stopaj
`PayableAmount`	decimal	Nihai tahsilat/ödeme	Net ücret + ödenecek KDV
`ToplamVergi`	decimal	Belge vergi toplamı	Vergi modeliyle uyumlu
`EArchiveMailTo`	string	Elektronik teslim adresi	Çoklu adresler `;` ile ayrılır.
`YaziIle`	string	Toplamın yazıyla gösterimi	Belge görünümünde kullanılır.
`SmmExternalId`	string	ERP dış referansı	Yeni oluşturma için benzersiz
`ChannelCode`	string	Kaynak kanal	Örn. `ERP`
`Kur`	object	TRY karşılığı toplamlar	Dövizli senaryolarda kullanılır.

Alici

Alan	Tip	VKN alıcı	TCKN alıcı
`VknTckn`	string	10 hane	11 hane
`Unvan`	string	Zorunlu	Kullanılmaz
`Ad`, `Soyad`	string	Kullanılmaz	İkisi de zorunlu
`VergiDaire`	string	Zorunlu	Kullanılmaz
`Adres`	object	Zorunlu	Zorunlu

AliciAdres

Alan grubu	Alanlar	Kural
Zorunlu çekirdek	`Ulke`, `Semt`, `Sehir`	Ülke, ilçe/semt ve şehir doldurulur.
Açık adres	`Mahalle`, `CaddeSokak`, `BinaAd`, `BinaNo`, `KapiNo`, `KasabaKoy`, `PostaKod`	Alıcıyı tanımlayacak yeterlilikte gönderilir.
İletişim	`Telefon`, `Telefax`	Varsa gönderilir.

MalHizmet

Alan grubu	Alanlar	İş anlamı
Kimlik	`LineId`, `Id`, `MalHizmetAd`	Satır sırası, dış/satır referansı ve hizmet açıklaması
Brüt ve KDV	`TotalAmount`, `KdvOran`, `HesaplananKdv`	Satır hizmet bedeli ve hesaplanan KDV
Stopaj	`StopajOran`, `TaxStopajTotalAmount`, `NetUcret`	Brüt üzerinden gelir vergisi kesintisi
Tevkifat	`TevkifatOran`, `TevkifatKodu`, `WithholdingTaxTotalAmount`, `TaxKdvTotalAmount`	KDV üzerinden tevkifat ve kalan KDV
Sonuç	`PayableAmount`, `ToplamVergi`, `KalemVergi`	Satır nihai tutarı ve vergi ayrıntısı

VergiGrup, Vergi ve Tevkifat

Model	Alanlar	Kullanım
`VergiGrup`	`Vergiler[]`, `Tevkifatlar[]`, `ToplamVergi`	Kalem veya belge düzeyinde vergi/kesinti ayrıntıları
`Vergi`	`Matrah`, `VergiTutar`, `VergiOran`, `VergiOranVarMi`, `VergiKodu`	Vergi matrahı, oranı, tutarı ve kodu
`Tevkifat`	`TevkifatKodu`, `TevkifatTutar`, `TevkifatOran`	Tevkifat kodu, oranı ve tutarı

Kur

Dövizli belgede toplamların TRY karşılığını taşır: TotalAmount, NetUcret, HesaplananKdv, TaxStopajTotalAmount, WithholdingTaxTotalAmount, TaxKdvTotalAmount ve PayableAmount.

Enum Değerleri

Alan	Değer	Anlam
`OutgoingSmmStatus`	`PdfCreated`	Belge ve PDF çıktısı oluşturuldu
`OutgoingSmmStatus`	`Signed`	Belge imzalı duruma ulaştı
`GonderimSekli`	`Kagit` / `Elektronik`	Teslim şekli

Response — Belge Detay

Endpoint	`Data` modeli	Kritik alanlar
Oluşturma	`OutgoingAddSmmReponseModel`	`HasError`, `Errors[]`, `SmmNumber`, `UUId`
Güncelleme	`OutgoingUpdateSmmResponseModel`	Aynı iş sonucu ve belge kimlikleri
Detay	`OutgoingSmmReponseModel`	Başlık, taraf, satır, vergi ve toplam modeli
Liste	`SearchResponseModel<OutgoingSmmSummaryResponseModel>`	UUID, alıcı, tarih, tutarlar, e-posta, belge/rapor/iptal durumları
PDF	`OutgoingSmmPdfResponseModel`	`SmmPdfFileBytes`

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

{
  "RefreshToken": "",
  "Data": {
    "HasError": false,
    "Errors": [],
    "SmmNumber": "SMM2026000000001",
    "UUId": "6b60c576-7ed9-4bf1-9f90-3c97747b7470"
  }
}

Başarı kararı: Data.HasError = false olmalı; numara ve UUID aynı Data nesnesinden alınmalıdır.

İçerik doğrulama yanıtı

{
  "RefreshToken": "",
  "Data": {
    "HasError": true,
    "Errors": [
      {
        "ErrorCode": "SMM010",
        "ErrorMessage": "Para Birimi TRY olmadığı durumda döviz kuru zorunludur."
      }
    ],
    "SmmNumber": null,
    "UUId": null
  }
}

Başarısız kabul: HasError = true iken belge oluşturulmuş kabul edilmez. Hata listesi tamamı okunmalı, veri düzeltilmeli ve mükerrerlik kontrolünden sonra tekrar gönderilmelidir.