{"openapi":"3.1.0","info":{"title":"Mirac Özdemir Hesaplama API","version":"1.0.0","description":"Vergi, finans, maaş/bordro ve benzeri hesaplayıcıları **sunucu tarafında** çalıştıran açık API. Hesaplamalar ondalık aritmetikle yapılır (kayan nokta yok) ve deterministiktir: aynı araç sürümü, aynı girdiler ve aynı oran tarihi her zaman aynı sonucu verir.\n\n- **Temel adres:** `https://api.mirac-ozdemir.com/v1/public`\n- **Kimlik doğrulama:** Yok. API anahtarı gerekmez.\n- **Biçim:** JSON (`Content-Type: application/json`), UTF-8.\n\n## Hızlı başlangıç\n\n1. **Aracı bulun:** `GET /v1/public/search?locale=tr&q=kdv` → her sonuçta kalıcı `key` (ör. `kdv`).\n2. **Tanımı alın:** `GET /v1/public/tools/by-key/kdv?locale=tr` → `inputSchema`, `outputSchema`, `uiSchema`, `content.labels`, `versionNumber`.\n3. **Hesaplayın:**\n\n```bash\ncurl -X POST https://api.mirac-ozdemir.com/v1/public/tools/by-key/kdv/calculate \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"inputs\":{\"amount\":\"1000\",\"mode\":\"exclusive\",\"vatRateOption\":\"standard\"}}'\n# → {\"data\":{\"result\":{\"net\":\"1000.00\",\"vat\":\"200.00\",\"gross\":\"1200.00\"},...},\"meta\":{...}}\n```\n\n## Temel kavramlar\n\n- **key / toolId / slug:** `key` (`kdv`) kalıcıdır ve tüm ortamlarda aynıdır; entegrasyonlarda bunu kullanın. `toolId` veritabanı UUID'sidir, ortama özgüdür. `slug` (`kdv-hesaplama`) web sitesindeki sayfa adresidir ve değişebilir.\n- **Ondalıklar string'dir:** `\"1234.56\"` (nokta ayırıcı, binlik ayırıcı yok). JSON number gönderilirse 422 (`TYPE_MISMATCH`). Sonuçlar da string döner ve her zaman `scale` kadar ondalık hane içerir; kendi tarafınızda kayan noktaya çevirmeden biçimlendirin.\n- **Enum:** `inputSchema.fields.<alan>.values` içindeki sabit değerlerden biri (dile göre değişmez). Görünen adlar `content.labels.inputs.<alan>.options` içindedir.\n- **Boolean:** JSON `true` / `false`. **Tarih:** `YYYY-MM-DD`.\n- **İsteğe bağlı alanlar:** `required: false` alanlar gönderilmezse `default` kullanılır. Tanımda olmayan alan gönderilirse `UNKNOWN_INPUT`.\n- **asOf:** Oranların yürürlük tarihi (`YYYY-MM-DD`, varsayılan bugün, Europe/Istanbul). Geçmiş bir tarihle hesaplamak için kullanın; o tarihte oran yoksa `RATE_UNAVAILABLE`.\n- **version:** Tanımdaki `versionNumber`. Gönderirseniz ve araç bu arada güncellendiyse 409 `CONFLICT` (`details.reason = \"VERSION_OUTDATED\"`, `details.currentVersion`) döner; tanımı yeniden alın. Göndermezseniz her zaman canlı sürüm kullanılır.\n\n## CORS\n\nBu belgedeki uçlar tüm origin'lere açıktır (`Access-Control-Allow-Origin: *`, çerez veya kimlik bilgisi yok); doğrudan tarayıcıdan çağırabilirsiniz. İzin verilen istek başlıkları: `Content-Type`, `X-Request-Id`. Okunabilir yanıt başlıkları: `X-Request-Id`, `Retry-After`, `RateLimit-Limit`, `RateLimit-Remaining`.\n\n## Hız sınırları\n\n| Uç | Sınır |\n| --- | --- |\n| Hesaplama (`calculateByKey`, `calculateTool`; ortak sayılır) | IP başına 60 istek / 60 sn |\n| Arama (`searchTools`) | IP başına 60 istek / 60 sn |\n\nSınırlar sabit zaman penceresiyle sayılır. Sınırlı uçlar `RateLimit-Limit` ve `RateLimit-Remaining` başlıklarını döner. Aşıldığında **429** `RATE_LIMITED`, `Retry-After` başlığı (saniye) ve `details.retryAfterSeconds` döner. Diğer GET uçları önbelleklenebilir yanıtlar verir (`Cache-Control`); tanımları kendi tarafınızda da önbelleğe alın.\n\n## Hatalar\n\nTüm hatalar aynı zarfla döner; mantığınızı `error.code` üzerine kurun (`message` İngilizcedir ve değişebilir):\n\n```json\n{ \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"Invalid calculation input\", \"details\": { \"fields\": [ { \"field\": \"amount\", \"reason\": \"TYPE_MISMATCH\", \"message\": \"amount must be a decimal string\" } ] } }, \"requestId\": \"5f0c6a5e-…\" }\n```\n\n| Kod | HTTP | Ne zaman |\n| --- | --- | --- |\n| `VALIDATION_ERROR` | 422 (bozuk JSON: 400) | Parametre/gövde şeması hatası (`details.issues[]`: `path`, `message`, `code`) veya hesaplama girdisi hatası (`details.fields[]`: `field`, `reason`, `message`; `reason`: `MISSING_INPUT`, `NULL_INPUT`, `INVALID_INPUT`, `TYPE_MISMATCH`, `OUT_OF_RANGE`, `SCALE_EXCEEDED`, `UNKNOWN_INPUT`). Geçersiz `asOf`: `details.field = \"asOf\"`. |\n| `NOT_FOUND` | 404 | Araç yok, yayında değil veya istenen dilde değil; bilinmeyen adres. |\n| `CONFLICT` | 409 | `details.reason = \"VERSION_OUTDATED\"`: gönderilen `version` artık canlı değil. |\n| `CALCULATION_ERROR` | 422 / 500 | 422: bu girdilerle hesap tanımsız (`details.reason`: `DIVISION_BY_ZERO`, `CALCULATION_OVERFLOW`, `INVALID_DATE_OPERATION`, `INVALID_ARGUMENT`, `NO_SOLUTION`). 500: araç geçici olarak hesaplanamıyor. |\n| `RATE_UNAVAILABLE` | 422 | `asOf` tarihinde yürürlükte oran yok (`details.rates`, `details.asOf`) veya oran kullanılamıyor (`details.reason`). |\n| `PAYLOAD_TOO_LARGE` | 413 | Gövde 16 KB'ı aşıyor. |\n| `RATE_LIMITED` | 429 | Hız sınırı aşıldı; `Retry-After` saniye bekleyin. |\n| `TIMEOUT` | 504 | İstek 15 sn içinde tamamlanamadı; tekrar deneyin. |\n| `SERVICE_UNAVAILABLE` | 503 | Hizmet geçici olarak kullanılamıyor; daha sonra tekrar deneyin. |\n| `MAINTENANCE` | 503 | Araç geçici olarak bakımda (`availability: \"MAINTENANCE\"`); `Retry-After` başlığı kadar (`details.retryAfterSeconds`) bekleyip yeniden deneyin. |\n| `INTERNAL_ERROR` | 500 | Beklenmeyen hata; ayrıntı yalnızca sunucu kayıtlarındadır (`requestId` ile). |\n\n## X-Request-Id\n\nHer yanıtta `X-Request-Id` başlığı ve hata gövdelerinde `requestId` bulunur. Kendi kimliğinizi `X-Request-Id` başlığıyla gönderebilirsiniz (`[A-Za-z0-9._:-]`, 8–128 karakter); geçersizse yenisi üretilir. Destek taleplerinde bu değeri iletin.\n\n## Gömülebilir widget\n\nKod yazmadan bir hesaplayıcıyı sitenize eklemek için iframe tabanlı widget: sayfanıza `<script src=\"https://api.mirac-ozdemir.com/widget.js\" async></script>` ekleyin ve aracı göstermek istediğiniz yere `<div data-mo-tool=\"kdv\" data-locale=\"tr\"></div>` yerleştirin (`data-theme`: `auto` / `light` / `dark`, `data-header`, `data-height` isteğe bağlı). Yükleyici iframe yüksekliğini içeriğe göre ayarlar.\n\n## Sorumluluk reddi\n\nSonuçlar bilgilendirme amaçlıdır; vergi, hukuk veya finans danışmanlığı yerine geçmez. Kullanılan oranlar ve kaynakları yanıttaki `rates` / `meta.rates` alanlarındadır.","contact":{"name":"Mirac Özdemir","url":"https://mirac-ozdemir.com"}},"servers":[{"url":"https://api.mirac-ozdemir.com","description":"Production"}],"tags":[{"name":"Araç Keşfi","description":"Yayındaki araçları listeleme, arama ve kategori ağacı."},{"name":"Araç Tanımı","description":"Bir aracın girdi/çıktı şeması, form ipuçları, etiketleri ve güncel oranları."},{"name":"Hesaplama","description":"Aracın canlı sürümüyle sunucu tarafında, deterministik hesaplama."}],"x-tagGroups":[{"name":"Geliştirici API","tags":["Araç Keşfi","Araç Tanımı","Hesaplama"]}],"paths":{"/v1/public/tools":{"get":{"operationId":"listTools","parameters":[{"name":"page","required":false,"in":"query","schema":{"default":1,"example":1,"type":"integer","minimum":1,"maximum":10000},"description":"Sayfa numarası, 1'den başlar."},{"name":"pageSize","required":false,"in":"query","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":100},"description":"Sayfa başına kayıt (varsayılan 20)."},{"name":"locale","required":true,"in":"query","schema":{"type":"string","enum":["tr","en"]},"description":"İçerik dili: `tr` veya `en`. Zorunludur; araç o dilde yoksa 404 döner."},{"name":"category","required":false,"in":"query","schema":{"description":"Category key; a main category also lists its subcategories","type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"description":"Kategori key'i; ana kategori verilirse alt kategorilerindeki araçlar da dahil edilir."}],"responses":{"200":{"description":"Araç listesi","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolListItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Doğrulama, hesaplama veya oran hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidParameter":{"summary":"Geçersiz parametre","value":{"error":{"code":"VALIDATION_ERROR","message":"Invalid request","details":{"issues":[{"path":"locale","message":"Invalid option: expected one of \"tr\"|\"en\"","code":"invalid_value"}]}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"500":{"description":"Beklenmeyen sunucu hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Araçları listele","tags":["Araç Keşfi"],"description":"Yayında ve arama motorlarına açık araçları başlığa göre sıralı ve sayfalı döndürür. `category` verilirse o kategori ve alt kategorilerindeki araçlar listelenir. Her öğedeki `key`, tanım ve hesaplama uçlarında kullanılacak kalıcı anahtardır."}},"/v1/public/search":{"get":{"operationId":"searchTools","parameters":[{"name":"page","required":false,"in":"query","schema":{"default":1,"example":1,"type":"integer","minimum":1,"maximum":10000},"description":"Sayfa numarası, 1'den başlar."},{"name":"pageSize","required":false,"in":"query","schema":{"default":20,"example":20,"type":"integer","minimum":1,"maximum":50},"description":"Sayfa başına kayıt (varsayılan 20)."},{"name":"locale","required":true,"in":"query","schema":{"type":"string","enum":["tr","en"]},"description":"İçerik dili: `tr` veya `en`. Zorunludur; araç o dilde yoksa 404 döner."},{"name":"q","required":false,"in":"query","schema":{"default":"","example":"kdv","type":"string","maxLength":100},"description":"Arama metni (en fazla 100 karakter)."},{"name":"category","required":false,"in":"query","schema":{"description":"Category key; a main category also lists its subcategories","type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"description":"Kategori key'i; ana kategori verilirse alt kategorilerindeki araçlar da dahil edilir."}],"responses":{"200":{"description":"Arama sonuçları","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ToolListItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"422":{"description":"Doğrulama, hesaplama veya oran hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidParameter":{"summary":"Geçersiz parametre","value":{"error":{"code":"VALIDATION_ERROR","message":"Invalid request","details":{"issues":[{"path":"locale","message":"Invalid option: expected one of \"tr\"|\"en\"","code":"invalid_value"}]}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"429":{"description":"Hız sınırı aşıldı; `Retry-After` saniye sonra tekrar deneyin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rateLimited":{"summary":"Hız sınırı aşıldı","value":{"error":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","details":{"retryAfterSeconds":42}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"500":{"description":"Beklenmeyen sunucu hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Araç ara","tags":["Araç Keşfi"],"description":"Başlık, açıklama ve anahtar kelimelerde tam metin ve benzerlik araması (dil kurallarına göre; Türkçe karakterler aksansız da eşleşir). Sonuçlar alaka düzeyine göre sıralanır; boş `q` tüm araçları listeler. Hız sınırı: IP başına 60 istek / 60 sn."}},"/v1/public/categories":{"get":{"operationId":"listCategories","parameters":[{"name":"locale","required":true,"in":"query","schema":{"type":"string","enum":["tr","en"]},"description":"İçerik dili: `tr` veya `en`. Zorunludur; araç o dilde yoksa 404 döner."}],"responses":{"200":{"description":"Kategori ağacı","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCategoryTree"}}}},"422":{"description":"Doğrulama, hesaplama veya oran hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidParameter":{"summary":"Geçersiz parametre","value":{"error":{"code":"VALIDATION_ERROR","message":"Invalid request","details":{"issues":[{"path":"locale","message":"Invalid option: expected one of \"tr\"|\"en\"","code":"invalid_value"}]}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"500":{"description":"Beklenmeyen sunucu hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Kategori ağacı","tags":["Araç Keşfi"],"description":"Aktif ana kategoriler ve alt kategorileri, yayındaki araç sayılarıyla. Kategori `key` değerini `/tools` ve `/search` uçlarında `category` filtresi olarak kullanın."}},"/v1/public/tools/by-key/{key}":{"get":{"operationId":"getToolByKey","parameters":[{"name":"key","required":true,"in":"path","schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","example":"kdv"},"description":"Aracın kalıcı anahtarı (ör. `kdv`): küçük harf, rakam ve tire, 2–64 karakter (`^[a-z0-9]+(-[a-z0-9]+)*$`)."},{"name":"locale","required":true,"in":"query","schema":{"type":"string","enum":["tr","en"]},"description":"İçerik dili: `tr` veya `en`. Zorunludur; araç o dilde yoksa 404 döner."}],"responses":{"200":{"description":"Araç tanımı ve sayfa verisi","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicToolResponse"},"example":{"data":{"id":"0b9f3c2e-8f56-4b43-9a7c-3c1b1f5e9d10","key":"kdv","versionNumber":1,"contentHash":"c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00","publishedAt":"2026-09-30T08:00:00.000Z","updatedAt":"2026-09-30T08:00:00.000Z","category":"kdv","categoryPath":[{"key":"tax","slug":"vergi","name":"Vergi","path":"/tr/kategori/vergi"},{"key":"kdv","slug":"kdv","name":"KDV Araçları","path":"/tr/kategori/kdv"}],"categories":[{"key":"kdv","slug":"kdv","name":"KDV Araçları","path":"/tr/kategori/kdv"}],"disclaimer":"TAX","indexable":true,"locale":"tr","slug":"kdv-hesaplama","path":"/tr/araclar/kdv-hesaplama","title":"KDV Hesaplama","content":{"shortDescription":"KDV dahil ve KDV hariç tutarları güncel KDV oranlarıyla hesaplayın.","longDescription":"…","instructions":"…","notes":"","warnings":[],"faq":[],"keywords":["kdv","katma değer vergisi"],"labels":{"inputs":{"amount":{"label":"Tutar","placeholder":"0,00","help":"Hesaplamak istediğiniz tutarı Türk lirası olarak girin."},"mode":{"label":"Girilen tutar","options":{"exclusive":"KDV hariç","inclusive":"KDV dahil"}},"vatRateOption":{"label":"KDV oranı","options":{"standard":"Genel oran","reduced10":"İndirimli oran","reduced1":"İndirimli oran (temel gıda vb.)"}}},"outputs":{"net":{"label":"KDV hariç tutar"},"vat":{"label":"KDV tutarı"},"gross":{"label":"KDV dahil tutar"}},"sections":{"main":{"title":"Hesaplama bilgileri"}}}},"seo":{"metaTitle":"KDV Hesaplama — KDV Dahil ve Hariç Tutar Hesaplama","metaDescription":"KDV dahil ve KDV hariç tutarları güncel %20, %10 ve %1 KDV oranlarıyla anında hesaplayın.","ogImage":"tax","robotsIndex":true,"robotsFollow":true},"inputSchema":{"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"}}},"outputSchema":{"fields":[{"key":"net","type":"decimal","format":"money","currency":"TRY","scale":2},{"key":"vat","type":"decimal","format":"money","currency":"TRY","scale":2},{"key":"gross","type":"decimal","format":"money","currency":"TRY","scale":2}]},"uiSchema":{"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"]}},"alternates":[{"locale":"tr","slug":"kdv-hesaplama","path":"/tr/araclar/kdv-hesaplama"},{"locale":"en","slug":"vat-calculator","path":"/en/tools/vat-calculator"}],"related":[],"ratesAsOf":"2026-10-01","rates":[{"binding":"vatRate","option":"standard","key":"tr.vat.standard","name":"KDV genel oran","description":null,"value":"20","unit":"PERCENT","effectiveFrom":"2023-07-10","effectiveTo":null,"source":"Cumhurbaşkanı Kararı No. 7346 (Resmî Gazete, 07.07.2023, Sayı 32241)","sourceUrl":null,"lastReviewedAt":"2026-10-01T09:00:00.000Z"},{"binding":"vatRate","option":"reduced10","key":"tr.vat.reduced-10","name":"KDV indirimli oran (%10)","description":null,"value":"10","unit":"PERCENT","effectiveFrom":"2023-07-10","effectiveTo":null,"source":"Cumhurbaşkanı Kararı No. 7346 (Resmî Gazete, 07.07.2023, Sayı 32241)","sourceUrl":null,"lastReviewedAt":"2026-10-01T09:00:00.000Z"},{"binding":"vatRate","option":"reduced1","key":"tr.vat.reduced-1","name":"KDV indirimli oran (%1)","description":null,"value":"1","unit":"PERCENT","effectiveFrom":"2023-07-10","effectiveTo":null,"source":"Cumhurbaşkanı Kararı No. 7346 (Resmî Gazete, 07.07.2023, Sayı 32241)","sourceUrl":null,"lastReviewedAt":"2026-10-01T09:00:00.000Z"}]}}}}},"404":{"description":"Bulunamadı","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notFound":{"summary":"Araç yok, yayında değil veya bu dilde yok","value":{"error":{"code":"NOT_FOUND","message":"Tool not found"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"422":{"description":"Doğrulama, hesaplama veya oran hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidParameter":{"summary":"Geçersiz parametre","value":{"error":{"code":"VALIDATION_ERROR","message":"Invalid request","details":{"issues":[{"path":"locale","message":"Invalid option: expected one of \"tr\"|\"en\"","code":"invalid_value"}]}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"500":{"description":"Beklenmeyen sunucu hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Araç tanımını key ile getir","tags":["Araç Tanımı"],"description":"Aracın canlı (yayındaki) sürümünü döndürür: `inputSchema` (girdiler, türleri, sınırları), `outputSchema` (sonuç alanları), `uiSchema` (form düzeni ipuçları), `content.labels` (seçilen dildeki etiketler), güncel oranlar (`rates`, `ratesAsOf`) ve `versionNumber`. Kendi formunuzu bu tanımdan üretebilirsiniz. Araç yoksa, yayında değilse veya bu dilde içeriği yoksa 404 döner (başka dile geri düşülmez)."}},"/v1/public/tools/by-key/{key}/calculate":{"post":{"operationId":"calculateByKey","parameters":[{"name":"key","required":true,"in":"path","schema":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","example":"kdv"},"description":"Aracın kalıcı anahtarı (ör. `kdv`): küçük harf, rakam ve tire, 2–64 karakter (`^[a-z0-9]+(-[a-z0-9]+)*$`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"},"examples":{"exclusive":{"summary":"KDV hariç 1000 TL, genel oran","value":{"inputs":{"amount":"1000","mode":"exclusive","vatRateOption":"standard"}}},"inclusive":{"summary":"KDV dahil 1200 TL, sürüm kontrolüyle","value":{"inputs":{"amount":"1200","mode":"inclusive","vatRateOption":"standard"},"version":1}},"historical":{"summary":"Geçmiş tarihteki oranla (asOf), %10 indirimli oran","value":{"inputs":{"amount":"1000","mode":"exclusive","vatRateOption":"reduced10"},"asOf":"2024-01-15"}}}}}},"responses":{"200":{"description":"Deterministik hesaplama sonucu","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculationResponse"},"examples":{"exclusive":{"summary":"KDV hariç 1000 TL → 200 TL KDV","value":{"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}]}}},"inclusive":{"summary":"KDV dahil 1200 TL → 1000 TL matrah","value":{"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}]}}},"historical":{"summary":"2024-01-15 tarihli %10 oranla","value":{"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}]}}}}}}},"400":{"description":"Bozuk istek: gövde geçerli JSON değil","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"malformedJson":{"summary":"Gövde geçerli JSON değil","value":{"error":{"code":"VALIDATION_ERROR","message":"Malformed JSON body"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"404":{"description":"Bulunamadı","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notFound":{"summary":"Araç yok veya yayında değil","value":{"error":{"code":"NOT_FOUND","message":"Tool not found"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"409":{"description":"Sürüm çakışması (`details.reason = VERSION_OUTDATED`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"versionOutdated":{"summary":"Gönderilen version artık canlı değil","value":{"error":{"code":"CONFLICT","message":"The tool has been updated; reload the page","details":{"reason":"VERSION_OUTDATED","currentVersion":2}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"413":{"description":"Gövde 16 KB sınırını aşıyor","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"tooLarge":{"summary":"Gövde sınırı aşıldı","value":{"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body is too large"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"422":{"description":"Doğrulama, hesaplama veya oran hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidInputs":{"summary":"Girdi doğrulaması (details.fields)","value":{"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"}},"invalidRequest":{"summary":"İstek şeması (details.issues)","value":{"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"}},"rateUnavailable":{"summary":"asOf tarihinde yürürlükte oran yok","value":{"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"}},"calculationError":{"summary":"Bu girdilerle hesap tanımsız","value":{"error":{"code":"CALCULATION_ERROR","message":"The calculation divides by zero for these inputs","details":{"reason":"DIVISION_BY_ZERO"}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"429":{"description":"Hız sınırı aşıldı; `Retry-After` saniye sonra tekrar deneyin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rateLimited":{"summary":"Hız sınırı aşıldı","value":{"error":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","details":{"retryAfterSeconds":42}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"500":{"description":"Beklenmeyen sunucu hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Hata","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Hesapla (key ile)","tags":["Hesaplama"],"description":"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.\n\nGö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).\n\nYanı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`).\n\nHız sınırı: IP başına 60 istek / 60 sn (iki hesaplama ucu ortak sayılır)."}},"/v1/public/tools/by-slug/{locale}/{slug}":{"get":{"operationId":"getToolBySlug","parameters":[{"name":"locale","required":true,"in":"path","schema":{"type":"string","enum":["tr","en"]},"description":"İçerik dili: `tr` veya `en`. Zorunludur; araç o dilde yoksa 404 döner."},{"name":"slug","required":true,"in":"path","schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"description":"Yerelleştirilmiş sayfa slug'ı (ör. `kdv-hesaplama`)."}],"responses":{"200":{"description":"Araç verisi veya yönlendirme","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicToolLookup"}}}},"404":{"description":"Bulunamadı","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notFound":{"summary":"Araç yok, yayında değil veya bu dilde yok","value":{"error":{"code":"NOT_FOUND","message":"Tool not found"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"422":{"description":"Doğrulama, hesaplama veya oran hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidParameter":{"summary":"Geçersiz parametre","value":{"error":{"code":"VALIDATION_ERROR","message":"Invalid request","details":{"issues":[{"path":"locale","message":"Invalid option: expected one of \"tr\"|\"en\"","code":"invalid_value"}]}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"500":{"description":"Beklenmeyen sunucu hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Araç sayfasını slug ile çözümle","tags":["Araç Tanımı"],"description":"Web sitesindeki sayfa adresinden (ör. `/tr/kdv-hesaplama`) araca ulaşır. Eski bir slug istenirse `data.kind = \"redirect\"` ve güncel slug döner (tek adım); aksi halde `data.kind = \"tool\"` ve `data.tool` by-key yanıtıyla aynıdır. Slug değişebilir; entegrasyonlarda `key` tercih edin."}},"/v1/public/tools/{toolId}/calculate":{"post":{"operationId":"calculateTool","parameters":[{"name":"toolId","required":true,"in":"path","schema":{"type":"string","format":"uuid","pattern":"^([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)$","example":"0b9f3c2e-8f56-4b43-9a7c-3c1b1f5e9d10"},"description":"Aracın UUID kimliği (ortama özgü)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"},"examples":{"exclusive":{"summary":"KDV hariç 1000 TL, genel oran","value":{"inputs":{"amount":"1000","mode":"exclusive","vatRateOption":"standard"}}},"inclusive":{"summary":"KDV dahil 1200 TL, sürüm kontrolüyle","value":{"inputs":{"amount":"1200","mode":"inclusive","vatRateOption":"standard"},"version":1}},"historical":{"summary":"Geçmiş tarihteki oranla (asOf), %10 indirimli oran","value":{"inputs":{"amount":"1000","mode":"exclusive","vatRateOption":"reduced10"},"asOf":"2024-01-15"}}}}}},"responses":{"200":{"description":"Deterministik hesaplama sonucu","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculationResponse"},"examples":{"exclusive":{"summary":"KDV hariç 1000 TL → 200 TL KDV","value":{"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}]}}},"inclusive":{"summary":"KDV dahil 1200 TL → 1000 TL matrah","value":{"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}]}}},"historical":{"summary":"2024-01-15 tarihli %10 oranla","value":{"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}]}}}}}}},"400":{"description":"Bozuk istek: gövde geçerli JSON değil","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"malformedJson":{"summary":"Gövde geçerli JSON değil","value":{"error":{"code":"VALIDATION_ERROR","message":"Malformed JSON body"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"404":{"description":"Bulunamadı","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"notFound":{"summary":"Araç yok veya yayında değil","value":{"error":{"code":"NOT_FOUND","message":"Tool not found"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"409":{"description":"Sürüm çakışması (`details.reason = VERSION_OUTDATED`)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"versionOutdated":{"summary":"Gönderilen version artık canlı değil","value":{"error":{"code":"CONFLICT","message":"The tool has been updated; reload the page","details":{"reason":"VERSION_OUTDATED","currentVersion":2}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"413":{"description":"Gövde 16 KB sınırını aşıyor","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"tooLarge":{"summary":"Gövde sınırı aşıldı","value":{"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body is too large"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"422":{"description":"Doğrulama, hesaplama veya oran hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidInputs":{"summary":"Girdi doğrulaması (details.fields)","value":{"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"}},"invalidRequest":{"summary":"İstek şeması (details.issues)","value":{"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"}},"rateUnavailable":{"summary":"asOf tarihinde yürürlükte oran yok","value":{"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"}},"calculationError":{"summary":"Bu girdilerle hesap tanımsız","value":{"error":{"code":"CALCULATION_ERROR","message":"The calculation divides by zero for these inputs","details":{"reason":"DIVISION_BY_ZERO"}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"429":{"description":"Hız sınırı aşıldı; `Retry-After` saniye sonra tekrar deneyin","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rateLimited":{"summary":"Hız sınırı aşıldı","value":{"error":{"code":"RATE_LIMITED","message":"Too many requests, please try again later","details":{"retryAfterSeconds":42}},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}}}}}},"500":{"description":"Beklenmeyen sunucu hatası","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Hata","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Hesapla (toolId ile)","tags":["Hesaplama"],"description":"`calculateByKey` ile aynı davranış; araç UUID ile adreslenir. `toolId` ortama özgüdür, kalıcı entegrasyonlarda key ile hesaplamayı kullanın.\n\nGö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).\n\nYanı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`).\n\nHız sınırı: IP başına 60 istek / 60 sn (iki hesaplama ucu ortak sayılır)."}}},"components":{"schemas":{"BooleanInputField":{"type":"object","description":"Evet/hayır. JSON `true` / `false` olarak gönderilir.","required":["type","required"],"properties":{"type":{"const":"boolean"},"required":{"type":"boolean","description":"`true` ise değer gönderilmelidir. `false` ise gönderilmeyen alan için `default` kullanılır."},"default":{"type":"boolean"}},"example":{"type":"boolean","required":false,"default":false}},"CalculateRequest":{"type":"object","properties":{"inputs":{"$ref":"#/components/schemas/CalculationInputs","description":"Girdi değerleri; anahtarlar aracın `inputSchema.fields` adlarıdır."},"version":{"description":"İsteğe bağlı: tanımda okuduğunuz `versionNumber`. Canlı sürümden farklıysa 409 `VERSION_OUTDATED`.","type":"integer","minimum":1,"maximum":9007199254740991},"asOf":{"description":"İsteğe bağlı: oranların yürürlük tarihi (`YYYY-MM-DD`, varsayılan bugün, Europe/Istanbul).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","example":"2026-01-15"}},"required":["inputs"],"additionalProperties":false},"CalculationInputs":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"anyOf":[{"type":"string","maxLength":64},{"type":"boolean"},{"type":"null"}]},"description":"Alan adı → değer. Ondalık ve tarih değerleri string, enum değerleri string, boolean değerler JSON `true`/`false`; JSON number reddedilir.","example":{"amount":"100","mode":"exclusive","vatRateOption":"standard"}},"CalculationRateMeta":{"type":"object","properties":{"binding":{"type":"string"},"key":{"type":"string"},"rateId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([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)$"},{"type":"null"}]},"valueId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([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)$"},{"type":"null"}]},"version":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"value":{"type":"string"},"effectiveFrom":{"type":["string","null"]},"effectiveTo":{"type":["string","null"]}},"required":["binding","key","rateId","valueId","version","value","effectiveFrom","effectiveTo"],"additionalProperties":false},"CalculationResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"result":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/OutputValue"}}},"required":["result","breakdown"],"additionalProperties":false},"meta":{"type":"object","properties":{"toolId":{"type":"string","format":"uuid","pattern":"^([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":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"asOf":{"type":"string"},"engineVersion":{"type":"string"},"dslVersion":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rates":{"type":"array","items":{"$ref":"#/components/schemas/CalculationRateMeta"}}},"required":["toolId","toolVersion","asOf","engineVersion","dslVersion","rates"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"CategoryRef":{"type":"object","properties":{"key":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"path":{"type":"string"}},"required":["key","slug","name","path"],"additionalProperties":false},"DateInputField":{"type":"object","description":"Takvim tarihi, `YYYY-MM-DD` biçiminde string.","required":["type","required"],"properties":{"type":{"const":"date"},"required":{"type":"boolean","description":"`true` ise değer gönderilmelidir. `false` ise gönderilmeyen alan için `default` kullanılır."},"min":{"type":"string","format":"date","description":"En erken tarih (dahil)."},"max":{"type":"string","format":"date","description":"En geç tarih (dahil)."},"default":{"type":"string","format":"date"}},"example":{"type":"date","required":true,"min":"2000-01-01"}},"DecimalInputField":{"type":"object","description":"Ondalık sayı. Değer **string** olarak gönderilir (ör. `\"1234.56\"`): nokta ondalık ayırıcıdır, binlik ayırıcı yoktur. JSON number reddedilir (`TYPE_MISMATCH`).","required":["type","required","scale"],"properties":{"type":{"const":"decimal"},"required":{"type":"boolean","description":"`true` ise değer gönderilmelidir. `false` ise gönderilmeyen alan için `default` kullanılır."},"scale":{"type":"integer","minimum":0,"maximum":10,"description":"İzin verilen azami ondalık hane sayısı; fazlası `SCALE_EXCEEDED` hatası verir."},"min":{"type":"string","description":"Alt sınır (dahil), ondalık string. Dışındaki değerler `OUT_OF_RANGE`.","examples":["0","1234.56"]},"max":{"type":"string","description":"Üst sınır (dahil), ondalık string.","examples":["0","1234.56"]},"default":{"type":"string","description":"Değer gönderilmezse kullanılan varsayılan.","examples":["0","1234.56"]}},"example":{"type":"decimal","required":true,"scale":2,"min":"0","max":"999999999999.99"}},"EnumInputField":{"type":"object","description":"Sabit seçenek listesi. `values` içindeki değerlerden biri string olarak gönderilir. Kullanıcıya gösterilecek metinler `content.labels.inputs.<alan>.options` içindedir.","required":["type","required","values"],"properties":{"type":{"const":"enum"},"required":{"type":"boolean","description":"`true` ise değer gönderilmelidir. `false` ise gönderilmeyen alan için `default` kullanılır."},"values":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"},"description":"Geçerli değerler (sabit, dile göre değişmez)."},"default":{"type":"string","description":"Varsayılan seçenek (`values` içinden)."}},"example":{"type":"enum","required":true,"values":["exclusive","inclusive"],"default":"exclusive"}},"ErrorResponse":{"type":"object","description":"Tüm hatalarda aynı zarf. `details` yapısı koda göre değişir (bkz. API açıklamasındaki tablo).","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","NOT_FOUND","CONFLICT","CALCULATION_ERROR","RATE_UNAVAILABLE","PAYLOAD_TOO_LARGE","RATE_LIMITED","TIMEOUT","SERVICE_UNAVAILABLE","MAINTENANCE","INTERNAL_ERROR"],"description":"Makine tarafından okunacak sabit kod; mantığınızı buna göre kurun."},"message":{"type":"string","description":"İngilizce, insan tarafından okunacak açıklama; değişebilir."},"details":{"type":"object","additionalProperties":{},"description":"`fields[]` (girdi hataları), `issues[]` (istek şeması), `reason`, `currentVersion`, `retryAfterSeconds`, `rates`, `asOf`."}}},"requestId":{"type":["string","null"],"description":"`X-Request-Id` yanıt başlığıyla aynı değer."}},"example":{"error":{"code":"NOT_FOUND","message":"Tool not found"},"requestId":"5f0c6a5e-2b7e-4a7b-9a51-0d9f0c1f7e21"}},"LocalizationContent":{"type":"object","properties":{"shortDescription":{"type":"string","minLength":0,"maxLength":300},"longDescription":{"type":"string","maxLength":20000},"instructions":{"type":"string","maxLength":10000},"notes":{"type":"string","maxLength":10000},"warnings":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"faq":{"maxItems":30,"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":300},"answer":{"type":"string","maxLength":5000}},"required":["question","answer"],"additionalProperties":false}},"keywords":{"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},"references":{"maxItems":8,"type":"array","items":{"$ref":"#/components/schemas/ToolReference"}},"labels":{"$ref":"#/components/schemas/ToolLabels","description":"Form ve sonuç etiketleri."}},"required":["shortDescription","longDescription","instructions","notes","warnings","faq","keywords","labels"],"additionalProperties":false},"LocalizationSeo":{"type":"object","properties":{"metaTitle":{"type":"string","minLength":0,"maxLength":120},"metaDescription":{"type":"string","minLength":0,"maxLength":300},"ogTitle":{"type":"string","minLength":0,"maxLength":120},"ogDescription":{"type":"string","minLength":0,"maxLength":300},"ogImage":{"type":"string","enum":["default","tax","finance","math","conversion","date","health"]},"robotsIndex":{"type":"boolean"},"robotsFollow":{"type":"boolean"}},"required":["metaTitle","metaDescription","ogImage","robotsIndex","robotsFollow"],"additionalProperties":false},"OutputValue":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","example":"120.00"},"format":{"type":"string","enum":["money","percent","number","date"]},"scale":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currency":{"type":"string"},"unit":{"type":"string"}},"required":["key","value","format","scale"],"additionalProperties":false},"PageMeta":{"type":"object","properties":{"page":{"type":"integer","minimum":1,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":1,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalPages":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["page","pageSize","total","totalPages"],"additionalProperties":false,"example":{"page":1,"pageSize":20,"total":100,"totalPages":5}},"PublicAvailability":{"type":"string","enum":["ONLINE","MAINTENANCE"]},"PublicCategoryNode":{"type":"object","properties":{"key":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"ogImage":{"type":"string","enum":["default","tax","finance","math","conversion","date","health"]},"indexable":{"type":"boolean"},"toolCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Published, indexable tools listed in the category, including its subcategories"},"availability":{"description":"MAINTENANCE: the category page answers 503 until it is back online","$ref":"#/components/schemas/PublicAvailability"},"alternates":{"type":"array","items":{"type":"object","properties":{"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"}},"required":["locale","slug","path"],"additionalProperties":false}},"updatedAt":{"type":"string"}},"required":["key","locale","slug","path","name","description","ogImage","indexable","toolCount","availability","alternates","updatedAt"],"additionalProperties":false},"PublicCategoryTree":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"ogImage":{"type":"string","enum":["default","tax","finance","math","conversion","date","health"]},"indexable":{"type":"boolean"},"toolCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Published, indexable tools listed in the category, including its subcategories"},"availability":{"description":"MAINTENANCE: the category page answers 503 until it is back online","$ref":"#/components/schemas/PublicAvailability"},"alternates":{"type":"array","items":{"type":"object","properties":{"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"}},"required":["locale","slug","path"],"additionalProperties":false}},"updatedAt":{"type":"string"},"children":{"type":"array","items":{"$ref":"#/components/schemas/PublicCategoryNode"}}},"required":["key","locale","slug","path","name","description","ogImage","indexable","toolCount","availability","alternates","updatedAt","children"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"PublicRate":{"type":"object","properties":{"binding":{"type":"string"},"option":{"type":["string","null"]},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"value":{"type":"string"},"unit":{"type":"string"},"effectiveFrom":{"type":"string"},"effectiveTo":{"type":["string","null"]},"source":{"type":"string"},"sourceUrl":{"type":["string","null"]},"lastReviewedAt":{"type":["string","null"]}},"required":["binding","option","key","value","unit","effectiveFrom","effectiveTo","source","sourceUrl","lastReviewedAt"],"additionalProperties":false},"PublicTool":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([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)$","description":"Veritabanı kimliği (UUID). Ortamdan ortama değişir; entegrasyonlarda `key` kullanın."},"key":{"type":"string","description":"Kalıcı araç anahtarı (ör. `kdv`); tüm ortamlarda aynıdır."},"versionNumber":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Canlı sürüm numarası. Hesaplama isteğinde `version` olarak gönderirseniz araç güncellendiğinde 409 alırsınız."},"contentHash":{"type":["string","null"],"description":"Yayınlanmış sürümün içerik özeti; önbellek anahtarı olarak kullanılabilir."},"publishedAt":{"type":["string","null"]},"updatedAt":{"type":"string"},"category":{"type":"string","description":"Primary category key"},"availability":{"description":"MAINTENANCE: the page shows a maintenance notice (503) and calculations are refused","$ref":"#/components/schemas/PublicAvailability"},"categoryPath":{"type":"array","items":{"$ref":"#/components/schemas/CategoryRef"},"description":"Breadcrumb trail of the primary category, main category first"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryRef"},"description":"Every category the tool is listed in, primary first"},"disclaimer":{"type":"string","enum":["NONE","TAX","FINANCIAL","LEGAL","HEALTH"],"description":"Gösterilmesi gereken uyarı türü (`TAX`, `FINANCIAL`, `LEGAL`, `HEALTH` veya `NONE`)."},"indexable":{"type":"boolean","description":"Arama motorlarına açık mı (yalnızca web sitesi için anlamlı)."},"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string","description":"Web sitesindeki sayfa yolu (`https://mirac-ozdemir.com` ile birleştirin)."},"title":{"type":"string"},"content":{"$ref":"#/components/schemas/LocalizationContent","description":"Seçilen dildeki metinler; form etiketleri `content.labels` içindedir."},"seo":{"$ref":"#/components/schemas/LocalizationSeo"},"inputSchema":{"$ref":"#/components/schemas/ToolInputSchema","description":"Girdi tanımı: hangi alanlar, türleri, sınırları ve varsayılanları."},"outputSchema":{"$ref":"#/components/schemas/ToolOutputSchema","description":"Sonuç alanları ve biçimleri."},"uiSchema":{"$ref":"#/components/schemas/ToolUiSchema","description":"Form düzeni ve bileşen ipuçları (yalnızca sunum)."},"alternates":{"type":"array","items":{"type":"object","properties":{"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"}},"required":["locale","slug","path"],"additionalProperties":false}},"related":{"type":"array","items":{"type":"object","properties":{"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"},"key":{"type":"string"},"title":{"type":"string"},"shortDescription":{"type":"string"}},"required":["locale","slug","path","key","title","shortDescription"],"additionalProperties":false}},"ratesAsOf":{"type":"string","description":"Gösterilen oranların geçerli olduğu tarih (bugün, Europe/Istanbul)."},"rates":{"type":"array","items":{"$ref":"#/components/schemas/PublicRate"},"description":"Aracın kullandığı güncel oranlar ve kaynakları (gösterim amaçlı; hesaplama sunucuda yapılır)."}},"required":["id","key","versionNumber","contentHash","publishedAt","updatedAt","category","availability","categoryPath","categories","disclaimer","indexable","locale","slug","path","title","content","seo","inputSchema","outputSchema","uiSchema","alternates","related","ratesAsOf","rates"],"additionalProperties":false},"PublicToolLookup":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"tool"},"tool":{"$ref":"#/components/schemas/PublicTool"}},"required":["kind","tool"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"redirect"},"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"}},"required":["kind","locale","slug","path"],"additionalProperties":false}]}},"required":["data"],"additionalProperties":false},"PublicToolResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicTool"}},"required":["data"],"additionalProperties":false},"ToolInputField":{"description":"Bir girdi alanı; `type` değerine göre biçimi değişir.","oneOf":[{"$ref":"#/components/schemas/DecimalInputField"},{"$ref":"#/components/schemas/EnumInputField"},{"$ref":"#/components/schemas/BooleanInputField"},{"$ref":"#/components/schemas/DateInputField"}],"discriminator":{"propertyName":"type","mapping":{"decimal":"#/components/schemas/DecimalInputField","enum":"#/components/schemas/EnumInputField","boolean":"#/components/schemas/BooleanInputField","date":"#/components/schemas/DateInputField"}}},"ToolInputSchema":{"type":"object","description":"Aracın kabul ettiği girdiler. `fields` anahtarları, hesaplama isteğindeki `inputs` nesnesinin anahtarlarıdır. Alan türü `type` ile belirlenir. Tanımda olmayan bir alan gönderilirse `UNKNOWN_INPUT` hatası döner. Nesne anahtarlarının sırası garanti edilmez; form sırası için `uiSchema.sections[].fields` kullanın.","required":["fields"],"properties":{"fields":{"type":"object","description":"Alan adı → alan tanımı.","propertyNames":{"type":"string","pattern":"^[a-z][A-Za-z0-9_]{0,63}$"},"maxProperties":50,"additionalProperties":{"$ref":"#/components/schemas/ToolInputField"}}},"example":{"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"}}}},"ToolLabels":{"type":"object","description":"İstenen dildeki görünen metinler. Anahtarlar `inputSchema`, `outputSchema` ve `uiSchema` içindeki adlardır.","required":["inputs","outputs","sections"],"properties":{"inputs":{"type":"object","description":"Girdi alanı adı → etiketler. `options`, enum değerinin görünen adıdır.","additionalProperties":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"description":{"type":"string"},"placeholder":{"type":"string"},"help":{"type":"string"},"options":{"type":"object","additionalProperties":{"type":"string"}}}}},"outputs":{"type":"object","description":"Sonuç anahtarı → etiket.","additionalProperties":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"description":{"type":"string"}}}},"sections":{"type":"object","description":"Bölüm anahtarı → başlık.","additionalProperties":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string"}}}}},"example":{"inputs":{"amount":{"label":"Tutar","placeholder":"0,00","help":"Hesaplamak istediğiniz tutarı Türk lirası olarak girin."},"mode":{"label":"Girilen tutar","options":{"exclusive":"KDV hariç","inclusive":"KDV dahil"}},"vatRateOption":{"label":"KDV oranı","options":{"standard":"Genel oran","reduced10":"İndirimli oran","reduced1":"İndirimli oran (temel gıda vb.)"}}},"outputs":{"net":{"label":"KDV hariç tutar"},"vat":{"label":"KDV tutarı"},"gross":{"label":"KDV dahil tutar"}},"sections":{"main":{"title":"Hesaplama bilgileri"}}}},"ToolListItem":{"type":"object","properties":{"toolId":{"type":"string","format":"uuid","pattern":"^([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)$"},"key":{"type":"string","description":"Kalıcı araç anahtarı (ör. `kdv`); tüm ortamlarda aynıdır.","example":"kdv"},"locale":{"type":"string","enum":["tr","en"]},"slug":{"type":"string"},"path":{"type":"string"},"title":{"type":"string"},"shortDescription":{"type":"string"},"category":{"type":"string"},"availability":{"$ref":"#/components/schemas/PublicAvailability"},"score":{"type":"number"}},"required":["toolId","key","locale","slug","path","title","shortDescription","category","availability","score"],"additionalProperties":false},"ToolOutputField":{"type":"object","description":"Bir sonuç alanı. Değer her zaman string döner: ondalıklar tam `scale` haneyle (ör. `\"1200.00\"`), tarihler `YYYY-MM-DD`.","required":["key","type","format","scale"],"properties":{"key":{"type":"string","pattern":"^[a-z][A-Za-z0-9_]{0,63}$","description":"Sonuç anahtarı (`data.result` içindeki ad)."},"type":{"type":"string","enum":["decimal","date"]},"format":{"type":"string","enum":["money","percent","number","date"],"description":"Gösterim biçimi: `money` (para; `currency` dolu), `percent` (yüzde değeri; `\"20\"` = %20), `number`, `date`."},"scale":{"type":"integer","minimum":0,"maximum":10,"description":"Sonuçtaki ondalık hane sayısı (tarihlerde 0)."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 para birimi (ör. `TRY`); `money` biçiminde bulunur."},"unit":{"type":"string","description":"Varsa birim (ör. `gün`, `ay`)."}}},"ToolOutputSchema":{"type":"object","description":"Aracın ürettiği sonuçlar, gösterim sırasıyla. Hesaplama yanıtında `data.result` bu `key` değerleriyle, `data.breakdown` aynı sırayla döner.","required":["fields"],"properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/ToolOutputField"}}},"example":{"fields":[{"key":"net","type":"decimal","format":"money","currency":"TRY","scale":2},{"key":"vat","type":"decimal","format":"money","currency":"TRY","scale":2},{"key":"gross","type":"decimal","format":"money","currency":"TRY","scale":2}]}},"ToolReference":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"publisher":{"type":"string","minLength":2,"maxLength":120},"url":{"type":"string","maxLength":500,"format":"uri"}},"required":["title","url"],"additionalProperties":false},"ToolUiSchema":{"type":"object","description":"Yalnızca sunum ipuçları: form bölümleri, alan sırası ve bileşen önerileri. Hesaplamayı etkilemez; kendi arayüzünüzü kurarken kullanabilirsiniz.","required":["sections","fields"],"properties":{"sections":{"type":"array","description":"Form bölümleri, gösterim sırasıyla. Bölüm başlıkları `content.labels.sections.<key>` içindedir.","items":{"type":"object","required":["key","fields"],"properties":{"key":{"type":"string","pattern":"^[a-z][A-Za-z0-9_]{0,63}$"},"fields":{"type":"array","items":{"type":"string","pattern":"^[a-z][A-Za-z0-9_]{0,63}$"},"description":"Bu bölümdeki girdi alanları, sırasıyla."}}}},"fields":{"type":"object","description":"Girdi alanı adı → sunum ipucu.","propertyNames":{"type":"string","pattern":"^[a-z][A-Za-z0-9_]{0,63}$"},"additionalProperties":{"type":"object","required":["widget"],"properties":{"widget":{"type":"string","enum":["number","money","percent","date","select","radio","checkbox","switch"],"description":"Önerilen form bileşeni."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"`money` bileşeni için para birimi."},"showRateValues":{"type":"boolean","description":"Oran seçimine bağlı enum alanlarında her seçeneğin yanında güncel oranı (`rates[]`) gösterin."},"visibleWhen":{"type":"object","description":"Alan yalnızca belirtilen girdi bu değere eşitken gösterilir. Gizli alan için değer göndermeyin (varsayılan kullanılır).","required":["input","equals"],"properties":{"input":{"type":"string","pattern":"^[a-z][A-Za-z0-9_]{0,63}$"},"equals":{"type":["string","boolean"]}}},"width":{"type":"string","enum":["full","half"]}}}},"result":{"type":"object","properties":{"highlight":{"type":"array","items":{"type":"string","pattern":"^[a-z][A-Za-z0-9_]{0,63}$"},"description":"Öne çıkarılacak sonuç anahtarları."}}}},"example":{"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"]}}}},"headers":{"XRequestId":{"description":"İstek kimliği; destek taleplerinde iletin.","schema":{"type":"string"}},"RetryAfter":{"description":"Tekrar denemeden önce beklenecek saniye.","schema":{"type":"integer","minimum":1}},"RateLimitLimit":{"description":"Penceredeki toplam istek hakkı.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Penceredeki kalan istek hakkı.","schema":{"type":"integer"}}}}}