API- und KI-Agentenzugriff

SimplyQuote stellt eine REST-API bereit, damit Ihre KI-Agenten, Skripte und Integrationen in Ihrem Namen mit Ihren Angeboten und Rechnungen arbeiten können. Der Zugriff wird über persönliche, eingeschränkte und widerrufbare Zugriffstokens kontrolliert.

1. API-Zugriff aktivieren

1. Öffnen Sie Ihre Einstellungsseite und melden Sie sich an
2. Scrollen Sie zum Abschnitt „API- und KI-Agentenzugriff".
3. Benennen Sie Ihr Token, wählen Sie die Berechtigungen und klicken Sie auf „Token erstellen".
4. Kopieren Sie das Token sofort — aus Sicherheitsgründen wird es nur einmal angezeigt.

2. Eine Anfrage senden

Senden Sie das Token als Bearer-Token im Authorization-Header:

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. Dokumente erstellen und aktualisieren

Zum Erstellen und Aktualisieren von Angeboten und Rechnungen wird dasselbe Token mit einer Schreibberechtigung verwendet. Die Summen werden immer serverseitig aus den gesendeten Positionen berechnet:

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

Erfolgsantwort (Listen entsprechend, mit quotes/invoices plus total/page/limit/has_more):

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Auflisten & Paginieren

Listen-Endpunkte akzeptieren updated_since (ISO 8601), page (Standard 1), limit (Standard 20, max. 100) und status (Groß-/Kleinschreibung egal; unbekannte Werte werden ignoriert). Antworten enthalten total, page, limit und has_more.

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

Feldregeln für Erstellen & Aktualisieren

items ist bei POST Pflicht: nicht-leeres Array, je Position eine nicht-leere description, quantity > 0 (Standard 1), unit_price >= 0 (Standard 0). tax_rate ist Prozent (0–100); bei der Erstellung impliziert tax_rate > 0 tax_enabled. currency wird in Großbuchstaben gespeichert. issue_date akzeptiert jedes lesbare Datum (gespeichert JJJJ-MM-TT). Angebote nutzen expiry_date, Rechnungen due_date (beide Aliase werden akzeptiert, null löscht). Status: Angebote draft|sent, Rechnungen draft|sent|viewed|paid|cancelled — paid setzt paid_at. Summen werden immer serverseitig neu berechnet.

4. Mit einem KI-Agenten verwenden

Geben Sie Ihrem Agenten die Basis-URL, Ihr Token und die folgende Endpunktliste. Beispielanweisungen für jeden Werkzeug-aufrufenden Agenten (Claude, GPT, LangChain usw.):

Du kannst auf mein SimplyQuote-Konto zugreifen.
Basis-URL: https://simplyquote.net
Sende bei jeder Anfrage den Header: Authorization: Bearer sq_dein_token_hier
Verfügbare Endpunkte: GET/POST /api/v1/quotes, GET/PATCH /api/v1/quotes/{id},
GET/POST /api/v1/invoices, GET/PATCH /api/v1/invoices/{id}, POST /api/mcp
Listen unterstützen ?page, ?limit (max. 100), ?status, ?updated_since und geben { success:true, data:{ quotes|invoices, total, page, limit, has_more } } zurück.
Einzelabrufe geben das bloße Objekt zurück. {id} ist die UUID, nicht die Dokumentennummer.
Verwende POST zum Erstellen von Dokumenten — sende immer items mit description, quantity und unit_price.

5. Über MCP verbinden (für Agenten empfohlen)

SimplyQuote bietet einen integrierten MCP-Server (Model Context Protocol) unter /api/mcp (zustandsloses Streamable-HTTP, JSON-RPC 2.0). Agenten, die entfernte MCP-Server unterstützen (Claude, ChatGPT, Cursor, VS Code usw.), können sich direkt mit Ihrem Token verbinden — ohne Formatierung von Prompts. Verfügbare Werkzeuge:

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

Beispiel für einen Tool-Aufruf (JSON-RPC 2.0 — Stapelanfragen werden abgelehnt, Mitteilungen geben 202, GET gibt 405):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

Jeder Werkzeugaufruf wird gegen die Berechtigungen Ihres Tokens geprüft — ein Nur-Lese-Token kann Listen und Daten abrufen, während das Erstellen von Angeboten oder Rechnungen die entsprechende Schreibberechtigung erfordert.

Endpunkte

Berechtigungen

• quotes:read — Ihre Angebote lesen
• invoices:read — Ihre Rechnungen lesen
• clients:read — Reserviert — noch kein separater Kunden-Endpunkt (Kundendaten stehen auf Angeboten/Rechnungen)
• quotes:write — Angebote erstellen und aktualisieren
• invoices:write — Rechnungen erstellen und aktualisieren
• clients:write — Reserviert — noch kein separater Kunden-Endpunkt (Kundendaten werden implizit beim Speichern von Angeboten/Rechnungen erstellt/aktualisiert)

Antwortformat und Fehler

REST-Endpunkte nutzen zwei Formate — prüfen Sie jeweils, welches gilt:

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

Einzelabrufe geben das obige bloße Objekt zurück (ohne Hülle), mit flachen { error, message }-Fehlern — z. B. 404 bei unbekannter ID. Listen sowie POST/PATCH nutzen immer die verpackte Antwort.

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — true bei Erfolg, false bei Fehler
• data — die Daten bei Erfolg
• error — Fehlercode, Meldung und optionale Details bei Fehler

Die häufigsten Fehlercodes:

• UNAUTHORIZED — Token fehlt, ist ungültig oder abgelaufen (HTTP 401)
• FORBIDDEN — Das Token besitzt nicht die erforderliche Berechtigung (HTTP 403)
• VALIDATION_ERROR — Der Anfragekörper hat die Validierung nicht bestanden (HTTP 400)
• NOT_FOUND — Das angeforderte Dokument existiert nicht (HTTP 404)
• DATABASE_ERROR — Speicherfehler während der Verarbeitung der Anfrage (HTTP 500)
• RATE_LIMIT — Zu viele Anfragen — versuchen Sie es später erneut (HTTP 429)

Webhooks, OAuth & Gesamtreferenz

Webhooks: Abonnements unter GET/POST/PATCH/DELETE /api/v1/webhooks verwalten (jedes gültige Token, keine spezielle Berechtigung). Die URL muss ein öffentlicher HTTPS-Endpunkt sein. Das Secret gibt es nur bei der Erstellung — Lieferungen per X-SimplyQuote-Signature (HMAC-SHA256) prüfen.

Partner-Apps nutzen OAuth 2.0 (/api/oauth/authorize, /api/oauth/token, /api/oauth/revoke) statt persönlicher Tokens. Details in docs/API.md und in der maschinenlesbaren Spezifikation unter /api/v1/openapi.json.

Sicherheitshinweise

• Tokens werden gehasht gespeichert — SimplyQuote speichert das Roh-Token niemals.
• Gewähren Sie nur die Berechtigungen, die Ihr Agent benötigt; meist reicht Nur-Lese-Zugriff.
• Widerrufen Sie ein Token jederzeit in den Einstellungen, um den Zugriff sofort zu beenden.
• Eine maschinenlesbare Spezifikation für Agenten ist verfügbar unter /api/v1/openapi.json