API

Developer API

Obolus, payroll ve tax-compare akislari icin sade bir public API sunar. MCP ve OpenAPI ayni public tool scope'unu anlatir.

Durum

Developer API bilerek dar tutulmustur ve su an payroll ile tax-compare akislari uzerine odaklanir. Scope kontrollu sekilde genisletilir ve su anda early public durumundadir.

MCP

Gercek remote MCP transport endpoint'i /api/mcp altindadir ve ChatGPT ile diger MCP client'lari icin tasarlanmistir. JSON discovery bilgisi ise ayri olarak /api/mcp-discovery uzerinden sunulur.

OpenAPI

OpenAPI, ayni public tool setinin REST odakli tanimidir. Swagger uyumlu dokumantasyon, client generation ve resmi schema ihtiyaci icin /api/openapi kullanilir.

Neler acik?

Su anki public scope, MCP ve OpenAPI discovery ile berechne, taxcompare tool'larini kapsar. Cockpit, Budget ve Invest urun ici akislardir ve public API olarak yayinlanmaz.

Hangi arayuz ne icin uygun?

Cogu public entegrasyon icin en mantikli secim OpenAPI ile REST ve dogrudan tool endpoint'leridir. MCP ise agent'ler ve discovery artı invoke akisi isteyen istemciler icin daha uygundur.

REST + OpenAPI

Klasik entegrasyonlar, dashboard'lar, backend servisleri, SDK generation ve geleneksel API client'lari icin onerilir.

MCP

AI agent'ler, tool runner'lar ve discovery ile invocation'i ayni kompakt, makinece okunabilir tanimda kullanmak isteyen sistemler icin onerilir.

Kimlik dogrulama

API key, uretim kullanimlari icin tasarlanmistir ve bazi endpoint'ler bugun auth'suz erisilebilir olsa bile tum request'lerde kullanilmasi onerilir. Public entegrasyonlar icin tercih edilen header x-public-api-key'dir.

  • Tercih edilen header: x-public-api-key: <key>
  • Alternatif olarak x-api-key veya Authorization: Bearer <token> desteklenir
  • OpenAPI, MCP discovery ve MCP transport ilgili deployment'a gore acik veya key-korumali olabilir
  • Stabil entegrasyonlar icin her zaman API key kullanilmasi onerilir
  • API key su anda self-service uretilmez; erisim ve yuksek limit icin dogrudan iletisim gerekir

Versiyonlama

Public API su anda /v1 URL'leri yerine contract versiyonu ile version edilir. API versiyonu: 2.1.0. MCP versiyonu: 1.0.1. Breaking change'ler yeni bir contract versiyonu ile yayinlanir; ekleyici degisiklikler ayni versiyon icinde gelebilir.

Locale ve URL yapisi

API'nin kendisi dil-noytrdur ve /api/... altinda calisir; locale prefix kullanmaz. /de, /en ve /tr sadece dokumantasyon icindir, API endpoint'i degildir.

Rate limit ve web trafigi

Rate limit mantigi route seviyesinde calisir ve web trafigi ile harici API kullanimini ayni endpoint'i kullandiklarinda ayni sekilde uygular. taxcompare icin mevcut limit route basina 5 dakikada 20 istektir; berechne cache miss durumlarinda 5 dakikada 1000 istege izin verir. berechne cache hit'leri limit kontrolunden once cevaplanabilir.

Onemli parametreler

  • Desteklenen ulke kodlari: DE, AT, US, CH, CA, AU, UK, IE
  • taxcompare icin minimum alanlar: annual_gross, tax_year, countries, currency
  • taxcompare currency alaninda eur, usd, chf, cad, aud, gbp gibi lower-case ISO degerleri kullanilir
  • taxcompare gross_mode shared_gross ve local_median_gross degerlerini destekler
  • tax_year su anda string veya integer olabilir; tipik deger 2026'dir
  • berechne bircok tutari cent gibi minor units cinsinden bekler

Input ve Output Parametreleri

Arama ve hizli yonelim icin kisa ozet yeterlidir: ayni public tool contract'lari tum desteklenen ulkeleri kapsar, ancak tek tek payroll alanlarinin anlami vergi sistemine gore degisir.

  • Input alanlari birden fazla ulke icin ortak request surface'i tanimlar.
  • Output alanlari contract seviyesinde stabil kalir, ancak is anlami ulkeye gore degisebilir.
  • Tum ulkeleri iceren ayrintili matris interaktif kalir ve client-side olarak yuklenir.

Temel endpoint'ler

/api/openapi

OpenAPI spesifikasyonu (Swagger uyumlu)

/api/mcp-discovery

Tool scope, metadata ve docs icin JSON discovery

/api/mcp

ChatGPT ve diger MCP client'lari icin Streamable HTTP MCP transport

/api/berechne

Dogrudan payroll/vergi cagrisi

/api/taxcompare

Dogrudan salary compare cagrisi

Quickstart

  1. Uretim ya da yuksek limit ihtiyaci icin API key talep et
  2. Asagidaki ornek request'lerden birini kopyalayip gonder
  3. Donen response'u kendi kullanim senaryonla kontrol et
  4. Gerektiginde detayli alanlar icin /api/openapi contract'ina bak

Response ve error modeli

Basarili cevaplar global bir ok/data envelope kullanmaz; bunun yerine dogrudan tool'e ozel response yapilari dondurur. Ayni contract versiyonu icinde ayni input'lar icin response'lar deterministiktir. Ayni contract versiyonu icinde response yapilari stabil kalir. Hata cevaplari ise error ve duruma gore details veya restricted_fields alanlariyla doner.

Ornek cevap (taxcompare, kisaltilmis):

{
  "results": [
    {
      "country": "DE",
      "net": 39750,
      "tax": 13000,
      "social_contributions": 7250,
      "effective_rate": 33.75,
      "input_annual_gross": 60000,
      "input_currency": "eur",
      "comparison_basis": "shared_gross"
    }
  ]
}

Errors

Ornek hata kodlari:

  • 400 validation error
  • 401 missing or invalid key
  • 403 restricted field access
  • 429 rate limiting
  • 500 internal server error
{
  "error": "Invalid taxcompare payload.",
  "details": [
    "body.countries must contain at least 1 items."
  ]
}

Ornekler

curl -s https://www.obolusfinanz.de/api/openapi
curl -s https://www.obolusfinanz.de/api/mcp-discovery
curl -N -H "Accept: text/event-stream" https://www.obolusfinanz.de/api/mcp
curl -X POST https://www.obolusfinanz.de/api/taxcompare \
  -H "Content-Type: application/json" \
  -H "x-public-api-key: YOUR_API_KEY" \
  -d '{
    "annual_gross": 60000,
    "tax_year": "2026",
    "countries": ["DE", "AT", "AU"],
    "currency": "eur"
  }'
curl -X POST https://www.obolusfinanz.de/api/mcp \
  -H "Content-Type: application/json" \
  -H "x-public-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "taxcompare",
      "arguments": {
        "annual_gross": 60000,
        "tax_year": "2026",
        "countries": ["DE", "AT", "AU"],
        "currency": "eur"
      }
    }
  }'

Not

MCP ve OpenAPI ayni contract kaynagindan uretilir. Bu contract kaynagi public API icin baglayici referanstir. Backend degisiklikleri public contract ile birlikte yayinlanmalidir.

API Kullanimı & Kurallar

Obolus API, gercek dunya finans araclari icin sade, acik ve faydali olacak sekilde tasarlanmistir.

Su alanlarda kullanabilirsin:

  • kisisel projeler
  • prototipler ve deneyler
  • ic araclar
  • kamuya acik uygulamalar

Dikkat edilmesi gerekenler:

  • asiri otomatik trafik veya suistimalden kacin
  • ham API ciktilarini tek basina bir urun olarak yeniden satmayin
  • API'yi daha genis bir uygulama veya is akisinin parcasi olarak kullanin

Atif

API'yi kamuya acik bir urunde kullaniyorsan, kucuk bir referans memnuniyetle karsilanir:

Powered by Obolus

Stabilite

API aktif olarak gelisiyor. Temel endpoint'ler stabil tutulur, ancak response yapilari zamanla iyilestirilebilir. Uretim kullaniminda response'lari daha savunmaci sekilde islemek iyi bir yaklasimdir.

Support

Public API sorulari, API key talebi, manuel erisim ya da daha yuksek limitler icin sitedeki contact ya da feedback formunu kullan; boylece API key alabilir veya limit ayari isteyebilirsin.