Sophie AI Chat API
Hallo, ich bin Sophie! 👋 Über diese API kannst Sie mich in Ihre eigene Anwendung integrieren. So können Ihre Benutzer von KI-gestützter Buchhaltungshilfe profitieren - direkt in Ihrer App!
Sophie ist Ihre intelligente Buchhaltungsassistentin, basierend auf Claude AI. Über diese API kannst Sie Sophie in Ihre eigene Anwendung integrieren und Ihren Benutzern KI-gestützte Buchhaltungshilfe anbieten.
Was kann Sophie?
- Fragen zur österreichischen Buchhaltung beantworten
- Belege analysieren und automatisch kategorisieren (OCR)
- UStG-konforme Beratung geben
- Bei der Rechnungserstellung helfen
- Auswertungen und Berichte erklären
Endpunkte
| Methode | Endpunkt | Beschreibung |
|---|---|---|
POST | /v1/sophie/chat | Chat-Nachricht senden |
POST | /v1/sophie/analyze | Beleg/Dokument analysieren (OCR) |
GET | /v1/sophie/conversations | Gesprächsverlauf auflisten |
GET | /v1/sophie/conversations/:id | Einzelnes Gespräch abrufen |
DELETE | /v1/sophie/conversations/:id | Gespräch löschen |
Chat-Nachricht - JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "SophieChatRequest",
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Deine Frage oder Nachricht an Sophie",
"maxLength": 4000
},
"conversation_id": {
"type": "string",
"description": "Optional: ID eines bestehenden Gesprächs"
},
"context": {
"type": "object",
"description": "Kontextinformationen für bessere Antworten",
"properties": {
"current_page": { "type": "string" },
"selected_receipt_id": { "type": "string" },
"selected_invoice_id": { "type": "string" },
"selected_customer_id": { "type": "string" }
}
},
"stream": {
"type": "boolean",
"default": false,
"description": "Echtzeit-Streaming der Antwort"
}
},
"required": ["message"]
}Chat-Antwort - JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "SophieChatResponse",
"type": "object",
"properties": {
"conversation_id": { "type": "string" },
"message": {
"type": "object",
"properties": {
"id": { "type": "string" },
"role": { "type": "string", "enum": ["assistant"] },
"content": { "type": "string" },
"created_at": { "type": "string", "format": "date-time" }
}
},
"suggestions": {
"type": "array",
"items": { "type": "string" },
"description": "Vorgeschlagene Folgefragen"
},
"related_help": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": { "type": "string" },
"url": { "type": "string" }
}
}
},
"usage": {
"type": "object",
"properties": {
"requests_used": { "type": "integer" },
"requests_limit": { "type": "integer" },
"requests_remaining": { "type": "integer" }
}
}
}
}Chat-Nachricht senden
POST /v1/sophie/chat
Sendet eine Nachricht an Sophie und erhält eine KI-generierte Antwort.
Request Body
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
message | string | Ja | Deine Frage oder Nachricht (max. 4000 Zeichen) |
conversation_id | string | Nein | Fortsetzung eines bestehenden Gesprächs |
context | object | Nein | Kontextinformationen (aktuelle Seite, ausgewählter Beleg) |
stream | boolean | Nein | Echtzeit-Streaming aktivieren |
Beispiel
cURL
curl -X POST "https://buchhaltgenie.at/api/v1/sophie/chat" \
-H "Authorization: Bearer sk_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"message": "Wie verbuche ich eine Bewirtungsrechnung?",
"context": {
"current_page": "expenses",
"selected_receipt_id": "rec_xyz789"
}
}'Antwort
{
"data": {
"conversation_id": "conv_abc123",
"message": {
"id": "msg_def456",
"role": "assistant",
"content": "Guten Tag! Bei einer Bewirtungsrechnung ist es wichtig, zwischen geschäftlichen und privaten Anlässen zu unterscheiden:\n\n**Geschäftliche Bewirtung:**\n- 50% der Kosten sind als Betriebsausgabe abzugsfähig\n- Die volle Vorsteuer kann geltend gemacht werden\n\n**Wichtig:** Auf der Rückseite der Rechnung solltest Sie notieren:\n- Anlass der Bewirtung\n- Teilnehmer\n- Geschäftlicher Grund\n\nMöchtest Sie, dass ich Ihnen bei der Verbuchung des ausgewählten Belegs helfe?",
"created_at": "2026-01-09T10:30:00Z"
},
"suggestions": [
"Ja, bitte verbuchen",
"Mehr Details zur Vorsteuer",
"Andere Frage stellen"
],
"related_help": [
{
"title": "Bewirtungskosten richtig absetzen",
"url": "/hilfe/ausgaben/bewirtungskosten"
}
],
"usage": {
"requests_used": 15,
"requests_limit": 300,
"requests_remaining": 285
}
}
}Gespräch fortsetzen
Um ein bestehendes Gespräch fortzusetzen, verwende die conversation_id:
cURL
curl -X POST "https://buchhaltgenie.at/api/v1/sophie/chat" \
-H "Authorization: Bearer sk_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"message": "Ja, bitte verbuchen",
"conversation_id": "conv_abc123"
}'Streaming-Antworten
Für Echtzeit-Antworten unterstützt Sophie Server-Sent Events (SSE):
cURL
curl -X POST "https://buchhaltgenie.at/api/v1/sophie/chat" \
-H "Authorization: Bearer sk_live_xxxx" \
-H "Accept: text/event-stream" \
-H "Content-Type: application/json" \
-d '{"message": "Erkläre mir die Vorsteuer", "stream": true}'SSE Event-Format
event: message
data: {"delta": "Guten "}
event: message
data: {"delta": "Tag! "}
event: message
data: {"delta": "Die Vorsteuer..."}
event: done
data: {"message_id": "msg_xyz", "conversation_id": "conv_abc"}Beleg analysieren (OCR)
POST /v1/sophie/analyze
Analysiert ein Dokument (Rechnung, Beleg, Kontoauszug) und extrahiert strukturierte Daten.
Request (Multipart Form)
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
file | file | Ja* | Datei (PDF, JPG, PNG) - max. 10 MB |
file_base64 | string | Ja* | Alternativ: Base64-kodierte Datei |
file_name | string | Nein | Dateiname (bei Base64) |
type | string | Nein | receipt, invoice, bank_statement, contract |
extract_fields | array | Nein | Gewünschte Felder: vendor, amount, date, vat |
*Entweder file oder file_base64 ist erforderlich.
Beispiel (Multipart)
cURL
curl -X POST "https://buchhaltgenie.at/api/v1/sophie/analyze" \
-H "Authorization: Bearer sk_live_xxxx" \
-F "file=@rechnung.pdf" \
-F "type=receipt"Beispiel (Base64)
cURL
curl -X POST "https://buchhaltgenie.at/api/v1/sophie/analyze" \
-H "Authorization: Bearer sk_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"file_base64": "JVBERi0xLjQKJeLjz9...",
"file_name": "rechnung.pdf",
"type": "receipt",
"extract_fields": ["vendor", "amount", "date", "vat"]
}'Analyse-Antwort
{
"data": {
"analysis_id": "ana_ghi789",
"status": "completed",
"document_type": "receipt",
"confidence": 0.95,
"extracted_data": {
"vendor": {
"name": "BILLA",
"address": "Musterstraße 5, 1010 Wien",
"uid_number": "ATU12345678"
},
"date": "2026-01-08",
"items": [
{
"description": "Bürobedarf",
"quantity": 1,
"amount": 24.99,
"vat_rate": 20
}
],
"subtotal": 20.83,
"vat_amount": 4.16,
"total": 24.99,
"currency": "EUR",
"payment_method": "card"
},
"suggested_category": "office_supplies",
"suggested_account": "6815",
"warnings": [],
"sophie_notes": "Dies sieht nach Büromaterial aus. Ich schlage vor, dies unter 'Bürobedarf' (Konto 6815) zu verbuchen. Die Vorsteuer von EUR 4,16 ist abzugsfähig."
}
}Analyse-Typen
| Typ | Beschreibung | Extrahierte Felder |
|---|---|---|
receipt | Kassenbon oder Rechnung | vendor, items, total, vat, date |
invoice | Eingangsrechnung | vendor, items, total, vat, date, due_date, invoice_number |
bank_statement | Kontoauszug | transactions, balance, period |
contract | Vertragsdokument | parties, terms, dates, amounts |
Gesprächsverlauf abrufen
GET /v1/sophie/conversations
Ruft eine Liste aller Gespräche mit Sophie ab.
Query-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
page | number | Seitennummer |
per_page | number | Gespräche pro Seite (Max: 50) |
Beispiel
cURL
curl -X GET "https://buchhaltgenie.at/api/v1/sophie/conversations?per_page=10" \
-H "Authorization: Bearer sk_live_xxxx"Antwort
{
"data": [
{
"id": "conv_abc123",
"title": "Bewirtungskosten",
"message_count": 5,
"last_message_at": "2026-01-09T10:35:00Z",
"created_at": "2026-01-09T10:30:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 10,
"total_count": 15
}
}Einzelnes Gespräch abrufen
GET /v1/sophie/conversations/:id
Ruft den vollständigen Verlauf eines Gesprächs ab.
Beispiel
cURL
curl -X GET "https://buchhaltgenie.at/api/v1/sophie/conversations/conv_abc123" \
-H "Authorization: Bearer sk_live_xxxx"Antwort
{
"data": {
"id": "conv_abc123",
"title": "Bewirtungskosten",
"messages": [
{
"id": "msg_001",
"role": "user",
"content": "Wie verbuche ich eine Bewirtungsrechnung?",
"created_at": "2026-01-09T10:30:00Z"
},
{
"id": "msg_002",
"role": "assistant",
"content": "Guten Tag! Bei einer Bewirtungsrechnung...",
"created_at": "2026-01-09T10:30:02Z"
}
],
"created_at": "2026-01-09T10:30:00Z"
}
}Gespräch löschen
DELETE /v1/sophie/conversations/:id
Löscht ein Gespräch und alle zugehörigen Nachrichten.
Beispiel
cURL
curl -X DELETE "https://buchhaltgenie.at/api/v1/sophie/conversations/conv_abc123" \
-H "Authorization: Bearer sk_live_xxxx"Fair-Use-Limits
Sophie unterliegt Fair-Use-Limits je nach Tarif:
| Tarif | Sophie-Anfragen/Monat | OCR-Analysen/Monat |
|---|---|---|
| Free | 5 | - |
| Starter | 30 | 20 |
| Pro | 300 | 60 |
| Business | 600 | 120 |
| Enterprise | 1.500 | 300 |
Sophie’s Tipp: Sie können Ihren aktuellen Verbrauch in jeder Antwort im usage-Objekt sehen. Bei Erreichen von 90% des Limits erhältst Sie eine Warnung.
Fehler-Codes
| Code | HTTP Status | Beschreibung |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Fair-Use-Limit erreicht |
INVALID_FILE_TYPE | 400 | Nicht unterstütztes Dateiformat |
FILE_TOO_LARGE | 400 | Datei größer als 10 MB |
ANALYSIS_FAILED | 500 | Dokumentanalyse fehlgeschlagen |
CONVERSATION_NOT_FOUND | 404 | Gespräch nicht gefunden |
MESSAGE_TOO_LONG | 400 | Nachricht überschreitet 4000 Zeichen |
INVALID_CONTEXT | 400 | Ungültiges Kontextobjekt |
Hinweise zur Nutzung
Wichtig: Sophie gibt keine rechtsverbindliche Steuerberatung. Bei komplexen Steuerfragen empfehlen wir die Konsultation eines Steuerberaters.
Best Practices
- Kontext bereitstellen: Je mehr Kontext Sie sendest (aktuelle Seite, ausgewählter Beleg), desto bessere Antworten erhältst du
- Gespräche fortsetzen: Nutze die
conversation_idfür zusammenhängende Fragen - Streaming nutzen: Für bessere UX verwende SSE-Streaming
- Feedback geben: Nutze die Bewertungsfunktion - Sophie lernt daraus
EU AI Act Compliance
Gemäß EU AI Act Art. 50 ist Sophie als KI-System gekennzeichnet. Alle Antworten enthalten den Hinweis, dass es sich um KI-generierte Inhalte handelt.
Nächste Schritte
- Authentifizierung - API-Zugang einrichten
- Rechnungen API - Rechnungen automatisch erstellen
- Transaktionen API - Von Sophie kategorisierte Belege verbuchen
- Sophie AI kennenlernen - Mehr über Sophies Fähigkeiten