Request Validation Levels for Signing Endpoint

# feat: Request Validation Levels for Signing Endpoint

Stand: 28. April 2026

---

## Summary

The current signing endpoint accepts requests without validating their content or completeness. This is acceptable for pure fiscalization use cases, but becomes a blocker for downstream features such as e-invoicing, where requests must be both arithmetically correct and contain all mandatory fields per EN 16931.

This issue proposes adding a **configurable validation level system** to the signing endpoint, including the ability to define a minimum required level and enforce it via HTTP error responses.

---

## Background

A signed receipt can only be converted into a compliant e-invoice (XRechnung / ZUGFeRD) if it contains complete and correct data — recipient details, VAT IDs, invoice date, line items with correct tax rates, etc. Without validation at the signing stage, there is no guarantee that the data is sufficient for e-invoice generation.

This is a prerequisite for: #[E-Invoice Issue]

---

## Proposed: Validation Level System

Validation levels are **cumulative** — each level implies all lower levels are satisfied.

| Level | Name | Description |
|-------|------|-------------|
| `0` | `Unvalidated` | No validation — current behavior |
| `1` | `Arithmetic` | Sums, taxes, and rounding are mathematically correct |
| `2` | `Complete` | All mandatory fields for a compliant e-invoice (EN 16931) are present |
| `3` | `RecipientValidated` | Recipient data validated (VAT ID format, PEPPOL ID resolvable) |
| `4` | `CountryCompliant` | Country-specific rules satisfied (e.g. SIRET for FR, VAT number format for DE) |

---

## Behavior: Input Level vs. Output Level

The client may declare an **asserted input level** in the request. The server independently evaluates the actual level reached and returns it in the response — regardless of the asserted level.

This allows passive use (validation result returned without enforcement) and active use (fail if minimum not met).

```json
// Request
{
"validationLevel": 0,
...
}

// Response
{
"validationLevel": 3,
"validationDetails": {
"arithmetic": true,
"complete": true,
"recipientValidated": true,
"countryCompliant": false
}
}
```

---

## Fail Behavior: Minimum Level Enforcement

A minimum required level can be configured per CashBox or passed as a request parameter. If the request does not reach the minimum level, signing is **not performed** and the endpoint returns:

- `422 Unprocessable Entity` (not `500`)
- Structured error body listing which fields or rules failed

```json
{
"error": "ValidationLevelNotReached",
"requiredLevel": 2,
"achievedLevel": 1,
"violations": [
{
"field": "recipient.vatId",
"rule": "required_for_complete",
"message": "Recipient VAT ID missing"
},
{
"field": "invoiceDate",
"rule": "required_for_complete",
"message": "Invoice date missing"
}
]
}
```

---

## Country-Specific Validation Rules

| Rule | Scope |
|------|-------|
| Arithmetic correctness, tax calculation | Global |
| EN 16931 mandatory fields | Global |
| VAT ID format (`DE123456789`) | DE-specific |
| SIRET number of recipient | FR-specific |
| PDP-compatible format requirements | FR-specific |
| XRechnung additional mandatory fields | DE / public sector |

Country-specific rules are activated based on the CashBox `countryCode` or an explicit `targetCountry` parameter in the request.

Start at the signing endpoint and trace how request validation, signing, and response errors currently work. Define the cumulative validation levels, asserted and achieved response fields, configurable minimum enforcement, 422 error structure, and country-specific rules; done means the behavior and API contract are specified and covered for passive and enforcing requests.

Written by the indexing model from the issue text.