KAOS API

Externe Schnittstelle von KAOS, dem CRM und der Warenwirtschaft von KAEMI. Basis-URL https://api-kaos.kaemi.app · openapi.json (OpenAPI 3.1)

Authentifizierung

Jede Anfrage unter /v1 trägt einen API-Schlüssel: Authorization: Bearer kaos_<prefix>_<secret>. Schlüssel legen Administratoren in KAOS unter Einstellungen → API-Schlüssel an; der Klartext erscheint nur beim Anlegen. Jeder Schlüssel handelt als eigenes Dienstkonto mit einer Rolle: Leser liest, Mitarbeiter legt an und ändert, Manager darf zusätzlich löschen. Widerrufene Schlüssel antworten mit 401 und "code": "revoked".

Aufbau

JSON in beide Richtungen (Content-Type: application/json), Zeiten als ISO 8601 (UTC), Beträge als Zahlen.
Listen: ?q= (Suchtext), ?page=, ?limit= (höchstens 100) → { "items": [...], "total": n, "page": p, "limit": l }; Aufgaben und Lead-Quellen liefern { "items": [...] }.
Fehler: { "error": "…", "code"?: "…", "issues"?: { "feld": "Meldung" } } – 400 Validierung, 401 Schlüssel, 403 Rolle, 404 unbekannt oder nicht freigegeben, 429 mehr als 600 Anfragen je Minute und Schlüssel (Retry-After: 60).
Anlegen antwortet mit 201 und dem Datensatz, Ändern mit 200, Löschen mit 204. IDs stammen immer aus Antworten der API.

Beispiele

curl -H "Authorization: Bearer $KAOS_KEY" "https://api-kaos.kaemi.app/v1/organizations?q=Muster"

curl -X POST "https://api-kaos.kaemi.app/v1/organizations" \
  -H "Authorization: Bearer $KAOS_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Muster GmbH","city":"Hamburg","email":"info@muster.example"}'

curl -X POST "https://api-kaos.kaemi.app/v1/leads" \
  -H "Authorization: Bearer $KAOS_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Anfrage Webformular","org_id":123,"source":"Website","note":"Interesse an Colocation"}'

curl -X POST "https://api-kaos.kaemi.app/v1/deals/45/status" \
  -H "Authorization: Bearer $KAOS_KEY" -H "Content-Type: application/json" \
  -d '{"status":"won"}'

Endpunkte

Organisationen

Methode	Pfad	Beschreibung	Body
`GET`	`/v1/organizations`	Organisationen suchen und blättern	–
`GET`	`/v1/organizations/{id}`	Organisation lesen	–
`POST`	`/v1/organizations`	Organisation anlegen	JSON (Schema in openapi.json)
`PATCH`	`/v1/organizations/{id}`	Organisation ändern	JSON (Schema in openapi.json)
`DELETE`	`/v1/organizations/{id}`	Organisation löschen	–

Kontakte

Methode	Pfad	Beschreibung	Body
`GET`	`/v1/persons`	Kontakte suchen und blättern	–
`GET`	`/v1/persons/{id}`	Kontakt lesen	–
`POST`	`/v1/persons`	Kontakt anlegen	JSON (Schema in openapi.json)
`PATCH`	`/v1/persons/{id}`	Kontakt ändern	JSON (Schema in openapi.json)
`DELETE`	`/v1/persons/{id}`	Kontakt löschen	–

Leads

Methode	Pfad	Beschreibung	Body
`GET`	`/v1/leads`	Leads suchen und blättern	–
`GET`	`/v1/leads/sources`	Lead-Quellen	–
`GET`	`/v1/leads/{id}`	Lead lesen	–
`POST`	`/v1/leads`	Lead anlegen (Organisation oder Kontakt nötig)	JSON (Schema in openapi.json)
`PATCH`	`/v1/leads/{id}`	Lead ändern	JSON (Schema in openapi.json)
`POST`	`/v1/leads/{id}/convert`	Lead in einen Deal umwandeln	JSON (Schema in openapi.json)
`POST`	`/v1/leads/{id}/lose`	Lead als verloren markieren	JSON (Schema in openapi.json)
`POST`	`/v1/leads/{id}/reopen`	Lead wieder öffnen	–
`DELETE`	`/v1/leads/{id}`	Lead löschen	–

Deals

Methode	Pfad	Beschreibung	Body
`GET`	`/v1/deals`	Deals suchen und blättern	–
`GET`	`/v1/deals/{id}`	Deal lesen	–
`POST`	`/v1/deals`	Deal anlegen	JSON (Schema in openapi.json)
`PATCH`	`/v1/deals/{id}`	Deal ändern (auch Phase und Besitzer)	JSON (Schema in openapi.json)
`POST`	`/v1/deals/{id}/status`	Deal gewonnen, verloren oder wieder offen setzen	JSON (Schema in openapi.json)
`DELETE`	`/v1/deals/{id}`	Deal löschen	–

Aufgaben

Methode	Pfad	Beschreibung	Body
`GET`	`/v1/activities`	Aufgaben und Aktivitäten	–
`POST`	`/v1/activities`	Aufgabe anlegen	JSON (Schema in openapi.json)
`PATCH`	`/v1/activities/{id}`	Aufgabe ändern oder erledigen	JSON (Schema in openapi.json)
`DELETE`	`/v1/activities/{id}`	Aufgabe löschen	–

Notizen

Methode	Pfad	Beschreibung	Body
`POST`	`/v1/notes`	Notiz anlegen	JSON (Schema in openapi.json)
`PATCH`	`/v1/notes/{id}`	Notiz ändern	JSON (Schema in openapi.json)
`DELETE`	`/v1/notes/{id}`	Notiz löschen	–

Angebote

Methode	Pfad	Beschreibung	Body
`GET`	`/v1/quotes`	Angebote suchen und blättern	–
`GET`	`/v1/quotes/{id}`	Angebot mit Positionen lesen	–
`GET`	`/v1/quotes/{id}/pdf`	Angebots-PDF	–
`POST`	`/v1/quotes`	Angebot anlegen	JSON (Schema in openapi.json)
`PATCH`	`/v1/quotes/{id}`	Angebot ändern	JSON (Schema in openapi.json)
`POST`	`/v1/quotes/{id}/status`	Angebotsstatus setzen	JSON (Schema in openapi.json)

Artikel

Methode	Pfad	Beschreibung	Body
`GET`	`/v1/articles`	Artikel suchen und blättern	–
`GET`	`/v1/articles/{id}`	Artikel lesen	–

Alle Felder, Pflichtangaben und Wertebereiche stehen maschinenlesbar in openapi.json.