---
title: "Documents éditoriaux"
description: "Documents Markdown publiés, traduisibles et versionnés (CGU, politiques, aide) — lecture publique."
---

Documents éditoriaux **traduisibles et versionnés** (CGU, politiques de confidentialité, pages d'aide…), rédigés en **Markdown**. Côté public, deux endpoints en **lecture seule** ; l'écriture (création, traductions, révisions) vit sur la surface admin `/admin/documents`. Le `title` et le corps sont résolus pour la **locale de requête** (fallback applicatif).

## `GET /api/documents`

Catalogue des documents publiés (**sans corps**) — listing léger, sans pagination.

- **Auth** : aucune.
- **Action** : [ListDocumentsAction](../src/Http/Action/Api/Document/ListDocumentsAction.php).
- **Query** : `category` (optionnel) — filtre exact, doit matcher `^[a-z0-9-]{1,32}$` (sinon ignoré).

```json
{
  "data": [
    {
      "type": "documents",
      "id":   "terms-of-service",
      "attributes": {
        "slug": "terms-of-service",
        "category": "legal",
        "title": "Conditions générales d'utilisation",
        "version": "2024-11",
        "effectiveAt": { "iso": "2024-11-01T00:00:00+00:00", "relative": "il y a 8 mois" },
        "updatedAt":   { "iso": "2024-11-01T09:30:00+00:00", "relative": "il y a 8 mois" }
      }
    }
  ],
  "links": { "self": "https://api.example/api/documents" },
  "meta":  { "total": 1 }
}
```

*(Les champs date sont l'objet riche `{ iso, formatted{long,short,dateOnly,time}, relative }` — abrégé ici.)*

---

## `GET /api/documents/{slug}`

Un document publié, **corps Markdown brut**, résolu pour la locale de requête.

- **Auth** : aucune.
- **Action** : [GetDocumentAction](../src/Http/Action/Api/Document/GetDocumentAction.php).
- **Path** : `slug` doit matcher `^[a-z0-9-]{1,80}$` (sinon `404`).
- **Cache HTTP** : `ETag` + `Cache-Control` ; `If-None-Match` → `304`.

```json
{
  "data": {
    "type": "documents",
    "id":   "terms-of-service",
    "attributes": {
      "slug": "terms-of-service",
      "category": "legal",
      "locale": "fr-FR",
      "title": "Conditions générales d'utilisation",
      "version": "2024-11",
      "effectiveAt": { "iso": "2024-11-01T00:00:00+00:00", "relative": "il y a 8 mois" },
      "body": "# Conditions générales\n\n…markdown brut…",
      "meta": { "title": "CGU — Example", "description": "Nos conditions d'utilisation." },
      "updatedAt": { "iso": "2024-11-01T09:30:00+00:00", "relative": "il y a 8 mois" }
    }
  }
}
```

- **`meta.title`** retombe sur `title` quand aucun `metaTitle` n'est renseigné.
- **`404 Document not found`** : slug mal formé, inconnu, non publié, ou aucune traduction servable dans la locale demandée ni le fallback.

---