Hesapla (key ile)

POST

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

const url = 'https://api.mirac-ozdemir.com/v1/public/tools/by-key/kdv/calculate';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"inputs":{"amount":"1000","mode":"exclusive","vatRateOption":"standard"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.mirac-ozdemir.com/v1/public/tools/by-key/kdv/calculate \
  --header 'Content-Type: application/json' \
  --data '{ "inputs": { "amount": "1000", "mode": "exclusive", "vatRateOption": "standard" } }'

Aracın canlı sürümüyle sunucu tarafında hesaplama yapar. Entegrasyonlar için önerilen hesaplama ucudur: key tüm ortamlarda aynıdır.

Gövde: inputs (alan adı → değer; ondalıklar ve tarihler string, enum değerleri string, boolean JSON true/false), isteğe bağlı version (tanımda okuduğunuz versionNumber; farklıysa 409 VERSION_OUTDATED) ve isteğe bağlı asOf (YYYY-MM-DD; oranların yürürlük tarihi, varsayılan bugün).

Yanıt: data.result (sonuç anahtarı → string değer), data.breakdown (biçim bilgisiyle sıralı sonuçlar), meta (kullanılan sürüm, tarih ve oranların kaynağı). Yanıtlar önbelleğe alınmaz (Cache-Control: no-store).

Hız sınırı: IP başına 60 istek / 60 sn (iki hesaplama ucu ortak sayılır).

Parameters

Path Parameters

key

required

string

>= 2 characters <= 64 characters /^[a-z0-9]+(-[a-z0-9]+)*$/

Example

kdv

Aracın kalıcı anahtarı (ör. kdv): küçük harf, rakam ve tire, 2–64 karakter (^[a-z0-9]+(-[a-z0-9]+)*$).

Request Body^required

application/json

object

inputs

required

Girdi değerleri; anahtarlar aracın inputSchema.fields adlarıdır.

object

key

additional properties

Any of:

string

<= 64 characters

version

İsteğe bağlı: tanımda okuduğunuz versionNumber. Canlı sürümden farklıysa 409 VERSION_OUTDATED.

integer

>= 1 <= 9007199254740991

asOf

İsteğe bağlı: oranların yürürlük tarihi (YYYY-MM-DD, varsayılan bugün, Europe/Istanbul).

string format: date

/^\d{4}-\d{2}-\d{2}$/

Examples

KDV hariç 1000 TL, genel oran

{
  "inputs": {
    "amount": "1000",
    "mode": "exclusive",
    "vatRateOption": "standard"
  }
}

KDV dahil 1200 TL, sürüm kontrolüyle

{
  "inputs": {
    "amount": "1200",
    "mode": "inclusive",
    "vatRateOption": "standard"
  },
  "version": 1
}

Geçmiş tarihteki oranla (asOf), %10 indirimli oran

{
  "inputs": {
    "amount": "1000",
    "mode": "exclusive",
    "vatRateOption": "reduced10"
  },
  "asOf": "2024-01-15"
}

Responses

200

Deterministik hesaplama sonucu

application/json

object

data

required

object

result

required

object

key

additional properties

string

breakdown

required

Array<object>

object

key

required

string

value

required

string

format

required

string

Allowed values: money percent number date

scale

required

integer

>= -9007199254740991 <= 9007199254740991

currency

string

unit

string

meta

required

object

toolId

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

toolVersion

required

Any of:

integer
null

integer

>= -9007199254740991 <= 9007199254740991

asOf

required

string

engineVersion

required

string

dslVersion

required

integer

>= -9007199254740991 <= 9007199254740991

rates

required

Array<object>

object

binding

required

string

key

required

string

rateId

required

Any of:

string
null

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

valueId

required

Any of:

string
null

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

version

required

Any of:

integer
null

integer

>= -9007199254740991 <= 9007199254740991

value

required

string

effectiveFrom

required

string | null

effectiveTo

required

string | null

Examples

KDV hariç 1000 TL → 200 TL KDV

{
  "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": "0b9f3c2e-8f56-4b43-9a7c-3c1b1f5e9d10",
    "toolVersion": 1,
    "asOf": "2026-10-01",
    "engineVersion": "1.2.0",
    "dslVersion": 1,
    "rates": [
      {
        "binding": "vatRate",
        "key": "tr.vat.standard",
        "rateId": "9c2f7a55-7a0e-4d7e-9e7a-2b8f6b1c0a11",
        "valueId": "1f1e0c3d-5b6a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 1,
        "value": "20",
        "effectiveFrom": "2023-07-10",
        "effectiveTo": null
      }
    ]
  }
}

KDV dahil 1200 TL → 1000 TL matrah

{
  "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": "0b9f3c2e-8f56-4b43-9a7c-3c1b1f5e9d10",
    "toolVersion": 1,
    "asOf": "2026-10-01",
    "engineVersion": "1.2.0",
    "dslVersion": 1,
    "rates": [
      {
        "binding": "vatRate",
        "key": "tr.vat.standard",
        "rateId": "9c2f7a55-7a0e-4d7e-9e7a-2b8f6b1c0a11",
        "valueId": "1f1e0c3d-5b6a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 1,
        "value": "20",
        "effectiveFrom": "2023-07-10",
        "effectiveTo": null
      }
    ]
  }
}

2024-01-15 tarihli %10 oranla

{
  "data": {
    "result": {
      "net": "1000.00",
      "vat": "100.00",
      "gross": "1100.00"
    },
    "breakdown": [
      {
        "key": "net",
        "value": "1000.00",
        "format": "money",
        "scale": 2,
        "currency": "TRY"
      },
      {
        "key": "vat",
        "value": "100.00",
        "format": "money",
        "scale": 2,
        "currency": "TRY"
      },
      {
        "key": "gross",
        "value": "1100.00",
        "format": "money",
        "scale": 2,
        "currency": "TRY"
      }
    ]
  },
  "meta": {
    "toolId": "0b9f3c2e-8f56-4b43-9a7c-3c1b1f5e9d10",
    "toolVersion": 1,
    "asOf": "2024-01-15",
    "engineVersion": "1.2.0",
    "dslVersion": 1,
    "rates": [
      {
        "binding": "vatRate",
        "key": "tr.vat.reduced-10",
        "rateId": "9c2f7a55-7a0e-4d7e-9e7a-2b8f6b1c0a11",
        "valueId": "1f1e0c3d-5b6a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 1,
        "value": "10",
        "effectiveFrom": "2023-07-10",
        "effectiveTo": null
      }
    ]
  }
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

RateLimit-Limit

integer

Penceredeki toplam istek hakkı.

RateLimit-Remaining

integer

Penceredeki kalan istek hakkı.

400

Bozuk istek: gövde geçerli JSON değil

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Examples

malformedJson

Gövde geçerli JSON değil

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Malformed JSON body"
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

404

Bulunamadı

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Examples

notFound

Araç yok veya yayında değil

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found"
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

409

Sürüm çakışması (details.reason = VERSION_OUTDATED)

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Examples

versionOutdated

Gönderilen version artık canlı değil

{
  "error": {
    "code": "CONFLICT",
    "message": "The tool has been updated; reload the page",
    "details": {
      "reason": "VERSION_OUTDATED",
      "currentVersion": 2
    }
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

413

Gövde 16 KB sınırını aşıyor

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Examples

tooLarge

Gövde sınırı aşıldı

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

422

Doğrulama, hesaplama veya oran hatası

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Examples

Girdi doğrulaması (details.fields)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid calculation input",
    "details": {
      "fields": [
        {
          "field": "amount",
          "reason": "TYPE_MISMATCH",
          "message": "amount must be a decimal string"
        },
        {
          "field": "mode",
          "reason": "INVALID_INPUT",
          "message": "mode must be one of exclusive, inclusive"
        }
      ]
    }
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

İstek şeması (details.issues)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request",
    "details": {
      "issues": [
        {
          "path": "inputs",
          "message": "Invalid input: expected record, received undefined",
          "code": "invalid_type"
        }
      ]
    }
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

asOf tarihinde yürürlükte oran yok

{
  "error": {
    "code": "RATE_UNAVAILABLE",
    "message": "No rate is in force for the requested date",
    "details": {
      "rates": [
        "tr.vat.standard"
      ],
      "asOf": "2000-01-01"
    }
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Bu girdilerle hesap tanımsız

{
  "error": {
    "code": "CALCULATION_ERROR",
    "message": "The calculation divides by zero for these inputs",
    "details": {
      "reason": "DIVISION_BY_ZERO"
    }
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

429

Hız sınırı aşıldı; Retry-After saniye sonra tekrar deneyin

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Examples

rateLimited

Hız sınırı aşıldı

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests, please try again later",
    "details": {
      "retryAfterSeconds": 42
    }
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

Retry-After

integer

>= 1

Tekrar denemeden önce beklenecek saniye.

500

Beklenmeyen sunucu hatası

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found"
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

503

Hata

application/json

Tüm hatalarda aynı zarf. details yapısı koda göre değişir (bkz. API açıklamasındaki tablo).

object

error

required

object

code

required

Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun.

string

Allowed values: VALIDATION_ERROR NOT_FOUND CONFLICT CALCULATION_ERROR RATE_UNAVAILABLE PAYLOAD_TOO_LARGE RATE_LIMITED TIMEOUT SERVICE_UNAVAILABLE MAINTENANCE INTERNAL_ERROR

message

required

İngilizce, insan tarafından okunacak açıklama; değişebilir.

string

details

fields[] (girdi hataları), issues[] (istek şeması), reason, currentVersion, retryAfterSeconds, rates, asOf.

object

key

additional properties

requestId

required

X-Request-Id yanıt başlığıyla aynı değer.

string | null

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found"
  },
  "requestId": "5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

Hesapla (key ile)

Parameters

Path Parameters

Example

Request Bodyrequired

Examples

Responses

200

Examples

Headers

400

Examples

Headers

404

Examples

Headers

409

Examples

Headers

413

Examples

Headers

422

Examples

Headers

429

Examples

Headers

500

Example

Headers

503

Example

Headers

Request Body^required