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

MCP, tool'lari, discovery'yi ve invocation'i agent dostu bir formatta anlatir. Bir istemci once kaynaklari ve tool semalarini gormek istiyorsa /api/mcp kullanilir.

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 ve MCP discovery 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

Temel endpoint'ler

/api/openapi

OpenAPI spesifikasyonu (Swagger uyumlu)

/api/mcp

MCP discovery ve gateway

/api/berechne

Dogrudan payroll/vergi cagrisi

/api/taxcompare

Dogrudan salary compare cagrisi

Quickstart

  1. 1. Uretim ya da yuksek limit ihtiyaci icin API key talep et
  2. 2. Asagidaki ornek request'lerden birini kopyalayip gonder
  3. 3. Donen response'u kendi kullanim senaryonla kontrol et
  4. 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": 0.3375,
      "input_annual_gross": 60000,
      "input_currency": "eur",
      "comparison_basis": "shared_gross"
    }
  ]
}

Errors

Typical error codes:

  • - 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
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 '{
    "tool": "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.

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.