238 lines
22 KiB
Markdown
238 lines
22 KiB
Markdown
# Tsumugu – API-Referenz (Ist-Stand)
|
||
|
||
**Stand:** 18.10.2026, ergänzt am 19.10.2026 um Quelleninstanzen, Fähigkeiten und Zuordnung und am 23.10.2026 um Download-Regeln, HTML-Mail mit Bildern, Übersicht und Suche. Erstellt im Code-Review aus `backend/app/main.py`, `api/routes.py`, `api/sources.py`, `api/export.py` und `api/correspondence.py`.
|
||
|
||
Diese Datei beschreibt die tatsächlich registrierten Endpunkte. Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 6.2](TSUMUGU_TECHNICAL_SPEC.md). OpenAPI ist in allen Umgebungen abgeschaltet (`docs_url=None`, `openapi_url=None`). Diese Datei ist deshalb die einzige Übersicht. Sie wird bei jeder Routenänderung mitgepflegt.
|
||
|
||
## Gemeinsame Regeln
|
||
|
||
| Thema | Regel im Code |
|
||
|---|---|
|
||
| Sitzung | Cookie `__Host-jinkendo-session` (Produktion, HTTPS) bzw. `jinkendo-session` (Development über HTTP). Gültigkeit `SESSION_TTL_HOURS`, Default 336 h |
|
||
| Schreibschutz | Alle Methoden außer GET/HEAD/OPTIONS unter `/api/` verlangen einen `Origin` aus `ALLOWED_ORIGINS` (Middleware) und den Header `X-CSRF-Token` der Session |
|
||
| Datenraum | Fachrouten verlangen `X-Scope-Kind` (`personal` oder `organization`) und `X-Scope-Id`. Beide müssen mit dem in der Session bestätigten Raum übereinstimmen, die Mitgliedschaft wird je Request geprüft |
|
||
| Handlungskontext | Lesend als Query `context_kind` und `context_id` (`case`/`matter` + UUID), schreibend als `context: {kind, id}` im JSON. Ohne Kontext gelten nur Owner und direkte Grants |
|
||
| Eingaben | JSON ohne unbekannte Felder (`extra="forbid"`); Upload als Multipart |
|
||
| Fehler | `application/problem+json` mit `type`, `title`, `status`, `detail`, `instance`, `code`. 401 keine Session, 403 fehlendes Recht bei sichtbarem Objekt, 404 unsichtbar oder nicht vorhanden, 409 Versionskonflikt, 422 ungültige Eingabe, 429 Login-Begrenzung, 503 Speicher nicht verfügbar |
|
||
| Versionen | Ändernde Aufrufe tragen `expected_version` des geänderten Ankers (Akte, Vorgang, Element, Aufgabe, Frist). Kapitel- und Ordnungsänderungen erhöhen die Version des Behälters |
|
||
| Listen | Antwort `{items, next_cursor}`. `next_cursor` ist außer in der Chronologie immer `null` |
|
||
|
||
Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R** Session und Datenraum-Header, **B** Betreiber (`is_superadmin`), **M** Verwalter des Raums. Alle Tabellen ohne Spalte „Auth“ verlangen **S+R**; die Objektrechte prüft danach die Rechteauswertung ([RECHTEMODELL_IST.md](RECHTEMODELL_IST.md)).
|
||
|
||
## Betrieb
|
||
|
||
| Methode | Pfad | Auth | Zweck |
|
||
|---|---|---|---|
|
||
| GET | `/api/health` | – | `{status, app}`; 503 bei DB-Fehler |
|
||
| GET | `/health/live` | – | Prozess lebt |
|
||
| GET | `/health/ready` | – | DB antwortet |
|
||
|
||
## Anmeldung, Session, Konten
|
||
|
||
| Methode | Pfad | Auth | Zweck |
|
||
|---|---|---|---|
|
||
| POST | `/api/v1/auth/login` | – | E-Mail, Passwort → Session-Sicht und Cookie. 8 Fehlversuche je Bucket (Hash aus IP und E-Mail) in 10 min, gezählt in `auth_login_attempts` |
|
||
| POST | `/api/v1/auth/logout` | S | Session widerrufen, Cookie löschen, 204 |
|
||
| GET / PUT | `/api/v1/auth/download-defaults` | S+R, Hauptnutzer | Voreinstellung je Rolle und `direct` (direkt freigegebene Personen); neue Räume übernehmen die drei Rollenwerte. Audit `download_defaults_changed` |
|
||
| GET | `/api/v1/auth/session` | S | Konto, bestätigter Datenraum, Räume, CSRF-Token, Epoche |
|
||
| POST | `/api/v1/auth/session/scope` | S | Datenraum wechseln (`kind`, `id`); erhöht die Epoche |
|
||
| GET | `/api/v1/auth/bootstrap` | – | `{available: true}`, solange kein Betreiber existiert, sonst 404 |
|
||
| POST | `/api/v1/auth/bootstrap` | – | erstes Konto als Betreiber anlegen, nur ohne vorhandenen Betreiber |
|
||
| GET | `/api/v1/auth/demo` | – | Beispielkonten; nur Development mit Datenbank `*_test` und `SEED_DEMO=true`, sonst 404 |
|
||
| GET | `/api/v1/accounts` | S+R, B | Betreiberkonten (`origin='operator'`) mit Status, Rolle, letzter Anmeldung; Filter `status=active\|disabled` |
|
||
| GET | `/api/v1/accounts/{id}` | S+R, B | Detail mit Raummitgliedschaften und Zahl aktiver Sitzungen |
|
||
| POST | `/api/v1/accounts` | S+R, B | Konto anlegen, persönlicher Raum, `must_change_password`. Ohne `password` erzeugt der Server ein Einmal-Passwort und liefert es einmal als `temporary_password`. `is_operator` optional |
|
||
| PATCH | `/api/v1/accounts/{id}` | S+R, B | `display_name`, `is_operator`, `status` (`active`/`disabled`), `account_kind: main` (Mitarbeiter zum Hauptnutzer machen). Letzter Betreiber und eigenes Konto sind geschützt |
|
||
| POST | `/api/v1/accounts/{id}/password-reset` | S+R, B | neues Einmal-Passwort, beendet alle Sitzungen; nicht für das eigene Konto |
|
||
| POST | `/api/v1/accounts/{id}/sessions/revoke` | S+R, B | alle Sitzungen des Kontos beenden |
|
||
| POST | `/api/v1/auth/password` | S | eigenes Passwort ändern (`current_password`, `new_password`); beendet die anderen Sitzungen; 204. Erlaubt auch bei `must_change_password` |
|
||
| GET | `/api/v1/auth/sessions` | S | eigene aktive Sitzungen (Gerätehinweis, zuletzt aktiv) |
|
||
| DELETE | `/api/v1/auth/sessions/{id}` | S | eigene andere Sitzung beenden; die aktuelle über Abmelden |
|
||
| POST | `/api/v1/auth/sessions/revoke-others` | S | überall sonst abmelden |
|
||
| GET | `/api/v1/principals?email=` | S+R | aktives Konto per E-Mail auflösen (ID, Anzeigename) |
|
||
| POST | `/api/v1/invitations` | S+R, M | Einladung in einen gemeinsamen Raum mit `role` (`member`/`manager`/`reader`); Antwort enthält das Token einmalig |
|
||
| POST | `/api/v1/invitations/{id}/accept` | – | Token, Anzeigename, Passwort → Konto, Mitgliedschaft mit der Rolle der Einladung, Session. Widerrufene, benutzte oder abgelaufene Einladung: 404 |
|
||
|
||
## Datenräume
|
||
|
||
| Methode | Pfad | Auth | Zweck |
|
||
|---|---|---|---|
|
||
| GET | `/api/v1/rooms` | S+R | wählbare Räume; `include_archived=true` ergänzt die archivierten Räume der Person |
|
||
| POST | `/api/v1/rooms` | S+R | gemeinsamen Raum anlegen, Anlegende Person wird Verwalter |
|
||
| PATCH | `/api/v1/rooms/{id}` | S+R, M / E | `name` (Verwalter); `status` und `default_visibility` nur der Eigentümer (E). Archivieren setzt Sitzungen im Raum auf den persönlichen Raum zurück |
|
||
| GET / PUT | `/api/v1/rooms/{id}/download-policy` | S+R, Mitglied / E | je Rolle (`manager`, `member`, `reader`), ob das Original gespeichert oder geöffnet werden darf; `can_change` nennt, ob die Person ändern darf. Fremde und unbekannte Räume: 404. Audit `room_download_policy_changed` |
|
||
| GET | `/api/v1/rooms/{id}/members` | S+R, M | Mitglieder mit Rolle und Kontostatus |
|
||
| POST | `/api/v1/rooms/{id}/members` | S+R, M | bestehendes Konto als `member`, `manager` oder `reader` aufnehmen oder dessen Rolle setzen |
|
||
| PATCH | `/api/v1/rooms/{id}/members/{subject_id}` | S+R, M | Rolle ändern; letzter Verwalter bleibt. Rückstufung auf `reader` entzieht Bearbeiten- und Freigeben-Grants auf Objekte des Raums |
|
||
| DELETE | `/api/v1/rooms/{id}/members/{subject_id}` | S+R, M | Mitgliedschaft beenden; letzter Verwalter bleibt |
|
||
| GET | `/api/v1/rooms/{id}/invitations` | S+R, M | offene Einladungen ohne Token |
|
||
| DELETE | `/api/v1/rooms/{id}/invitations/{invitation_id}` | S+R, M | Einladung widerrufen |
|
||
| POST | `/api/v1/rooms/{id}/owner` | S+R, E | Raum an ein aktives Mitglied übertragen (Eigentümer); der neue Eigentümer wird Verwalter |
|
||
| GET | `/api/v1/rooms/{id}/exposure` | S+R, Mitglied | eigene Akten und Vorgänge: mit dem Raum geteilt (`room`) oder dort abgelegt, aber nicht geteilt (`private`) |
|
||
| POST | `/api/v1/rooms/{id}/my-content/visibility` | S+R, Mitglied | `room`: alle eigenen im Raum abgelegten Akten und Vorgänge mit dem Raum teilen; `private`: alle eigenen Freigaben an diesen Raum beenden |
|
||
| GET | `/api/v1/cases/{id}/room-share`, `/api/v1/matters/{id}/room-share` | S+R, Owner | Freigaben des Eintrags an Datenräume (mit Mitgliedern, Rolle, Ausnahme) und die Räume, mit denen er noch teilen kann |
|
||
| PUT / DELETE | `/api/v1/cases/{id}/room-share/rooms/{room_id}` (PUT antwortet zusätzlich mit `effect`), `/api/v1/matters/{id}/room-share/rooms/{room_id}` | S+R, Owner | mit dem Raum teilen (`access`: `edit` = Rechte nach Rolle, `read` = höchstens Lesen) oder die Freigabe beenden; nur in Räumen, in denen der Owner Mitglied oder Verwalter ist |
|
||
| PUT | `/api/v1/cases/{id}/room-share/people/{subject_id}`, `/api/v1/matters/{id}/room-share/people/{subject_id}` | S+R, Owner | eine Person von der Raumfreigabe ausnehmen (`excluded`) |
|
||
| POST | `/api/v1/admin/rooms/{id}/owner` | S+R, B | Betreiber setzt einen Eigentümer ein, nur wenn der bisherige nicht mehr handeln kann (Konto deaktiviert oder nicht mehr Mitglied) |
|
||
| GET | `/api/v1/rooms/overview` | S+R | Räume der Person als Kacheln: Rolle, Eigentümer, Zahl der Mitglieder und der lesbaren Akten und Vorgänge; Mitgliedernamen nur für Verwalter |
|
||
| GET | `/api/v1/rooms/{id}/contents` | S+R, Mitglied | Akten und Vorgänge, die mit dem Raum geteilt und für die Person lesbar sind, mit Zählern |
|
||
| POST | `/api/v1/rooms/{id}/shares` | S+R, Mitglied | mehrere eigene Einträge auf einmal mit dem Raum teilen (alle oder keiner); Antwort nennt die Wirkung je Mitglied |
|
||
| GET | `/api/v1/cases/{id}/outline`, `/api/v1/matters/{id}/outline` | S+R | Struktur für den Navigationsbaum: Kapitel, Unterakten und Vorgänge bzw. Teilvorgänge, nur aus Lesbarem; für Vorgänge optional `context_kind=case&context_id=` |
|
||
| GET | `/api/v1/team` | S+R, Hauptnutzer | Personen in den eigenen Räumen mit Rolle je Raum; `mine` = selbst eingeladen |
|
||
| PATCH | `/api/v1/team/{id}` | S+R, Hauptnutzer | `status` eines selbst eingeladenen Mitarbeiters; fremde und unbekannte ID: 403 |
|
||
| POST | `/api/v1/team/{id}/password-reset` | S+R, Hauptnutzer | Einmal-Passwort für einen selbst eingeladenen Mitarbeiter |
|
||
| DELETE | `/api/v1/team/{id}/memberships` | S+R, Hauptnutzer | Person aus allen eigenen Räumen entfernen |
|
||
| GET | `/api/v1/admin/team` | S+R, B | Hauptnutzer mit Mitarbeitern, Räumen und Rollen; `format=csv` für den Export |
|
||
| GET | `/api/v1/admin/rooms` | S+R, B | alle gemeinsamen Räume mit Zustand, Mitgliederzahl, Verwaltern; keine Inhalte |
|
||
| POST | `/api/v1/admin/rooms/{id}/managers` | S+R, B | Verwalter einsetzen, nur wenn der Raum keinen aktiven Verwalter hat |
|
||
| GET | `/api/v1/admin/events` | S+R, B | Verwaltungsprotokoll (`cursor`, `limit`) für Konto, Sitzung, Raum, Mitgliedschaft, Einladung |
|
||
|
||
## Akten
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| GET | `/api/v1/cases` | lesbare Akten und Unterakten |
|
||
| POST | `/api/v1/cases` | Akte anlegen (`title`, optional `parent_case_id`, `rights_mode`, `home_scope_id`) |
|
||
| GET | `/api/v1/cases/{id}` | Akte mit Trail, Kapiteln, Unterakten, Vorgangsbaum, direkten Einbindungen, `contained` (Inhalte zugeordneter Vorgänge), Aufgaben, Fristen, Grants (für Freigebende) |
|
||
| PATCH | `/api/v1/cases/{id}` | Titel, Status `open`/`closed` |
|
||
| POST | `/api/v1/cases/{id}/delete` | Akte löschen (`deleted_at`); nur ohne Unterakten und Vorgangszuordnungen. Verlangt `edit` (siehe Review R-01) |
|
||
| POST | `/api/v1/cases/{id}/grants` | Grant per E-Mail (`can_read`, `can_edit`, `can_share`) |
|
||
| POST | `/api/v1/cases/{id}/chapters` | Kapitel anlegen, optional `parent_chapter_id`, `document_on` |
|
||
| POST | `/api/v1/cases/{id}/chapters/order` | Geschwisterreihenfolge |
|
||
| PATCH | `/api/v1/cases/{id}/content-order` | Ordnungsart `date`/`position`, Richtung |
|
||
| POST | `/api/v1/cases/{id}/bindings/order` | eigene Reihenfolge der sichtbaren Einbindungen |
|
||
| POST | `/api/v1/cases/{id}/bindings/chapters` | mehrere Einbindungen in ein Kapitel |
|
||
| GET | `/api/v1/cases/{id}/course` | fachlicher Verlauf |
|
||
| GET | `/api/v1/cases/{id}/chronology?cursor=` | Änderungsprotokoll, 40 Einträge je Seite |
|
||
|
||
## Vorgänge
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| GET | `/api/v1/matters` | lesbare Vorgänge mit lesbaren Kontexten |
|
||
| POST | `/api/v1/matters` | Vorgang oder Teilvorgang (`parent_matter_id`, `context`) |
|
||
| GET | `/api/v1/matters/{id}` | Vorgang mit Trail, Zuordnungen (`placements`, `case_links`), Teilvorgängen, Querverweisen, Einbindungen, Aufgaben, Fristen |
|
||
| PATCH | `/api/v1/matters/{id}` | Titel, Status |
|
||
| POST | `/api/v1/matters/{id}/delete` | Vorgang löschen; nur ohne Teilvorgänge. Verlangt `edit` (Review R-01) |
|
||
| POST | `/api/v1/matters/{id}/move` | Akte wechseln (`case_id`), Elternvorgang setzen oder lösen |
|
||
| POST | `/api/v1/matters/{id}/case-links` | Akte zuordnen; Freigaberecht am Vorgang und Bearbeitungsrecht an der Akte |
|
||
| DELETE | `/api/v1/matter-case-links/{id}` | Zuordnung lösen |
|
||
| POST | `/api/v1/matters/{id}/cross-links` | Querverweis (`target_matter_id`, `target_context`) |
|
||
| DELETE | `/api/v1/matter-cross-links/{id}` | Querverweis lösen |
|
||
| POST | `/api/v1/matters/{id}/grants` | Grant am Vorgang |
|
||
| POST | `/api/v1/matters/{id}/chapters` | Kapitel (Kontext als Query) |
|
||
| POST | `/api/v1/matters/{id}/chapters/order` | Geschwisterreihenfolge |
|
||
| PATCH | `/api/v1/matters/{id}/content-order` | Ordnungsart |
|
||
| POST | `/api/v1/matters/{id}/bindings/order` | eigene Reihenfolge |
|
||
| POST | `/api/v1/matters/{id}/bindings/chapters` | mehrere Einbindungen in ein Kapitel |
|
||
| GET | `/api/v1/matters/{id}/course` | fachlicher Verlauf |
|
||
| GET | `/api/v1/matters/{id}/chronology?cursor=` | Änderungsprotokoll |
|
||
|
||
## Kapitel
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| PATCH | `/api/v1/chapters/{id}` | Kapiteldatum |
|
||
| PATCH | `/api/v1/chapters/{id}/title` | umbenennen |
|
||
| POST | `/api/v1/chapters/{id}/parent` | umhängen, `parent_chapter_id: null` = oberste Ebene |
|
||
| POST | `/api/v1/chapters/{id}/delete` | auflösen; Inhalte und Kinder rücken eine Ebene nach oben |
|
||
|
||
## Inhalte und Einbindungen
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| POST | `/api/v1/notes` | Notiz mit Einbindung (`context`, optional `placement`, `chapter_id`, `dates`, `communication_direction`) |
|
||
| PATCH | `/api/v1/notes/{id}` | gemeinsamen Text ändern; Antwort mit `visible_bindings` und `notice` |
|
||
| POST | `/api/v1/files` | Datei hochladen (Multipart: `title`, `context_kind`, `context_id`, `upload`, optional Platzierung, Kapitel, Daten, Richtung); PDF, PNG, JPEG, WebP bis 20 MiB |
|
||
| GET | `/api/v1/files/{id}/content` | Datei als `attachment` mit Dateiname (UTF-8, `filename*`), `no-store`. Mit `save=true` zusätzlich das Download-Recht, sonst 403 |
|
||
| POST | `/api/v1/external-refs` | externe Referenz (`paperless`, `imap`, `url`) mit `detail` |
|
||
| POST | `/api/v1/sources/link` | wie oben, nur `paperless`/`imap` (doppelter Weg, siehe Connectoren-Befund) |
|
||
| GET | `/api/v1/elements` | eigene, nicht eingebundene Elemente (max. 100) |
|
||
| POST | `/api/v1/elements/{id}/delete` | überall löschen; nur Element-Owner |
|
||
| PATCH | `/api/v1/elements/{id}/title` | Titel |
|
||
| PATCH | `/api/v1/elements/{id}/summary` | Kurzbeschreibung (≤ 400 Zeichen) |
|
||
| PATCH | `/api/v1/elements/{id}/dates` | Dokument-, Versand-, Zugangsdatum |
|
||
| POST | `/api/v1/elements/{id}/references` | Bezug auf eine andere Unterlage (zyklusfrei) |
|
||
| DELETE | `/api/v1/elements/{id}/references/{target}` | Bezug lösen |
|
||
| POST | `/api/v1/bindings` | Element in weiteren Kontext einbinden (`share` an der Quelle, `edit` am Ziel) |
|
||
| DELETE | `/api/v1/bindings/{id}` | Einbindung lösen |
|
||
| PATCH | `/api/v1/bindings/{id}/chapter` | Kapitel einer Einbindung |
|
||
| PATCH | `/api/v1/bindings/{id}/communication` | Richtung `in`/`out`/`local`/`null` |
|
||
| POST | `/api/v1/bindings/{id}/annotations` | kontextbezogene Anmerkung |
|
||
| PUT | `/api/v1/exceptions` | Kontextausnahme am Element, Vorgang, Aufgabe oder Frist setzen bzw. löschen; nur Owner |
|
||
| DELETE | `/api/v1/grants/{id}` | Grant entziehen |
|
||
|
||
## Aufgaben, Fristen, Übersichten, Suche
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| POST | `/api/v1/tasks` | Aufgabe, optional mit Vorgang und Kontext |
|
||
| PATCH | `/api/v1/tasks/{id}` | Titel, Arbeitstermin, Status `open`/`done` |
|
||
| POST | `/api/v1/tasks/{id}/assignee` | zuweisen (E-Mail) oder lösen; legt begrenztes Grant an. Keine Oberfläche |
|
||
| POST | `/api/v1/tasks/{id}/deadline-links` | Frist verknüpfen |
|
||
| PUT | `/api/v1/tasks/{id}/elements` | verknüpfte Inhalte ersetzen (max. 40) |
|
||
| POST | `/api/v1/tasks/{id}/dependencies` | Abhängigkeit von anderer Aufgabe (zyklusfrei) |
|
||
| DELETE | `/api/v1/tasks/{id}/dependencies/{other}` | Abhängigkeit lösen |
|
||
| POST | `/api/v1/deadlines` | Frist |
|
||
| PATCH | `/api/v1/deadlines/{id}` | Titel, Datum |
|
||
| POST | `/api/v1/deadlines/{id}/fulfill` | als erfüllt kennzeichnen |
|
||
| GET | `/api/v1/views/open-tasks` | offene sichtbare Aufgaben, höchstens 200. Gelesen wird in Blöcken mit Rechteprüfung je Zeile (R-11 behoben) |
|
||
| GET | `/api/v1/views/open-deadlines` | offene sichtbare Fristen, wie oben |
|
||
| GET | `/api/v1/views/recent-matters` | acht zuletzt geänderte sichtbare Vorgänge |
|
||
| GET | `/api/v1/placement-targets` | bearbeitbare Akten und Vorgänge als Ziele |
|
||
| GET | `/api/v1/search?q=` | Akten, Vorgänge, Elemente (Titel und Notiztext), max. 50 |
|
||
|
||
## Quellen
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| GET | `/api/v1/connectors` | eigene Zugänge ohne Secret, mit Fähigkeiten der registrierten Quelle, `has_secret` und letztem Prüfstand (`probe`) |
|
||
| GET | `/api/v1/connectors/{id}` | Detail eines eigenen Zugangs: nicht geheime Einstellungen, `has_secret`, Fähigkeiten, Schutzprofil, Prüfstand und Zahl der eigenen Verknüpfungen. Nie das Secret. Fremde Instanz: 404 |
|
||
| POST | `/api/v1/connectors` | neue Instanz einer registrierten Quelle; Body `{kind, name, config}`. `config` wird gegen das Feldmanifest des Moduls geprüft (`modules[].config_fields` aus `/api/v1/sources/capabilities`); unbekannte Art oder unbekanntes Feld wird abgewiesen; ersetzt keinen vorhandenen Zugang. Die flachen Felder der ersten Lieferung (`base_url`, `token`, `host`, …) gelten nur als Kompatibilität und werden in `config` übersetzt |
|
||
| PATCH | `/api/v1/connectors/{id}` | Name, Einstellungen und Zugangsdaten derselben Instanz. Ein leeres Geheimnisfeld behält das gespeicherte Geheimnis; der letzte Prüfstand wird zurückgesetzt |
|
||
| DELETE | `/api/v1/connectors/{id}` | Zugang löschen; bestehende Referenzen bleiben und werden nicht umgehängt |
|
||
| POST | `/api/v1/connectors/{id}/probe` | gespeicherten Zugang prüfen; Ergebnis (auch ein Fehler) wird als Prüfstand festgehalten. Es gibt keine Prüfung mit ungespeicherten Entwürfen |
|
||
| GET | `/api/v1/sources/capabilities` | erklärte Such-, Lese- und Editorfähigkeiten; nicht Vorhandenes bleibt falsch |
|
||
| GET | `/api/v1/sources/{kind}/search` | Suche der registrierten Quelle im erklärten Umfang; unbekannte Art und nicht erklärte Filter antworten `422` |
|
||
| GET | `/api/v1/sources/{kind}/navigate?connector_id=` | Fachnavigation, wenn die Quelle sie erklärt |
|
||
| GET | `/api/v1/sources/{kind}/preview` | Vorschau vor dem Übernehmen, wenn die Quelle sie erklärt |
|
||
| GET | `/api/v1/sources/paperless/documents?q=&connector_id=` | Kompatibilitätshülle der Paperless-Suche; delegiert an dieselbe Suche |
|
||
| GET | `/api/v1/sources/imap/mailboxes?connector_id=` | IMAP-Fächer |
|
||
| GET | `/api/v1/sources/imap/messages?connector_id=&mailbox=&q=&before=` | Nachrichtenliste, 30 je Seite, Fortsetzung über `before` |
|
||
| GET | `/api/v1/sources/imap/message?connector_id=&mailbox=&uid=` | Vorschau vor dem Übernehmen |
|
||
| GET | `/api/v1/external-refs/{id}/content` | Original der gebundenen Instanz über das registrierte Modul (`inline`, mit Dateiname). Mit `save=true` zusätzlich das Download-Recht |
|
||
| GET | `/api/v1/external-refs/{id}/mail` | vollständige E-Mail als JSON, Identität per Message-ID geprüft; `html` ist bereinigt, `remote_images` zählt Bilder fremder Server |
|
||
| GET | `/api/v1/external-refs/{id}/mail/html-with-images` | dieselbe bereinigte Mail, die Bilder fremder Server lädt der Server auf Anforderung und liefert sie eingebettet (`loaded`, `failed`) |
|
||
| GET | `/api/v1/external-refs/{id}/mail/original` | EML unter dem Betreff als Name; verlangt das Download-Recht (403 sonst) |
|
||
| GET | `/api/v1/external-refs/{id}/mail/attachments/{index}` | Anlage (`inline`, siehe Review R-03); mit `save=true` das Download-Recht |
|
||
| POST | `/api/v1/external-refs/{id}/assignment` | Owner ordnet eine mehrdeutige oder ungebundene Referenz bewusst einer eigenen Instanz zu |
|
||
|
||
Quelleninhalte einer eigenen Referenz laufen über die gebundene Instanz. Eine freigegebene Referenz mit `use_owner_sources` nutzt den gebundenen Zugang des Owners. Zugangsdaten und die übrigen Treffer dieses Zugangs werden nicht ausgeliefert. Eine Suche ohne `connector_id` wählt bei mehreren eigenen Instanzen nicht den zuletzt angelegten Zugang (Review R-10).
|
||
|
||
## Übergabepaket
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| GET | `/api/v1/matters/{id}/export-tree` | Auswahlbaum mit `exportable` und Grund |
|
||
| POST | `/api/v1/matters/{id}/export/review` | Prüfung: `ready`, `issues`, `notices`, `entries` mit Paketpfaden |
|
||
| POST | `/api/v1/matters/{id}/export` | ZIP nur bei `ready` und mit Download-Recht am Vorgang (403 sonst); Audit `export_created`. Knoten `attachment`, `dispatch-item` und `evidence` gehören zur Auswahl |
|
||
|
||
## Anlagen und Versand
|
||
|
||
Alle schreibenden Aufrufe prüfen den Handlungskontext, `expected_version` und den Behälter (`placement`, sonst der Kontext). Fremde oder unlesbare IDs antworten mit 404. Ohne Bearbeitungsrecht mit 403.
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| POST | `/api/v1/elements/{id}/attachments` | Anlagen zuordnen, optional nur als Anlagenansicht |
|
||
| POST | `/api/v1/elements/{id}/attachments/order` | Reihenfolge |
|
||
| POST | `/api/v1/elements/{id}/attachments/{attachment_id}/detach` | nur diese Zuordnung lösen |
|
||
| PATCH | `/api/v1/bindings/{id}/fold` | Vorkommen als Anlage, Nachweis oder wieder eigenständig |
|
||
| POST | `/api/v1/elements/{id}/dispatches` | Versand dokumentieren und Fassung sichern oder als Lücke kennzeichnen |
|
||
| POST | `/api/v1/dispatches/{id}/evidence` | Nachweis ergänzen |
|
||
| POST | `/api/v1/dispatches/{id}/evidence/{element_id}/detach` | nur diesen Beleg vom Versand lösen |
|
||
| POST | `/api/v1/dispatches/{id}/correct` | Weg, Datum oder Gegenüber berichtigen |
|
||
| GET | `/api/v1/dispatches/{id}` | Manifest, Nachweise, Berichtigungen |
|
||
| GET | `/api/v1/dispatches/{id}/items/{item_id}/content` | gesicherte Bytes; eine Lücke liefert 404 und nicht die aktuelle Datei |
|
||
|
||
Eingabe für beide POST-Aufrufe: `{context, selected: [Knoten-IDs], assignments: {Knoten-ID: connector_id}}`.
|