{ "openapi": "3.1.0", "info": { "title": "GECO AML Labs · API-Vertragsvorschau", "version": "0.1.0-preview", "summary": "Vorgeschlagener öffentlicher Integrationsvertrag für einen abgegrenzten API-Pilot.", "description": "API-Vertragsvorschau · v0.1 · Stand 28.10.2026. Diese Spezifikation ist ein Vorschlag auf Grundlage eines internen Prototyps. Sie beschreibt keine freigegebene öffentliche API oder produktive SDKs. Alle Beispiele sind fiktiv. Host, Authentisierung, Quellen, Auftragsverarbeitung und Betrieb werden vor einem Pilot vereinbart; deshalb fehlt bewusst servers. Menschliche Entscheidungen bleiben von KI- und Matchausgaben getrennt. Ein Export ist keine Einreichung oder behördliche Meldung. Eigene Lese- und Suchverträge für Mandate, Beteiligte, Nachweise und Entscheidungen fehlen in dieser Vorschau. Fehlende Lese- und Wiederanlaufverträge sind vor einer produktiven Integration zu vereinbaren." }, "tags": [ { "name": "Arbeitsbereiche" }, { "name": "Mandate" }, { "name": "Beteiligte" }, { "name": "Vorgänge" }, { "name": "Checks" }, { "name": "Nachweise" }, { "name": "Entscheidungen" }, { "name": "Events" } ], "security": [ { "PilotBearer": [] } ], "paths": { "/workspaces/{workspace_id}": { "get": { "operationId": "retrieveWorkspace", "tags": [ "Arbeitsbereiche" ], "summary": "Arbeitsbereich lesen", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Prüfen Sie zuerst, welchem vereinbarten Arbeitsbereich Ihre Integration zugeordnet ist. Workspaces werden im Pilot eingerichtet; dieser Vertrag bietet keine öffentliche Anlage oder automatische Mandanten-Provisionierung.\n\nDie Workspace-ID strukturiert die Ressourcen. Jede Anfrage braucht zusätzlich eine auf diesen Workspace begrenzte Berechtigung.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } } ], "responses": { "200": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" }, "example": { "id": "ws_demo", "name": "Fiktiver Integrationspilot", "status": "pilot_setup" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/workspaces/{workspace_id}/mandates": { "post": { "operationId": "createMandate", "tags": [ "Mandate" ], "summary": "Mandat zuordnen", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Legen Sie die Geschäftsbeziehung an, zu der Personen, Nachweise und einzelne Prüfanlässe gehören. Ihre externe Referenz hält die Verbindung zum bestehenden Kanzlei-, Mandanten- oder Fachsystem.\n\nEin Mandat kann mehrere Vorgänge enthalten. Die technische Anlage bestätigt weder die Verpflichteteneigenschaft noch eine abgeschlossene Sorgfaltsprüfung.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" }, "example": { "id": "mdt_demo", "workspace_id": "ws_demo", "external_reference": "mandate_demo_2026_01", "label": "Beispielmandat", "purpose": "professional_mandate", "responsible_role": "mandate_team", "status": "open", "created_at": "2026-10-28T09:01:00Z" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateCreate" }, "example": { "external_reference": "mandate_demo_2026_01", "label": "Beispielmandat", "purpose": "professional_mandate", "responsible_role": "mandate_team" } } } } } }, "/workspaces/{workspace_id}/parties": { "post": { "operationId": "createParty", "tags": [ "Beteiligte" ], "summary": "Beteiligte erfassen", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Erfassen Sie eine natürliche Person oder Gesellschaft im Kontext eines Mandats. Name und optionale Registerangabe sind zunächst Angaben mit offenem Prüfstand.\n\nIdentität, Vertretungsmacht und wirtschaftliche Berechtigung sind verschiedene Fragen. Ein neu erfasster Beteiligter hat verification_state = not_checked.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" }, "example": { "id": "pty_demo", "workspace_id": "ws_demo", "mandate_id": "mdt_demo", "kind": "legal_entity", "display_name": "Fiktivpark Verwaltung GmbH", "verification_state": "not_checked" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartyCreate" }, "example": { "mandate_id": "mdt_demo", "kind": "legal_entity", "display_name": "Fiktivpark Verwaltung GmbH" } } } } } }, "/workspaces/{workspace_id}/cases": { "post": { "operationId": "createCase", "tags": [ "Vorgänge" ], "summary": "Prüfvorgang eröffnen", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Ein Vorgang verbindet einen konkreten Anlass mit den betroffenen Beteiligten. Beim Wechsel einer Gesellschafterin bleiben das ursprüngliche Mandat und dessen ältere Prüfungen erhalten.\n\nDer neue Vorgang startet in gathering mit version = 1. Zugeordnete Beteiligte müssen zum genannten Mandat im selben Workspace gehören.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" }, "example": { "id": "cas_demo", "workspace_id": "ws_demo", "mandate_id": "mdt_demo", "party_ids": [ "pty_demo" ], "purpose": "ownership_change", "external_reference": "change_demo_01", "status": "gathering", "version": 1, "updated_at": "2026-10-28T09:02:00Z" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCreate" }, "example": { "mandate_id": "mdt_demo", "party_ids": [ "pty_demo" ], "purpose": "ownership_change", "external_reference": "change_demo_01" } } } } } }, "/workspaces/{workspace_id}/cases/{case_id}": { "get": { "operationId": "retrieveCase", "tags": [ "Vorgänge" ], "summary": "Vorgangsstand lesen", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Lesen Sie Bearbeitungsstand und aktuelle Version vor einem menschlichen Review erneut. Auch neue Nachweise und abgeschlossene Checks können die Version erhöhen.\n\nexpected_case_version einer Entscheidung bezieht sich auf diesen Stand. Ein veralteter Browser darf neu hinzugekommene Informationen nicht still übergehen.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "name": "case_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } } ], "responses": { "200": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" }, "example": { "id": "cas_demo", "workspace_id": "ws_demo", "mandate_id": "mdt_demo", "party_ids": [ "pty_demo" ], "purpose": "ownership_change", "external_reference": "change_demo_01", "status": "gathering", "version": 1, "updated_at": "2026-10-28T09:02:00Z" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/workspaces/{workspace_id}/cases/{case_id}/checks": { "post": { "operationId": "createCheck", "tags": [ "Checks" ], "summary": "Abgegrenzten Check anfordern", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Benennen Sie eine einzelne Prüfaufgabe, ihre Beteiligten und die Nachweisbasis. Die tatsächlich zulässigen Datenquellen, fachlichen Kriterien und Anbieterzugänge werden im Pilot vereinbart.\n\n202 Accepted heißt: Auftrag angenommen. status = queued und result_state = unknown sind kein negatives Suchergebnis. Der Vorgang bleibt fachlich offen.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "name": "case_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Check" }, "example": { "id": "chk_demo", "workspace_id": "ws_demo", "case_id": "cas_demo", "kind": "beneficial_ownership", "party_ids": [ "pty_demo" ], "evidence_ids": [ "evd_demo" ], "source_scope": "agreed_pilot_sources", "status": "queued", "result_state": "unknown", "source_coverage": { "scope": "agreed_pilot_sources", "as_of": null, "limitations": [ "Noch keine Auswertung abgeschlossen." ] }, "findings": [], "created_at": "2026-10-28T09:03:00Z" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCreate" }, "example": { "kind": "beneficial_ownership", "party_ids": [ "pty_demo" ], "evidence_ids": [ "evd_demo" ], "source_scope": "agreed_pilot_sources" } } } } } }, "/workspaces/{workspace_id}/checks/{check_id}": { "get": { "operationId": "retrieveCheck", "tags": [ "Checks" ], "summary": "Check und Grenzen lesen", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Lesen Sie Laufstatus, Ergebniszustand, Quellenabdeckung und Hinweise gemeinsam. Im fiktiven Beispiel fehlt eine Beteiligungsebene: Der technische Lauf ist beendet, das Ergebnis bleibt inconclusive.\n\nEin potential_match ist ein Prüfhinweis. Ein no_match gilt nur für die ausgewiesene Abdeckung und den dokumentierten Stand. Beides ersetzt keine verantwortete Entscheidung.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "name": "check_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } } ], "responses": { "200": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Check" }, "example": { "id": "chk_demo", "workspace_id": "ws_demo", "case_id": "cas_demo", "kind": "beneficial_ownership", "party_ids": [ "pty_demo" ], "evidence_ids": [ "evd_demo" ], "source_scope": "agreed_pilot_sources", "status": "completed", "result_state": "inconclusive", "source_coverage": { "scope": "agreed_pilot_sources", "as_of": "2026-10-28T09:03:00Z", "limitations": [ "Weitere Beteiligungsebene fehlt." ] }, "findings": [ { "party_id": "pty_demo", "summary": "Die mittelbare Kontrollgrundlage bleibt offen.", "evidence_ids": [ "evd_demo" ] } ], "created_at": "2026-10-28T09:03:00Z" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/workspaces/{workspace_id}/cases/{case_id}/evidence": { "post": { "operationId": "recordEvidence", "tags": [ "Nachweise" ], "summary": "Nachweis referenzieren", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Halten Sie Quelle, Eingangszeitpunkt, bekannten Inhaltsstand und den Bezug zur Originaldatei fest. Dokumentenablage, Aufbewahrung und Zugriffsrechte sind Teil der Pilotvereinbarung; dieser Endpunkt nimmt nur Metadaten entgegen.\n\nUnbekannter Inhaltsstand bleibt null. Ein neuer Nachweis ersetzt keine alte Quelle stillschweigend. Der Hash unterstützt die Zuordnung der Bytes und beweist nicht die Richtigkeit der Quelle.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "name": "case_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evidence" }, "example": { "id": "evd_demo", "workspace_id": "ws_demo", "case_id": "cas_demo", "kind": "client_document", "label": "Fiktive Gesellschafterliste", "source_name": "Fiktive Mandantenunterlage", "captured_at": "2026-10-28T09:00:00Z", "effective_at": null, "document_reference": "doc_demo_01", "media_type": "application/pdf", "sha256": "3ce3aca1d1a0791250b6ad07f3de0c093c32ba1c7d86425091fcb67d3233ab73", "recorded_at": "2026-10-28T09:02:30Z" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceCreate" }, "example": { "kind": "client_document", "label": "Fiktive Gesellschafterliste", "source_name": "Fiktive Mandantenunterlage", "captured_at": "2026-10-28T09:00:00Z", "effective_at": null, "document_reference": "doc_demo_01", "media_type": "application/pdf", "sha256": "3ce3aca1d1a0791250b6ad07f3de0c093c32ba1c7d86425091fcb67d3233ab73" } } } } } }, "/workspaces/{workspace_id}/cases/{case_id}/decisions": { "post": { "operationId": "recordHumanDecision", "tags": [ "Entscheidungen" ], "summary": "Menschliche Entscheidung festhalten", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Eine berechtigte menschliche Prüferrolle dokumentiert den nächsten Schritt und dessen Begründung. Die API bindet die Identität serverseitig an die authentisierte Person; ein Maschinenkonto kann sich nicht durch ein frei gesetztes actor_id zum Reviewer machen.\n\nVorgangsversion, Zugehörigkeit der Referenzen und Prüferrolle werden atomar geprüft. Bei 409 version_conflict zuerst den aktuellen Vorgang lesen und erneut beurteilen. KI-Ausgaben und Matchwerte erzeugen keine Entscheidung.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "name": "case_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Decision" }, "example": { "id": "dec_demo", "workspace_id": "ws_demo", "case_id": "cas_demo", "expected_case_version": 4, "outcome": "request_information", "rationale": "Die weitere Beteiligungsebene ist nicht belegt. Das Mandatsteam fordert den fehlenden Strukturnachweis an.", "evidence_ids": [ "evd_demo" ], "check_ids": [ "chk_demo" ], "actor_type": "human", "actor_id": "usr_reviewer_demo", "resulting_case_version": 5, "recorded_at": "2026-10-28T09:05:00Z" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionCreate" }, "example": { "expected_case_version": 4, "outcome": "request_information", "rationale": "Die weitere Beteiligungsebene ist nicht belegt. Das Mandatsteam fordert den fehlenden Strukturnachweis an.", "evidence_ids": [ "evd_demo" ], "check_ids": [ "chk_demo" ] } } } } } }, "/workspaces/{workspace_id}/events": { "get": { "operationId": "listWorkspaceEvents", "tags": [ "Events" ], "summary": "Änderungen dauerhaft nachführen", "description": "Vorgeschlagener Vertrag, keine öffentliche Laufzeit. Lesen Sie den fortsetzbaren Eventstrom eines Workspaces in aufsteigender sequence-Reihenfolge. Nutzen Sie nach dem ersten Abruf den opaken next_cursor als after-Parameter. Ein technischer Ausfall darf den fachlichen Übergang nicht unsichtbar machen.\n\nSpeichern Sie den Cursor erst nach dauerhafter Verarbeitung aller Events der Seite. Wiederholte Zustellung ist vorgesehen; deduplizieren Sie nach workspace_id und Event-ID, nicht nach Zeitstempel.", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "description": "Ressourcen-ID innerhalb des vereinbarten Pilot-Workspaces.", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Keine Berechtigung ohne zusätzliche Authentisierung." } }, { "name": "after", "in": "query", "required": false, "description": "next_cursor der letzten dauerhaft verarbeiteten Seite; initial weglassen.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximale Seitengröße.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Vorgeschlagene Antwort; ausschließlich fiktive Beispieldaten.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "data": [ { "id": "evt_demo", "workspace_id": "ws_demo", "sequence": 12, "type": "decision.recorded", "schema_version": "0.1", "case_id": "cas_demo", "resource": { "kind": "decision", "id": "dec_demo", "version": 5 }, "occurred_at": "2026-10-28T09:05:00Z" } ], "has_more": false, "next_cursor": "cursor_demo_12" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "webhooks": { "workspaceEvent": { "post": { "operationId": "receiveWorkspaceEvent", "summary": "Vorgeschlagene Eventzustellung an Ihre vereinbarte Empfangsadresse.", "description": "Vorschlag: mindestens einmalige Zustellung, mögliche Wiederholung und abweichende Zustellreihenfolge. HMAC-SHA256 über timestamp + Punkt + unveränderte Requestbytes; Signatur vor Verarbeitung prüfen. Zeitfenster ±300 Sekunden, Empfangsschlüssel pro Ziel, Rotation im Pilot vereinbaren. Erst nach dauerhafter Übernahme in die eigene Inbox 2xx bestätigen. Wiederanlauf über GET events.", "security": [], "parameters": [ { "name": "X-GECO-Event-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Muss mit id im Event übereinstimmen." } }, { "name": "X-GECO-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Unix-Zeitstempel der konkreten Zustellung in Sekunden." }, { "name": "X-GECO-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1=[a-f0-9]{64}$" }, "description": "HMAC mit separat vereinbartem Empfangsschlüssel. Keine Schlüssel in Event oder URL." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_demo", "workspace_id": "ws_demo", "sequence": 12, "type": "decision.recorded", "schema_version": "0.1", "case_id": "cas_demo", "resource": { "kind": "decision", "id": "dec_demo", "version": 5 }, "occurred_at": "2026-10-28T09:05:00Z" } } } }, "responses": { "200": { "description": "Event dauerhaft in der Inbox übernommen oder bereits bekannt." }, "400": { "description": "Ungültiger Umschlag oder Zeitstempel außerhalb des vereinbarten Fensters." }, "401": { "description": "Signatur ungültig." }, "503": { "description": "Keine dauerhafte Annahme möglich; Zustellung wiederholen." } } } } }, "components": { "securitySchemes": { "PilotBearer": { "type": "http", "scheme": "bearer", "description": "Vorgesehener, auf Workspace und Rollen begrenzter Pilotzugang. Ausgabe, Lebensdauer und menschlicher Review-Kontext werden gesondert vereinbart. Diese Spezifikation enthält keine Zugangsdaten." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Vorschlag: mindestens 24 Stunden speichern, Scope Workspace + Methode + Pfad. Identischer Schlüssel und identischer normalisierter JSON-Body liefern innerhalb des vereinbarten Speicherfensters den ursprünglichen Status und Body. Abweichender Body: 409 idempotency_conflict. Laufende Anfrage: 409 request_in_progress. Nach Ablauf des Fensters oder weiter unklarem Ausgang keinen neuen Schreibauftrag auslösen; mit dem vereinbarten Pilotbetrieb klären. Diese Vorschau bietet keinen allgemeinen Lookup über externe Referenzen. Fehlende Lese- und Wiederanlaufverträge vor produktiver Integration vereinbaren. Keine personenbezogenen Werte im Schlüssel.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$" } } }, "responses": { "InvalidRequest": { "description": "Ungültiges JSON oder unzulässige Anfrageform.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthenticated": { "description": "Authentisierung fehlt oder ist ungültig.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Workspace- oder Rollenberechtigung fehlt.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Ressource im berechtigten Workspace nicht gefunden.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "Idempotenzkonflikt, noch laufende Anfrage oder veraltete Vorgangsversion.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unprocessable": { "description": "Feldvalidierung, unpassende Referenz oder fachliche Vorbedingung verletzt.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "Vereinbartes Anfragelimit erreicht. Retry-After beachten.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." }, "Retry-After": { "schema": { "type": "string" }, "description": "Wartezeit in Sekunden oder HTTP-Datum." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalError": { "description": "Interner Fehler. Innerhalb des vereinbarten Idempotenzfensters denselben Body und Schlüssel wiederholen. Nach dessen Ablauf oder weiter unklarem Ausgang keinen neuen Schreibauftrag auslösen; mit dem vereinbarten Pilotbetrieb klären.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unavailable": { "description": "Vereinbarte Quelle oder Verarbeitung vorübergehend nicht verfügbar. Kein no_match ableiten.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Technische Rückfragereferenz." }, "Retry-After": { "schema": { "type": "string" }, "description": "Wartezeit in Sekunden oder HTTP-Datum." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Im Pilot zugewiesene Arbeitsbereichs-ID; Kenntnis der ID ersetzt keine Berechtigung." }, "name": { "type": "string", "description": "Vereinbarte Bezeichnung des Arbeitsbereichs." }, "status": { "type": "string", "description": "Technischer Pilotstatus des Arbeitsbereichs.", "enum": [ "pilot_setup", "pilot_active", "suspended" ] } }, "required": [ "id", "name", "status" ], "description": "Vereinbarter Arbeitsbereich. Öffentliche Selbstbedienungs-Provisionierung ist nicht Teil dieser Vorschau." }, "MandateCreate": { "type": "object", "properties": { "external_reference": { "type": "string", "description": "Stabile Zuordnung in Ihrer Anwendung; keine Personenangaben im Schlüssel.", "minLength": 1, "maxLength": 120 }, "label": { "type": "string", "description": "Arbeitsbezeichnung des Mandats oder der Geschäftsbeziehung.", "minLength": 1, "maxLength": 160 }, "purpose": { "type": "string", "description": "Fachlicher Kontext; keine automatische Feststellung der Verpflichteteneigenschaft.", "enum": [ "professional_mandate", "property_transaction" ] }, "responsible_role": { "type": "string", "description": "Fachlich verantwortliche Rolle in Ihrem vereinbarten Ablauf.", "minLength": 1, "maxLength": 80 } }, "required": [ "external_reference", "label", "purpose", "responsible_role" ], "description": "", "additionalProperties": false }, "Mandate": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Serverseitige Ressourcen-ID." }, "workspace_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger, im Pilot eingerichteter Arbeitsbereich." }, "external_reference": { "type": "string", "description": "Stabile Zuordnung in Ihrer Anwendung; keine Personenangaben im Schlüssel.", "minLength": 1, "maxLength": 120 }, "label": { "type": "string", "description": "Arbeitsbezeichnung des Mandats oder der Geschäftsbeziehung.", "minLength": 1, "maxLength": 160 }, "purpose": { "type": "string", "description": "Fachlicher Kontext; keine automatische Feststellung der Verpflichteteneigenschaft.", "enum": [ "professional_mandate", "property_transaction" ] }, "responsible_role": { "type": "string", "description": "Fachlich verantwortliche Rolle in Ihrem vereinbarten Ablauf.", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "description": "Bearbeitungsstand der Geschäftsbeziehung.", "enum": [ "open", "on_hold", "closed" ] }, "created_at": { "type": "string", "description": "Serverseitiger Anlagezeitpunkt.", "format": "date-time" } }, "required": [ "id", "workspace_id", "external_reference", "label", "purpose", "responsible_role", "status", "created_at" ], "description": "" }, "PartyCreate": { "type": "object", "properties": { "mandate_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Übergeordnetes Mandat im selben Workspace." }, "kind": { "type": "string", "description": "Typ der beteiligten Person oder Gesellschaft.", "enum": [ "natural_person", "legal_entity" ] }, "display_name": { "type": "string", "description": "Fiktiver Beispielname; im Pilot gelten Datenminimierung und vereinbarte Zugriffszwecke.", "minLength": 1, "maxLength": 200 }, "registration": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO-Ländercode des Registers.", "pattern": "^[A-Z]{2}$" }, "registry": { "type": "string", "description": "Registerbezeichnung; kein Abrufauftrag.", "maxLength": 120 }, "number": { "type": "string", "description": "Registerschlüssel als Zeichenfolge.", "maxLength": 100 } }, "required": [ "country", "registry", "number" ], "description": "Optionaler Registerbezug. Eine Angabe ist noch kein Identitätsnachweis.", "additionalProperties": false } }, "required": [ "mandate_id", "kind", "display_name" ], "description": "", "additionalProperties": false }, "Party": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Serverseitige Ressourcen-ID." }, "workspace_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger, im Pilot eingerichteter Arbeitsbereich." }, "mandate_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Übergeordnetes Mandat im selben Workspace." }, "kind": { "type": "string", "description": "Typ der beteiligten Person oder Gesellschaft.", "enum": [ "natural_person", "legal_entity" ] }, "display_name": { "type": "string", "description": "Fiktiver Beispielname; im Pilot gelten Datenminimierung und vereinbarte Zugriffszwecke.", "minLength": 1, "maxLength": 200 }, "registration": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO-Ländercode des Registers.", "pattern": "^[A-Z]{2}$" }, "registry": { "type": "string", "description": "Registerbezeichnung; kein Abrufauftrag.", "maxLength": 120 }, "number": { "type": "string", "description": "Registerschlüssel als Zeichenfolge.", "maxLength": 100 } }, "required": [ "country", "registry", "number" ], "description": "Optionaler Registerbezug. Eine Angabe ist noch kein Identitätsnachweis.", "additionalProperties": false }, "verification_state": { "type": "string", "description": "Dokumentierter Identitätsstand. Neu angelegte Angaben starten mit not_checked.", "enum": [ "not_checked", "incomplete", "verified", "conflicting" ] } }, "required": [ "id", "workspace_id", "mandate_id", "kind", "display_name", "verification_state" ], "description": "" }, "CaseCreate": { "type": "object", "properties": { "mandate_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Mandat, zu dem dieser konkrete Prüfanlass gehört." }, "party_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 1, "uniqueItems": true, "description": "Beteiligte desselben Mandats. Beziehungen und Vertretungsmacht werden gesondert geklärt." }, "purpose": { "type": "string", "description": "Anlass der Bearbeitung.", "enum": [ "onboarding", "ownership_change", "periodic_review", "transaction_review" ] }, "external_reference": { "type": "string", "description": "Verknüpfung zum Vorgang in Ihrer Anwendung.", "minLength": 1, "maxLength": 120 } }, "required": [ "mandate_id", "party_ids", "purpose", "external_reference" ], "description": "", "additionalProperties": false }, "Case": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Serverseitige Ressourcen-ID." }, "workspace_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger, im Pilot eingerichteter Arbeitsbereich." }, "mandate_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Mandat, zu dem dieser konkrete Prüfanlass gehört." }, "party_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 1, "uniqueItems": true, "description": "Beteiligte desselben Mandats. Beziehungen und Vertretungsmacht werden gesondert geklärt." }, "purpose": { "type": "string", "description": "Anlass der Bearbeitung.", "enum": [ "onboarding", "ownership_change", "periodic_review", "transaction_review" ] }, "external_reference": { "type": "string", "description": "Verknüpfung zum Vorgang in Ihrer Anwendung.", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "description": "Bearbeitungszustand; keine Aussage über gesetzliche Erfüllung.", "enum": [ "gathering", "in_review", "decision_recorded", "closed" ] }, "version": { "type": "integer", "minimum": 1, "description": "Monoton steigende Version bei Änderungen an Vorgang, Nachweisen, Checks oder Entscheidungen." }, "updated_at": { "type": "string", "description": "Serverseitiger Zeitpunkt der letzten Vorgangsänderung.", "format": "date-time" } }, "required": [ "id", "workspace_id", "mandate_id", "party_ids", "purpose", "external_reference", "status", "version", "updated_at" ], "description": "" }, "CheckCreate": { "type": "object", "properties": { "kind": { "type": "string", "description": "Getrennte Prüfaufgabe. PEP- und Sanktionshinweise bleiben fachlich unterschiedliche Fragen.", "enum": [ "identity_consistency", "beneficial_ownership", "pep", "sanctions" ] }, "party_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 1, "uniqueItems": true, "description": "Für diesen Check ausgewählte Beteiligte des Vorgangs." }, "evidence_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 0, "uniqueItems": true, "description": "Zum Start berücksichtigte Nachweise desselben Vorgangs; darf bei noch fehlenden Nachweisen leer sein." }, "source_scope": { "type": "string", "description": "Im Pilot vereinbarte Quellenabdeckung. Der Wert löst keine unvereinbarte Anbieterabfrage aus.", "minLength": 1, "maxLength": 120 } }, "required": [ "kind", "party_ids", "evidence_ids", "source_scope" ], "description": "", "additionalProperties": false }, "SourceCoverage": { "type": "object", "properties": { "scope": { "type": "string", "description": "Benannte und vereinbarte Quellenmenge." }, "as_of": { "type": [ "string", "null" ], "format": "date-time", "description": "Bekannter Quellenstand; null, falls noch keine belastbare Abfrage vorliegt." }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "Fehlende Merkmale, Quellenlücken oder zeitliche Einschränkungen." } }, "required": [ "scope", "as_of", "limitations" ], "description": "" }, "Finding": { "type": "object", "properties": { "party_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Betroffene beteiligte Person oder Gesellschaft." }, "summary": { "type": "string", "description": "Sachlicher Hinweis zur weiteren Prüfung; keine vorweggenommene Entscheidung." }, "evidence_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 0, "uniqueItems": true, "description": "Nachvollziehbare Nachweisreferenzen des Hinweises." } }, "required": [ "party_id", "summary", "evidence_ids" ], "description": "" }, "Check": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Serverseitige Ressourcen-ID." }, "workspace_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger, im Pilot eingerichteter Arbeitsbereich." }, "case_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger Vorgang." }, "kind": { "type": "string", "description": "Getrennte Prüfaufgabe. PEP- und Sanktionshinweise bleiben fachlich unterschiedliche Fragen.", "enum": [ "identity_consistency", "beneficial_ownership", "pep", "sanctions" ] }, "party_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 1, "uniqueItems": true, "description": "Für diesen Check ausgewählte Beteiligte des Vorgangs." }, "evidence_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 0, "uniqueItems": true, "description": "Zum Start berücksichtigte Nachweise desselben Vorgangs; darf bei noch fehlenden Nachweisen leer sein." }, "source_scope": { "type": "string", "description": "Im Pilot vereinbarte Quellenabdeckung. Der Wert löst keine unvereinbarte Anbieterabfrage aus.", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "description": "Technischer Laufzustand. 202 bestätigt nur die Annahme des Auftrags.", "enum": [ "queued", "running", "completed", "failed" ] }, "result_state": { "type": "string", "description": "Ergebnis innerhalb der dokumentierten Abdeckung. unknown ist nie gleich no_match.", "enum": [ "unknown", "no_match", "potential_match", "inconclusive" ] }, "source_coverage": { "$ref": "#/components/schemas/SourceCoverage" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "Prüfhinweise. Ein leeres Array ist ohne result_state und Quellenabdeckung nicht auswertbar." }, "created_at": { "type": "string", "description": "Serverseitiger Annahmezeitpunkt.", "format": "date-time" } }, "required": [ "id", "workspace_id", "case_id", "kind", "party_ids", "evidence_ids", "source_scope", "status", "result_state", "source_coverage", "findings", "created_at" ], "description": "", "allOf": [ { "if": { "properties": { "status": { "enum": [ "queued", "running", "failed" ] } }, "required": [ "status" ] }, "then": { "properties": { "result_state": { "const": "unknown" } } }, "else": { "properties": { "result_state": { "enum": [ "no_match", "potential_match", "inconclusive" ] } } } } ] }, "EvidenceCreate": { "type": "object", "properties": { "kind": { "type": "string", "description": "Art des referenzierten Nachweises.", "enum": [ "register_extract", "client_document", "review_note" ] }, "label": { "type": "string", "description": "Für Bearbeitende lesbarer Dokumenttitel.", "minLength": 1, "maxLength": 160 }, "source_name": { "type": "string", "description": "Herkunft des Nachweises, einschließlich manueller Beschaffung.", "minLength": 1, "maxLength": 160 }, "captured_at": { "type": "string", "description": "Zeitpunkt der Beschaffung oder des Eingangs; nicht automatisch der inhaltliche Gültigkeitsstand.", "format": "date-time" }, "effective_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Bekannter inhaltlicher Stand; null bedeutet ausdrücklich unbekannt." }, "document_reference": { "type": "string", "description": "Referenz auf das im Pilot vereinbarte Dokumentenlager. Dieser Vertrag lädt keine Datei hoch und ruft keine URL ab.", "minLength": 1, "maxLength": 200 }, "media_type": { "type": "string", "description": "Medientyp der Originaldatei.", "minLength": 1, "maxLength": 100 }, "sha256": { "type": "string", "description": "SHA-256 der Originalbytes zur späteren Zuordnung. Der Hash beweist weder Herkunft noch inhaltliche Richtigkeit.", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "label", "source_name", "captured_at", "document_reference", "media_type", "sha256" ], "description": "", "additionalProperties": false }, "Evidence": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Serverseitige Ressourcen-ID." }, "workspace_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger, im Pilot eingerichteter Arbeitsbereich." }, "case_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger Vorgang." }, "kind": { "type": "string", "description": "Art des referenzierten Nachweises.", "enum": [ "register_extract", "client_document", "review_note" ] }, "label": { "type": "string", "description": "Für Bearbeitende lesbarer Dokumenttitel.", "minLength": 1, "maxLength": 160 }, "source_name": { "type": "string", "description": "Herkunft des Nachweises, einschließlich manueller Beschaffung.", "minLength": 1, "maxLength": 160 }, "captured_at": { "type": "string", "description": "Zeitpunkt der Beschaffung oder des Eingangs; nicht automatisch der inhaltliche Gültigkeitsstand.", "format": "date-time" }, "effective_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Bekannter inhaltlicher Stand; null bedeutet ausdrücklich unbekannt." }, "document_reference": { "type": "string", "description": "Referenz auf das im Pilot vereinbarte Dokumentenlager. Dieser Vertrag lädt keine Datei hoch und ruft keine URL ab.", "minLength": 1, "maxLength": 200 }, "media_type": { "type": "string", "description": "Medientyp der Originaldatei.", "minLength": 1, "maxLength": 100 }, "sha256": { "type": "string", "description": "SHA-256 der Originalbytes zur späteren Zuordnung. Der Hash beweist weder Herkunft noch inhaltliche Richtigkeit.", "pattern": "^[a-f0-9]{64}$" }, "recorded_at": { "type": "string", "description": "Serverseitiger Referenzierungszeitpunkt.", "format": "date-time" } }, "required": [ "id", "workspace_id", "case_id", "kind", "label", "source_name", "captured_at", "effective_at", "document_reference", "media_type", "sha256", "recorded_at" ], "description": "Unveränderlicher Nachweisdatensatz. Eine Korrektur erzeugt einen neuen Datensatz; sie überschreibt die Originalreferenz nicht." }, "DecisionCreate": { "type": "object", "properties": { "expected_case_version": { "type": "integer", "minimum": 1, "description": "Zuletzt gelesene Vorgangsversion. Ein veralteter Stand führt zu 409 version_conflict." }, "outcome": { "type": "string", "description": "Verantworteter nächster Schritt; keine automatische rechtliche Freigabe oder Meldung.", "enum": [ "request_information", "continue_relationship", "escalate", "end_relationship" ] }, "rationale": { "type": "string", "description": "Menschlich verfasste fachliche Begründung einschließlich offener Fragen.", "minLength": 20, "maxLength": 8000 }, "evidence_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 1, "uniqueItems": true, "description": "Nachweise, auf die sich die Entscheidung konkret stützt." }, "check_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 0, "uniqueItems": true, "description": "Berücksichtigte Checks. Unbekannte oder widersprüchliche Ergebnisse bleiben im Review erkennbar." } }, "required": [ "expected_case_version", "outcome", "rationale", "evidence_ids", "check_ids" ], "description": "Nur für eine authentisierte menschliche Prüferrolle. actor_id und actor_type werden nicht vom Request übernommen.", "additionalProperties": false }, "Decision": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Serverseitige Ressourcen-ID." }, "workspace_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger, im Pilot eingerichteter Arbeitsbereich." }, "case_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Zugehöriger Vorgang." }, "expected_case_version": { "type": "integer", "minimum": 1, "description": "Zuletzt gelesene Vorgangsversion. Ein veralteter Stand führt zu 409 version_conflict." }, "outcome": { "type": "string", "description": "Verantworteter nächster Schritt; keine automatische rechtliche Freigabe oder Meldung.", "enum": [ "request_information", "continue_relationship", "escalate", "end_relationship" ] }, "rationale": { "type": "string", "description": "Menschlich verfasste fachliche Begründung einschließlich offener Fragen.", "minLength": 20, "maxLength": 8000 }, "evidence_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 1, "uniqueItems": true, "description": "Nachweise, auf die sich die Entscheidung konkret stützt." }, "check_ids": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Ressourcen-ID im selben Workspace." }, "minItems": 0, "uniqueItems": true, "description": "Berücksichtigte Checks. Unbekannte oder widersprüchliche Ergebnisse bleiben im Review erkennbar." }, "actor_type": { "type": "string", "description": "Die Entscheidung stammt aus dem menschlichen Review.", "const": "human" }, "actor_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Serverseitig aus der authentisierten Prüferidentität ermittelt; kein frei gesetzter Benutzername." }, "resulting_case_version": { "type": "integer", "minimum": 2, "description": "Neue Vorgangsversion nach der atomar gespeicherten Entscheidung." }, "recorded_at": { "type": "string", "description": "Serverseitiger Entscheidungszeitpunkt.", "format": "date-time" } }, "required": [ "id", "workspace_id", "case_id", "expected_case_version", "outcome", "rationale", "evidence_ids", "check_ids", "actor_type", "actor_id", "resulting_case_version", "recorded_at" ], "description": "" }, "Event": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Stabile Event-ID; bleibt bei erneuter Zustellung gleich." }, "workspace_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Arbeitsbereich, zu dem das Event gehört." }, "sequence": { "type": "integer", "minimum": 1, "description": "Stabile, aufsteigende Position im Eventlog dieses Workspaces. Lücken sind zulässig; Zeitstempel ersetzen keinen Cursor." }, "type": { "type": "string", "description": "Versionierter fachlich-technischer Ereignistyp.", "enum": [ "case.created", "check.completed", "check.failed", "evidence.recorded", "decision.recorded", "case.closed" ] }, "schema_version": { "type": "string", "description": "Version dieses Event-Umschlags.", "const": "0.1" }, "case_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Vorgangsbezug für den vorhandenen GET-Case-Vertrag. Ein Event garantiert keinen Lesezugang für andere Ressourcenarten." }, "resource": { "type": "object", "properties": { "kind": { "type": "string", "description": "Geänderte Ressourcenart.", "enum": [ "case", "check", "evidence", "decision" ] }, "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Geänderte Ressourcen-ID." }, "version": { "type": "integer", "minimum": 1, "description": "Vorgangsversion zum Ereigniszeitpunkt." } }, "required": [ "kind", "id", "version" ], "description": "" }, "occurred_at": { "type": "string", "description": "Entstehungszeitpunkt, nicht Zustellzeitpunkt.", "format": "date-time" } }, "required": [ "id", "workspace_id", "sequence", "type", "schema_version", "case_id", "resource", "occurred_at" ], "description": "Kleiner Event-Umschlag ohne Dokumentinhalte und Klarnamen. Event und Ressourcenänderung sollen atomar protokolliert werden." }, "EventList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "Events in aufsteigender sequence-Reihenfolge." }, "has_more": { "type": "boolean", "description": "Weitere Events sind bereits verfügbar." }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaker Fortsetzungscursor; erst nach dauerhafter Verarbeitung speichern." } }, "required": [ "data", "has_more", "next_cursor" ], "description": "" }, "FieldError": { "type": "object", "properties": { "pointer": { "type": "string", "description": "JSON Pointer zum beanstandeten Eingabefeld." }, "code": { "type": "string", "description": "Maschinenlesbarer Feldfehler." }, "message": { "type": "string", "description": "Kurzer Hinweis ohne unnötige Wiederholung personenbezogener Eingaben." } }, "required": [ "pointer", "code", "message" ], "description": "" }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "Stabile Fehlerart als URI.", "format": "uri" }, "title": { "type": "string", "description": "Kurze Fehlerbezeichnung." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string", "description": "Stabiler Code für die Fehlerbehandlung.", "enum": [ "invalid_request", "validation_failed", "unauthenticated", "forbidden", "not_found", "idempotency_conflict", "request_in_progress", "version_conflict", "precondition_failed", "rate_limited", "source_unavailable", "internal_error" ] }, "detail": { "type": "string", "description": "Konkrete Abhilfe; ohne Dokumentinhalt, Token oder unnötige Personendaten." }, "request_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,95}$", "description": "Technische Referenz für Rückfragen." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" }, "description": "Optional: einzelne Validierungsfehler." } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "description": "" } } }, "x-contract-status": "proposal-not-public-runtime", "x-idempotency-minimum-retention-seconds": 86400 }