@cosmicdrift/kumiko-samples 0.411.0 → 0.412.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/packages/bundled-features/package.json +1 -1
- package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
- package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
- package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
- package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
- package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
- package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
- package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
- package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
- package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
- package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
- package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
- package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
- package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
- package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
- package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
- package/packages/bundled-features/src/agent-tools/changes.json +24 -0
- package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
- package/packages/bundled-features/src/agent-tools/index.ts +24 -0
- package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
- package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
- package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
- package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
- package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
- package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
- package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
- package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
- package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
- package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
- package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
- package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
- package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
- package/samples/recipes/api-docs/README.md +52 -0
- package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/index.json +371 -0
- package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
- package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
- package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
- package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
- package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
- package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
- package/samples/recipes/api-docs/kumiko.config.ts +33 -0
- package/samples/recipes/api-docs/package.json +14 -0
- package/samples/recipes/api-docs/src/feature.ts +218 -0
- package/samples/recipes/api-docs/tsconfig.json +22 -0
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# API docs
|
|
2
|
+
|
|
3
|
+
API documentation for personal access tokens, generated from the app itself. A helpdesk
|
|
4
|
+
feature exposes its ticket handlers through token scopes; `kumiko api-docs` turns the
|
|
5
|
+
registry, the translations and recorded requests into Markdown pages, an OpenAPI file and
|
|
6
|
+
an `index.json` that a website or an agent can read.
|
|
7
|
+
|
|
8
|
+
## What it shows
|
|
9
|
+
|
|
10
|
+
- **Scopes decide the content.** Only handlers that a scope of the token feature reaches
|
|
11
|
+
appear. `helpdesk:write:ticket:purge` is reachable from a screen but in no scope, so it is
|
|
12
|
+
listed under `apiDocs.uiOnlyWrites` with a reason; without that entry the generator reports it.
|
|
13
|
+
- **Texts come from the feature.** Titles, descriptions and field labels per locale use the
|
|
14
|
+
keys `<handler qn>:title`, `:description` and `:field:<name>`; the German pages need the
|
|
15
|
+
German translations, the menu path to the token screen comes from the nav tree.
|
|
16
|
+
- **Examples are recordings.** The integration test sends real requests with a token through
|
|
17
|
+
`recordApiExample` from `@cosmicdrift/kumiko-testing/api-examples`. UUIDs, timestamps and
|
|
18
|
+
tokens are replaced by fixed values, so a recording only changes when the API changes.
|
|
19
|
+
- **The output is a golden.** `api-docs/` is committed and the golden test fails when the
|
|
20
|
+
generator would produce something else.
|
|
21
|
+
|
|
22
|
+
## Commands
|
|
23
|
+
|
|
24
|
+
Record the examples (writes `api-examples/`, needs Postgres from `docker compose up -d`):
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
KUMIKO_RECORD_API_EXAMPLES=1 bun test --config=bunfig.integration.toml samples/recipes/api-docs/src/__tests__/api-docs.integration.test.ts
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Regenerate the golden (empties and rewrites `api-docs/`):
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
KUMIKO_UPDATE_API_DOCS_GOLDEN=1 bun test samples/recipes/api-docs/src/__tests__/api-docs.golden.test.ts
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Both tests run without the flags as ordinary checks.
|
|
37
|
+
|
|
38
|
+
In an app, `kumiko api-docs` writes the pages to `apiDocs.outDir` (default `api-docs`) and
|
|
39
|
+
`kumiko api-docs --check` compares them with the disk, so a CI step can keep them current.
|
|
40
|
+
The golden test pins the framework and app version in `index.json` and `openapi.json`, so
|
|
41
|
+
those two files differ from a real run of the command.
|
|
42
|
+
|
|
43
|
+
## Files
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
kumiko.config.ts features and the apiDocs block
|
|
47
|
+
src/feature.ts helpdesk feature and the token feature with its scopes
|
|
48
|
+
src/__tests__/api-docs.integration.test.ts mints a token, records the examples, checks scope limits
|
|
49
|
+
src/__tests__/api-docs.golden.test.ts generator output equals api-docs/
|
|
50
|
+
api-examples/ recorded requests and responses
|
|
51
|
+
api-docs/ the golden output
|
|
52
|
+
```
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Webhook-Ereignisse"
|
|
3
|
+
description: "Webhook-Ereignisse: wann sie ausgelöst werden, welchen Scope sie brauchen und was ihre Nutzlast enthält."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Ein Webhook-Ereignis meldet deinem System, dass sich etwas geändert hat. Jedes Ereignis hat einen Namen, eine Version und eine Nutzlast. Der bei einem Ereignis genannte Scope ist der Token-Scope, der das Abonnieren erlaubt.
|
|
7
|
+
|
|
8
|
+
## Zustellung
|
|
9
|
+
|
|
10
|
+
Zustellungen sind signiert, damit du den Absender prüfen kannst. Eine fehlgeschlagene Zustellung wird einige Male wiederholt, bevor sie verworfen wird. Antworte innerhalb weniger Sekunden und behandle wiederholte Zustellungen desselben Ereignisses als eine.
|
|
11
|
+
|
|
12
|
+
## Versionen
|
|
13
|
+
|
|
14
|
+
Ein neues optionales Feld behält die Version. Eine inkompatible Änderung, etwa ein entferntes oder umbenanntes Feld oder ein geänderter Typ, bekommt eine neue Version.
|
|
15
|
+
|
|
16
|
+
## Ereignisse
|
|
17
|
+
|
|
18
|
+
### ticket.closed
|
|
19
|
+
|
|
20
|
+
Ein Ticket wurde geschlossen und seine Lösung festgehalten.
|
|
21
|
+
|
|
22
|
+
- Version: `1`
|
|
23
|
+
- Benötigter Scope: `tickets:read`
|
|
24
|
+
|
|
25
|
+
| Feld | Typ | Pflicht | Beschreibung |
|
|
26
|
+
| --- | --- | --- | --- |
|
|
27
|
+
| `id` | string (uuid) | ja | ID des geschlossenen Tickets |
|
|
28
|
+
| `resolution` | string | ja | Wie das Ticket gelöst wurde |
|
|
29
|
+
|
|
30
|
+
**Beispiel-Nutzlast**
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
35
|
+
"resolution": "Replaced the roller"
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### ticket.created
|
|
40
|
+
|
|
41
|
+
Ein Datensatz vom Typ Ticket wurde angelegt.
|
|
42
|
+
|
|
43
|
+
- Version: `1`
|
|
44
|
+
- Benötigter Scope: `tickets:read`
|
|
45
|
+
|
|
46
|
+
| Feld | Typ | Pflicht | Beschreibung |
|
|
47
|
+
| --- | --- | --- | --- |
|
|
48
|
+
| `id` | string (uuid) | ja | Ticket-ID |
|
|
49
|
+
| `title` | string | ja | Titel |
|
|
50
|
+
| `status` | "open" \| "closed" | ja | Status |
|
|
51
|
+
| `priority` | "low" \| "normal" \| "high" | ja | Priorität |
|
|
52
|
+
|
|
53
|
+
**Beispiel-Nutzlast**
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
58
|
+
"title": "Scanner jams",
|
|
59
|
+
"status": "open",
|
|
60
|
+
"priority": "low"
|
|
61
|
+
}
|
|
62
|
+
```
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "HTTP-API"
|
|
3
|
+
description: "Endpunkte, Request-Body, Antworten, Fehlercodes, Listen und Batches der HTTP-API."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Jeder Aufruf ist ein POST mit JSON-Body. Das Feld `type` nennt den Handler, `payload` enthält dessen Felder. Die Referenzseiten listen jeden Handler mit seinen Feldern.
|
|
7
|
+
|
|
8
|
+
## Endpunkte
|
|
9
|
+
|
|
10
|
+
| Endpoint | |
|
|
11
|
+
| --- | --- |
|
|
12
|
+
| `POST /api/query` | Liest Daten. Ändert nie etwas. |
|
|
13
|
+
| `POST /api/write` | Ändert Daten: anlegen, ändern, löschen oder eine bestimmte Aktion. |
|
|
14
|
+
| `POST /api/batch` | Führt mehrere Schreibaufrufe in einer Transaktion aus. |
|
|
15
|
+
|
|
16
|
+
## Authentifizierung
|
|
17
|
+
|
|
18
|
+
Sende einen API-Token im Header `Authorization` als `Bearer <token>`. Anfragen mit Token brauchen weder Cookie noch CSRF-Token. Der Token legt auch das Konto fest, in dem die Anfrage läuft. Du sendest also nie eine Konto- oder Mandanten-ID.
|
|
19
|
+
|
|
20
|
+
## Request-Body
|
|
21
|
+
|
|
22
|
+
`type` ist der Name des Handlers, zum Beispiel `helpdesk:query:ticket:detail`. `payload` enthält die Felder aus der Referenz. `requestId` ist optional, siehe unten. Das Payload darf höchstens 20 Ebenen tief verschachtelt sein.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
curl -X POST https://helpdesk.example.com/api/query \
|
|
26
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
27
|
+
-H "Content-Type: application/json" \
|
|
28
|
+
-d '{
|
|
29
|
+
"type": "helpdesk:query:ticket:detail",
|
|
30
|
+
"payload": {
|
|
31
|
+
"id": "00000000-0000-4000-8000-000000000001"
|
|
32
|
+
}
|
|
33
|
+
}'
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Antworten
|
|
37
|
+
|
|
38
|
+
Ein erfolgreiches Lesen liefert `data`. Ein erfolgreiches Schreiben liefert `isSuccess: true` und `data`.
|
|
39
|
+
|
|
40
|
+
Bei einem Fehler ist der HTTP-Status 4xx oder 5xx und der Body enthält `error`. Schreibaufrufe liefern zusätzlich `isSuccess: false`. Werte `error.code` und den Status aus. `message` ist für Menschen gedacht und kann sich ändern.
|
|
41
|
+
|
|
42
|
+
## Fehlercodes
|
|
43
|
+
|
|
44
|
+
| Code | HTTP-Status | Bedeutung |
|
|
45
|
+
| --- | --- | --- |
|
|
46
|
+
| `ambiguous_auth` | 400 | Die Anfrage enthielt Session-Cookie und Token. Sende nur eines von beiden. |
|
|
47
|
+
| `validation_error` | 400 | Das Payload passt nicht zu den Feldern des Handlers. `details` nennt die Felder. |
|
|
48
|
+
| `invalid_token` | 401 | Der Token ist unbekannt, widerrufen oder abgelaufen. |
|
|
49
|
+
| `missing_token` | 401 | Der Header `Authorization` fehlt. |
|
|
50
|
+
| `unauthenticated` | 401 | Es wurden keine gültigen Zugangsdaten gesendet. |
|
|
51
|
+
| `access_denied` | 403 | Dem Token fehlt der Scope für diesen Handler, oder der Endpunkt nimmt keine Tokens an. |
|
|
52
|
+
| `feature_disabled` | 403 | Diese Funktion ist abgeschaltet oder nicht Teil deines Tarifs. |
|
|
53
|
+
| `not_found` | 404 | Der Datensatz existiert nicht oder du darfst ihn nicht sehen. |
|
|
54
|
+
| `conflict` | 409 | Die Änderung widerspricht dem aktuellen Stand der Daten. |
|
|
55
|
+
| `idempotent_replay` | 409 | Diese Änderung wurde unter demselben Idempotenz-Schlüssel schon ausgeführt. Der erste Versuch war erfolgreich, sende sie nicht noch einmal. |
|
|
56
|
+
| `precondition_failed` | 409 | Ein Feld des Datensatzes hat nicht mehr den Wert, den die Änderung erwartet hat. Lies den Datensatz neu und wiederhole. |
|
|
57
|
+
| `record_locked` | 409 | Eine andere Änderung sperrt den Datensatz. Wiederhole gleich. |
|
|
58
|
+
| `unique_violation` | 409 | Ein Datensatz mit diesem Wert existiert bereits. |
|
|
59
|
+
| `version_conflict` | 409 | Der Datensatz hat sich nach deinem Lesen geändert. Lies ihn neu und wiederhole mit der neuen `version`. |
|
|
60
|
+
| `unconfigured` | 422 | Eine Einstellung, die diese Funktion braucht, ist noch leer. Richte sie zuerst in der App ein und wiederhole dann. |
|
|
61
|
+
| `unprocessable` | 422 | Die Daten sind gültig, aber eine Fachregel lehnt die Änderung ab. `details.reason` nennt die Regel. |
|
|
62
|
+
| `pat_rate_limited` | 429 | Dieser Token hat in kurzer Zeit zu viele Anfragen gesendet. Warte einen Moment und wiederhole. |
|
|
63
|
+
| `rate_limited` | 429 | Zu viele Anfragen. Warte so viele Sekunden, wie der Header `Retry-After` angibt. |
|
|
64
|
+
| `internal_error` | 500 | Unerwarteter Serverfehler. Wiederhole später. |
|
|
65
|
+
| `rate_limit_unavailable` | 503 | Die Ratenbegrenzung ist vorübergehend nicht verfügbar, die Anfrage wurde abgelehnt. Wiederhole gleich. |
|
|
66
|
+
| `member_read_timeout` | 504 | Ein Lesevorgang auf dem Server hat zu lange gedauert und wurde abgebrochen. Wiederhole später. |
|
|
67
|
+
|
|
68
|
+
## Versionen und Konflikte
|
|
69
|
+
|
|
70
|
+
Jeder Datensatz hat eine `version`. Ein Update nimmt die `version`, die du zuletzt gelesen hast. Hat jemand den Datensatz zwischenzeitlich geändert, schlägt der Aufruf mit 409 `version_conflict` fehl. Lies den Datensatz neu, prüfe die Änderung und sende sie mit der neuen Version.
|
|
71
|
+
|
|
72
|
+
## Listen
|
|
73
|
+
|
|
74
|
+
Listen-Handler enden auf `:list` und akzeptieren diese Felder:
|
|
75
|
+
|
|
76
|
+
| Feld | Typ | Beschreibung |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| `cursor` | string | Position aus `nextCursor` der vorherigen Seite. |
|
|
79
|
+
| `limit` | integer | Zeilen pro Seite, standardmäßig 50, höchstens 200. |
|
|
80
|
+
| `search` | string | Volltextsuche über die durchsuchbaren Felder. |
|
|
81
|
+
| `sort` | string | Feld, nach dem sortiert wird. |
|
|
82
|
+
| `sortDirection` | "asc" \| "desc" | `asc` oder `desc`. |
|
|
83
|
+
| `offset` | integer | Anzahl der zu überspringenden Zeilen. Nutze besser `cursor` zum Blättern. |
|
|
84
|
+
| `totalCount` | boolean | Mit `true` bekommst du zusätzlich `total`, die Anzahl der passenden Zeilen. |
|
|
85
|
+
| `includeDeleted` | boolean | Mit `true` sind gelöschte Zeilen enthalten. Nur für Entitäten mit Soft Delete. |
|
|
86
|
+
| `onlyDeleted` | boolean | Mit `true` kommen nur gelöschte Zeilen zurück. Nur für Entitäten mit Soft Delete, nicht zusammen mit `includeDeleted`. |
|
|
87
|
+
| `filter` | object | Ein Feldfilter mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
88
|
+
| `filters` | array of object | Mehrere Feldfilter, je mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
89
|
+
| `namedFilter` | string | Name eines vordefinierten Filters der Entität, zum Beispiel einer Arbeitsliste. |
|
|
90
|
+
| `aggregate` | object | Liefert aggregierte Werte statt Zeilen. |
|
|
91
|
+
|
|
92
|
+
Die Antwort enthält `rows` und `nextCursor`. Für die nächste Seite sendest du `nextCursor` als `cursor`. Auf der letzten Seite ist `nextCursor` `null`.
|
|
93
|
+
|
|
94
|
+
## Batches
|
|
95
|
+
|
|
96
|
+
`POST /api/batch` nimmt `commands`, eine Liste von Schreibaufrufen `{ type, payload }`. Sie laufen in einer Transaktion: Schlägt einer fehl, wirkt keiner. Die Antwort hat dann `isSuccess: false`, den `error` und `failedIndex`, die Position des fehlgeschlagenen Befehls ab 0 gezählt.
|
|
97
|
+
|
|
98
|
+
## Sicher wiederholen
|
|
99
|
+
|
|
100
|
+
Sende bei Schreib- und Batch-Aufrufen eine `requestId` mit. Das ist ein beliebiger String, der pro Änderung eindeutig ist. Reißt die Verbindung ab und du sendest denselben Aufruf mit derselben `requestId` erneut, bekommst du das erste Ergebnis zurück und die Änderung läuft nicht doppelt.
|
|
@@ -0,0 +1,305 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Tickets"
|
|
3
|
+
description: "API-Referenz für Tickets: jeder Handler mit seinen Feldern und einem Beispiel."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
### ticket: detail
|
|
7
|
+
|
|
8
|
+
**Ticket anzeigen**
|
|
9
|
+
|
|
10
|
+
Liefert ein Ticket.
|
|
11
|
+
|
|
12
|
+
- Benötigter Scope: `tickets:read`
|
|
13
|
+
- Endpunkt: `POST /api/query`
|
|
14
|
+
|
|
15
|
+
| Feld | Typ | Pflicht | Beschreibung |
|
|
16
|
+
| --- | --- | --- | --- |
|
|
17
|
+
| `id` | string (uuid) | ja | Ticket-ID |
|
|
18
|
+
|
|
19
|
+
**Beispielanfrage**
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
curl -X POST https://helpdesk.example.com/api/query \
|
|
23
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
24
|
+
-H "Content-Type: application/json" \
|
|
25
|
+
-d '{
|
|
26
|
+
"type": "helpdesk:query:ticket:detail",
|
|
27
|
+
"payload": {
|
|
28
|
+
"id": "00000000-0000-4000-8000-000000000001"
|
|
29
|
+
}
|
|
30
|
+
}'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**Beispielantwort**
|
|
34
|
+
|
|
35
|
+
Status: 200
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"data": {
|
|
40
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
41
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
42
|
+
"version": 1,
|
|
43
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
44
|
+
"modifiedAt": null,
|
|
45
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
46
|
+
"modifiedById": null,
|
|
47
|
+
"title": "Printer is on fire",
|
|
48
|
+
"status": "open",
|
|
49
|
+
"priority": "high"
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### ticket: list
|
|
55
|
+
|
|
56
|
+
**Tickets auflisten**
|
|
57
|
+
|
|
58
|
+
Listet Tickets, neueste zuerst.
|
|
59
|
+
|
|
60
|
+
- Benötigter Scope: `tickets:read`
|
|
61
|
+
- Endpunkt: `POST /api/query`
|
|
62
|
+
|
|
63
|
+
| Feld | Typ | Pflicht | Beschreibung |
|
|
64
|
+
| --- | --- | --- | --- |
|
|
65
|
+
| `cursor` | string | nein | Position aus `nextCursor` der vorherigen Seite. |
|
|
66
|
+
| `limit` | integer | nein | Zeilen pro Seite, standardmäßig 50, höchstens 200. |
|
|
67
|
+
| `search` | string | nein | Volltextsuche über die durchsuchbaren Felder. |
|
|
68
|
+
| `sort` | string | nein | Feld, nach dem sortiert wird. |
|
|
69
|
+
| `sortDirection` | "asc" \| "desc" | nein | `asc` oder `desc`. |
|
|
70
|
+
| `offset` | integer | nein | Anzahl der zu überspringenden Zeilen. Nutze besser `cursor` zum Blättern. |
|
|
71
|
+
| `totalCount` | boolean | nein | Mit `true` bekommst du zusätzlich `total`, die Anzahl der passenden Zeilen. |
|
|
72
|
+
| `includeDeleted` | boolean | nein | Mit `true` sind gelöschte Zeilen enthalten. Nur für Entitäten mit Soft Delete. |
|
|
73
|
+
| `onlyDeleted` | boolean | nein | Mit `true` kommen nur gelöschte Zeilen zurück. Nur für Entitäten mit Soft Delete, nicht zusammen mit `includeDeleted`. |
|
|
74
|
+
| `filter` | object | nein | Ein Feldfilter mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
75
|
+
| `filter.field` | string | ja | |
|
|
76
|
+
| `filter.op` | "eq" \| "ne" \| "lt" \| "gt" \| "lte" \| "gte" \| "in" | ja | |
|
|
77
|
+
| `filter.value` | any | ja | |
|
|
78
|
+
| `filters` | array of object | nein | Mehrere Feldfilter, je mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
79
|
+
| `namedFilter` | string | nein | Name eines vordefinierten Filters der Entität, zum Beispiel einer Arbeitsliste. |
|
|
80
|
+
| `aggregate` | object | nein | Liefert aggregierte Werte statt Zeilen. |
|
|
81
|
+
| `aggregate.groupBy` | string | nein | |
|
|
82
|
+
| `aggregate.measures` | array of object | nein | |
|
|
83
|
+
|
|
84
|
+
**Beispielanfrage**
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
curl -X POST https://helpdesk.example.com/api/query \
|
|
88
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
89
|
+
-H "Content-Type: application/json" \
|
|
90
|
+
-d '{
|
|
91
|
+
"type": "helpdesk:query:ticket:list",
|
|
92
|
+
"payload": {}
|
|
93
|
+
}'
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**Beispielantwort**
|
|
97
|
+
|
|
98
|
+
Status: 200
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"data": {
|
|
103
|
+
"rows": [
|
|
104
|
+
{
|
|
105
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
106
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
107
|
+
"version": 1,
|
|
108
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
109
|
+
"modifiedAt": null,
|
|
110
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
111
|
+
"modifiedById": null,
|
|
112
|
+
"title": "Printer is on fire",
|
|
113
|
+
"status": "open",
|
|
114
|
+
"priority": "high"
|
|
115
|
+
}
|
|
116
|
+
],
|
|
117
|
+
"nextCursor": null
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### ticket: close
|
|
123
|
+
|
|
124
|
+
**Ticket schließen**
|
|
125
|
+
|
|
126
|
+
Schließt ein Ticket und hält fest, wie es gelöst wurde.
|
|
127
|
+
|
|
128
|
+
- Benötigter Scope: `tickets:write`
|
|
129
|
+
- Endpunkt: `POST /api/write`
|
|
130
|
+
|
|
131
|
+
| Feld | Typ | Pflicht | Beschreibung |
|
|
132
|
+
| --- | --- | --- | --- |
|
|
133
|
+
| `id` | string (uuid) | ja | Ticket |
|
|
134
|
+
| `resolution` | string | ja | Lösung |
|
|
135
|
+
|
|
136
|
+
**Beispielanfrage**
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
curl -X POST https://helpdesk.example.com/api/write \
|
|
140
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
141
|
+
-H "Content-Type: application/json" \
|
|
142
|
+
-d '{
|
|
143
|
+
"type": "helpdesk:write:ticket:close",
|
|
144
|
+
"payload": {
|
|
145
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
146
|
+
"resolution": "Replaced the cartridge"
|
|
147
|
+
}
|
|
148
|
+
}'
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
**Beispielantwort**
|
|
152
|
+
|
|
153
|
+
Status: 200
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"isSuccess": true,
|
|
158
|
+
"data": {
|
|
159
|
+
"id": "00000000-0000-4000-8000-000000000001"
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### ticket: create
|
|
165
|
+
|
|
166
|
+
**Ticket anlegen**
|
|
167
|
+
|
|
168
|
+
Legt ein neues Ticket an.
|
|
169
|
+
|
|
170
|
+
- Benötigter Scope: `tickets:write`
|
|
171
|
+
- Endpunkt: `POST /api/write`
|
|
172
|
+
|
|
173
|
+
| Feld | Typ | Pflicht | Beschreibung |
|
|
174
|
+
| --- | --- | --- | --- |
|
|
175
|
+
| `title` | string | ja | Titel |
|
|
176
|
+
| `status` | "open" \| "closed" | nein | Status |
|
|
177
|
+
| `priority` | "low" \| "normal" \| "high" | nein | Priorität |
|
|
178
|
+
|
|
179
|
+
**Beispielanfrage**
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
curl -X POST https://helpdesk.example.com/api/write \
|
|
183
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
184
|
+
-H "Content-Type: application/json" \
|
|
185
|
+
-d '{
|
|
186
|
+
"type": "helpdesk:write:ticket:create",
|
|
187
|
+
"payload": {
|
|
188
|
+
"title": "Printer is on fire",
|
|
189
|
+
"priority": "high"
|
|
190
|
+
}
|
|
191
|
+
}'
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**Beispielantwort**
|
|
195
|
+
|
|
196
|
+
Status: 200
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{
|
|
200
|
+
"isSuccess": true,
|
|
201
|
+
"data": {
|
|
202
|
+
"kind": "save",
|
|
203
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
204
|
+
"data": {
|
|
205
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
206
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
207
|
+
"version": 1,
|
|
208
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
209
|
+
"modifiedAt": null,
|
|
210
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
211
|
+
"modifiedById": null,
|
|
212
|
+
"title": "Printer is on fire",
|
|
213
|
+
"status": "open",
|
|
214
|
+
"priority": "high"
|
|
215
|
+
},
|
|
216
|
+
"changes": {
|
|
217
|
+
"title": "Printer is on fire",
|
|
218
|
+
"status": "open",
|
|
219
|
+
"priority": "high"
|
|
220
|
+
},
|
|
221
|
+
"previous": {},
|
|
222
|
+
"isNew": true,
|
|
223
|
+
"entityName": "ticket"
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### ticket: update
|
|
229
|
+
|
|
230
|
+
**Ticket ändern**
|
|
231
|
+
|
|
232
|
+
Ändert Titel oder Priorität eines Tickets.
|
|
233
|
+
|
|
234
|
+
- Benötigter Scope: `tickets:write`
|
|
235
|
+
- Endpunkt: `POST /api/write`
|
|
236
|
+
|
|
237
|
+
| Feld | Typ | Pflicht | Beschreibung |
|
|
238
|
+
| --- | --- | --- | --- |
|
|
239
|
+
| `id` | string (uuid) | ja | Ticket-ID |
|
|
240
|
+
| `version` | number | ja | |
|
|
241
|
+
| `changes` | object | ja | |
|
|
242
|
+
| `changes.title` | string | nein | Titel |
|
|
243
|
+
| `changes.status` | "open" \| "closed" | nein | Status |
|
|
244
|
+
| `changes.priority` | "low" \| "normal" \| "high" | nein | Priorität |
|
|
245
|
+
|
|
246
|
+
**Beispielanfrage**
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
curl -X POST https://helpdesk.example.com/api/write \
|
|
250
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
251
|
+
-H "Content-Type: application/json" \
|
|
252
|
+
-d '{
|
|
253
|
+
"type": "helpdesk:write:ticket:update",
|
|
254
|
+
"payload": {
|
|
255
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
256
|
+
"version": 1,
|
|
257
|
+
"changes": {
|
|
258
|
+
"priority": "normal"
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}'
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**Beispielantwort**
|
|
265
|
+
|
|
266
|
+
Status: 200
|
|
267
|
+
|
|
268
|
+
```json
|
|
269
|
+
{
|
|
270
|
+
"isSuccess": true,
|
|
271
|
+
"data": {
|
|
272
|
+
"kind": "save",
|
|
273
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
274
|
+
"data": {
|
|
275
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
276
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
277
|
+
"version": 2,
|
|
278
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
279
|
+
"modifiedAt": "2026-01-15T09:30:00.000Z",
|
|
280
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
281
|
+
"modifiedById": "00000000-0000-4000-8000-000000000003",
|
|
282
|
+
"title": "Printer is on fire",
|
|
283
|
+
"status": "open",
|
|
284
|
+
"priority": "normal"
|
|
285
|
+
},
|
|
286
|
+
"changes": {
|
|
287
|
+
"priority": "normal"
|
|
288
|
+
},
|
|
289
|
+
"previous": {
|
|
290
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
291
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
292
|
+
"version": 1,
|
|
293
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
294
|
+
"modifiedAt": null,
|
|
295
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
296
|
+
"modifiedById": null,
|
|
297
|
+
"title": "Printer is on fire",
|
|
298
|
+
"status": "open",
|
|
299
|
+
"priority": "high"
|
|
300
|
+
},
|
|
301
|
+
"isNew": false,
|
|
302
|
+
"entityName": "ticket"
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
```
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "API-Tokens"
|
|
3
|
+
description: "Lege einen API-Token für Helpdesk an, wähle seine Scopes und sende ihn mit deinen Anfragen."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Mit einem API-Token kann ein Skript oder ein anderer Dienst die API von Helpdesk in deinem Namen aufrufen. Seine Scopes bestimmen, welche Daten er lesen oder ändern darf.
|
|
7
|
+
|
|
8
|
+
## Token anlegen
|
|
9
|
+
|
|
10
|
+
1. Öffne Einstellungen › API-Tokens.
|
|
11
|
+
2. Wähle **Neuen Token erstellen**.
|
|
12
|
+
3. Gib einen Namen ein, wähle die Scopes und das Ablaufdatum und bestätige mit deinem Passwort.
|
|
13
|
+
4. Kopiere den Token. Er beginnt mit `kpat_` und wird nur einmal angezeigt.
|
|
14
|
+
|
|
15
|
+
Ein Token läuft nach 90 Tagen ab, wenn du keinen anderen Ablauf wählst. Möglich sind höchstens 3650 Tage.
|
|
16
|
+
|
|
17
|
+
## Token verwenden
|
|
18
|
+
|
|
19
|
+
Sende den Token im Header `Authorization`. Anfragen mit Token brauchen weder Cookie noch CSRF-Token.
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
curl -X POST https://helpdesk.example.com/api/query \
|
|
23
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
24
|
+
-H "Content-Type: application/json" \
|
|
25
|
+
-d '{
|
|
26
|
+
"type": "helpdesk:query:ticket:detail",
|
|
27
|
+
"payload": {
|
|
28
|
+
"id": "00000000-0000-4000-8000-000000000001"
|
|
29
|
+
}
|
|
30
|
+
}'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Scopes
|
|
34
|
+
|
|
35
|
+
Jeder Scope hat zwei Stufen. `read` erlaubt die lesenden Handler. `write` erlaubt alles, was `read` erlaubt, und zusätzlich die schreibenden Handler.
|
|
36
|
+
|
|
37
|
+
| Scope | Berechtigung | Handler |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| `tickets` (Tickets) | `tickets:read` | `helpdesk:query:ticket:detail`, `helpdesk:query:ticket:list` |
|
|
40
|
+
| `tickets` (Tickets) | `tickets:write` | `helpdesk:write:ticket:close`, `helpdesk:write:ticket:create`, `helpdesk:write:ticket:update` |
|
|
41
|
+
|
|
42
|
+
## Ratenbegrenzung
|
|
43
|
+
|
|
44
|
+
Jeder Token darf 60 Anfragen pro 60 Sekunden senden. Darüber antwortet die API mit 429 `pat_rate_limited`.
|
|
45
|
+
|
|
46
|
+
API-Tokens sind in jedem Helpdesk-Tarif enthalten.
|
|
47
|
+
|
|
48
|
+
## Fehler
|
|
49
|
+
|
|
50
|
+
| HTTP-Status | Code | Ursache |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| 401 | `missing_token` | Es fehlt der Header `Authorization`. |
|
|
53
|
+
| 401 | `invalid_token` | Der Token ist unbekannt, widerrufen oder abgelaufen. |
|
|
54
|
+
| 403 | `access_denied` | Dem Token fehlt der Scope für diesen Handler. |
|
|
55
|
+
| 403 | `access_denied` | Der Endpunkt nimmt keine Tokens an. Tokens funktionieren nur an den API-Endpunkten. |
|
|
56
|
+
| 429 | `pat_rate_limited` | Zu viele Anfragen mit diesem Token. |
|
|
57
|
+
|
|
58
|
+
## Token widerrufen
|
|
59
|
+
|
|
60
|
+
Widerrufe einen Token in Einstellungen › API-Tokens, sobald du ihn nicht mehr brauchst. Wenn du dein Passwort änderst, werden alle deine Tokens widerrufen. Ein Token handelt immer mit deinen aktuellen Rollen. Verlässt du das Konto oder wird dein Benutzer gelöscht, funktioniert er nicht mehr.
|
|
61
|
+
|
|
62
|
+
## Sicherheit
|
|
63
|
+
|
|
64
|
+
- Behandle einen Token wie ein Passwort. Bewahre ihn in einem Secret Store auf, nie im Code, in einem Repository, in einer App oder Webseite oder in einem Log.
|
|
65
|
+
- Gib jedem Skript einen eigenen Token mit nur den Scopes, die es braucht.
|
|
66
|
+
- Widerrufe Tokens, die du nicht mehr nutzt. Widerrufe einen Token sofort, wenn er in fremde Hände gelangt sein könnte.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Webhook events"
|
|
3
|
+
description: "Webhook events: when they fire, which scope they need and what their payload contains."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
A webhook event tells your system that something changed. Every event has a name, a version and a payload. The scope listed for an event is the token scope that allows subscribing to it.
|
|
7
|
+
|
|
8
|
+
## Delivery
|
|
9
|
+
|
|
10
|
+
Deliveries are signed so that you can verify the sender. A delivery that fails is retried a few times before it is dropped. Answer within a few seconds and treat repeated deliveries of the same event as one.
|
|
11
|
+
|
|
12
|
+
## Versions
|
|
13
|
+
|
|
14
|
+
Adding an optional field keeps the version. A breaking change, such as removing or renaming a field or changing its type, gets a new version.
|
|
15
|
+
|
|
16
|
+
## Events
|
|
17
|
+
|
|
18
|
+
### ticket.closed
|
|
19
|
+
|
|
20
|
+
A ticket was closed and its resolution recorded.
|
|
21
|
+
|
|
22
|
+
- Version: `1`
|
|
23
|
+
- Required scope: `tickets:read`
|
|
24
|
+
|
|
25
|
+
| Field | Type | Required | Description |
|
|
26
|
+
| --- | --- | --- | --- |
|
|
27
|
+
| `id` | string (uuid) | yes | ID of the closed ticket |
|
|
28
|
+
| `resolution` | string | yes | How the ticket was resolved |
|
|
29
|
+
|
|
30
|
+
**Example payload**
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
35
|
+
"resolution": "Replaced the roller"
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### ticket.created
|
|
40
|
+
|
|
41
|
+
A record of type ticket was created.
|
|
42
|
+
|
|
43
|
+
- Version: `1`
|
|
44
|
+
- Required scope: `tickets:read`
|
|
45
|
+
|
|
46
|
+
| Field | Type | Required | Description |
|
|
47
|
+
| --- | --- | --- | --- |
|
|
48
|
+
| `id` | string (uuid) | yes | Ticket ID |
|
|
49
|
+
| `title` | string | yes | Title |
|
|
50
|
+
| `status` | "open" \| "closed" | yes | Status |
|
|
51
|
+
| `priority` | "low" \| "normal" \| "high" | yes | Priority |
|
|
52
|
+
|
|
53
|
+
**Example payload**
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
58
|
+
"title": "Scanner jams",
|
|
59
|
+
"status": "open",
|
|
60
|
+
"priority": "low"
|
|
61
|
+
}
|
|
62
|
+
```
|