> For the complete documentation index, see [llms.txt](https://doc.demarche.numerique.gouv.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.demarche.numerique.gouv.fr/pour-aller-plus-loin/api-de-preremplissage.md). # API de préremplissage Grâce à l'API de préremplissage, il est possible de préremplir un dossier pour une démarche donnée. Vous disposez de données sur vos usager·ères et vous souhaitez les utiliser pour **préremplir** un dossier ? ## Présentation **demarche.numerique.gouv.fr** propose une **API de préremplissage.** Pour une démarche donnée, elle permet de préremplir un dossier, avec les données dont vous disposez déjà. {% hint style="info" %} Pour accéder à cette fonctionnalité, la démarche doit : * être soit en brouillon, soit publiée (donc la fonctionnalité n'est pas disponible pour les démarches closes) * être en opendata (configurable depuis la tuile "Présentation") {% endhint %} Le dossier est créé en **brouillon** et vous pouvez y diriger votre usager·ère afin qu'iel s'authentifie, poursuive son remplissage, et le dépose auprès de l'administration. Cette API est REST et ne nécessite pas d'authentification. {% embed url="" %} Présentation de l'API de préremplissage {% endembed %} ## Clés et valeurs Le principe du préremplissage d'un dossier est le suivant : vous fournissez à l'API un couple clé / valeur pour chaque champ de la démarche à préremplir. La **clé** est un identifiant en base 64. Elle identifie le champ de façon unique. Elle est stable et ne change pas dans le temps. Elle ressemble à une chaîne de cette forme : "champ\_Q2hhbXAtMTx0MjM2OX==". La **valeur** est la donnée à renseigner dans le champ du formulaire. Selon le type de champ, cette valeur peut être contrainte. Par exemple, il est impossible de fournir la valeur "toto" pour un champ de type entier. Le format attendu pour chaque type de champ est indiqué sur la page `/preremplir/` (voir [Démarrage rapide](#demarrage-rapide)). Certains champs, comme le champ carte, attendent une valeur structurée : voir l'[exemple de préremplissage d'un champ carte](#exemple-preremplir-un-champ-carte). ## Préremplissage en GET (par URL) L'API de préremplissage met à votre disposition une URL, que vous **pouvez communiquer à votre usager·ère**. Cette URL crée un dossier prérempli en brouillon. Elle permet à l'usager·ère de s'authentifier, puis d'accéder au dossier afin de poursuivre son remplissage et enfin de le déposer. L'URL prend la forme suivante : {% code overflow="wrap" %} ``` https://demarche.numerique.gouv.fr/commencer/?=&= ``` {% endcode %} Comme il s'agit d'une URL, celle-ci est **limitée en longueur** (à 2000 caractères environ, selon les navigateurs). Le préremplissage par URL convient donc uniquement si vous avez peu de champs à préremplir, et / ou qu'il s'agit de champs dont la valeur est courte. Dans le cas contraire, il est préférable d'effectuer un [préremplissage en POST](#preremplissage-en-post). ## Préremplissage en POST L'API de préremplissage permet la création d'un dossier prérempli avec un appel en POST. Cette approche n'impose pas de limite sur la quantité ou la longueur des champs à préremplir. ### Requête La requête doit être adressé en POST à l'URL `/api/public/v1/demarches//dossiers`. Elle prend donc en paramètre de route l'ID de la démarche. Il est ensuite nécessaire d'indiquer : * le content type `application/json` dans les headers de la requête * la liste de couples clé / valeur, au format JSON, dans le body de la requête Une requête complète prend donc la forme suivante : ```shell curl --request POST 'https://demarche.numerique.gouv.fr/api/public/v1/demarches//dossiers' \ --header 'Content-Type: application/json' \ --data '{"cle1": "valeur1", "cle2": "valeur2"}' ``` ### Réponse L'API répond en JSON. La réponse contient l'URL du dossier vers laquelle **diriger l'usager·ère**. Iel peut alors s'authentifier, poursuivre le remplissage et déposer le dossier auprès de l'administration. La réponse prend la forme suivante : ```json { "dossier_url": "https://demarche.numerique.gouv.fr/commencer/?prefill_token=", "dossier_id": "", "dossier_number": } ``` Au moment de la réponse, le dossier est orphelin. Il est rattaché à l'usager·ère après son authentification. ## Exemple : préremplir un champ carte Le champ carte est plus technique que les autres champs : sa valeur n'est pas un simple texte, mais une **géométrie** au format [GeoJSON](https://geojson.org). ### Format de la valeur Un champ carte se préremplit avec **une seule géométrie** GeoJSON de type `Point`, `LineString` ou `Polygon`. Elle apparaît sur la carte comme si l'usager·ère l'avait tracée, et iel peut la modifier ou la supprimer. Les coordonnées sont exprimées en WGS84 (GPS), dans l'ordre **\[longitude, latitude]**. Par exemple, pour un point à Paris : ```json {"type": "Point", "coordinates": [2.3086, 48.8495]} ``` Selon le mode de préremplissage : * **en GET**, la géométrie est passée sous forme de **chaîne JSON**, encodée dans l'URL : `?champ_Q2hhbXAtMTIz=%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B2.3086%2C48.8495%5D%7D` * **en POST**, la géométrie peut être passée directement comme objet JSON : `{"champ_Q2hhbXAtMTIz": {"type": "Point", "coordinates": [2.3086, 48.8495]}}` ### Exemple de requête en POST Voici une requête complète qui préremplit un champ carte avec un polygone (une parcelle, par exemple), ainsi qu'un champ texte : ```shell curl --request POST 'https://demarche.numerique.gouv.fr/api/public/v1/demarches//dossiers' \ --header 'Content-Type: application/json' \ --data '{ "champ_Q2hhbXAtMTIz": { "type": "Polygon", "coordinates": [[ [2.3070, 48.8490], [2.3100, 48.8490], [2.3100, 48.8505], [2.3070, 48.8505], [2.3070, 48.8490] ]] }, "champ_Q2hhbXAtNDU2": "Parcelle située rue de Vaugirard" }' ``` Quelques points d'attention pour un polygone : * les coordonnées sont entourées de **deux paires de crochets** : `[[ ... ]]` ; * le **dernier point doit être identique au premier**, pour fermer le polygone. La réponse est la même que pour tout [préremplissage en POST](#reponse) : elle contient l'URL du dossier vers laquelle diriger l'usager·ère. {% hint style="warning" %} Une géométrie invalide (type non accepté, JSON malformé, ou coordonnées hors des limites WGS84 comme des coordonnées en Lambert 93) est **ignorée** : le dossier est créé, mais le champ carte reste vide. Attention à l'ordre des coordonnées : une latitude et une longitude inversées peuvent rester dans les limites et être acceptées, en plaçant le point au mauvais endroit. {% endhint %} ## Environnement **demarche.numerique.gouv.fr** ne propose pas d'environnement de test, intégration, préproduction ou sandbox, sur lequel réaliser votre intégration. À la place, vous pouvez travailler sans risque directement sur la production (https\://**demarche.numerique.gouv.fr)**. En effet, au cours de l'intégration, vous allez créer des dossiers en brouillon, et ceux-ci : * **sont supprimés** périodiquement, * **ne sont pas soumis à l'administration** tant qu'ils ne sont pas récupérés, complétés et déposés par un·e usager·ère, * **sont invisibles** pour l'administration concernée tant qu'ils ne sont pas soumis. Si vous le souhaitez, vous pouvez également prendre possession de ces dossiers en vous authentifiant, comme le ferait l'usager·ère, afin de les supprimer manuellement depuis la page . ## Démarrage rapide Vous connaissez le nom de la démarche ? Alors rendez-vous directement sur la page `/preremplir/`. Par exemple, si votre démarche est `une-demarche-a-preremplir`, alors ouvrez la page : {% hint style="success" %} {% endhint %} Vous y trouverez : * les champs de la démarche, avec leur ID, leur type, leur description et les valeurs possibles pour le préremplissage * l'URL pour le [préremplissage en GET](#preremplissage-en-get-par-url) * un exemple de requête et de réponse pour le [préremplissage en POST](#preremplissage-en-post) ## Structure de la démarche ### Requête Un point de terminaison vous donnant accès à une description en JSON du schéma de la démarche est à votre disposition. La requête doit être adressée en GET à l'URLl `/preremplir//schema`. Par exemple, si votre démarche est `une-demarche-a-preremplir`, la requête doit être adressée à : {% hint style="success" %} {% endhint %} L'API répond en JSON. La réponse contient des informations génériques sur la démarche ainsi que l’identifiant stable, le titre, la description de chaque champ de la démarche. Elle indique aussi les champs requis ou non. ### Réponse La réponse prend la forme suivante : ```json { "id": "ID_démarche", "number": "Numéro_démarche", "title": "Titre_démarche", "description": "Description_démarche", "state": "publiee", "declarative": null, "dateCreation": "2023-01-16T11:10:48+01:00", "datePublication": "2023-01-16T11:18:32+01:00", "dateDerniereModification": "2023-01-16T16:55:21+01:00", "dateDepublication": null, "dateFermeture": null, "notice": null, "deliberation": null, "cadreJuridiqueUrl": "http://cadredemarche.fr/cadre", "revision": { "id": "ID_Revision", "datePublication": "2023-01-16T16:55:21+01:00", "champDescriptors": [ { "__typename": "TextChampDescriptor", "id": "Stable_ID_Démarche1", "label": "Titre_Démarche1", "description": "Description_Démarche1", "required": true }, { "__typename": "TextareaChampDescriptor", "id": "Stable_ID_Démarche2", "label": "Titre_Démarche2", "description": "Description_Démarche2", "required": false } ] } } ``` ## Statistiques sur le traitement des dossiers Pour une démarche donnée, vous pouvez obtenir des statistiques sur le traitement des dossiers, de deux manières différentes : * en HTML, en vous rendant avec un navigateur sur la page `/statistiques/` * en JSON, en envoyant une requête en GET à l'URL `/api/public/v1/demarches//stats` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://doc.demarche.numerique.gouv.fr/pour-aller-plus-loin/api-de-preremplissage.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.