API-Dokumentation

Passion Tax bietet Tax-Tech-Plattformen eine REST-Schnittstelle, um steuerliche Sachverhalte programmatisch zur Vermittlung an qualifizierte Steuerberater einzureichen.

Übersicht

Basis-URL: https://passiontax.velentis.ai
Format: JSON über HTTPS
Authentifizierung: Bearer-Token (API-Schlüssel)
Rate-Limit: Standard 30 Anfragen / Minute pro Schlüssel

Authentifizierung

Senden Sie Ihren API-Schlüssel als Bearer-Token im Authorization-Header. Schlüssel beginnen mit ptk_ und sind 64 Zeichen lang. Wenden Sie sich an api@passiontax.velentis.ai, um einen Schlüssel zu beantragen.

Authorization: Bearer ptk_a1b2c3d4e5f6...

Endpoint: Fall einreichen

POST/api/webhooks/intake

Request Body

{
  "sachverhalt": "Mandant beschreibt sein Steuerproblem im Detail...",
  "mandant": {
    "vorname": "Max",
    "nachname": "Mustermann",
    "email": "max@example.de",
    "typ": "privatperson",
    "telefon": "+49 30 1234567",
    "adresse": {
      "strasse": "Hauptstraße 1",
      "plz": "10115",
      "ort": "Berlin"
    },
    "steuer_id": "12345678901"
  },
  "produkt_code": "SP-A01",
  "referenz_id": "mica-12345",
  "callback_url": "https://mica.com/api/passiontax-callback"
}

Felder

Feld	Typ	Pflicht	Beschreibung
sachverhalt	string	ja	Freitext-Beschreibung des steuerlichen Anliegens (20–20.000 Zeichen)
mandant.vorname	string	ja	Vorname des Mandanten
mandant.nachname	string	ja	Nachname des Mandanten
mandant.email	string	ja	Gültige E-Mail (wird zum Plattform-Login)
mandant.typ	enum	nein	privatperson · einzelunternehmer · personengesellschaft · kapitalgesellschaft (default: privatperson)
produkt_code	string	nein	Standardprodukt-Code (z.B. SP-A01). Wenn nicht angegeben, klassifiziert die KI automatisch.
referenz_id	string	nein	Ihre interne Referenz für Tracking + Callbacks
callback_url	string	nein	URL für Status-Update-Callbacks (HTTPS empfohlen)

Response (201 Created)

{
  "success": true,
  "fall_id": "cd20024c-03c2-40b5-9226-3ec76480021f",
  "fall_nummer": "TT-2026-0042",
  "status": "zugewiesen",
  "steuerberater": {
    "name": "Dr. Maria Hofmann",
    "fachgebiet": "erbschaftsteuer"
  },
  "mandant_login_url": "https://passiontax.velentis.ai/login",
  "mandant_temporary_password": "Pt-a1b2c3d4!"
}

mandant_temporary_password wird nur zurückgegeben, wenn ein neuer Mandant angelegt wurde. Geben Sie das Passwort sicher an den Mandanten weiter — es wird nicht erneut anzeigbar sein.

Status-Callbacks

Wenn Sie eine callback_url angeben, sendet Passion Tax bei jedem relevanten Statuswechsel einen POST-Request an Ihre URL.

POST {your-callback-url}
Content-Type: application/json
User-Agent: PassionTax-Webhook/1.0

{
  "event": "case.status_changed",
  "fall_id": "cd20024c-...",
  "fall_nummer": "TT-2026-0042",
  "referenz_id": "mica-12345",
  "new_status": "in_bearbeitung",
  "timestamp": "2026-04-11T19:30:00.000Z"
}

Events

case.created — Fall angelegt, noch ohne Berater
case.assigned — Berater wurde automatisch zugewiesen
case.status_changed — generischer Statuswechsel
case.completed — Berater hat den Fall abgeschlossen
case.rated — Mandant hat den Fall bewertet

Callbacks haben einen Timeout von 5 Sekunden und werden nicht automatisch wiederholt. Implementieren Sie auf Ihrer Seite ggf. ein eigenes Retry-Verfahren.

Fehlercodes

Status	Beschreibung
400	Validierungsfehler (siehe `details` im Response-Body)
401	API-Schlüssel fehlt, ungültig oder deaktiviert
403	Schlüssel hat keine intake-Berechtigung
429	Rate-Limit überschritten — siehe `Retry-After`
500	Interner Fehler — bitte erneut versuchen oder Support kontaktieren

Beispiel

curl -X POST https://passiontax.velentis.ai/api/webhooks/intake \
  -H "Authorization: Bearer ptk_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "sachverhalt": "Ich möchte meine Einkommensteuer 2025 erstellen lassen. Bruttojahresgehalt ca. 75.000 €, ein Mietobjekt.",
    "mandant": {
      "vorname": "Max",
      "nachname": "Mustermann",
      "email": "max@example.de",
      "typ": "privatperson"
    },
    "produkt_code": "SP-A01",
    "referenz_id": "mica-12345"
  }'

Kontakt

Bei Fragen zur API oder für die Beantragung eines Schlüssels: api@passiontax.velentis.ai