direkt-vermittlung-de/docs/api_docs.md

Here is the API Documentation & Implementation Guide for DirektVermittlungDe (DVD). This document focuses on the practical implementation scenarios derived from the architectural requirements and the OpenAPI specification designed in the previous step.

---

API Documentation: Core Scenarios & Implementation Guide

Version: 1.0 Target Audience: Frontend Developers (Citizen App), Backend Integrators (Authority Systems) Base URL: https://api.direktvermittlung.de/v1

Overview

[cite_start]This API enables the "Direct Vermittlung" workflow: receiving documents, routing them to the correct authority, and facilitating direct communication[cite: 1, 4]. [cite_start]It is designed to be stateless [cite: 40][cite_start], secure (E2E encryption) [cite: 23][cite_start], and scalable (10k+ sessions)[cite: 20].

---

0. Authentication

[cite_start]All endpoints require a valid OAuth2 Bearer Token[cite: 40].

• Citizens use citizen:write scope (via BundID/eID).
• Officials use official:read/official:write scopes (via Authority SSO).

---

Scenario 1: The "Digital Intake" (Document Submission)

[cite_start]User Story: A citizen scans a tax assessment letter to find the right contact person without manual searching[cite: 1, 13].

Implementation Logic

1. [cite_start]Metadata Separation: The client must extract non-sensitive routing data (Authority Name, Reference Number) as plaintext metadata[cite: 2, 4].
2. [cite_start]Encryption: The actual PDF content (encryptedPayload) is encrypted on the client side before upload to meet NFR-5 (E2E Encryption)[cite: 23].
3. [cite_start]Routing: The backend Routing Engine uses the plaintext metadata to assign the DocumentEnvelope to the correct unit[cite: 4].

API Request: POST /documents

{
  "metadata": {
    "authorityId": "Finanzamt-München-I",
    "referenceNumber": "123/456/789", 
    "docType": "NOTICE",
    "issuedAt": "2025-10-25T00:00:00Z"
  },
  "encryptedPayload": "BASE64_ENCRYPTED_BLOB_..." 
}

Success Response (201 Created)

{
  "id": "doc-882291",
  "status": "ROUTED",
  "assignedUnit": "Steuerfestsetzung-Team-B" 
}

[cite_start]Note: The assignedUnit confirms that the Routing Engine successfully mapped the request in < 500ms[cite: 20].

---

Scenario 2: Starting a Clarification Thread

[cite_start]User Story: The citizen has a question about the document and wants to start a chat or request a callback[cite: 5, 6].

Implementation Logic

1. [cite_start]Context: The thread is explicitly linked to the documentId (doc-882291), creating a "Subject-Context" binding[cite: 6].
2. [cite_start]Type Selection: The user selects the channel: TEXT_CHAT, CALLBACK_REQUEST, or APPOINTMENT[cite: 5].

API Request: POST /documents/doc-882291/threads

{
  "type": "CALLBACK_REQUEST",
  "initialMessage": "I do not understand the calculation on page 2. Please call me.",
  "preferredTimeSlot": "2025-10-28T14:00:00Z"
}

Success Response (201 Created)

{
  "threadId": "th-9912",
  "status": "PENDING_OFFICIAL",
  "estimatedWaitTime": "4h"
}

---

Scenario 3: Real-time Communication & History

[cite_start]User Story: An official replies to the inquiry, and the citizen views the chat history[cite: 7].

Implementation Logic

1. [cite_start]Performance: To support fast loading (NFR-1 < 300ms)[cite: 19], we use Cursor-based pagination for messages.
2. Polling/Updates: The frontend polls this endpoint (or uses a WebSocket subscription, if extended) to show new messages.

API Request: GET /threads/th-9912/messages

Query Parameters: ?limit=20&before=2025-10-27T10:00:00Z

Success Response (200 OK)

{
  "data": [
    {
      "id": "msg-552",
      "senderRole": "OFFICIAL",
      "content": "encrypted_content_string...", 
      "timestamp": "2025-10-27T09:45:00Z"
    },
    {
      "id": "msg-551",
      "senderRole": "CITIZEN",
      "content": "encrypted_content_string...",
      "timestamp": "2025-10-27T09:30:00Z"
    }
  ],
  "paging": {
    "nextCursor": "2025-10-27T09:30:00Z"
  }
}

---

Scenario 4: Data Export (Authority Integration)

[cite_start]User Story: The issue is resolved, and the authority imports the chat history and document into their eAkte system[cite: 11, 35].

Implementation Logic

1. [cite_start]Asynchronous Processing: Since exports can be large (PDFs + Chat Logs), the API returns immediately with a jobId[cite: 28, 43].
2. [cite_start]Format: The export format is configurable (e.g., PDF summary of chat + original attachments)[cite: 12].

API Request: POST /exports

{
  "caseId": "doc-882291",
  "targetSystem": "eAkte-Standard-V2",
  "includeAttachments": true
}

Success Response (202 Accepted)

{
  "jobId": "job-5512",
  "status": "QUEUED",
  "statusUrl": "/exports/job-5512"
}

---

Error Handling Standards

[cite_start]To ensure clarity for developers[cite: 16], the API uses standard HTTP codes:

• 400 Bad Request: Validation failed (e.g., missing Aktenzeichen).
• 404 Not Found: Document or Thread ID does not exist.
• [cite_start]429 Too Many Requests: Rate limit exceeded (NFR protection)[cite: 19].
• 503 Service Unavailable: Maintenance or backend overload.

xxx