REST · v1 · 50 Webhooks

Bau auf dVersum.

Eine kuratierte Referenz für die Endpunkte, die du täglich brauchst — Authentifizierung, Webhooks, und die Kern-Ressourcen für Kunden, Rechnungen, Aufgaben, Zeiterfassung und mehr. Alle Beispiele sind copy-paste-fertig.

Basis-URLhttps://api.dversum.com/api/v1

Einführung

Die dVersum-API spricht REST über HTTPS. Anfragen werden mit JSON gesendet, Antworten kommen als JSON zurück. Alle Zeitstempel sind ISO 8601 in UTC. Geldbeträge sind ganzzahlig in Cent. IDs sind UUIDv4.

Authentifizierung

Authentifiziere jede Anfrage mit einem persönlichen API-Token im Authorization-Header. Erstelle Tokens unter Einstellungen → API. Jeder Token gehört zu einem Nutzer + einer Organisation; Berechtigungen entsprechen denen des Nutzers.

curl

curl https://api.dversum.com/api/v1/clients \
  -H"Authorization: Bearer dvk_live_…"

Speichere Tokens nie im Frontend-Code. Für serverseitige Integrationen reicht ein einzelner Token; für Multi-Tenant-Szenarien rotiere regelmäßig.

Konventionen

IDs: UUIDv4. Pfadparameter heißen immer `{id}` oder `{resource_id}`.
Geld: Ganzzahlig in Cent. `12500` = 125,00 € — keine Floats.
Datum / Zeit: ISO 8601 mit Z-Suffix (UTC). Anzeigen erfolgt in Europe/Berlin.
Sprache: Setze `Accept-Language: de` oder `en` — wirkt sich auf generierte E-Mail-Inhalte und ZUGFeRD-Labels aus.
Felder: Antworten verwenden snake_case. Unbekannte Felder im Request werden ignoriert.

Fehler

Fehler kommen als JSON mit `error` (kurze Maschinenkennung) und `message` (für Menschen). HTTP-Statuscodes folgen REST-Konventionen.

HTTP 422

{"error":"validation_failed","message":"client_id is required","field":"client_id"
}

Status	Bedeutung
`400`	Ungültige Anfrage — JSON-Parse-Fehler oder fehlendes Feld
`401`	Kein oder ungültiger Token
`403`	Token ist gültig, hat aber keine Berechtigung für die Ressource
`404`	Ressource existiert nicht (oder gehört zu einer anderen Organisation)
`409`	Konflikt — z. B. doppelte Slug/E-Mail
`422`	Validierung fehlgeschlagen
`429`	Rate-Limit überschritten — siehe Rate-Limits
`5xx`	Serverfehler — bitte erneut versuchen oder Support kontaktieren

Pagination

Listen-Endpunkte unterstützen `?page=` und `?per_page=` (max. 100). Die Antwort enthält `total`, sodass du die Gesamtzahl der Seiten selbst berechnen kannst.

curl

curl"https://api.dversum.com/api/v1/invoices?page=2&per_page=50" \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

Rate-Limits

Pro Token: 120 Anfragen / Minute. Bei Überschreitung antwortet der Server mit 429 und einem `Retry-After`-Header. Antworten enthalten `X-RateLimit-Limit`, `X-RateLimit-Remaining` und `X-RateLimit-Reset` zur Überwachung.

Webhook-Auslieferungen werden separat gerated-limitet (1000/Min pro Organisation). Wenn dein Endpunkt nicht innerhalb von 5 Sek mit 2xx antwortet, wiederholen wir mit exponential backoff bis zu 5×.

Webhooks

Webhooks pushen Ereignisse an deinen HTTPS-Endpunkt, sobald sie in dVersum passieren — bezahlte Rechnungen, neue Tasks, geänderte Projekte. Jede Auslieferung ist signiert und idempotent (`Idempotency-Key` im Header).

Abonnement anlegen

Lege einen Webhook-Endpunkt unter Einstellungen → Webhooks an oder per API:

POST/webhooks

curl -X POST https://api.dversum.com/api/v1/webhooks \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"url":"https://example.com/dversum-webhook","events": ["invoice.paid","quote.signed"],"active": true
  }'

Der `secret`, mit dem zukünftige Payloads signiert werden, kommt im POST-Response zurück — bewahre ihn sicher auf.

Signatur prüfen

Jede Auslieferung enthält den Header `X-Dversum-Signature: sha256=<hex>`. Berechne HMAC-SHA-256 über den rohen Request-Body mit deinem `secret` und vergleiche zeitkonstant.

Node.js

import crypto from 'node:crypto'

const signature = req.headers['x-dversum-signature'].replace('sha256=', '')
const expected = crypto
  .createHmac('sha256', process.env.DVERSUM_WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest('hex')

if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  return res.status(401).end()
}

Verfügbare Ereignisse

50 Ereignisse über 11 Ressourcen.

Rechnungen

invoice.created
invoice.updated
invoice.sent
invoice.paid
invoice.partially_paid
invoice.overdue
invoice.deleted

Angebote

quote.created
quote.updated
quote.sent
quote.signed
quote.rejected
quote.expired
quote.converted
quote.deleted

Verträge

contract.created
contract.signed
contract.cancelled

Mahnungen

reminder.sent

Kunden

client.created
client.updated
client.deleted

Projekte

project.created
project.updated
project.archived
project.deleted

Aufgaben

task.created
task.updated
task.completed
task.assigned
task.moved
task.deleted
subtask.created
subtask.completed
subtask.deleted
comment.created

Zeiterfassung

time_entry.created
time_entry.started
time_entry.stopped
time_entry.updated
time_entry.deleted

Seiten

page.created
page.updated
page.deleted

Abwesenheiten

absence.created
absence.updated
absence.deleted

Buchungen

booking.created
booking.cancelled
booking.rescheduled

Kunden

Kunden sind die zentralen Geschäftspartner — Rechnungen, Angebote, Projekte und Verträge laufen alle gegen einen Kunden.

GET/clients

Listet Kunden der Organisation.

curl

curl https://api.dversum.com/api/v1/clients \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

Beispielantwort

{"clients": [
    {"id":"01H8Z…","name":"ATAS Vertriebs GmbH","email":"kontakt@atas.de","color":"#45e59f"
    }
  ],"total": 47
}

POST/clients

Legt einen neuen Kunden an.

curl

curl -X POST https://api.dversum.com/api/v1/clients \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"name":"ATAS Vertriebs GmbH","email":"kontakt@atas.de","vat_id":"DE123456789","country":"DE"
  }'

GET/clients/{id}

Liefert einen einzelnen Kunden samt verknüpfter Ressourcen.

curl

curl https://api.dversum.com/api/v1/clients/CLIENT_ID \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

PUT/clients/{id}

Aktualisiert einen Kunden.

curl

curl -X PUT https://api.dversum.com/api/v1/clients/CLIENT_ID \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"email":"neu@atas.de" }'

DELETE/clients/{id}

Löscht einen Kunden (nur wenn keine Rechnungen verknüpft sind).

curl

curl -X DELETE https://api.dversum.com/api/v1/clients/CLIENT_ID \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

Projekte

Projekte enthalten Aufgaben, Zeiteinträge, Seiten und Whiteboards. Ein Projekt kann optional einem Kunden zugeordnet sein.

GET/projects

Listet alle Projekte. Filter mit ?archived=false oder ?client_id=…

curl

curl"https://api.dversum.com/api/v1/projects?archived=false" \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

POST/projects

Erstellt ein neues Projekt mit Standard-Kanban-Spalten.

curl

curl -X POST https://api.dversum.com/api/v1/projects \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"name":"Q2 Relaunch","client_id":"CLIENT_ID","color":"#45e59f"
  }'

GET/projects/{id}/tasks

Listet alle Aufgaben eines Projekts mit Spalten- und Assignee-Daten.

curl

curl https://api.dversum.com/api/v1/projects/PROJECT_ID/tasks \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

PATCH/projects/{id}/status

Setzt den Projektstatus (active / on_hold / archived).

curl

curl -X PATCH https://api.dversum.com/api/v1/projects/PROJECT_ID/status \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"status":"archived" }'

Aufgaben

Aufgaben gehören zu einem Projekt und einer Kanban-Spalte. Sie unterstützen Tags, Anhänge, Unteraufgaben und Kommentare.

POST/tasks

Erstellt eine Aufgabe in der angegebenen Spalte.

curl

curl -X POST https://api.dversum.com/api/v1/tasks \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"title":"Mockup für Landing Page","project_id":"PROJECT_ID","column_id":"COLUMN_ID","due_date":"2026-06-30","assignee_ids": ["USER_ID"]
  }'

PATCH/tasks/{id}/move

Verschiebt eine Aufgabe in eine andere Spalte (oder ein anderes Projekt).

curl

curl -X PATCH https://api.dversum.com/api/v1/tasks/TASK_ID/move \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"column_id":"TARGET_COLUMN_ID","position": 0 }'

PATCH/tasks/{id}/toggle-done

Markiert eine Aufgabe als erledigt bzw. offen.

curl

curl -X PATCH https://api.dversum.com/api/v1/tasks/TASK_ID/toggle-done \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

POST/tasks/{taskId}/comments

Postet einen Kommentar. Mit `@vero` im Inhalt antwortet die KI im Thread.

curl

curl -X POST https://api.dversum.com/api/v1/tasks/TASK_ID/comments \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"content":"<p>@vero summarise the thread</p>" }'

Rechnungen

§14-UStG-konforme Rechnungen mit ZUGFeRD-XML, Mahnungs-Workflow und DATEV-Export. Beträge in Cent (Integer).

GET/invoices

Listet Rechnungen. Filter: ?status=, ?client_id=, ?from=YYYY-MM-DD&to=YYYY-MM-DD.

curl

curl"https://api.dversum.com/api/v1/invoices?status=sent&from=2026-01-01" \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

POST/invoices

Erstellt eine Rechnung als Entwurf. Erst beim Senden (POST /send) wird die Rechnungsnummer vergeben und GoBD-gesperrt.

curl

curl -X POST https://api.dversum.com/api/v1/invoices \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"client_id":"CLIENT_ID","issue_date":"2026-06-05","due_date":"2026-06-19","line_items": [
      {"description":"Beratung","quantity": 8,"unit_price_cents": 12500,"tax_rate": 19 }
    ]
  }'

POST/invoices/{id}/send

Sendet die Rechnung an den Kunden, sperrt sie (§14 UStG / GoBD), erzeugt die ZUGFeRD-PDF und löst invoice.sent aus.

curl

curl -X POST https://api.dversum.com/api/v1/invoices/INVOICE_ID/send \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

GET/invoices/{id}/pdf

Lädt die Rechnung als ZUGFeRD-PDF/A-3 herunter.

curl

curl https://api.dversum.com/api/v1/invoices/INVOICE_ID/pdf \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -o invoice.pdf

POST/invoices/{id}/payments

Bucht eine Zahlung (vollständig oder Teilzahlung) auf der Rechnung.

curl

curl -X POST https://api.dversum.com/api/v1/invoices/INVOICE_ID/payments \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"amount_cents": 119000,"paid_at":"2026-06-12","method":"transfer" }'

POST/invoices/{id}/credit-note

Erstellt eine Gutschrift (GS-) zur Rechnung — gespiegelte Beträge, ZUGFeRD DocumentTypeCode 381.

curl

curl -X POST https://api.dversum.com/api/v1/invoices/INVOICE_ID/credit-note \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

Angebote

Angebote mit digitaler Unterschrift und 1-Klick-Umwandlung in eine Rechnung.

POST/quotes

Erstellt ein neues Angebot.

curl

curl -X POST https://api.dversum.com/api/v1/quotes \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"client_id":"CLIENT_ID","valid_until":"2026-07-05","line_items": [
      {"description":"Webdesign","quantity": 1,"unit_price_cents": 350000,"tax_rate": 19 }
    ]
  }'

POST/quotes/{id}/send

Sendet das Angebot per E-Mail inklusive Unterzeichnungslink.

curl

curl -X POST https://api.dversum.com/api/v1/quotes/QUOTE_ID/send \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

POST/quotes/{id}/convert-to-invoice

Wandelt ein unterzeichnetes Angebot in eine Rechnung um.

curl

curl -X POST https://api.dversum.com/api/v1/quotes/QUOTE_ID/convert-to-invoice \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

Zeiterfassung

Zeiterfassung pro Aufgabe oder Projekt. Timer oder Bulk-Einträge — beides erzeugt dieselbe Datenstruktur.

POST/time-entries/start

Startet einen Timer für die aktuelle Aufgabe.

curl

curl -X POST https://api.dversum.com/api/v1/time-entries/start \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"task_id":"TASK_ID","description":"Mockup feedback" }'

POST/time-entries/{id}/stop

Stoppt den laufenden Timer.

curl

curl -X POST https://api.dversum.com/api/v1/time-entries/TIME_ENTRY_ID/stop \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

POST/time-entries

Erstellt einen Zeiteintrag rückwirkend.

curl

curl -X POST https://api.dversum.com/api/v1/time-entries \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"task_id":"TASK_ID","started_at":"2026-06-04T09:00:00Z","ended_at":"2026-06-04T11:30:00Z","billable": true
  }'

Kalender

Kalenderereignisse mit optionaler Google-Meet-Verknüpfung. Erstellte Events können automatisch zu Google Calendar synchronisiert werden.

GET/calendar/events

Listet Ereignisse im Zeitraum (?from=…&to=… in ISO 8601).

curl

curl"https://api.dversum.com/api/v1/calendar/events?from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z" \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

POST/calendar/events

Erstellt ein Ereignis. Setze attach_meet=true für ein Google-Meet-Link.

curl

curl -X POST https://api.dversum.com/api/v1/calendar/events \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"title":"Kickoff","start_time":"2026-06-12T10:00:00Z","end_time":"2026-06-12T11:00:00Z","attach_meet": true,"attendee_emails": ["client@example.com"]
  }'

Seiten

Notion-ähnliche Tiptap-Seiten mit verschachtelter Hierarchie. Markdown-Inhalte werden serverseitig in ProseMirror konvertiert — inkl. Tabellen.

POST/pages

Erstellt eine neue Seite mit optionalem Markdown-Inhalt.

curl

curl -X POST https://api.dversum.com/api/v1/pages \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"title":"Q2 Analyse","icon":"📊","content":"# Q2 Analyse\n\n| Metrik | Wert |\n|---|---|\n| Revenue | 41.804 € |"
  }'

PUT/pages/{id}/content

Ersetzt den Inhalt der Seite mit Markdown (oder ProseMirror-JSON).

curl

curl -X PUT https://api.dversum.com/api/v1/pages/PAGE_ID/content \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"content":"## Updated section\n\nNeuer Text" }'

GET/pages/tree

Liefert die vollständige Seitenhierarchie als geschachtelte Liste.

curl

curl https://api.dversum.com/api/v1/pages/tree \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

Dateien

S3-gespeicherte Dateien mit Ordnerhierarchie und WeTransfer-ähnlichen Share-Links.

POST/storage/files

Lädt eine Datei hoch (multipart/form-data, max. 100 MB).

curl

curl -X POST https://api.dversum.com/api/v1/storage/files \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -F"file=@./report.pdf" \
  -F"folder_id=FOLDER_ID"

GET/storage/files/{id}/download

Erzeugt eine signierte S3-URL (gültig 5 Min) für den Download.

curl

curl https://api.dversum.com/api/v1/storage/files/FILE_ID/download \
  -H"Authorization: Bearer $DVERSUM_TOKEN"

POST/storage/shares/{fileId}

Erstellt einen öffentlichen Share-Link mit optionalem Passwort und Ablaufdatum.

curl

curl -X POST https://api.dversum.com/api/v1/storage/shares/FILE_ID \
  -H"Authorization: Bearer $DVERSUM_TOKEN" \
  -H"Content-Type: application/json" \
  -d '{"password":"geheim","expires_at":"2026-07-01T00:00:00Z","max_downloads": 10 }'

Buchungen

Cal.com-ähnliche öffentliche Buchungsseite pro Nutzer. Die Buchungs-Endpunkte sind unauthentifiziert und geben den verfügbaren Slot-Pool zurück.

GET/public/booking/{user_slug}/{type_slug}

Liefert Metadaten zur Buchungsart (Name, Dauer, Beschreibung).

curl

curl https://api.dversum.com/api/v1/public/booking/admin/termin-mit-naumche

GET/public/booking/{user_slug}/{type_slug}/slots

Berechnet verfügbare Slots im Zeitraum (?from=…&to=… RFC 3339, max. 90 Tage).

curl

curl"https://api.dversum.com/api/v1/public/booking/admin/termin-mit-naumche/slots?from=2026-06-04T00:00:00Z&to=2026-06-11T00:00:00Z"

POST/public/booking/{user_slug}/{type_slug}/book

Bucht einen Slot — sendet Bestätigungsmail an Gast + Host und legt das Kalenderereignis an.

curl

curl -X POST https://api.dversum.com/api/v1/public/booking/admin/termin-mit-naumche/book \
  -H"Content-Type: application/json" \
  -d '{"start":"2026-06-05T09:00:00Z","name":"Max Mustermann","email":"max@example.com","agenda":"Kurzes Intro-Gespräch","timezone":"Europe/Berlin"
  }'

SDKs & Integrationen

MCP-Server

Modell-Kontext-Protokoll für Claude Desktop, Cursor und andere AI-Clients. Über 100 Tools für CRUD auf alle Kern-Ressourcen.

npx -y @dversum/mcp-server

Browser-Erweiterung

dVersum Companion — Universal-Element-Picker für Chrome/Edge. Speichert Webinhalte als Aufgaben.

Chrome Web Store →

Postman-Collection

Komplette Sammlung aller Endpunkte mit vordefinierten Variablen. Bald verfügbar.

Bald verfügbar

OpenAPI 3.1

Maschinenlesbare Spezifikation — generiere Clients für TypeScript, Python, Go. Bald verfügbar.

Bald verfügbar

n8n

Eingehende Webhooks aus n8n (oder jeder Automations-Plattform). Berechtigungen pro Webhook fein granular einstellbar.

Anleitung →

Zapier / Make

Über die Webhook-Trigger sofort einsatzbar. Eigener App-Connector folgt.

Bald verfügbar

Support

Fehlt dir ein Endpunkt? Stimmt eine Antwort nicht? Schreib uns — wir antworten in Tagen, nicht Wochen.

api@dversum.com·Hilfe-Center·GitHub