Hesaplama

Hesaplama uçları aracın canlı sürümünü sunucuda çalıştırır. İki uç aynı davranır; biri key, diğeri toolId ile adresler (entegrasyonlar için key önerilir):

POST /v1/public/tools/by-key/{key}/calculate
POST /v1/public/tools/{toolId}/calculate

İstek

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

Alan	Zorunlu	Açıklama
`inputs`	evet	Alan adı → değer. Anahtarlar `inputSchema.fields` adlarıdır.
`asOf`	hayır	Oranların yürürlük tarihi, `YYYY-MM-DD`. Varsayılan bugün (`Europe/Istanbul`).
`version`	hayır	Tanımdan okuduğunuz `versionNumber`. Canlı sürümden farklıysa `409`.

İstek gövdesi en çok 16 KB olabilir; bilinmeyen üst düzey alanlar reddedilir.

Değer kuralları

Ondalıklar ve tarihler string, enum değerleri string, boolean JSON true/false.
JSON sayı (1000) reddedilir: 422 VALIDATION_ERROR, details.issues[] içinde ilgili yol.
required: false alanlar gönderilmezse default kullanılır.
Tanımda olmayan alan → details.fields[].reason = "UNKNOWN_INPUT".
Sınır ve ondalık kontrolleri: OUT_OF_RANGE, SCALE_EXCEEDED; eksik zorunlu alan MISSING_INPUT, null değer NULL_INPUT.

Yanıt

{
  "data": {
    "result": { "net": "1000.00", "vat": "200.00", "gross": "1200.00" },
    "breakdown": [
      { "key": "net", "value": "1000.00", "format": "money", "scale": 2, "currency": "TRY" },
      { "key": "vat", "value": "200.00", "format": "money", "scale": 2, "currency": "TRY" },
      { "key": "gross", "value": "1200.00", "format": "money", "scale": 2, "currency": "TRY" }
    ]
  },
  "meta": {
    "toolId": "8410ffe8-825a-41a1-9488-078f3a7c7f42",
    "toolVersion": 1,
    "asOf": "2026-10-11",
    "engineVersion": "1.2.0",
    "dslVersion": 1,
    "rates": [
      {
        "binding": "vatRate",
        "key": "tr.vat.standard",
        "rateId": "31fb806c-…",
        "valueId": "65a8771b-…",
        "version": 1,
        "value": "20",
        "effectiveFrom": "2023-07-10",
        "effectiveTo": null
      }
    ]
  }
}

data

result: sonuç anahtarı → string değer. Kodunuzda doğrudan anahtarla okuyun (data.result.gross).
breakdown: aynı sonuçların sıralı ve biçim bilgili listesi (format, scale, currency, unit). Sonuç tablosu çiziyorsanız bunu kullanın; sıra aracın tanımladığı sıradır.

Biçimlendirme

`format`	Anlamı	Gösterim önerisi
`money`	Para (`currency`)	`Intl.NumberFormat('tr-TR', { style: 'currency', currency })`
`percent`	Yüzde değeri (`"20"` = %20)	`20 %`
`number`	Sayı	`scale` kadar ondalık
`date`	Tarih `YYYY-MM-DD`	Yerel tarih biçimi

String değeri kayan noktaya çevirmeden biçimlendirmek için ondalık kütüphanesi (decimal.js, Python Decimal, .NET decimal) kullanın; ya da string’i olduğu gibi gösterin.

Geçmiş tarihli hesaplama

asOf ile o tarihte yürürlükteki oranlarla hesaplayın (örn. geçmiş bir KDV oranı):

curl -X POST "https://api.mirac-ozdemir.com/v1/public/tools/by-key/kdv/calculate" \
  -H "Content-Type: application/json" \
  -d '{"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). Örneğin bir oranın tanımlı olmadığı çok eski bir tarih bu hatayı verir.

`version` ile güncelliği doğrulama

Tanımı önbelleğe alıp formunuzu ondan ürettiyseniz hesaplamada version gönderin. Araç bu arada güncellenmişse hesaplama yapılmaz:

{ "error": { "code": "CONFLICT", "message": "…", "details": { "reason": "VERSION_OUTDATED", "currentVersion": 2 } }, "requestId": "…" }

Bu durumda tanımı yeniden alın (getToolByKey), formunuzu güncelleyin ve isteği tekrarlayın. Sürekli taze veri istiyorsanız version göndermeyip her seferinde canlı sürümle hesaplayabilirsiniz.

Hata ve sınırlar

Hesaplama uçları IP başına dakikada 60 istekle sınırlıdır; iki ucun sınırı ortaktır.
Hesaplama yanıtları no-store ile gelir; önbelleğe alınmamalıdır.
Bakımdaki bir araç 503 MAINTENANCE döner.

Tüm hata kodları ve işleme önerileri: Hatalar.