Examples

All examples follow the same flow: find the tool → calculate. In production code, add error handling and a timeout.

BASE="https://api.mirac-ozdemir.com/v1/public"

curl -s "$BASE/search?locale=tr&q=kdv&pageSize=1"

curl -s -X POST "$BASE/tools/by-key/kdv/calculate" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"amount":"1000","mode":"exclusive","vatRateOption":"standard"}}'

const BASE = 'https://api.mirac-ozdemir.com/v1/public';

async function api(path, init) {
  const response = await fetch(`${BASE}${path}`, { signal: AbortSignal.timeout(20_000), ...init });
  const body = await response.json();
  if (!response.ok) throw Object.assign(new Error(body.error.code), body.error, { requestId: body.requestId });
  return body;
}

const { data: [first] } = await api('/search?locale=tr&q=kdv&pageSize=1');
console.log(first.key, first.title);

const { data, meta } = await api(`/tools/by-key/${first.key}/calculate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ inputs: { amount: '1000', mode: 'exclusive', vatRateOption: 'standard' } }),
});
console.log(data.result, meta.rates);

interface Breakdown { key: string; value: string; format: 'money' | 'percent' | 'number' | 'date'; scale: number; currency?: string; unit?: string }
interface CalculationResponse {
  data: { result: Record<string, string>; breakdown: Breakdown[] };
  meta: { toolVersion: number; asOf: string; rates: Array<{ key: string; value: string; effectiveFrom: string | null; effectiveTo: string | null }> };
}

const BASE = 'https://api.mirac-ozdemir.com/v1/public';

export async function calculate(key: string, inputs: Record<string, string | boolean>, asOf?: string): Promise<CalculationResponse> {
  const response = await fetch(`${BASE}/tools/by-key/${encodeURIComponent(key)}/calculate`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ inputs, ...(asOf ? { asOf } : {}) }),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${(await response.json()).error?.code}`);
  return response.json() as Promise<CalculationResponse>;
}

const { data } = await calculate('kdv', { amount: '1000', mode: 'exclusive', vatRateOption: 'standard' });

For full type support, use type generation from OpenAPI.

import requests

BASE = "https://api.mirac-ozdemir.com/v1/public"

first = requests.get(f"{BASE}/search", params={"locale": "tr", "q": "kdv", "pageSize": 1}, timeout=15).json()["data"][0]
print(first["key"], first["title"])

r = requests.post(
    f"{BASE}/tools/by-key/{first['key']}/calculate",
    json={"inputs": {"amount": "1000", "mode": "exclusive", "vatRateOption": "standard"}},
    timeout=20,
)
r.raise_for_status()
body = r.json()
print(body["data"]["result"])  # {'net': '1000.00', 'vat': '200.00', 'gross': '1200.00'}

Handle money amounts with decimal.Decimal: Decimal(body["data"]["result"]["gross"]).

<?php
$base = 'https://api.mirac-ozdemir.com/v1/public';

$ch = curl_init("$base/tools/by-key/kdv/calculate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['inputs' => ['amount' => '1000', 'mode' => 'exclusive', 'vatRateOption' => 'standard']]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$body = json_decode($response, true);
if ($status !== 200) {
    throw new RuntimeException($body['error']['code'] . ' (' . $body['requestId'] . ')');
}
echo $body['data']['result']['gross']; // "1200.00"

Handle amounts as strings or with bcmath instead of float.

using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.mirac-ozdemir.com/v1/public/"), Timeout = TimeSpan.FromSeconds(20) };

var request = new { inputs = new Dictionary<string, object> { ["amount"] = "1000", ["mode"] = "exclusive", ["vatRateOption"] = "standard" } };
using var response = await http.PostAsJsonAsync("tools/by-key/kdv/calculate", request);
var json = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    var error = JsonDocument.Parse(json).RootElement.GetProperty("error").GetProperty("code").GetString();
    throw new InvalidOperationException($"{error} ({(int)response.StatusCode})");
}

var gross = JsonDocument.Parse(json).RootElement.GetProperty("data").GetProperty("result").GetProperty("gross").GetString();
var amount = decimal.Parse(gross!, System.Globalization.CultureInfo.InvariantCulture); // 1200.00

Drawing a results table from the definition

breakdown carries both the label keys and the format; the labels are in the definition:

const { data: tool } = await api(`/tools/by-key/${key}?locale=tr`);
const { data, meta } = await api(`/tools/by-key/${key}/calculate`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ version: tool.versionNumber, inputs }) });

for (const item of data.breakdown) {
  const label = tool.content.labels.outputs[item.key]?.label ?? item.key;
  const value = item.format === 'money'
    ? new Intl.NumberFormat('tr-TR', { style: 'currency', currency: item.currency }).format(item.value)
    : item.value;
  console.log(`${label}: ${value}`);
}