API

Developer API

Obolus stellt eine schlanke oeffentliche API fuer Payroll- und Tax-Compare-Workflows bereit. MCP und OpenAPI beschreiben denselben freigegebenen Tool-Scope.

Status

Die Developer API ist bewusst schlank gehalten und deckt derzeit Payroll- und Tax-Compare-Workflows ab. Der Scope wird kontrolliert erweitert und befindet sich aktuell im Early Public Status.

MCP

MCP beschreibt Tools, Discovery und Invocation in einem agentenfreundlichen Format. Verwende /api/mcp, wenn ein Client zuerst Ressourcen, Tools und Invocation-Schemas sehen soll.

OpenAPI

OpenAPI ist die REST-orientierte Spezifikation derselben oeffentlichen Tools. Verwende /api/openapi fuer Swagger-kompatible Dokumentation, Client-Generierung und formale Request/Response-Schemas.

Was ist oeffentlich?

Der aktuelle Public Scope umfasst Discovery ueber MCP und OpenAPI sowie die beiden Tools berechne und taxcompare. Cockpit-, Budget- und Invest-Interaktionen bleiben bewusst Produkt-Flow und werden nicht als Public API veroeffentlicht.

Welche Schnittstelle ist fuer was gedacht?

Fuer die meisten oeffentlichen Integrationen ist REST ueber OpenAPI plus direkter Tool-Call die richtige Wahl. MCP ist die bessere Schicht fuer Agenten, Tool-Runtime-Systeme und Clients, die Discovery und Invocation ueber einen Gateway-Ansatz brauchen.

REST + OpenAPI

Empfohlen fuer klassische Integrationen, Dashboards, Backend-Services, SDK-Generierung und konventionelle API-Clients.

MCP

Empfohlen fuer AI-Agents, Tool-Runner und Systeme, die Tool-Discovery und Invocation ueber eine kompakte, maschinenlesbare Beschreibung verwenden wollen.

Authentifizierung

API-Keys sind fuer produktive Nutzung vorgesehen und sollten in allen Requests verwendet werden, auch wenn einzelne Endpunkte aktuell noch ohne Auth erreichbar sein koennen. Fuer oeffentliche Integrationen ist x-public-api-key der bevorzugte Header.

  • - Bevorzugter Header: x-public-api-key: <key>
  • - Alternativ unterstuetzt: x-api-key oder Authorization: Bearer <token>
  • - OpenAPI- und MCP-Discovery koennen offen oder key-geschuetzt sein, abhaengig vom jeweiligen Deployment.
  • - Fuer stabile Integrationen sollte immer ein API-Key verwendet werden.
  • - API-Keys koennen aktuell nicht self-service erzeugt werden; fuer Access und hoehere Limits ist direkter Kontakt noetig.

Versionierung

Die oeffentliche API wird aktuell ueber die Contract-Version statt ueber /v1-URLs versioniert. API-Version: 2.1.0. MCP-Version: 1.0.1. Nicht abwaertskompatible Aenderungen werden mit einer neuen Contract-Version ausgerollt; additive Erweiterungen koennen innerhalb derselben Version erfolgen.

Locale und URL-Struktur

Die API selbst ist sprachneutral und lebt unter /api/..., nicht unter einem Locale-Praefix. Die /de-, /en- und /tr-Pfade gelten fuer die Dokumentation, nicht fuer die API-Endpunkte.

Rate Limits und Website-Traffic

Rate Limits gelten auf Route-Ebene und werden aktuell unabhaengig von der Quelle angewendet, wenn Website-Traffic und externe API-Nutzung dieselben Endpunkte nutzen. Fuer taxcompare gelten aktuell 20 Requests pro 5 Minuten je Route; berechne ist grosszuegiger und nutzt 1000 Requests pro 5 Minuten fuer Cache-Misses. Cache-Hits bei berechne koennen vor der eigentlichen Limit-Pruefung beantwortet werden.

Wichtige Parameter

  • - Unterstuetzte Laendercodes: DE, AT, US, CH, CA, AU, UK, IE
  • - Mindestfelder fuer taxcompare: annual_gross, tax_year, countries, currency
  • - taxcompare currency nutzt lower-case ISO-Werte wie eur, usd, chf, cad, aud, gbp
  • - taxcompare gross_mode unterstuetzt shared_gross und local_median_gross
  • - tax_year wird derzeit als String oder Integer akzeptiert, typischerweise 2026
  • - berechne erwartet viele Betraege in Minor Units wie Cent

Wichtige Endpunkte

/api/openapi

OpenAPI-Spezifikation (Swagger-kompatibel)

/api/mcp

MCP-Discovery und Gateway

/api/berechne

Direkter Payroll- und Tax-Call

/api/taxcompare

Direkter Salary-Compare-Call

Quickstart

  1. 1. API-Key anfragen, wenn du produktiv oder mit hoeheren Limits integrieren willst
  2. 2. Einen Beispiel-Request unten direkt kopieren und senden
  3. 3. Die Response pruefen und mit deinem Use Case abgleichen
  4. 4. Details und erweiterte Felder bei Bedarf im OpenAPI-Contract unter /api/openapi nachsehen

Responses und Fehler

Erfolgsantworten verwenden kein globales ok/data-Envelope, sondern liefern direkt tool-spezifische Response-Strukturen. Fuer identische Inputs innerhalb derselben Contract-Version sind Responses deterministisch. Innerhalb derselben Contract-Version bleiben Response-Strukturen stabil. Fehler folgen einem schlanken JSON-Format mit error und optional details oder restricted_fields.

Beispielantwort (taxcompare, gekuerzt):

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

Fehler

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."
  ]
}

Beispiele

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

Hinweis

MCP und OpenAPI werden aus derselben Vertragsquelle erzeugt. Diese Contract-Quelle ist die verbindliche Grundlage der oeffentlichen API. Aenderungen am Backend sollten immer gemeinsam mit dem oeffentlichen Contract ausgeliefert werden.

Support

Bei Fragen zur oeffentlichen API, fuer API-Key-Anfragen, manuelle Freischaltung oder fuer hoeheren Durchsatz nutze bitte das Kontakt- oder Feedback-Formular auf der Website, um API-Keys zu erhalten oder Limits anzupassen.