Temel kavramlar

key, toolId ve slug

Bir araç üç şekilde adreslenebilir:

Tanımlayıcı	Örnek	Kalıcılık	Ne için kullanılır
`key`	`kdv`	Kalıcı, tüm ortamlarda aynı	Entegrasyonlar. Önerilen tanımlayıcı.
`toolId`	`8410ffe8-…` (UUID)	Ortama özgü	Yalnızca `toolId` ile hesaplayan uç (`calculateTool`).
`slug`	`kdv-hesaplama`	Değişebilir, dile göre farklı	Web sitesindeki sayfa adresi.

key kuralı: küçük harf, rakam ve tire; 2–64 karakter (^[a-z0-9]+(-[a-z0-9]+)*$). Listeler ve arama sonuçları her kayıtta key döner. Tüm anahtarlar araç kataloğunda listelidir.

Diller

locale parametresi tr veya en olabilir. Bir araç istenen dilde yayınlanmamışsa 404 NOT_FOUND döner; başka dile otomatik düşülmez. Araç tanımındaki alternates alanı aracın hangi dillerde ve hangi adreslerde bulunduğunu gösterir.

Ondalıklar string’dir

Para ve oran değerleri string olarak gönderilir ve alınır: "1234.56". Nokta ondalık ayırıcıdır, binlik ayırıcı yoktur. JSON sayı (1234.56) gönderirseniz istek 422 VALIDATION_ERROR ile reddedilir.

Sonuçlar da string döner ve her zaman alanın scale değeri kadar ondalık hane içerir ("1200.00"). Bunları kendi tarafınızda kayan noktaya çevirmeden biçimlendirin; hesaplamalar sunucuda ondalık aritmetikle yapılır, kayan nokta hatası oluşmaz.

Tür	Gönderim	Örnek
`decimal`	string	`"1234.56"`
`date`	string, `YYYY-MM-DD`	`"2026-01-15"`
`boolean`	JSON `true` / `false`	`true`
`enum`	string, tanımdaki `values` değerlerinden biri	`"exclusive"`

asOf: oran tarihi

Vergi oranları, istisna tutarları ve limitler zamanla değişir. Her hesaplama, asOf tarihinde yürürlükte olan oranlarla yapılır. Göndermezseniz bugün kullanılır (Europe/Istanbul). Geçmiş bir tarihle hesaplamak için gönderin:

{ "asOf": "2023-01-15", "inputs": { "amount": "1000", "mode": "exclusive", "vatRateOption": "standard" } }

O tarihte yürürlükte oran yoksa 422 RATE_UNAVAILABLE döner (details.rates, details.asOf). Yanıttaki meta.rates, kullanılan her oranın anahtarını, değerini ve yürürlük aralığını verir; sonucu denetlenebilir kılmak için saklayın.

Araç sürümü

Bir aracın tanımı güncellendiğinde versionNumber artar. Tanımı okuyup kendi formunuzu üretiyorsanız hesaplama isteğinde bu numarayı version olarak gönderin:

Sürüm hâlâ canlıysa hesaplama yapılır.
Araç bu arada güncellendiyse 409 CONFLICT (details.reason = "VERSION_OUTDATED") döner; tanımı yeniden alıp formunuzu güncelleyin.
version göndermezseniz her zaman canlı sürüm kullanılır.

Yanıttaki meta.toolVersion hesaplamada kullanılan sürümü gösterir. API sürümü (/v1) ile araç sürümü birbirinden bağımsızdır.

Kullanılabilirlik

Listelerde ve tanımda availability alanı bulunur:

ONLINE: normal çalışıyor.
MAINTENANCE: araç geçici olarak bakımda. Hesaplama isteği 503 MAINTENANCE ve Retry-After ile döner.

Bakımdaki bir araçtan hata beklemeniz gerekir; kullanıcıya “geçici olarak kullanılamıyor” mesajı gösterip Retry-After kadar sonra yeniden deneyin. Bkz. Hatalar.

Deterministik sonuçlar

Aynı araç sürümü, aynı girdiler ve aynı asOf tarihi her zaman aynı sonucu verir. Hesaplama tanımı (formül) herkese açık değildir; yalnızca girdi/çıktı şeması, etiketler, oranlar ve sonuçlar yayınlanır.