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.

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

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