API

Obolus Maaş ve Vergi API: REST ve MCP

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

Genel MCP istemcileri icin /api/mcp/public kullanilir; /api/mcp/claude uyumlu bir eski adres olarak kalir. ChatGPT uygulamasi /api/mcp kullanir. Arac kapsaminin JSON tanimi /api/mcp-discovery adresindedir.

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.

Agent discovery

Obolus publishes a Model Context Protocol (MCP) server for tax calculation, a Claude-compatible MCP endpoint, and an OpenAPI specification so AI agents, developer tools, and LLM crawlers can discover the public payroll and tax comparison API surface.

OpenAPI specification

Swagger-compatible OpenAPI specification for the Obolus REST API, including payroll and tax comparison schemas.

MCP discovery descriptor

Machine-readable descriptor for the public Obolus Model Context Protocol tool scope.

MCP Server for Tax Calculation

Remote Model Context Protocol (MCP) server for tax calculation, net salary workflows, and country tax comparison agents.

Public MCP Server for Tax Calculation

Agent-neutral read-only Model Context Protocol endpoint for Obolus payroll and tax comparison tools.

Claude MCP Server for Tax Calculation

Claude-compatible tool-only Model Context Protocol endpoint for Obolus payroll and tax comparison tools.

llms.txt

AI-system orientation file listing canonical Obolus pages and machine-readable API resources.

ChatGPT App

Obolus ChatGPT App, global net gelir ve maaş karşılaştırmaları için aynı açık MCP ve API yüzeyini kullanır. Ayrı bir tüketici akışı değil, Obolus hesaplama çekirdeğinin teknik entegrasyonudur.

Obolus'u ChatGPT'de aç

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

Herkese acik, salt okunur hesaplama araclari oturum veya API anahtari olmadan kullanilabilir. Entegrasyonlar icin API anahtari istege baglidir; bazi dagitimlarda belirli endpoint'ler icin gerekli olabilir. Tercih edilen baslik x-public-api-key'dir.

  • Tercih edilen header: x-public-api-key: <key>
  • Alternatifler: x-api-key veya Authorization: Bearer <API anahtari> (uyumluluk takma adi; OAuth tokeni degil)
  • OpenAPI, MCP discovery ve MCP transport ilgili deployment'a gore acik veya key-korumali olabilir
  • Herkese acik MCP hesaplama araclari icin tarayici oturumu gerekmez
  • API anahtarlari su anda kullanici tarafindan olusturulamaz; gerekirse iletisim formunu kullanin

Versiyonlama

API, /v1 URL'leri yerine contract surumleri kullanir. API contract: 2.1.0; MCP arac contract'i: 1.0.1. Desteklenen MCP protokol nesilleri: 2025-11-25, 2026-07-28. Contract ve protokol surumleri farkli bilgilerdir.

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

REST limitleri: taxcompare 20 requests / 5 minutes; berechne 60 requests / 5 minutes (cache miss). MCP transport: POST 200 requests / 5 minutes, GET 100 requests / 5 minutes; iki MCP endpoint'inin limitleri ayridir. MCP araci ve dogrulanmis API anahtari basina ek limitler yalnizca sunucu ayarlarinda etkinlestirilirse uygulanir. berechne cache hit'leri REST limit kontrolunden once cevaplanabilir.

Onemli parametreler

  • Desteklenen ulke kodlari: DE, AT, US, CH, CA, AU, UK, IE
  • shared_gross modunda taxcompare: salary_ct (tam sayi, kurusun karsiligi), tax_year, countries, currency ve gross_mode
  • local_median_gross modunda taxcompare: tax_year, countries, currency ve gross_mode; maas girdisi gerekmez
  • taxcompare currency alani EUR veya eur gibi buyuk ya da kucuk harfli ISO kodlarini kabul eder; yanitlarda kodlar kucuk harfe donusturulur
  • taxcompare gross_mode shared_gross ve local_median_gross degerlerini destekler
  • tax_year su anda string veya integer olabilir; tipik deger 2026'dir
  • DE icin berechne: country, tax_year ve amount, currency, period alanlarini iceren gross_salary tercih edilir; location, tax ve social_security profili tanimlar. gross_salary.amount ana para birimindedir: yillik 60.000 EUR icin 60000
  • Personen[].Gehalt_ct gibi eski berechne alanlari mevcut entegrasyonlar icin desteklenir ve alt para birimi kullanir: yillik 60.000 EUR icin 6000000 cent. Diger ulkelerin ayrintili hesaplari simdilik bu eski alanlari kullanir

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/mcp/public

Tum istemciler icin acik MCP hesaplama araclari

/api/mcp/claude

ChatGPT arayuz metadatasi olmadan onceki MCP adresi

/api/berechne

Dogrudan payroll/vergi cagrisi

/api/taxcompare

Dogrudan salary compare cagrisi

Quickstart

  1. Herkese acik ornek istegi oturum olmadan gonder; gerekirse API anahtari iste
  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 REST yanitlari genel bir ok/data zarfi yerine araca ozel yapilar dondurur. MCP yanitlari ayrica ana para biriminde tutarlarin ozetini ve varsa hesaplama zamani, veri ve yontem surumu, varsayimlar, uyarilar ve backend'den gelen engine_revision bilgisini icerir. Vergi verileri veya doviz kuru degistiginde ayni girdiler farkli sonuc verebilir. REST hatalari error ve gerekirse details veya restricted_fields icerir.

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" \
  -d '{
    "salary_ct": 6000000,
    "tax_year": "2026",
    "countries": ["DE", "AT", "AU"],
    "currency": "eur",
    "gross_mode": "shared_gross"
  }'
curl -X POST https://www.obolusfinanz.de/api/taxcompare \
  -H "Content-Type: application/json" \
  -d '{
    "tax_year": "2026",
    "countries": ["DE", "CH", "UK"],
    "currency": "eur",
    "gross_mode": "local_median_gross"
  }'
curl -X POST https://www.obolusfinanz.de/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "taxcompare",
      "arguments": {
        "salary_ct": 6000000,
        "tax_year": "2026",
        "countries": ["DE", "AT", "AU"],
        "currency": "eur",
        "gross_mode": "shared_gross"
      }
    }
  }'

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.