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à.

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

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.

Présentation de l'API de préremplissage

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/<nom-demarche> (voir Démarrage rapide).

Certains champs, comme le champ carte, attendent une valeur structurée : voir l'exemple de préremplissage d'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 :

https://demarche.numerique.gouv.fr/commencer/<nom-demarche>?<cle1>=<valeur1>&<cle2>=<valeur2>

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.

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/<id-demarche>/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 :

curl --request POST 'https://demarche.numerique.gouv.fr/api/public/v1/demarches/<id>/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 :

{
  "dossier_url": "https://demarche.numerique.gouv.fr/commencer/<nom-demarche>?prefill_token=<token de préremplissage>",
  "dossier_id": "<ID du dossier en base 64>",
  "dossier_number": <ID du dossier en tant qu'entier>
}

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.

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 :

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

curl --request POST 'https://demarche.numerique.gouv.fr/api/public/v1/demarches/<id>/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 : elle contient l'URL du dossier vers laquelle diriger l'usager·ère.

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.

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 https://demarche.numerique.gouv.fr/dossiers.

Démarrage rapide

Vous connaissez le nom de la démarche ? Alors rendez-vous directement sur la page /preremplir/<nom-demarche>.

Par exemple, si votre démarche est une-demarche-a-preremplir, alors ouvrez la page :

https://demarche.numerique.gouv.fr/preremplir/une-demarche-a-preremplir

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

• un exemple de requête et de réponse pour le préremplissage 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/<nom-demarche>/schema.

Par exemple, si votre démarche est une-demarche-a-preremplir, la requête doit être adressée à :

https://demarche.numerique.gouv.fr/preremplir/une-demarche-a-preremplir/schema

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 :

{
  "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/<nom-demarche>

• en JSON, en envoyant une requête en GET à l'URL /api/public/v1/demarches/<id-demarche>/stats