# Hukuki belge yayımla

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

Bir hukuki belge sürümünü yayımlar. KeenAuth `url`'yi çıkış vekiliyle bir kez çeker ve gövdenin SHA-256 özetini `content_sha256` olarak saklar: yalnız HTTPS, özel ve platform adresleri engelli, en çok 5 MiB, 10 saniye; 200 dışı yanıt ya da boş gövde çekilemedi sayılır ve hiçbir şey yazılmaz. `url`, `version`, `locale` ve özet yayından sonra değişmez. `effective_at` verilmezse şimdidir ve geçmişte olamaz.

## İstek

JSON gövdesi (bilinmeyen alanlar `400 unknown_field` ile reddedilir):

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `Idempotency-Key` | başlık | hayır | Yeniden denenen isteği güvenli yapan isteğe bağlı anahtar (16-64 karakter). |
| `kind` | string | evet | `terms`, `privacy_notice` ya da `custom`. |
| `version` | string | evet | Sizin sürüm etiketiniz, 1-64 karakter. |
| `locale` | string | evet | BCP 47 dil etiketi; ortamda etkin olmalı. |
| `url` | string | evet | Barındırdığınız HTTPS sayfası, en çok 2048 bayt. |
| `application_id` | string \| null | hayır | Belgenin uygulandığı uygulama (`app_…`); verilmezse ya da `null` ise ortamın tüm uygulamaları. |
| `effective_at` | string (date-time) | hayır | Belgenin yürürlük anı; verilmezse şimdi, geçmişte olamaz. |
| `requires_reacceptance` | boolean | hayır | `true` ise kullanıcılar `effective_at` sonrasındaki ilk etkileşimli girişte yeniden kabul ekranını görür. Varsayılan `false`. |

## Yanıt

`201 Created`; belge.

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

## Hatalar

| HTTP | code | Ne zaman |
|---|---|---|
| 400 | `unknown_field` | Gövdede bilinmeyen alan var. |
| 409 | `conflict` | Aynı uygulama, tür, sürüm ve dilde belge zaten var. |
| 415 | `unsupported_media_type` | İçerik türü `application/json` değil. |
| 422 | `legal_document_unreachable` | URL çıkış vekiliyle çekilemedi ya da özetlenemedi; hiçbir şey yazılmadı. |
| 422 | `validation_failed` | Bir alan geçersiz (örneğin `url` HTTPS değil, `locale` bilinmiyor, `effective_at` geçmişte ya da `application_id` ortamda yok: `unknown_application`). |
| 401 | `unauthenticated` | Kimlik bilgisi yok, geçersiz ya da iptal edilmiş. |
| 403 | `insufficient_permissions` | Kimlik bilgisinde gerekli izin yok. |
| 429 | `rate_limited` | Hız sınırı aşıldı; `Retry-After` süresinden sonra yeniden deneyin. |
| 503 | `service_unavailable` | Bu dağıtımda belge çekme yapılandırılmamış ya da bir bağımlılık geçici olarak kullanılamıyor. |

## Örnek

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