generated from coulomb/repo-seed
175 lines
5.5 KiB
Markdown
175 lines
5.5 KiB
Markdown
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 |