# Publier un document juridique

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

Publie une version d'un document juridique. KeenAuth récupère `url` une seule fois via son proxy de sortie et stocke le hachage SHA-256 du corps dans `content_sha256` : HTTPS uniquement, adresses privées et de la plateforme bloquées, 5 Mio maximum, 10 secondes ; une réponse autre que 200 ou un corps vide est considéré comme inaccessible et rien n'est enregistré. `url`, `version`, `locale` et le hachage ne changent jamais après la publication. `effective_at` vaut maintenant par défaut et ne peut pas être dans le passé.

## Requête

Corps JSON (les champs inconnus sont rejetés avec `400 unknown_field`) :

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `Idempotency-Key` | header | non | Clé facultative (16-64 caractères) qui rend une requête réessayée sûre. |
| `kind` | string | oui | `terms`, `privacy_notice` ou `custom`. |
| `version` | string | oui | Votre libellé de version, 1 à 64 caractères. |
| `locale` | string | oui | Balise de langue BCP 47 ; doit être activée dans l'environnement. |
| `url` | string | oui | Page HTTPS que vous hébergez, 2048 octets maximum. |
| `application_id` | string \| null | non | Application concernée (`app_…`) ; absent ou `null` signifie toutes les applications de l'environnement. |
| `effective_at` | string (date-time) | non | Date de prise d'effet ; maintenant par défaut, ne peut pas être dans le passé. |
| `requires_reacceptance` | boolean | non | Si `true`, les utilisateurs voient l'écran de réacceptation à leur prochaine connexion interactive après `effective_at`. Par défaut `false`. |

## Réponse

`201 Created` avec le document.

```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"
}
```

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 400 | `unknown_field` | Le corps contient un champ inconnu. |
| 409 | `conflict` | Un document avec la même application, le même type, la même version et la même langue existe déjà. |
| 415 | `unsupported_media_type` | Le type de contenu n'est pas `application/json`. |
| 422 | `legal_document_unreachable` | L'URL n'a pas pu être récupérée ou hachée via le proxy de sortie ; rien n'a été enregistré. |
| 422 | `validation_failed` | Un champ est invalide (par exemple `url` non HTTPS, `locale` inconnue, `effective_at` dans le passé, ou `application_id` absent de l'environnement : `unknown_application`). |
| 401 | `unauthenticated` | L'authentification est manquante, invalide ou révoquée. |
| 403 | `insufficient_permissions` | L'authentification manque la permission requise. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après la période `Retry-After`. |
| 503 | `service_unavailable` | La récupération des documents n'est pas configurée dans ce déploiement, ou une dépendance est temporairement indisponible. |

## Exemple

```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}'
```