Araç keşfi

Üç uç, katalogdaki araçları bulmanıza yardım eder. Hepsi locale (tr veya en) ister.

Arama

curl "https://api.mirac-ozdemir.com/v1/public/search?locale=tr&q=kdv&pageSize=2"

Parametre	Zorunlu	Açıklama
locale	evet	tr veya en.
q	hayır	Arama metni, en çok 100 karakter. Boşsa tüm araçlar sıralanır.
category	hayır	Kategori anahtarı. Ana kategori, alt kategorilerini de kapsar.
page	hayır	Varsayılan 1.
pageSize	hayır	Varsayılan 20, en çok 50.

{
  "data": [
    {
      "toolId": "7fbb657f-1877-4d62-a586-c0595b30f5e6",
      "key": "kdvli-fiyat-karsilastirma",
      "locale": "tr",
      "slug": "kdvli-fiyat-karsilastirma",
      "title": "KDV'li Fiyat Karşılaştırma (İki Teklif)",
      "shortDescription": "KDV dahil veya hariç, farklı KDV oranlarıyla verilmiş iki teklifi gerçek maliyetinize göre karşılaştırın.",
      "category": "kdv",
      "availability": "ONLINE",
      "score": 3.149,
      "path": "/tr/araclar/kdvli-fiyat-karsilastirma"
    }
  ],
  "meta": { "page": 1, "pageSize": 2, "total": 33, "totalPages": 17 }
}

• Arama Türkçe karakterleri ve yazım varyasyonlarını (kdv, k.d.v.) tolere eder.
• score ilgililik puanıdır; sonuçlar bu sıraya göre gelir.
• Arama uçları hız sınırlıdır (dakikada 60); sonuçları önbelleğe alın ve arama kutusunda kullanıcı yazarken gecikmeli (debounce) istek atın.

Listeleme

curl "https://api.mirac-ozdemir.com/v1/public/tools?locale=tr&category=kdv&page=1&pageSize=20"

searchTools ile aynı alanları döner. pageSize üst sınırı 100’dür. Tüm kataloğu çekmek için meta.totalPages kadar sayfayı dolaşın:

JavaScript

async function listAllTools(locale = 'tr') {
  const items = [];
  for (let page = 1; ; page += 1) {
    const url = `https://api.mirac-ozdemir.com/v1/public/tools?locale=${locale}&page=${page}&pageSize=100`;
    const { data, meta } = await (await fetch(url)).json();
    items.push(...data);
    if (page >= meta.totalPages) return items;
  }
}

Python

import requests

def list_all_tools(locale="tr"):
    items, page = [], 1
    while True:
        r = requests.get(
            "https://api.mirac-ozdemir.com/v1/public/tools",
            params={"locale": locale, "page": page, "pageSize": 100},
            timeout=15,
        ).json()
        items += r["data"]
        if page >= r["meta"]["totalPages"]:
            return items
        page += 1

İpucu

Tüm kataloğun anlık görüntüsü Araç kataloğu sayfasında aranabilir biçimde yer alır.

Kategoriler

curl "https://api.mirac-ozdemir.com/v1/public/categories?locale=tr"

Yanıt, ana kategorilerden ve alt kategorilerden oluşan bir ağaçtır:

{
  "data": [
    {
      "key": "tax",
      "locale": "tr",
      "slug": "vergi",
      "path": "/tr/kategori/vergi",
      "name": "Vergi",
      "description": "KDV, gelir vergisi, stopaj, harçlar…",
      "toolCount": 116,
      "availability": "ONLINE",
      "alternates": [
        { "locale": "tr", "slug": "vergi", "path": "/tr/kategori/vergi" },
        { "locale": "en", "slug": "tax", "path": "/en/category/tax" }
      ],
      "children": [{ "key": "kdv", "name": "KDV Araçları", "toolCount": 13 }]
    }
  ]
}

Kategori key’ini category parametresinde kullanarak listeyi daraltabilirsiniz (category=tax tüm alt kategorileri de kapsar). availability: "MAINTENANCE" olan bir kategorideki araçlar geçici olarak hesaplanamaz.

Site adresinden araç çözümleme

Web sitesinin adresini (/tr/araclar/kdv-hesaplama) elinizde tutuyorsanız by-slug ucu aracı çözümler:

curl "https://api.mirac-ozdemir.com/v1/public/tools/by-slug/tr/kdv-hesaplama"

Yanıt iki biçimden biridir: kind: "tool" (araç tanımı) veya kind: "redirect" (slug değişmişse yeni adres: locale, slug, path). Entegrasyonlar için kalıcı key ile by-key kullanmak daha güvenlidir.