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`

```json
{
  "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`)

```json
{
  "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`

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`

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

### Success Response (`202 Accepted`)

```json
{
  "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