API

Olvano bietet eine REST-API zur Anbindung Ihrer eigenen Systeme — Rechnungen erstellen und auslesen, Kontakte verwalten und über Webhooks auf Ereignisse reagieren. Diese Seite führt Sie vom Token bis zum ersten Aufruf; die vollständige, ausführbare Liste der Endpunkte finden Sie in der interaktiven Referenz.

Bevor Sie beginnen

Sie benötigen zwei Dinge:

1. Ein Konto im Tarif byznys (der free-Tarif hat keine API).
2. Einen API-Token, der an dieses Konto gebunden ist (siehe unten).

Tokens werden vom Kontoinhaber erstellt. Ein Token gehört zu genau einem Konto und trägt seine eigenen Berechtigungen (Scopes), sodass Sie pro Integration einen eigenen Token ausstellen können.

Einen API-Token erstellen

Gehen Sie in der App zu Einstellungen → API-Tokens (/app/{slug}/settings/api-tokens), wählen Sie Neuer Token, benennen Sie ihn und legen Sie seine Berechtigungen fest. Der Token im Klartext wird nur einmal angezeigt — kopieren Sie ihn sofort und bewahren Sie ihn sicher auf.

Tokens beginnen mit dem Präfix sg_. Gespeichert wird nur ein HMAC-Digest, sodass der Token nie wieder angezeigt werden kann — geht er verloren, erstellen Sie einen neuen und löschen den alten.

Berechtigungen (Scopes)

Das Lesen (GET) gängiger Ressourcen erfordert keine Berechtigung; das Schreiben schon. Operationen, die dem Kontoinhaber vorbehalten sind (Tokens, Webhooks und Bankkonten verwalten), stehen einem API-Token nie zur Verfügung — selbst ein vom Kontoinhaber ausgestellter Token erhält 403.

Authentifizierung und Basis-URL

Authentifizieren Sie jede Anfrage mit dem Token im Authorization-Header:

Authorization: Bearer sg_your_token

Die Basis-URL ist die Domain Ihrer Instanz + /api. Konto-Endpunkte haben die Form /api/accounts/{slug}/…. Die folgenden Beispiele verwenden Umgebungsvariablen:

export STARGATE="https://app.stargate.app"   # durch die Domain Ihrer Instanz ersetzen (lokal http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

Ihre erste Anfrage

Die Rechnungen eines Kontos auflisten:

curl "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN"

Die Antwort ist eine paginierte Liste:

{
  "invoices": [ { "id": "…", "number": "2026-0001", "status": "open", "total": "3630.00" } ],
  "total": 128,
  "page": 1,
  "pageSize": 40
}

Paginierung, Sortierung und Suche

Listen-Endpunkte akzeptieren diese Query-Parameter:

Rechnungen lassen sich zusätzlich nach status, documentType und subjectId filtern. Ein ungültiger Parameter unterbricht die Liste nie — stattdessen wird der Standard verwendet (z. B. ?page=abc → 1). Jede Antwort enthält total, page und pageSize, sodass sich die Seitenanzahl leicht ableiten lässt.

Eine Rechnung erstellen

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CUSTOMER_ID",
    "lines": [
      { "name": "Consulting", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

subjectId ist die ID des Kunden — Sie erhalten sie aus der Kontaktliste (GET /api/accounts/$SLUG/subjects) oder legen einen Kontakt über POST …/subjects an. Pflichtfelder sind subjectId und mindestens eine Position in lines (jeweils mit name und unitPrice). Optional können Sie documentType, currency, variableSymbol, due, issuedOn und weitere Felder senden — das vollständige Schema finden Sie in der interaktiven Referenz.

Bei Erfolg werden 201 und die erstellte Rechnung zurückgegeben:

{ "invoice": { "id": "…", "number": "2026-0002", "status": "open", "total": "3630.00" } }

Fehler

Fehler verwenden ein einheitliches Format — einen HTTP-Status sowie JSON mit statusMessage und einem data-Feld für die maschinelle Verarbeitung:

{
  "statusCode": 400,
  "statusMessage": "Invalid invoice",
  "data": { "formErrors": [], "fieldErrors": { "subjectId": ["Required"] } }
}

Bei Domänenfehlern ist data.code ein maschinenlesbarer Code (z. B. subject_not_found), auf den Sie sich eher verlassen können als auf den Meldungstext.

Tariflimits

Der free-Tarif führt keine API-Aufrufe aus (Kontingent 0); byznys verfügt über die API und alle Funktionen. Wird ein Limit überschritten (z. B. die Anzahl der Kontakte), gibt die API 402 mit plan_limit_reached zurück; für eine Funktion außerhalb des Tarifs (Webhooks, Ausgaben …) gibt sie 403 mit plan_feature_unavailable zurück. Die aktuellen Limits und die Nutzung Ihres Kontos lesen Sie über:

curl "$STARGATE/api/accounts/$SLUG/entitlements" -H "Authorization: Bearer $TOKEN"

Webhooks

Ein Webhook benachrichtigt Sie in Echtzeit über Ereignisse, statt dass Sie die API abfragen müssen. Webhooks sind eine Funktion des byznys-Tarifs und werden vom Kontoinhaber verwaltet.

Registrierung über die API (oder in den Kontoeinstellungen):

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer your-shared-secret"
  }'

Tragen Sie konkrete Namen in events ein oder * für alle. Verfügbare Ereignisse:

invoice_created, invoice_sent, invoice_paid, invoice_overdue, invoice_cancelled, invoice_uncollectible, invoice_viewed, invoice_reminder_sent, recurring_generator_invoice_created.

Olvano sendet ein POST an Ihre URL mit folgendem Body:

{ "event_name": "invoice_paid", "body": { "…": "event data" } }

• Wenn Sie authHeader setzen, wird er als Authorization-Header gesendet — verwenden Sie ihn, um zu prüfen, dass die Anfrage wirklich von Olvano stammt.
• Jede Zustellung trägt einen Idempotency-Key-Header (UUID) — nutzen Sie ihn zur Deduplizierung.
• Die Zustellung wird bis zu 5× mit exponentiellem Backoff wiederholt, bis Sie einen 2xx-Status zurückgeben. Fehlgeschlagene Zustellungen werden über GET …/webhooks/{id}/failed_deliveries aufgelistet.

Interaktive Referenz

Die vollständige, stets aktuelle Liste der Endpunkte — mit Parametern, Schemata und der Möglichkeit, sie direkt aus dem Browser aufzurufen:

• API-Referenz öffnen (/api-docs)
• Maschinenlesbares OpenAPI-Schema: /api/_openapi.json