Zum Inhalt springen
Annuva
Dokumentation · REST-API

API & KI

REST-API

Authentifizierung, Konventionen und Beispiele für die REST-API von Annuva.

Alle Geschäftsdaten stehen unter /api/v1 bereit. API, MCP-Tools und die Formulare der App entstehen aus denselben Entity-Definitionen – die API kann also immer, was die Oberfläche kann.

Authentifizierung

Erstelle in Annuva unter Profil → API-Tokens ein persönliches Token und sende es als Bearer-Token:

bash
curl -H "Authorization: Bearer an_…" https://annuva.example.com/api/v1/customers
  • Ein Token gehört seinem Benutzer und hat dieselben Rechte wie er (Admin-Endpunkte brauchen einen Admin).
  • Der Umfang ist read oder read_write. Lese-Tokens dürfen nur GET-Endpunkte aufrufen.
  • Tokens können ablaufen. Das Token wird nur einmal angezeigt – leg es in deinem Passwortmanager ab.
  • Im Browser funktioniert auch das Sitzungs-Cookie.

Konventionen

  • JSON rein und raus, Content-Type: application/json für Request-Bodys.
  • Geldbeträge sind in den Entity-Endpunkten Dezimalzahlen in der Währung der Instanz (60.5); das Dashboard liefert ganzzahlige Cent.
  • Datumswerte sind YYYY-MM-DD, Zeitstempel ISO 8601.
  • IDs sind UUIDs.

Listen

GET /api/v1/{entity} liefert {items, total, limit, offset} und versteht:

Parameter Beschreibung
q Volltextsuche
sort, order Sortierfeld und asc / desc
limit, offset Blättern (max. 1000)
customerId Nur Datensätze eines Kunden
includeArchived Nur Kunden: archivierte einschließen
filter[feld] Gleichheitsfilter, z. B. filter[status]=open

Entities: customers, partners, resources, offers, recurring-charges, recurring-costs, expenses, tasks, tax-years, tax-adjustments, invoice-templates und invoices.

Fehler

Fehler kommen mit passendem HTTP-Statuscode und einem JSON-Body:

json
{
    "error": {
        "code": "unauthorized",
        "message": "Authentication required.",
        "details": null
    }
}

Bei Validierungsfehlern (400) enthält details die betroffenen Felder.

Endpunkte im Überblick

Endpunkt Beschreibung
GET /api/v1/{entity} Liste
POST /api/v1/{entity} Anlegen
GET/PATCH/DELETE /api/v1/{entity}/{id} Lesen, ändern, löschen
POST/DELETE /api/v1/customers/{id}/archive Kunden archivieren oder wiederherstellen
POST /api/v1/invoices/{id}/{action} issue, pay, reopen, cancel, send, remind
GET /api/v1/invoices/{id}/pdf Rechnungs-PDF (Vorschau bei Entwürfen)
POST /api/v1/billing/run Abrechnungslauf (dryRun für einen Probelauf)
GET /api/v1/dashboard Alle Dashboard-Werte (year, customer); Beträge in Cent
POST /api/v1/files, GET /api/v1/files/{id} Dateien hoch- und herunterladen
GET/PATCH /api/v1/settings Firmeneinstellungen (Admins)
GET /api/v1/openapi OpenAPI-3.1-Beschreibung

Die vollständige Liste mit allen Parametern steht in der API-Referenz.

Beispiele

Einen Kunden anlegen:

bash
curl -X POST https://annuva.example.com/api/v1/customers \
    -H "Authorization: Bearer an_…" \
    -H "Content-Type: application/json" \
    -d '{"name": "Bäckerei Huber", "channel": "direct", "status": "active", "language": "de"}'

Probelauf der Abrechnung bis zum Jahresende:

bash
curl -X POST https://annuva.example.com/api/v1/billing/run \
    -H "Authorization: Bearer an_…" \
    -H "Content-Type: application/json" \
    -d '{"until": "2026-12-31", "dryRun": true}'

Einen Entwurf ausstellen und das PDF herunterladen:

bash
curl -X POST https://annuva.example.com/api/v1/invoices/<id>/issue -H "Authorization: Bearer an_…"
curl -o rechnung.pdf https://annuva.example.com/api/v1/invoices/<id>/pdf -H "Authorization: Bearer an_…"

OpenAPI

Jede Instanz beschreibt ihre API unter /api/v1/openapi (OpenAPI 3.1). Importiere sie in Postman, Insomnia oder Bruno oder erzeuge daraus einen Client.

Diese Seite auf GitHub bearbeiten