API GraphQL
Pour être informé des évolutions de l'API, vous pouvez vous inscrire à notre newsletter dédiée
L'API GraphQL de demarches-simplifiees.fr permet de consulter :
  • les informations d'une démarche,
  • la liste et les détails des dossiers d'une démarche,
  • les détails d'un dossier spécifique.
Elle permet également de modifier certaines informations d'un dossier :
  • Envoyer un message à l'usager d'un dossier ;
  • Changer l'état d'un dossier (accepté, refusé, etc.)

Présentation de l'API

3 minutes pour tout savoir de notre API

Aperçu général de GraphQL

Cette API suit le paradigme GraphQL. Pour plus d'informations sur le fonctionnement de GraphQL en général, vous pouvez consulter les liens suivants :

Accéder à l’API GraphQL de demarches-simplifiees.fr

Point d'entrée de l’API

L’API est accessible à l’adresse https://www.demarches-simplifiees.fr/api/v2/graphql (cette adresse n’est pas visitable dans un navigateur). Elle renvoie des données au format JSON, à travers un transport HTTPS.
Pour construire une requête et interpréter les réponses, consultez la documentation complète du schéma de l’API.

Éditeur de requêtes en ligne

Une fois authentifié en tant qu’administrateur disposant d’un token, vous pouvez également accéder à l’éditeur de requêtes en ligne (attention, ne confondez pas cette adresse avec celle de l’endpoint, qui ressemble) :

Vous êtes un organisme public, un intégrateur, une SSII ou un éditeur, et vous souhaitez tester l’API Graph QL

Vous devez effectuer une démarche auprès des équipes DS et pour cela remplir une demande à l’adresse suivante.
Demande d'adhésion à "démarches-simplifiées" pour les organismes, privés et publics, qui veulent tester les API · demarches-simplifiees.fr
Votre demande sera examinée, et vous recevrez un token de test, ainsi qu'un accès à un formulaire de test qui vous permettra d’effectuer des saisies de dossiers puis de tester les API.

Authentification

Tous les appels sont authentifiés et doivent donc fournir un jeton valide qui est accessible dans la partie profil de l’administrateur. Ce jeton doit être fourni dans l’en-tête HTTP Authorization de la requête.
Authorization: Bearer token=valeur_du_jeton.
post
https://www.demarches-simplifiees.fr
/api/v2/graphql
GraphQL

Exemple de requête

Pour tester que tout fonctionne bien

Pour tester l’API, le plus simple est d’effectuer une requête curl telle que ci dessous. Le principe est le même avec un autre client HTTP : remplacez votre_token et votre_numero_de_demarche par les valeurs souhaitez, et n’oubliez pas de préciser le content-type :
1
curl 'https://www.demarches-simplifiees.fr/api/v2/graphql' \
2
--header 'Authorization: Bearer <votre_token>' \
3
--header 'Content-Type: application/json' \
4
--data '{ "query": "query getDemarche($demarcheNumber: Int!) { demarche(number: $demarcheNumber) { id dossiers { nodes { id demandeur { ... on PersonnePhysique { civilite nom prenom } ... on PersonneMorale { siret } } } } } }", "variables": { "demarcheNumber": <votre_numero_de_demarche> } }'
Copied!
Vous devriez alors obtenir des informations en sortie. S’il y a des dossiers dans votre démarche, cette requête vous donne les noms des demandeurs. Si la démarche s’adresse à des entreprises, vous aurez le numéro SIRET des demandeurs.

Récupérer les informations d’une démarche, et les dossiers associés

Voici une requête plus lisible, mais plus complexe, qui va chercher beaucoup d’informations sur les dossiers

Queries

1
query getDemarche(
2
$demarcheNumber: Int!
3
$state: DossierState
4
$order: Order
5
$after: String
6
) {
7
demarche(number: $demarcheNumber) {
8
id
9
number
10
title
11
publishedRevision {
12
...RevisionFragment
13
}
14
groupeInstructeurs {
15
id
16
number
17
label
18
instructeurs {
19
id
20
email
21
}
22
}
23
dossiers(state: $state, order: $order, after: $after) {
24
nodes {
25
...DossierFragment
26
}
27
}
28
}
29
}
30
31
query getGroupeInstructeur(
32
$groupeInstructeurNumber: Int!
33
$state: DossierState
34
$order: Order
35
$after: String
36
) {
37
groupeInstructeur(number: $groupeInstructeurNumber) {
38
id
39
number
40
label
41
instructeurs {
42
id
43
email
44
}
45
dossiers(state: $state, order: $order, after: $after) {
46
nodes {
47
...DossierFragment
48
}
49
}
50
}
51
}
52
53
query getDossier($dossierNumber: Int!) {
54
dossier(number: $dossierNumber) {
55
...DossierFragment
56
demarche {
57
...DemarcheDescriptorFragment
58
}
59
}
60
}
61
62
query getDeletedDossiers($demarcheNumber: Int!, $order: Order, $after: String) {
63
demarche(number: $demarcheNumber) {
64
deletedDossiers(order: $order, after: $after) {
65
nodes {
66
...DeletedDossierFragment
67
}
68
}
69
}
70
}
71
72
fragment DossierFragment on Dossier {
73
id
74
number
75
archived
76
state
77
dateDerniereModification
78
dateDepot
79
datePassageEnConstruction
80
datePassageEnInstruction
81
dateTraitement
82
motivation
83
motivationAttachment {
84
...FileFragment
85
}
86
attestation {
87
...FileFragment
88
}
89
pdf {
90
url
91
}
92
instructeurs {
93
email
94
}
95
groupeInstructeur {
96
id
97
number
98
label
99
}
100
revision {
101
...RevisionFragment
102
}
103
traitements {
104
state
105
emailAgentTraitant
106
dateTraitement
107
motivation
108
}
109
champs {
110
...ChampFragment
111
...RootChampFragment
112
}
113
annotations {
114
...ChampFragment
115
...RootChampFragment
116
}
117
avis {
118
...AvisFragment
119
}
120
messages {
121
...MessageFragment
122
}
123
demandeur {
124
... on PersonnePhysique {
125
civilite
126
nom
127
prenom
128
dateDeNaissance
129
}
130
...PersonneMoraleFragment
131
}
132
}
133
134
fragment DemarcheDescriptorFragment on DemarcheDescriptor {
135
id
136
number
137
title
138
description
139
state
140
declarative
141
dateCreation
142
datePublication
143
dateDerniereModification
144
dateDepublication
145
dateFermeture
146
}
147
148
fragment DeletedDossierFragment on DeletedDossier {
149
id
150
number
151
dateSupression
152
state
153
reason
154
}
155
156
fragment RevisionFragment on Revision {
157
id
158
champDescriptors {
159
...ChampDescriptorFragment
160
champDescriptors {
161
...ChampDescriptorFragment
162
}
163
}
164
annotationDescriptors {
165
...ChampDescriptorFragment
166
champDescriptors {
167
...ChampDescriptorFragment
168
}
169
}
170
}
171
172
fragment ChampDescriptorFragment on ChampDescriptor {
173
id
174
type
175
label
176
description
177
required
178
options
179
}
180
181
fragment AvisFragment on Avis {
182
id
183
question
184
reponse
185
dateQuestion
186
dateReponse
187
claimant {
188
email
189
}
190
expert {
191
email
192
}
193
attachment {
194
...FileFragment
195
}
196
}
197
198
fragment MessageFragment on Message {
199
id
200
email
201
body
202
createdAt
203
attachment {
204
...FileFragment
205
}
206
}
207
208
fragment GeoAreaFragment on GeoArea {
209
id
210
source
211
description
212
geometry {
213
type
214
coordinates
215
}
216
... on ParcelleCadastrale {
217
commune
218
numero
219
section
220
prefixe
221
surface
222
}
223
}
224
225
fragment RootChampFragment on Champ {
226
... on RepetitionChamp {
227
champs {
228
...ChampFragment
229
}
230
}
231
... on SiretChamp {
232
etablissement {
233
...PersonneMoraleFragment
234
}
235
}
236
... on CarteChamp {
237
geoAreas {
238
...GeoAreaFragment
239
}
240
}
241
... on DossierLinkChamp {
242
dossier {
243
id
244
state
245
usager {
246
email
247
}
248
}
249
}
250
}
251
252
fragment ChampFragment on Champ {
253
id
254
label
255
stringValue
256
... on DateChamp {
257
date
258
}
259
... on DatetimeChamp {
260
datetime
261
}
262
... on CheckboxChamp {
263
checked: value
264
}
265
... on DecimalNumberChamp {
266
decimalNumber: value
267
}
268
... on IntegerNumberChamp {
269
integerNumber: value
270
}
271
... on CiviliteChamp {
272
civilite: value
273
}
274
... on LinkedDropDownListChamp {
275
primaryValue
276
secondaryValue
277
}
278
... on MultipleDropDownListChamp {
279
values
280
}
281
... on PieceJustificativeChamp {
282
file {
283
...FileFragment
284
}
285
}
286
... on AddressChamp {
287
address {
288
...AddressFragment
289
}
290
}
291
... on CommuneChamp {
292
commune {
293
name
294
code
295
}
296
departement {
297
name
298
code
299
}
300
}
301
}
302
303
fragment PersonneMoraleFragment on PersonneMorale {
304
siret
305
siegeSocial
306
naf
307
libelleNaf
308
address {
309
...AddressFragment
310
}
311
entreprise {
312
siren
313
capitalSocial
314
numeroTvaIntracommunautaire
315
formeJuridique
316
formeJuridiqueCode
317
nomCommercial
318
raisonSociale
319
siretSiegeSocial
320
codeEffectifEntreprise
321
dateCreation
322
nom
323
prenom
324
attestationFiscaleAttachment {
325
...FileFragment
326
}
327
attestationSocialeAttachment {
328
...FileFragment
329
}
330
}
331
association {
332
rna
333
titre
334
objet
335
dateCreation
336
dateDeclaration
337
datePublication
338
}
339
}
340
341
fragment FileFragment on File {
342
filename
343
contentType
344
checksum
345
byteSizeBigInt
346
url
347
}
348
349
fragment AddressFragment on Address {
350
label
351
type
352
streetAddress
353
streetNumber
354
streetName
355
postalCode
356
cityName
357
cityCode
358
departmentName
359
departmentCode
360
regionName
361
regionCode
362
}
363
Copied!

Variables

1
# Tout les dossiers d’une démarche
2
{
3
"query": <query>,
4
"operationName": "getDemarche",
5
"variables": {
6
"demarcheNumber": 1234
7
}
8
}
9
10
# Tout les dossiers "en_instruction" d’une démarche
11
{
12
"query": <query>,
13
"operationName": "getDemarche",
14
"variables": {
15
"demarcheNumber": 1234,
16
"state": "en_instruction"
17
}
18
}
19
20
# Tout les dossiers supprimés d’une démarche
21
{
22
"query": <query>,
23
"operationName": "getDeletedDossiers",
24
"variables": {
25
"demarcheNumber": 1234
26
}
27
}
28
29
# Tout les dossiers d’un groupe instructeur
30
{
31
"query": <query>,
32
"operationName": "getGroupeInstructeur",
33
"variables": {
34
"groupeInstructeurNumber": 1234
35
}
36
}
37
38
# Un dossier par son numero
39
{
40
"query": <query>,
41
"operationName": "getDossier",
42
"variables": {
43
"dossierNumber": 1234
44
}
45
}
Copied!

Pagination

La pagination sur l’API GraphQL se fait par "curseur". Ça veut dire que pour récupérer la prochaine page il faut passer à l’API le "curseur" de la fin de la page précédente.
Voici un exemple. On commence par faire une query pour récupérer les 100 premiers dossiers :
1
query getDemarche($demarcheNumber: Int!, $after: String) {
2
demarche(number: $demarcheNumber) {
3
dossiers(first: 100, after: $after) {
4
pageInfo {
5
endCursor
6
hasNextPage
7
}
8
nodes {
9
id
10
number
11
}
12
}
13
}
14
}
Copied!
1
{
2
"query": <query>,
3
"operationName": "getDemarche",
4
"variables": {
5
"demarcheNumber": 1234
6
}
7
}
Copied!
Dans le résultat obtenu il faut lire la valeur du "curseur" dans le champ demarche.dossiers.pageInfo.endCursor . On peut passer alors ce "curseur" comme argument after dans la prochaine query. Et ainsi de suite jusqu’à ce que le champ demarche.dossiers.pageInfo.hasNextPage soit égale à false.
1
query getDemarche($demarcheNumber: Int!, $after: String) {
2
demarche(number: $demarcheNumber) {
3
dossiers(first: 100, after: $after) {
4
pageInfo {
5
endCursor
6
hasNextPage
7
}
8
nodes {
9
id
10
number
11
}
12
}
13
}
14
}
Copied!
1
{
2
"query": <query>,
3
"operationName": "getDemarche",
4
"variables": {
5
"demarcheNumber": 1234,
6
"after" "abc"
7
}
8
}
Copied!

Modifier l’état ou les informations d’un dossier

Certaines opérations sur dossier sont accessibles via l’API :
  • Affecter un dossier à un groupe instructeur
  • Changer l’état du dossier
  • Envoyer un message à l’usager qui a déposé le dossier
  • Ajouter des annotations privées sur un dossier
Attention ! Les identifiants utilisés dans les variables input des mutations sont les identifiants « technique » que vous devez récupérer dans les réponses des requêtes précédentes. En particulier, l'identifiant du dossier est différent du « numéro de dossier » :
1
query getDossierIdByNumber($dossierNumber: Int!) {
2
dossier(number: $dossierNumber) {
3
id
4
}
5
}
6
7
{
8
"query": <query>,
9
"operationName": "getDossierIdByNumber",
10
"variables": {
11
"dossierNumber": 1234
12
}
13
}
Copied!
Si un identifiant d’instructeur est demandé, il s’agit d’identifier l’instructeur qui sera enregistré dans le système comme responsable de l’opération. Pour récupérer la liste des instructeurs avec leurs identifiants, vous avez plusieurs possibilités.
Vous pouvez récupérer tous les instructeurs qui suivent un dossier :
1
query getInstructeursForDossier($dossierNumber: Int!) {
2
dossier(number: $dossierNumber) {
3
instructeurs {
4
id
5
email
6
}
7
}
8
}
9
10
{
11
"query": <query>,
12
"operationName": "getInstructeursForDossier",
13
"variables": {
14
"dossierNumber": 1234
15
}
16
}
Copied!
Vous pouvez récupérer tous les instructeurs d'un « groupe instructeur » :
1
query getInstructeursForGroupeInstructeur($groupeInstructeurNumber: Int!) {
2
groupeInstructeur(number: $groupeInstructeurNumber) {
3
instructeurs {
4
id
5
email
6
}
7
}
8
}
9
10
{
11
"query": <query>,
12
"operationName": "getInstructeursForGroupeInstructeur",
13
"variables": {
14
"groupeInstructeurNumber": 1234
15
}
16
}
Copied!

Queries

1
mutation dossierArchiver($input: DossierArchiverInput!) {
2
dossierArchiver(input: $input) {
3
dossier {
4
id
5
}
6
errors {
7
message
8
}
9
}
10
}
11
12
mutation dossierPasserEnInstruction($input: DossierPasserEnInstructionInput!) {
13
dossierPasserEnInstruction(input: $input) {
14
dossier {
15
id
16
}
17
errors {
18
message
19
}
20
}
21
}
22
23
mutation dossierAccepter($input: DossierAccepterInput!) {
24
dossierAccepter(input: $input) {
25
dossier {
26
id
27
}
28
errors {
29
message
30
}
31
}
32
}
33
34
mutation dossierRefuser($input: DossierRefuserInput!) {
35
dossierRefuser(input: $input) {
36
dossier {
37
id
38
}
39
errors {
40
message
41
}
42
}
43
}
44
45
mutation dossierClasserSansSuite($input: DossierClasserSansSuiteInput!) {
46
dossierClasserSansSuite(input: $input) {
47
dossier {
48
id
49
}
50
errors {
51
message
52
}
53
}
54
}
55
Copied!

Variables

1
# Archiver un dossier
2
{
3
"query": <query>,
4
"operationName": "dossierArchiver",
5
"variables": {
6
"input": {
7
"dossierId": "UHJvY4VkdXKlLTI5NTgw",
8
"instructeurId": "OPJvtN7kdXKlLTI4NTlf"
9
}
10
}
11
}
12
13
# Passer un dossier en instruction
14
{
15
"query": <query>,
16
"operationName": "dossierPasserEnInstruction",
17
"variables": {
18
"input": {
19
"dossierId": "UHJvY4VkdXKlLTI5NTgw",
20
"instructeurId": "OPJvtN7kdXKlLTI4NTlf"
21
}
22
}
23
}
24
25
# Accepter un dossier
26
{
27
"query": <query>,
28
"operationName": "dossierAccepter",
29
"variables": {
30
"input": {
31
"dossierId": "UHJvY4VkdXKlLTI5NTgw",
32
"instructeurId": "OPJvtN7kdXKlLTI4NTlf",
33
"motivation": "J’accepte ce dossier"
34
}
35
}
36
}
37
38
# Refuser un dossier
39
{
40
"query": <query>,
41
"operationName": "dossierRefuser",
42
"variables": {
43
"input": {
44
"dossierId": "UHJvY4VkdXKlLTI5NTgw",
45
"instructeurId": "OPJvtN7kdXKlLTI4NTlf",
46
"motivation": "Je refuse ce dossier"
47
}
48
}
49
}
50
51
# Classer un dossier sans suite
52
{
53
"query": <query>,
54
"operationName": "dossierClasserSansSuite",
55
"variables": {
56
"input": {
57
"dossierId": "UHJvY4VkdXKlLTI5NTgw",
58
"instructeurId": "OPJvtN7kdXKlLTI4NTlf",
59
"motivation": "Je classe ce dossier sans suite"
60
}
61
}
62
}
Copied!
Pour plus d’informations sur le format des requêtes et des réponses, consultez la documentation complète du schéma de l’API.
Pour être informé des évolutions de l’API, vous pouvez vous inscrire à notre newsletter dédiée