Araç tanımı

Bir aracın tanımı, ona nasıl istek göndereceğinizi ve sonucu nasıl göstereceğinizi anlatır. Kendi arayüzünüzü kuruyorsanız her aracı tek tek kodlamak yerine tanımdan genel bir form üretebilirsiniz; web sitemiz de araçları böyle çizer.

curl "https://api.mirac-ozdemir.com/v1/public/tools/by-key/kdv?locale=tr"

Yanıtın alanları

Alan	Açıklama
`id`, `key`, `slug`, `locale`, `path`	Tanımlayıcılar ve sayfa adresi.
`title`, `content`	Başlık; açıklamalar, rehber metinleri, SSS ve uyarılar; `content.labels` (aşağıda).
`inputSchema`	Kabul edilen girdiler.
`outputSchema`	Dönen sonuç alanları.
`uiSchema`	Yalnızca sunum ipuçları (bölümler, alan sırası, bileşen önerisi).
`rates`, `ratesAsOf`	Aracın kullandığı güncel oranlar ve kaynakları.
`versionNumber`, `contentHash`, `publishedAt`, `updatedAt`	Sürüm bilgisi.
`availability`	`ONLINE` veya `MAINTENANCE`.
`category`, `categoryPath`, `categories`	Kategoriler.
`alternates`, `related`, `seo`	Diğer diller, ilgili araçlar ve SEO alanları.
`disclaimer`	Sorumluluk reddi türü (ör. `TAX`).

inputSchema

inputSchema.fields, alan adı → alan tanımı haritasıdır. Anahtarlar, hesaplama isteğindeki inputs nesnesinin anahtarlarıdır. Nesne anahtarlarının sırası garanti edilmez; gösterim sırası için uiSchema kullanın.

{
  "fields": {
    "amount": { "type": "decimal", "required": true, "scale": 2, "min": "0", "max": "999999999999.99" },
    "mode": { "type": "enum", "required": true, "values": ["exclusive", "inclusive"], "default": "exclusive" },
    "vatRateOption": { "type": "enum", "required": true, "values": ["standard", "reduced10", "reduced1"], "default": "standard" }
  }
}

Dört alan türü vardır:

`type`	Özellikler	Gönderim
`decimal`	`scale` (azami ondalık hane, 0–10), `min`, `max`, `default`	string (`"1234.56"`)
`date`	`min`, `max`, `default` (`YYYY-MM-DD`)	string (`"2026-01-15"`)
`boolean`	`default`	JSON `true` / `false`
`enum`	`values` (1–50 sabit değer), `default`	string, `values` içinden

Ortak özellik required: true ise değer zorunludur; false ise gönderilmeyen alan için default kullanılır. Tanımda olmayan bir alan göndermek UNKNOWN_INPUT hatası verir. Sınır dışı değerler OUT_OF_RANGE, fazla ondalık hane SCALE_EXCEEDED hatasıdır.

outputSchema

{ "fields": [{ "key": "net", "type": "decimal", "scale": 2, "format": "money", "currency": "TRY" }] }

Özellik	Açıklama
`key`	`data.result` içindeki ad.
`type`	`decimal` veya `date`.
`format`	`money`, `percent`, `number` veya `date`. `percent` değerlerde `"20"` = %20.
`scale`	Ondalık hane sayısı.
`currency`	`money` için ISO 4217 kodu (`TRY`).
`unit`	Varsa birim (`gün`, `ay`).

uiSchema

Hesaplamayı etkilemeyen sunum ipuçlarıdır:

{
  "sections": [{ "key": "main", "fields": ["amount", "mode", "vatRateOption"] }],
  "fields": {
    "amount": { "widget": "money", "currency": "TRY" },
    "mode": { "widget": "radio" },
    "vatRateOption": { "widget": "select", "showRateValues": true }
  },
  "result": { "highlight": ["net", "vat", "gross"] }
}

sections[]: form bölümleri ve içindeki alanların sırası. Bölüm başlıkları content.labels.sections.<key> içindedir.
fields.<alan>.widget: number, money, percent, date, select, radio, checkbox, switch.
showRateValues: enum seçeneği bir orana bağlıysa her seçeneğin yanında güncel oranı (rates[]) gösterin.
visibleWhen: { "input": "...", "equals": ... }. Alan yalnızca ilgili girdi bu değere eşitken gösterilir; gizli alan için değer göndermeyin (varsayılanı kullanılır).
width: full veya half.
result.highlight: öne çıkarılacak sonuç anahtarları.

Etiketler

Kullanıcıya gösterilecek metinler content.labels içindedir ve seçilen dildedir:

{
  "inputs": { "vatRateOption": { "label": "KDV oranı", "options": { "standard": "Genel oran", "reduced10": "İndirimli oran", "reduced1": "İndirimli oran (temel gıda vb.)" } } },
  "outputs": { "net": { "label": "KDV hariç tutar", "description": "Faturadaki matrah…" } },
  "sections": { "main": "…" }
}

Oranlar

rates[], aracın kullandığı yürürlükteki yasal oranları kaynaklarıyla verir:

{
  "binding": "vatRate",
  "option": "reduced1",
  "key": "tr.vat.reduced-1",
  "name": "KDV indirimli oran (%1)",
  "value": "1",
  "unit": "PERCENT",
  "effectiveFrom": "2023-07-10",
  "effectiveTo": null,
  "source": "Cumhurbaşkanı Kararı No. 7346 (Resmî Gazete, 07.07.2023, Sayı 32241)",
  "sourceUrl": "https://…",
  "lastReviewedAt": "2026-10-01T12:00:00.000Z"
}

option, oranın hangi enum seçeneğine bağlı olduğunu gösterir; böylece seçim listesinde “Genel oran (%20)” gibi metin üretebilirsiniz. ratesAsOf, oranların hangi tarihe göre listelendiğini söyler.

Tanımdan genel form üretme

JavaScript

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

const { data: tool } = await (await fetch(`${API}/tools/by-key/kdv?locale=tr`)).json();
const { fields } = tool.inputSchema;
const labels = tool.content.labels;

// Sıra ve gruplama uiSchema'dan gelir
for (const section of tool.uiSchema.sections) {
  for (const name of section.fields) {
    const field = fields[name];
    const widget = tool.uiSchema.fields[name]?.widget;
    console.log(labels.inputs[name].label, field.type, widget);
  }
}

Gönderirken required: false alanları boş bırakabilir, gizli (visibleWhen) alanları hiç göndermeyebilirsiniz. Bir sonraki adım: Hesaplama.