# Pubblica un documento legale

`POST /v1/legal-documents` · permesso `legal-documents:write`

Pubblica una versione di un documento legale. KeenAuth recupera `url` una sola volta tramite il proxy di uscita e salva l'hash SHA-256 del body in `content_sha256`: solo HTTPS, indirizzi privati e della piattaforma bloccati, al massimo 5 MiB, 10 secondi; una risposta diversa da 200 o un body vuoto è considerato irraggiungibile e non viene salvato nulla. `url`, `version`, `locale` e l'hash non cambiano mai dopo la pubblicazione. `effective_at` è per impostazione predefinita adesso e non può essere nel passato.

## Richiesta

Body JSON (i campi sconosciuti vengono rifiutati con `400 unknown_field`):

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `Idempotency-Key` | header | no | Chiave opzionale (16-64 caratteri) che rende sicura una richiesta ritentata. |
| `kind` | string | sì | `terms`, `privacy_notice` o `custom`. |
| `version` | string | sì | La tua etichetta di versione, 1-64 caratteri. |
| `locale` | string | sì | Tag di lingua BCP 47; deve essere abilitato nell'ambiente. |
| `url` | string | sì | Pagina HTTPS che ospiti, al massimo 2048 byte. |
| `application_id` | string \| null | no | Applicazione a cui si applica il documento (`app_…`); omesso o `null` indica tutte le applicazioni dell'ambiente. |
| `effective_at` | string (date-time) | no | Quando il documento entra in vigore; predefinito adesso, non può essere nel passato. |
| `requires_reacceptance` | boolean | no | Se `true`, gli utenti vedono la schermata di riaccettazione al successivo accesso interattivo dopo `effective_at`. Predefinito `false`. |

## Risposta

`201 Created` con il documento.

```json
{
  "id": "ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "application_id": null,
  "kind": "terms",
  "version": "2026-10",
  "locale": "en",
  "url": "https://example.com/legal/terms-2026-10",
  "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "effective_at": "2026-11-01T00:00:00Z",
  "requires_reacceptance": true,
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}
```

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `unknown_field` | Il body contiene un campo sconosciuto. |
| 409 | `conflict` | Esiste già un documento con la stessa applicazione, tipo, versione e lingua. |
| 415 | `unsupported_media_type` | Il content type non è `application/json`. |
| 422 | `legal_document_unreachable` | Non è stato possibile recuperare o calcolare l'hash dell'URL tramite il proxy di uscita; non è stato salvato nulla. |
| 422 | `validation_failed` | Un campo non è valido (ad esempio `url` non HTTPS, `locale` sconosciuta, `effective_at` nel passato o `application_id` non presente nell'ambiente: `unknown_application`). |
| 401 | `unauthenticated` | La credenziale è mancante, non valida o revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha il permesso richiesto. |
| 429 | `rate_limited` | Il limite di velocità è stato superato; riprova dopo il periodo `Retry-After`. |
| 503 | `service_unavailable` | Il recupero dei documenti non è configurato in questo deployment, oppure una dipendenza è temporaneamente non disponibile. |

## Esempio

```bash
curl -X POST https://api.eu.keenauth.com/v1/legal-documents \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"terms","version":"2026-10","locale":"en","url":"https://example.com/legal/terms-2026-10","effective_at":"2026-11-01T00:00:00Z","requires_reacceptance":true}'
```