# API Dossiers Législatifs & Amendements

## 📜 Routes des dossiers législatifs

| Méthode | Route | Description |
| :--- | :--- | :--- |
| `GET` | `/api/v1/dossiers` | Liste paginée des dossiers législatifs déposés à l'AN et au Sénat (ceux qui ont au moins un scrutin). `gouvernement=projets` ne garde que les projets de loi du Gouvernement, `gouvernement=49-3` les textes sur lesquels il a engagé sa responsabilité, avec ou sans scrutin (depuis juin 2017) |
| `GET` | `/api/v1/dossiers/trending` | Dossiers ayant le plus de scrutins sur les 3 derniers mois |
| `GET` | `/api/v1/dossiers/:uid` | Fiche complète d'un dossier (titre, statut, procédure, résumé IA). `gouvernement` : le projet de loi du Gouvernement (gouvernement, signataires et leur rôle, stade) et les recours au 49.3 sur ce texte avec leurs motions de censure ; sur un dossier d'engagement, le texte visé ; `null` pour les autres dossiers |
| `GET` | `/api/v1/dossiers/:uid/chronologie` | Étapes du parcours du texte, d'une chambre à l'autre |
| `GET` | `/api/v1/dossiers/:uid/scrutins` | Tous les scrutins publics rattachés à ce texte |
| `GET` | `/api/v1/dossiers/:uid/amendements` | Amendements déposés sur le dossier |

---

## ✏️ Amendements d'un dossier

`GET /api/v1/dossiers/:uid/amendements` est paginé (`page`, `limit` jusqu'à 100), du dépôt le plus récent au plus ancien. Filtres :

| Paramètre | Effet |
| :--- | :--- |
| `voted=true` | Seulement les amendements mis aux voix par un scrutin public |
| `groupe=<slug>` | Seulement ceux dont l'auteur siégeait dans ce groupe **au dépôt** (pas son groupe actuel) |
| `sort=<valeur>` | Seulement ceux qui ont ce sort, tel que publié |
| `racines=true` | Sans les sous-amendements |
| `parentId=<id>` | Les sous-amendements d'un amendement |
| `discussionCommune=<id>&chambre=<chambre>` | Les amendements d'une même discussion commune |
| `discussionIdentique=<id>&chambre=<chambre>` | Les amendements identiques entre eux |
| `amendement=<uid>` | Un seul amendement, par son uid, s'il est rangé dans ce dossier |

Avec `parentId`, `discussionCommune` ou `discussionIdentique`, la liste suit l'ordre d'appel en séance plutôt que la date de dépôt. Un identifiant de discussion n'est unique qu'au sein d'une chambre, d'où le paramètre `chambre`.

La fiche du dossier (`GET /api/v1/dossiers/:uid`) donne les 20 premiers amendements, sous-amendements compris ; chacun porte son parent et son nombre de sous-amendements, de quoi les regrouper.

### Champs de séance

Chaque amendement renvoyé par l'API (liste d'un dossier, détail d'un scrutin, liste d'un parlementaire) porte, en plus de son texte :

| Champ | Contenu |
| :--- | :--- |
| `alinea` | L'alinéa visé, tel que publié : « Après l'alinéa 9 » à l'Assemblée, « 2 » ou « Rédaction complète » au Sénat |
| `alineaNumero` | Le numéro de l'alinéa seul |
| `idDiscussionCommune`, `positionDiscussionCommune` | La discussion commune (amendements discutés ensemble) et la place qu'y occupe l'amendement : `Premier`, `Milieu` ou `Dernier`. La place n'est publiée que par l'Assemblée |
| `idDiscussionIdentique`, `positionDiscussionIdentique` | Le groupe d'amendements identiques, mis aux voix ensemble |
| `chronotag` | Date de la dernière modification publiée par l'Assemblée. Le Sénat n'en publie pas |
| `triAmendement` | Clé de l'ordre d'appel en séance (Assemblée), à trier en ordre lexicographique |
| `seanceDiscussionRef` | Uid de la séance de discussion (Assemblée), soit l'`uid` d'une réunion de l'agenda quand elle y figure |
| `amendementParentId`, `amendementParent` | Pour un sous-amendement : l'amendement qu'il modifie (`id`, `uid`, `numero`, `auteurLibelle`) |
| `sousAmendementsCount` | Le nombre de sous-amendements de l'amendement |

### Renvois au droit en vigueur

Les mêmes routes donnent, dans `renvois`, les articles et textes de loi que cite le dispositif (« l'article L. 242-1 du code de la sécurité sociale »), avec leur adresse sur Légifrance. Un amendement sans renvoi reconnu a un tableau vide.

| Champ | Contenu |
| :--- | :--- |
| `debut`, `fin` | Position du passage dans `dispositif`, en unités de code UTF-16 : `dispositif.slice(debut, fin)` en JavaScript. Les renvois sont triés et ne se chevauchent pas |
| `type` | `article` ou `texte` (un code, une loi cités sans article) |
| `article` | Identifiant Légifrance (`LEGIARTI…`) de l'article, **dans la version en vigueur au dépôt de l'amendement** ; `null` pour un texte |
| `texte` | Identifiant Légifrance du texte : `LEGITEXT…` pour un code, `JORFTEXT…` pour un texte paru au Journal officiel |
| `nature` | `CODE`, `LOI`, `LOI_ORGANIQUE`, `ORDONNANCE`, `DECRET`, `CONSTITUTION`… |
| `url` | La page Légifrance de l'article ou du texte, datée du jour du dépôt de l'amendement (`…/LEGIARTI…/AAAA-MM-JJ`) : Légifrance affiche la version alors en vigueur. Sans la date, il afficherait la version d'aujourd'hui, même sous l'identifiant d'une version ancienne |

Les références sont repérées par la grammaire de [@tricoteuses/tisseuse](https://www.npmjs.com/package/@tricoteuses/tisseuse) et rattachées à notre index de la base LEGI de la DILA. Environ un amendement sur trois en a au moins une. Ne sont pas liés : les articles du texte en discussion (« l'article 3 » sans autre précision), une partie des renvois de forme « le même code », les textes européens, les sections (titres, chapitres). Les positions portent sur le dispositif **tel que l'API le renvoie** : nettoyer le texte (balises, `&nbsp;`) avant de découper décale les liens.

---

## 🗂️ Routes des sujets

Un sujet regroupe les dossiers de l'Assemblée nationale et du Sénat qui portent sur le même texte :

| Méthode | Route | Description |
| :--- | :--- | :--- |
| `GET` | `/api/v1/sujets` | Liste des sujets avec pagination et filtres thématiques |
| `GET` | `/api/v1/sujets/featured` | Sujets majeurs mis en avant |
| `GET` | `/api/v1/sujets/:slug` | Synthèse complète du sujet (enjeux, résumés, positions comparées). `gouvernement` : comme sur un dossier, pour l'ensemble de ses dossiers |
| `GET` | `/api/v1/sujets/:slug/presse` | Articles de presse récents, lus en direct sur Google Actualités (liens seulement, cache de 3 h) |

Toutes les routes des sujets (`/categories`, `/:slug/archive`, `/:slug/documents-lies`, `/:slug/dossiers`, `/:slug/chronologie`, `/:slug/scrutins`, `/:slug/stats`) et leurs schémas de réponse : [explorateur de l'API](/api).
