Overview

Mirac Özdemir Hesaplama API 1.0.0

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.

Temel adres: https://api.mirac-ozdemir.com/v1/public
Kimlik doğrulama: Yok. API anahtarı gerekmez.
Biçim: JSON (Content-Type: application/json), UTF-8.

Hızlı başlangıç

Aracı bulun: GET /v1/public/search?locale=tr&q=kdv → her sonuçta kalıcı key (ör. kdv).
Tanımı alın: GET /v1/public/tools/by-key/kdv?locale=tr → inputSchema, outputSchema, uiSchema, content.labels, versionNumber.
Hesaplayın:

curl -X POST https://api.mirac-ozdemir.com/v1/public/tools/by-key/kdv/calculate \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"amount":"1000","mode":"exclusive","vatRateOption":"standard"}}'
# → {"data":{"result":{"net":"1000.00","vat":"200.00","gross":"1200.00"},...},"meta":{...}}

Temel kavramlar

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.
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.
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.
Boolean: JSON true / false. Tarih: YYYY-MM-DD.
İsteğe bağlı alanlar: required: false alanlar gönderilmezse default kullanılır. Tanımda olmayan alan gönderilirse UNKNOWN_INPUT.
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.
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.

CORS

Bu 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.

Hız sınırları

Uç	Sınır
Hesaplama (`calculateByKey`, `calculateTool`; ortak sayılır)	IP başına 60 istek / 60 sn
Arama (`searchTools`)	IP başına 60 istek / 60 sn

Sı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.

Hatalar

Tüm hatalar aynı zarfla döner; mantığınızı error.code üzerine kurun (message İngilizcedir ve değişebilir):

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid calculation input", "details": { "fields": [ { "field": "amount", "reason": "TYPE_MISMATCH", "message": "amount must be a decimal string" } ] } }, "requestId": "5f0c6a5e-…" }

Kod	HTTP	Ne zaman
`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"`.
`NOT_FOUND`	404	Araç yok, yayında değil veya istenen dilde değil; bilinmeyen adres.
`CONFLICT`	409	`details.reason = "VERSION_OUTDATED"`: gönderilen `version` artık canlı değil.
`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.
`RATE_UNAVAILABLE`	422	`asOf` tarihinde yürürlükte oran yok (`details.rates`, `details.asOf`) veya oran kullanılamıyor (`details.reason`).
`PAYLOAD_TOO_LARGE`	413	Gövde 16 KB’ı aşıyor.
`RATE_LIMITED`	429	Hız sınırı aşıldı; `Retry-After` saniye bekleyin.
`TIMEOUT`	504	İstek 15 sn içinde tamamlanamadı; tekrar deneyin.
`SERVICE_UNAVAILABLE`	503	Hizmet geçici olarak kullanılamıyor; daha sonra tekrar deneyin.
`MAINTENANCE`	503	Araç geçici olarak bakımda (`availability: "MAINTENANCE"`); `Retry-After` başlığı kadar (`details.retryAfterSeconds`) bekleyip yeniden deneyin.
`INTERNAL_ERROR`	500	Beklenmeyen hata; ayrıntı yalnızca sunucu kayıtlarındadır (`requestId` ile).

X-Request-Id

Her 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.

Kod 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.

Sorumluluk reddi

Sonuç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.

Mirac Özdemir

https://mirac-ozdemir.com

Information

OpenAPI version: 3.1.0