Araç sayfasını slug ile çözümle

GET

/v1/public/tools/by-slug/{locale}/{slug}

curl --request GET \
  --url https://api.mirac-ozdemir.com/v1/public/tools/by-slug/tr/example

• Production

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.

Parameters

Path Parameters

locale

required

string

Allowed values: tr en

İçerik dili: tr veya en. Zorunludur; araç o dilde yoksa 404 döner.

slug

required

string

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

Yerelleştirilmiş sayfa slug’ı (ör. kdv-hesaplama).

Responses

200

Araç verisi veya yönlendirme

Media typeapplication/json

object

data

required

One of:

object

object

kind

required

string

Allowed value: tool

tool

required

object

id

required

Veritabanı kimliği (UUID). Ortamdan ortama değişir; entegrasyonlarda key kullanın.

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)$/

key

required

Kalıcı araç anahtarı (ör. kdv); tüm ortamlarda aynıdır.

string

versionNumber

required

Any of:

integer

integer

>= -9007199254740991 <= 9007199254740991

null

null

contentHash

required

Yayınlanmış sürümün içerik özeti; önbellek anahtarı olarak kullanılabilir.

string | null

publishedAt

required

string | null

updatedAt

required

string

category

required

Primary category key

string

availability

required

MAINTENANCE: the page shows a maintenance notice (503) and calculations are refused

string

Allowed values: ONLINE MAINTENANCE

categoryPath

required

Breadcrumb trail of the primary category, main category first

Array<object>

object

key

required

string

slug

required

string

name

required

string

path

required

string

categories

required

Every category the tool is listed in, primary first

Array<object>

object

key

required

string

slug

required

string

name

required

string

path

required

string

disclaimer

required

Gösterilmesi gereken uyarı türü (TAX, FINANCIAL, LEGAL, HEALTH veya NONE).

string

Allowed values: NONE TAX FINANCIAL LEGAL HEALTH

indexable

required

Arama motorlarına açık mı (yalnızca web sitesi için anlamlı).

boolean

locale

required

string

Allowed values: tr en

slug

required

string

path

required

Web sitesindeki sayfa yolu (https://mirac-ozdemir.com ile birleştirin).

string

title

required

string

content

required

Seçilen dildeki metinler; form etiketleri content.labels içindedir.

object

shortDescription

required

string

0 <= 300 characters

longDescription

required

string

<= 20000 characters

instructions

required

string

<= 10000 characters

notes

required

string

<= 10000 characters

warnings

required

Array<string>

<= 10 items

faq

required

Array<object>

<= 30 items

object

question

required

string

>= 1 characters <= 300 characters

answer

required

string

<= 5000 characters

keywords

required

Array<string>

<= 30 items

references

Array<object>

<= 8 items

object

title

required

string

>= 3 characters <= 200 characters

publisher

string

>= 2 characters <= 120 characters

url

required

string format: uri

<= 500 characters

labels

required

Form ve sonuç etiketleri.

object

inputs

required

Girdi alanı adı → etiketler. options, enum değerinin görünen adıdır.

object

key

additional properties

object

label

required

string

description

string

placeholder

string

help

string

options

object

key

additional properties

string

outputs

required

Sonuç anahtarı → etiket.

object

key

additional properties

object

label

required

string

description

string

sections

required

Bölüm anahtarı → başlık.

object

key

additional properties

object

title

required

string

description

string

seo

required

object

metaTitle

required

string

0 <= 120 characters

metaDescription

required

string

0 <= 300 characters

ogTitle

string

0 <= 120 characters

ogDescription

string

0 <= 300 characters

ogImage

required

string

Allowed values: default tax finance math conversion date health

robotsIndex

required

boolean

robotsFollow

required

boolean

inputSchema

required

Girdi tanımı: hangi alanlar, türleri, sınırları ve varsayılanları.

object

fields

required

Alan adı → alan tanımı.

object

<= 50 properties

key

additional properties

One of: discriminator: type

object

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

object

type

required

Allowed value: decimal

required

required

true ise değer gönderilmelidir. false ise gönderilmeyen alan için default kullanılır.

boolean

scale

required

İzin verilen azami ondalık hane sayısı; fazlası SCALE_EXCEEDED hatası verir.

integer

<= 10

min

Alt sınır (dahil), ondalık string. Dışındaki değerler OUT_OF_RANGE.

string

max

Üst sınır (dahil), ondalık string.

string

default

Değer gönderilmezse kullanılan varsayılan.

string

object

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.

object

type

required

Allowed value: enum

required

required

true ise değer gönderilmelidir. false ise gönderilmeyen alan için default kullanılır.

boolean

values

required

Geçerli değerler (sabit, dile göre değişmez).

Array<string>

>= 1 items <= 50 items

default

Varsayılan seçenek (values içinden).

string

object

Evet/hayır. JSON true / false olarak gönderilir.

object

type

required

Allowed value: boolean

required

required

true ise değer gönderilmelidir. false ise gönderilmeyen alan için default kullanılır.

boolean

default

boolean

object

Takvim tarihi, YYYY-MM-DD biçiminde string.

object

type

required

Allowed value: date

required

required

true ise değer gönderilmelidir. false ise gönderilmeyen alan için default kullanılır.

boolean

min

En erken tarih (dahil).

string format: date

max

En geç tarih (dahil).

string format: date

default

string format: date

outputSchema

required

Sonuç alanları ve biçimleri.

object

fields

required

Array<object>

Bir sonuç alanı. Değer her zaman string döner: ondalıklar tam scale haneyle (ör. "1200.00"), tarihler YYYY-MM-DD.

object

key

required

Sonuç anahtarı (data.result içindeki ad).

string

/^[a-z][A-Za-z0-9_]{0,63}$/

type

required

string

Allowed values: decimal date

format

required

Gösterim biçimi: money (para; currency dolu), percent (yüzde değeri; "20" = %20), number, date.

string

Allowed values: money percent number date

scale

required

Sonuçtaki ondalık hane sayısı (tarihlerde 0).

integer

<= 10

currency

ISO 4217 para birimi (ör. TRY); money biçiminde bulunur.

string

/^[A-Z]{3}$/

unit

Varsa birim (ör. gün, ay).

string

uiSchema

required

Form düzeni ve bileşen ipuçları (yalnızca sunum).

object

sections

required

Form bölümleri, gösterim sırasıyla. Bölüm başlıkları content.labels.sections.<key> içindedir.

Array<object>

object

key

required

string

/^[a-z][A-Za-z0-9_]{0,63}$/

fields

required

Bu bölümdeki girdi alanları, sırasıyla.

Array<string>

fields

required

Girdi alanı adı → sunum ipucu.

object

key

additional properties

object

widget

required

Önerilen form bileşeni.

string

Allowed values: number money percent date select radio checkbox switch

currency

money bileşeni için para birimi.

string

/^[A-Z]{3}$/

showRateValues

Oran seçimine bağlı enum alanlarında her seçeneğin yanında güncel oranı (rates[]) gösterin.

boolean

visibleWhen

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

object

input

required

string

/^[a-z][A-Za-z0-9_]{0,63}$/

equals

required

string | boolean

width

string

Allowed values: full half

result

object

highlight

Öne çıkarılacak sonuç anahtarları.

Array<string>

alternates

required

Array<object>

object

locale

required

string

Allowed values: tr en

slug

required

string

path

required

string

related

required

Array<object>

object

locale

required

string

Allowed values: tr en

slug

required

string

path

required

string

key

required

string

title

required

string

shortDescription

required

string

ratesAsOf

required

Gösterilen oranların geçerli olduğu tarih (bugün, Europe/Istanbul).

string

rates

required

Aracın kullandığı güncel oranlar ve kaynakları (gösterim amaçlı; hesaplama sunucuda yapılır).

Array<object>

object

binding

required

string

option

required

string | null

key

required

string

name

string

description

string | null

value

required

string

unit

required

string

effectiveFrom

required

string

effectiveTo

required

string | null

source

required

string

sourceUrl

required

string | null

lastReviewedAt

required

string | null

object

object

kind

required

string

Allowed value: redirect

locale

required

string

Allowed values: tr en

slug

required

string

path

required

string

Example

{
  "data": {
    "kind": "tool",
    "tool": {
      "availability": "ONLINE",
      "disclaimer": "NONE",
      "locale": "tr",
      "content": {
        "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": {
        "ogImage": "default"
      },
      "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"
        }
      ],
      "related": [
        {
          "locale": "tr"
        }
      ]
    }
  }
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

404

Bulunamadı

Media typeapplication/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

ExamplenotFound

Araç yok, yayında değil veya bu dilde yok

{
  "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.

422

Doğrulama, hesaplama veya oran hatası

Media typeapplication/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

ExampleinvalidParameter

Geçersiz parametre

{
  "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"
}

Headers

X-Request-Id

string

İstek kimliği; destek taleplerinde iletin.

500

Beklenmeyen sunucu hatası

Media typeapplication/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.