English version

logo Keyclic

Documentation du service Keyclic¶

Keyclic est une application de remontĂ©e et de traitement de demandes. Elle permet Ă  ses utilisateurs de signaler des dysfonctionnements, des problĂšmes techniques ou tout autre type d’information, et de remonter ces signalements aux organisations concernĂ©es.

Sommaire¶

Aperçu¶

Fonctionnement général¶

L’application Keyclic est librement ouverte aux inscriptions. Une fois inscrit, tout utilisateur peut crĂ©er des demandes. Une demande est toujours liĂ©e Ă  une zone de responsabilitĂ© et comporte Ă©ventuellement une position gĂ©ographique et des donnĂ©es complĂ©mentaires photos, description, mĂ©tadonnĂ©es, etc.

Certains utilisateurs peuvent Ă©galement ĂȘtre regroupĂ©s au sein d’organisations. Une organisation est donc un groupe d’utilisateurs membres de la mĂȘme entreprise, association, corporation, Ă©cole, etc. Tout utilisateur est libre de crĂ©er sa propre organisation et d’inviter d’autres utilisateurs Ă  en devenir membres.

Les administrateurs dĂ©finissent des zones de responsabilitĂ© sur lesquelles leur organisation peut intervenir, des catĂ©gories d’intervention (exemple : plomberie, peinture, climatisation), un cycle de vie de la demande (exemple : Nouveau, En cours, TerminĂ©) et un ensemble de paramĂštres concernant la confidentialitĂ© des demandes reçues.

Ainsi, quand un utilisateur crĂ©e une demande, la zone de responsabilitĂ© de cette demande permet de lui proposer les catĂ©gories et de le laisser choisir celle qui lui semble la plus adaptĂ©e. Aussi, quand un utilisateur crĂ©e une demande, suivant les paramĂštres de confidentialitĂ© de l’organisation, celui-ci peut avoir le choix de la rendre publique ou privĂ©e. Si publique, la demande est visible par la communautĂ© : ainsi, les autres utilisateurs peuvent la commenter et/ou la soutenir (Voir la page ConfidentialitĂ© des demandes).

La demande envoyée :

  • elle est transmise Ă  l’organisation concernĂ©e, si les paramĂštres de confidentialitĂ© de cette organisation autorise l’utlisateur,
  • elle n’est pas transmise Ă  l’organisation concernĂ©e, si les paramĂštres de confidentialitĂ© de cette organisation n’autorise pas l’utlisateur.

Un administrateur a donc accĂšs Ă  l’ensemble des demandes concernant son organisation. Pour chaque demande, il peut crĂ©er une ou plusieurs interventions, et affecter ces interventions aux membres de son organisation. Une autre possibilitĂ© est de dĂ©lĂ©guer cette demande Ă  une organisation partenaire, le partenaire aura alors la charge de crĂ©er des interventions. Une fois que toutes les interventions ont Ă©tĂ© accomplies, il pourra considĂ©rer que le traitement est terminĂ© et clĂŽturer la demande.

Vocabulaire¶

Demande¶

Remarque effectuĂ©e sur le terrain par un utilisateur, pouvant porter sur un dysfonctionnement, un problĂšme technique, une nuisance, etc. Toute demande est forcĂ©ment faite en une position gĂ©ographique donnĂ©e. Elle peut Ă©ventuellement comporter des photos, et ĂȘtre commentĂ©e et/ou soutenue par les autres utilisateurs.

Terme technique : feedback.

Voir la page Demandes.

Demande (organisation)¶

Toute demande peut entraĂźner la gĂ©nĂ©ration d’une demande Ă  une organisation. Une demande reprend donc toutes les informations de la demande dont elle est issu, et n’est visible et manipulable que par l’organisation concernĂ©e. C’est sur cette demande que l’organisation travaille : crĂ©ation d’interventions, suivi, dĂ©lĂ©gation, etc.

Terme technique : report.

Voir la page Rapports

Organisation¶

Groupe d’utilisateurs pouvant ĂȘtre une entreprise, une Ă©cole, une association, un groupe de personnel d’un site, d’un chantier, etc.

Terme technique : organization.

Voir la page Organisations.

Zone de responsabilité¶

Aire géographique sur laquelle une organisation peut intervenir.

Terme technique : place.

Voir la section Gestion des zones de responsabilité.

Catégorie¶

Secteur d’activitĂ© d’une organisation.

Terme technique : category.

Voir la section Gestion des catégories.

Soutien¶

Une demande peut ĂȘtre soutenue par les utilisateurs de la communautĂ©, afin de leur donner plus de poids.

Terme technique : contribution.

Voir la section Soutiens.

Intervention¶

Une intervention est une tĂąche crĂ©Ă©e par un administrateur sur une demande donnĂ©e. Cette tĂąche est assignĂ©e Ă  un membre de l’organisation. Un rapport ne peut ĂȘtre clĂŽturĂ© que si toutes les interventions qui lui sont liĂ©es ont Ă©tĂ© accomplies (ou refusĂ©es).

Terme technique : operation.

Voir la section Interventions.

Partenaires¶

Un administrateur peut dĂ©finir des organisations partenaires, qui sont d’autres organisations auxquelles il pourra dĂ©lĂ©guer des demandes.

Terme technique : relationship.

Voir la section Gestion des partenariats.

Considérations techniques¶

L’API Keyclic est une API REST. Toutes les opĂ©rations sont effectuĂ©es via le protocole https et sĂ©curisĂ©es par JSON Web Tokens. Les donnĂ©es sont Ă©changĂ©es exclusivement au format JSON.

Le nom de domaine de l’API Keyclic est :

api.keyclic.com

Applications et clĂ©s d’applications¶

Tout client de l’API doit transmettre dans les headers de chaque requĂȘte une clĂ© dĂ©finissant l’application sur laquelle il travaille.

Si vous dĂ©veloppez un client pour travailler sur une application existante de Keyclic, vous devez connaĂźtre la clĂ© de cette application. Si au contraire vous dĂ©veloppez un client pour une nouvelle application, merci de vous adresser Ă  la sociĂ©tĂ© Keyclic pour que celle-ci crĂ©e l’application et sa configuration et vous fournisse la clĂ© correspondante.

Exemples de clĂ©s d’applications :

  • com.keyclic.app
  • com.keyclic.city
  • com.keyclic.highway

Chaque requĂȘte doit donc prĂ©ciser, dans ses headers, la valeur du paramĂštre X-Keyclic-App. Voir ci-dessous le paragraphe RequĂȘtes pour la mise en Ɠuvre.

Notez cependant que la base utilisateurs est commune Ă  toutes les applications Keyclic. De fait, les endpoints d’inscription et de connexion (voir : Authentification et connexion) font exception Ă  la rĂšgle ci-dessus : ces deux endpoints n’exigent pas qu’une clĂ© d’application leur soit fournie.

RequĂȘtes¶

Dans cette documentation, chaque endpoint de l’API sera dĂ©crit par le chemin d’accĂšs Ă  la ressource prĂ©cĂ©dĂ© du verbe HTTP.

Exemple :

GET /feedbacks

Le endpoint ci-dessus retourne toutes les demandes. Son URL véritable est

https://api.keyclic.com/feedbacks

mais pour des raisons de concision, dans cette documentation, nous ne préciserons jamais le protocole ni le nom de domaine.

ParamĂštres d’URL¶

Dans cette documentation, les variables d’URI (exemples : identifiant d’une ressource, numĂ©ro de page, etc) seront exprimĂ©s entre accolades. Par exemple, pour rĂ©cupĂ©rer une demande (feedback) donnĂ©e :

GET /feedbacks/{feedback}

Dans l’API Keyclic, conformĂ©ment aux principes d’architecture REST, les paramĂštres de filtrage sont toujours passĂ©s en « query string Â». Exemple :

GET /feedbacks?page={page}

Par ailleurs, pour une meilleure lisibilitĂ©, les paramĂštres d’URI seront Ă©crits tels quels dans cette documentation, et non sous leur forme URL encodĂ©e :

GET /feedbacks?before=2018-04-22T01:00:00+05:00
Headers¶

En plus des headers conventionnels de HTTP/1.1, l’API Keyclic accepte, et mĂȘme exige dans la plupart des cas, le header X-Keyclic-App, correspondant Ă  l’application utilisĂ©e (voir ci-dessus : Applications et clĂ©s d’applications). Par exemple, pour rĂ©cupĂ©rer toutes les demandes sur l’application com.keyclic.app, la requĂȘte comportera le header :

X-Keyclic-App : com.keyclic.app

Tous les endpoints exigent que ce header soit fourni, à l’exception des endpoints de login et de changement de mot de passe. (voir : Authentification et connexion)

Toutes les requĂȘtes (Ă  l’exception du login, du register et du changement de mot de passe) doivent aussi comporter le header Authorization afin d’authentifier l’utilisateur. (voir : Authentification et connexion)

Format des requĂȘtes et rĂ©ponses¶

Le seul type de contenu acceptĂ© par l’API Keyclic est JSON. Vos requĂȘtes devront donc comporter le header :

Content-type: application/json

et le corps des requĂȘtes devra toujours ĂȘtre formatĂ© en JSON. Les rĂ©ponses sont Ă©galement toujours retournĂ©es au format JSON.

Envoi de fichiers¶

Tous les fichiers sont envoyĂ©s en base 64 Ă  l’API. Voici par exemple l’ajout d’une image reprĂ©sentant un carrĂ© rouge d’1 pixel sur 1 sur une demande :

POST /feedbacks/{feedback}/images
{
    "image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAIAAAACDbGyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIVDRUfvq7u+AAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVAjXY3wrIcGABJgYUAGpfABZiwEnbOeFrwAAAABJRU5ErkJggg=="
}

Modification de ressources¶

Dans l’API Keyclic, la modification des ressources s’effectue avec la mĂ©thode PATCH. Contrairement Ă  la mĂ©thode PUT, la mĂ©thode PATCH permet de modifier une seule propriĂ©tĂ© ou une partie seulement des propriĂ©tĂ©s d’une ressource, sans qu’il soit nĂ©cessaire d’en envoyer une reprĂ©sentation complĂšte. Le format utilisĂ© pour la description du patch est JSON Patch.

À titre d’exemple, voici la modification de la propriĂ©tĂ© billingEmailAddress d’une organisation :

PATCH /organizations/{organization}
{
    "billingEmailAddress":"test@test.com"
}

Retours d’erreurs¶

Toute erreur entraĂźne une rĂ©ponse de code 4xx reflĂ©tant le type d’erreur.

Quand il s’agit d’une erreur de type 400 (Bad Request), les raisons de l’erreur sont retournĂ©es.

Les erreurs sont décrites au format vdn.error.

L’exemple suivant montre un retour d’erreur de validation. Le champ path indique la propriĂ©tĂ© sur laquelle porte l’erreur (ici : reporter), et le champ message indique la nature de l’erreur.

{
    "@context": "https://github.com/blongden/vnd.error",
    "@type": "ValidationError",
    "message": "Validation failed.",
    "total": 1,
    "_embedded": {
        "errors": [
            {
                "@context": "https://github.com/blongden/vnd.error",
                "@type": "Error",
                "message": "Cette valeur ne doit pas \u00eatre vide.",
                "path": "reporter"
            }
        ]
    }
}

Changements de statut¶

Plusieurs ressources manipulĂ©es par l’API ont un cycle de vie et possĂšdent un certain statut Ă  un instant donnĂ©. C’est le cas des demandes et des interventions.

Pour ces ressources, l’état est toujours indiquĂ© dans la rĂ©ponse avec le paramĂštre state, et les actions possibles pour faire Ă©voluer ce statut sont toujours indiquĂ©es sous le paramĂštre stateTransitions. Exemple :

GET reports/{report}

RĂ©ponse (partielle) :

{
    "type": "Report",
    "id": "cb7118b5-a821-4cf2-9475-0c0d0efdb8d0",
    "state": "NEW",
    "_embedded": {
        "stateTransitions": [
            "accept",
            "refuse"
        ]
    }
}

Dans l’exemple ci-dessus, la demande est en statut NEW et les actions possibles sur son statut sont accept et refuse.

Tout changement de statut est effectué avec la méthode POST en passant le nom de la transition dans le body.

Par exemple, pour accepter la demande ci-dessus :

POST /reports/{report}/workflow/transition
{
    "transition": "accept"
}

La réponse nous informe que la demande possÚde désormais le statut ACCEPTED, et que les actions possibles sont désormais refuse, hold et progress :

{
    "type": "Report",
    "id": "32219286-528a-4f97-b81e-fe7a8cb85707",
    "state": "ACCEPTED",
    "_embedded": {
        "stateTransitions": [
            "refuse",
            "hold",
            "progress"
        ]
    }
}

Les actions et status possibles pour chaque type de ressources sont décrits dans les sections idoines de cette documentation.

Authentification et connexion¶

L’API Keyclic se base sur le standard JSON Web Tokens pour la sĂ©curisation de l’échange des donnĂ©es. Toute requĂȘte Ă  l’API est nĂ©cessairement effectuĂ©e en fournissant un jeton d’accĂšs (accessToken) permettant au serveur de vĂ©rifier l’identitĂ© de l’utilisateur. Un endpoint permet Ă  l’utilisateur d’obtenir ce jeton d’accĂšs en fournissant son login et son mot de passe. Cette section dĂ©taille la crĂ©ation d’un compte, l’obtention et l’utilisation d’un accessToken, et la modification d’un compte utilisateur.

Pour plus d’informations sur le standard JWT, voir : le site officiel de JSON Web Tokens.

CrĂ©ation d’un compte utilisateur¶

Un nouveau compte utilisateur est crĂ©Ă© avec la requĂȘte :

POST /security/register
{
    "email":"test@test.com",
    "password":"test"
}

Le nouvel utilisateur se voit attribuer un identifiant unique et le rĂŽle ROLE_USER, lui permettant d’utiliser les fonctionnalitĂ©s de base de l’API.

Connexion¶

La connexion consiste Ă  envoyer ses credentials au serveur afin d’obtenir en retour un accessToken qui sera utilisĂ© pour les requĂȘtes ultĂ©rieures.

La connexion s’effectue avec la requĂȘte :

POST /security/login
{
    "login":"test@test.com",
    "password":"test"
}

Si les credentials sont reconnus par le serveur, celui-ci retourne un accessToken qui sera utilisĂ© par l’utilisateur pour ses futures requĂȘtes.

Utilisation du token¶

La quasi-totalitĂ© des requĂȘtes Ă  l’API nĂ©cessitent que l’utilisateur soit authentifiĂ©, c’est-Ă -dire qu’il fournisse son accessToken. Le token est envoyĂ© dans l’en-tĂȘte Authorization de la requĂȘte, prĂ©fixĂ© par Bearer.

Par exemple, pour rĂ©cupĂ©rer la liste des feedbacks de l’application com.keyclic.app, un utilisateur utilise le endpoint :

GET /feedbacks
Request headers :
    X-Keyclic-App : com.keyclic.app
    Authorization : Bearer eyJhbGciOiJSUzI1NiJ9.eyJyb2xlcyI6WyJPUkdBTklaQVRJT046QURNSU4iLCJST0xFX1VTRVIiXSwidXNlcm5hbWUiOiJ0ZXN0MjJAdGVzdC5jb20iLCJpcCI6Ijc3LjIwMy40NS40NCIsImV4cCI6MTQ4OTI0MTQ0NCwiaWF0IjoxNDg5MTU1MDQ0fQ.ZIqbBVSgJaXKj73IPYbFeEfie6FUIflv-ausUO-AAzVjPg8-jdhFv3nqsdOVJvE_AB4bXjME1CRVFI7xD2SYCA8V6E6H2-y0XZE8SN_XTpHGMxDvOP27C2VUNQfPwgeWxjXzlDopo_U9ybAEX4QdFhW14aeRgb9YWMDlzSD6VLgJO-LuprxX668Ajq5X9c8YND4D_p4WRDSQr8pqb3rTY9NQ6O34F-OpDJlAUYj0pwMehYWpywVKJHRMv9xCRRoI8HrU6H3J3wo-K2OtQVJi9XFZ8g8sohw_ZaasG7dohxrO-NtYSrOPXIXPI6kCDRuMi7sce06wfno1bC3jBoc83EhiBSBpDbWL98DSjPbF1SaCeE05aATfM5cMEXbnp8Iwh-QLxglE4M-ZISJ8VooxzJxa7cWLlFW-iu0XWVFWrMbYgmSoU0PKRQB47w_IOPxjWzDeMUTSA3esDwkxsYlNdS9SZe201EvI6zur5Ayot0PEGfAgex6Ew-eKOHAfnuDiqeLQLbWs4Y69FO2DooWUhkfVGdl-IGglDPgk2AOs3w19e7mx-Gmm8DlUUr-bK61NPPQ8dy7HPjXnU63-jbA17MAjHaRTO4eKopcZMWbpL-jgQjJltV3R5_0qNODaHCS_auZs2cyqFN0HL9Rred5g7t6Fxyk-8MyyX0GiTyHsp3c

Toutes les requĂȘtes Ă  l’API Keyclic nĂ©cessitent l’envoi d’un accessToken dans les headers, Ă  l’exception Ă©vidente des endpoints suivants :

  • crĂ©ation d’un compte (POST /security/register)
  • login (POST /security/login)
  • demande de changement de mot de passe (POST /security/password/change-request)
  • changement de mot de passe (POST /security/password/change/{changePasswordToken})

Modification du mot de passe¶

Un utilisateur qui souhaite modifier son mot de passe procĂšde en deux Ă©tapes.

Il effectue d’abord une demande de changement de mot passe :

POST /security/password/change-request
{
    "email":"test@test.com"
}

Cette requĂȘte envoie un email Ă  l’utilisateur contenant un lien se terminant par un token de vĂ©rification. Exemple de lien :

https://domain.com/#/password-reset/jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA

Dans le lien ci-dessus, jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA est le jeton de changement de mot de passe. La portion d’URL https://domain.com/#/password-reset/ dĂ©pend de la configuration de l’application.

L’utilisateur peut ensuite changer son mot de passe avec :

POST /security/password/change/jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA
{
    "password":"password"
}

Modification des données utilisateur¶

Pour les donnĂ©es autres que le mot de passe, l’utilisateur enverra une requĂȘte sur le endpoint :

PATCH /people/{user}

Pour plus d’informations sur les requĂȘtes PATCH, voir la section Modification de ressources.

Par exemple, pour modifier son nom :

{
    "familyName": "Nom de famille"
}

Les champs qu’un utilisateur peut modifier sont : son nom (familyName), son prĂ©nom (givenName), sa photo (image), son travail (job), son adresse email (email).

Membres d’organisation et rĂŽles¶

Quand un utilisateur est collaborateur d’une organisation, il peut bĂ©nĂ©ficier d’aucun, d’un ou plusieurs rĂŽles dĂ©finissant un ensemble de permissions et de possibilitĂ©s d’actions. Ces rĂŽles peuvent ĂȘtre cumulĂ©s pour un mĂȘme utilisateur et sont au nombre de cinq :

  • Administrateur
  • Agent
  • Intervenant
  • Statistiques
  • Export

Un utilisateur pouvant ĂȘtre membre de plusieurs organisations, les rĂŽles qu’il possĂšde sont indĂ©pendants et peuvent ĂȘtre diffĂ©rents d’une organisation Ă  une autre. Tout utilisateur nouvellement attachĂ© Ă  une organisation devient « Collaborateur d’organisation Â». Un « Collaborateur d’organisation Â» possĂšde les mĂȘmes droits qu’un utilisateur de base sans attachement Ă  une organisation.

Administrateur¶

Tout utilisateur a la possibilité de créer une nouvelle organisation.

L’utilisateur qui crĂ©e une nouvelle organisation en devient automatiquement collaborateur et administrateur, c’est-Ă -dire qu’il se voit attribuer le rĂŽle Â« Administrateur Â».

Il obtient les permissions et droits suivants :

  • Ajouter de nouveaux collaborateurs Ă  son organisation
  • Modifier les rĂŽles des collaborateurs
  • GĂ©rer les catĂ©gories de son organisation
  • GĂ©rer les zones de responsabilitĂ© de son organisation
  • GĂ©rer les partenaires de son organisation
  • Consulter et gĂ©rer les demanes reçues et les interventions liĂ©es Ă  ces demandes

Voir : Organisations

Voir : Rapports

Note : Un utilisateur peut ĂȘtre « ORGANIZATION:ADMIN Â» de plusieurs organisations et une organisation peut avoir plusieurs « ORGANIZATION:ADMIN Â».

Intervenant¶

Un « Collaborateur d’organisation Â» possĂ©dant ce rĂŽle peut  :

  • Recevoir une assignation Ă  une intervention
  • Éditer une intervention (changement des libellĂ©s, ajout de photos de constatation, etc)
  • Changer le statut d’une intervention

Note : Un utilisateur peut ĂȘtre « ORGANIZATION:OPERATOR Â» de plusieurs organisations et une organisation peut avoir plusieurs « ORGANIZATION:OPERATOR Â».

Analyste¶

Le rĂŽle « Analyste Â» permet d’accĂ©der aux statistiques d’une organisation.

Note : Un utilisateur peut avoir le rĂŽle « ORGANIZATION:ANALYTICS Â» pour plusieurs organisations et une organisation peut avoir plusieurs utilisateurs avec le rĂŽle « ORGANIZATION:ANALYTICS Â».

Export¶

Le rĂŽle « Export Â» permet d’accĂ©der aux fonctionnalitĂ©s d’exportation Excel des demandes qu’a reçu une organisation.

Note : Un utilisateur peut avoir le rĂŽle « ORGANIZATION:EXPORT Â» pour plusieurs organisations et une organisation peut avoir plusieurs utilisateurs avec le rĂŽle « ORGANIZATION:EXPORT Â».

Récupération des utilisateurs¶

Pour rĂ©cupĂ©rer l’ensemble des utilisateurs de l’application :

GET /people

Pour récupérer un utilisateur :

GET /people/{user}

Pour rechercher les utilisateurs dont l’adresse email match un mot donnĂ© :

GET /people?search[email]=martin

Exemple de rĂ©cupĂ©ration des rĂŽles d’un utilisateur¶

La lecture d’une ressource utilisateur permet de dĂ©couvrir si la personne appartient Ă  une organisation et quel(s) rĂŽle(s) il y tient.

GET /people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships
{
    "page": 1,
    "limit": 10,
    "pages": 1,
    "total": 1,
    "_links": {
        "self": {
            "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships?page=1&limit=10"
        },
        "first": {
            "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships?page=1&limit=10"
        },
        "last": {
            "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a/memberships?page=1&limit=10"
        }
    },
    "_embedded": {
        "items": [
            {
                "id": "b0e7e28f-5b91-4c73-875e-8f34aa03553a",
                "roles": [
                    "ORGANIZATION:ADMIN",
                    "ORGANIZATION:AGENT"
                ],
                "createdAt": "2018-02-27T10:00:00+02:00",
                "_links": {
                    "self": {
                        "href": "/organizations/84d36093-b8bc-47ad-bc8a-a043b3e301a9/members/b0e7e28f-5b91-4c73-875e-8f34aa03553a",
                        "iriTemplate": {
                            "mapping": {
                                "organization": "84d36093-b8bc-47ad-bc8a-a043b3e301a9",
                                "member": "b0e7e28f-5b91-4c73-875e-8f34aa03553a"
                            }
                        }
                    },
                    "person": {
                        "href": "/people/5020c6ea-ca07-42d1-994f-d90b86703b1a",
                        "iriTemplate": {
                            "mapping": {
                                "person": "5020c6ea-ca07-42d1-994f-d90b86703b1a"
                            }
                        }
                    },
                    "organization": {
                        "href": "/organizations/84d36093-b8bc-47ad-bc8a-a043b3e301a9",
                        "iriTemplate": {
                            "mapping": {
                                "organization": "84d36093-b8bc-47ad-bc8a-a043b3e301a9"
                            }
                        }
                    }
                },
                "_embedded": {
                    "availableRoles": [
                        "ORGANIZATION:ADMIN",
                        "ORGANIZATION:ANALYTICS",
                        "ORGANIZATION:EXPORT",
                        "ORGANIZATION:READ_ONLY"
                    ]
                }
            }
        ]
    }
}

Ce retour indique que l’utilisateur :

  • Est membre de l’organisation 84d36093-b8bc-47ad-bc8a-a043b3e301a9
  • PossĂšde le rĂŽle ORGANIZATION:ADMIN, il est donc administrateur de l’organisation 84d36093-b8bc-47ad-bc8a-a043b3e301a9
  • PossĂšde le rĂŽle ORGANIZATION:AGENT, il est donc agent de l’organisation 84d36093-b8bc-47ad-bc8a-a043b3e301a9
  • Est affiliĂ© avec une seule organisation
  • A rejoint l’organisation le 27 fĂ©vrier 2018.

Aussi, un membre possĂšde deux id diffĂ©rents, un id membre et un id utilisateur. Ainsi, dans le retour prĂ©cĂ©dent on voit que son id utilisateur (5020c6ea-ca07-42d1-994f-d90b86703b1a) est diffĂ©rent de son id membre (b0e7e28f-5b91-4c73-875e-8f34aa03553a). L’API distingue les actions effectuĂ©es en tant que membre et celles effectuĂ©es en tant qu’utilisateur simple.

Organisations¶

Dans l’application Keyclic, une organisation est une entitĂ© telle que corporation, entreprise, dĂ©partement d’entreprise, association, Ă©cole, institution, etc Ă  laquelle peuvent ĂȘtre rattachĂ©es les demandes faites par les utilisateurs.

Un ou plusieurs membres d’une organisation peuvent en ĂȘtre les Administrateur. Une organisation possĂšde au minimum un administrateur.

Les Administrateur peuvent dĂ©finir les champs d’intervention de leur organisation en crĂ©ant des catĂ©gories (exemple : voirie, transports, etc) et des zones de responsabilitĂ©.

L’utilisateur a alors accĂšs Ă  des informations lui permettant de l’aiguiller vers l’organisation la plus adĂ©quate.

CrĂ©ation d’une organisation¶

Tout utilisateur peut créer une nouvelle organisation :

POST /organizations
{
    "name":"Nom de l'organisation",
    "billingEmailAddress":"test@test.com",
    "notificationEmailAddress":"test@test.com"
}

L’utilisateur devient automatiquement membre et administrateur de cette nouvelle organisation.

Pour rĂ©cupĂ©rer toutes les organisations de l’application :

GET /organizations

Il est possible de filtrer la requĂȘte ci-dessus sur un point gĂ©ographique (voir ci-dessous : Gestion des zones de responsabilitĂ©) :

GET /organizations?geo_coordinates=+44.851404209987386-0.5762618780136108

Gestion des membres¶

Pour ajouter un nouveau membre Ă  une organisation :

POST /organizations/{organization}/members
{
    "person":"63d07fc5-f4e6-471c-a8cc-3c3f227c8c2d"
}

Ce endpoint est rĂ©servĂ© Ă  un utilisateur possĂ©dant le rĂŽle Administrateur et membre de l’organisation {organization}.

Pour rĂ©cupĂ©rer les membres d’une organisation :

GET /organizations/{organization}/members

Pour retirer un membre d’une organisation, un Administrateur de cette organisation exĂ©cutera la requĂȘte :

DELETE /organizations/{organization}/members/{member}

Gestion des zones de responsabilité¶

Un Administrateur peut créer des zones de responsabilité, correspondant aux lieux sur lesquels cette organisation intervient :

POST /organizations/{organization}/places
{
    "name": "Test",
    "polygon":
    {
        "rings":
        [
            {
                "points":
                [
                    {
                        "longitude": 2.373991012573242,
                        "latitude": 48.84088179130599
                    },
                    {
                        "longitude": 2.3763084411621094,
                        "latitude": 48.84205393836751
                    },
                    {
                        "longitude": 2.376694679260254,
                        "latitude": 48.84189859515306
                    },
                    {
                        "longitude": 2.3787975311279297,
                        "latitude": 48.84041574931067
                    },
                    {
                        "longitude": 2.376115322113037,
                        "latitude": 48.839031720249054
                    },
                    {
                        "longitude": 2.373991012573242,
                        "latitude": 48.84088179130599
                    }
                ]
            }
        ],
        "srid": 4326
    }
}

Pour rĂ©cupĂ©rer toutes les zones de responsabilitĂ© de l’application :

GET /places

La requĂȘte ci-dessus peut-ĂȘtre filtrĂ©e sur une organisation donnĂ©e et/ou sur un point gĂ©ographique donnĂ© :

GET /places?geo_coordinates=+44.851404209987386-0.5762618780136108&organization={organization}

Gestion des catégories¶

Les catĂ©gories sont les secteurs d’activitĂ© d’une organisation. Un Administrateur peut crĂ©er une nouvelle catĂ©gorie en lui donnant un nom, une couleur et une icĂŽne. L’icĂŽne sera choisie dans le jeu d’icĂŽnes de Font Awesome.

POST /organizations/{organization}/categories
{
    "name":"Nom de la catégorie",
    "color":"#ff0000",
    "icon":"fa-bug"
}

Les 3 propriĂ©tĂ©s name, color et icon peuvent ĂȘtre Ă©ditĂ©es par une requĂȘte PATCH (voir : Modification de ressources).

Pour rĂ©cupĂ©rer l’ensemble des catĂ©gories de l’application :

GET /categories

La requĂȘte ci-dessus peut-ĂȘtre filtrĂ©e sur une organisation donnĂ©e et/ou sur un point gĂ©ographique donnĂ© :

GET /categories?geo_coordinates=+44.851404209987386-0.5762618780136108&organization={organization}

Gestion des partenariats¶

Une organisation peut avoir des partenaires, c’est-Ă -dire des organisations qui lui sont rattachĂ©es et Ă  qui l”Administrateur de l’organisation pourra dĂ©lĂ©guer des demandes. La relation de partenariat est unilatĂ©rale : si une organisation A est partenaire d’une organisation B, B n’est pas forcĂ©ment partenaire de A.

Pour ajouter un nouveau partenaire Ă  l’organisation, un administrateur de l’organisation requĂȘtera sur le endpoint :

POST /organizations/{organization}/relationships
{
    "organization":"84d36093-b8bc-47ad-bc8a-a043b3e301a9"
}

Pour rĂ©cupĂ©rer les partenaires d’une organisation :

GET /organizations/{organization}/relationships

Cette requĂȘte ne peut ĂȘtre exĂ©cutĂ©e que par un administrateur de l’organisation.

Demandes¶

Une demande est toujours faite en une zone de responsabilitĂ© donnĂ©e. Cette zone de responsabilitĂ© peut ĂȘtre renseignĂ©e directement ou peut ĂȘtre dĂ©terminĂ©e grĂące Ă  une position gĂ©ographique. Si les 2 sont spĂ©cifiĂ©s alors la position gĂ©ographique permettra de prĂ©ciser le lieu (par exemple : au sein d’une grande zone de responsabilitĂ©).

Les paramÚtres optionnels étant la description, la catégorie, une ou plusieurs photos et des métadonnées.

Tous les utilisateurs peuvent créer des demandes.

CrĂ©ation d’une demande¶

POST /feedbacks/issues

Exemple du minimum requis pour effectuer une demande, une demande est crĂ©Ă©e sans catĂ©gorie et sans description. L’utilisateur Ă©mettant cette demande est dĂ©tectĂ© automatiquement grĂące Ă  l’authentification.

{
    "businessActivity": "4bff7cb9-0fd2-4b44-9b0e-f6d17bb4ef36",
    "geo": {
        "elevation": 1,
        "point": {
            "latitude": 44.851343361295214,
            "longitude": -0.5763262510299683
        }
    }
}

Exemple plus complet, une catégorie et une description sont précisées :

{
    "businessActivity": "4bff7cb9-0fd2-4b44-9b0e-f6d17bb4ef36",
    "category": "b0d007d5-e6ad-4113-b2b5-d8a1858a2fb1",
    "description": "Mon feedback 5",
    "geo": {
        "elevation":1,
        "point": {
            "latitude":44.851343361295214,
            "longitude":-0.5763262510299683
        }
    },
    "visibility": "VISIBILITY_PUBLIC"
}

La visibilitĂ© de la demande est par dĂ©faut VISIBILITY_PRIVATE si celle-ci n’est pas renseignĂ©e.

L’utilisateur peut ensuite ajouter une ou plusieurs images à sa demande :

POST /feedbacks/{feedback}/images
{
    "image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAIAAAACDbGyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIVDRUfvq7u+AAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVAjXY3wrIcGABJgYUAGpfABZiwEnbOeFrwAAAABJRU5ErkJggg=="
}

Pour plus d’informations sur l’envoi d’images, voir Envoi de fichiers.

Rattachement d’une demande Ă  une organisation¶

Le service Keyclic ne se contente pas de recueillir des demandes : elle sont transmises aux organisations concernées, qui en assureront le traitement. Pour cela, trois cas de figure peuvent se présenter :

  • Si la position gĂ©ographique de la demande ne correspond Ă  aucune zone de responsabilitĂ©, alors aucune organisation ne recevra cette demande.
  • Si la position gĂ©ographique de la demande se trouve dans une zone de responsabilitĂ© dĂ©finie par une organisation, la demande est automatiquement remontĂ© Ă  l’organisation en question.
  • Si la position gĂ©ographique de la demande se trouve sur deux (ou plus) zones de responsabilitĂ© appartenant Ă  deux (ou plus) organisations diffĂ©rentes, mais que l’utilisateur n’a pas prĂ©cisĂ© de secteur d’activitĂ© particulier, alors plusieurs demandes sont gĂ©nĂ©rĂ©es et remontĂ©es Ă  toutes les organisations concernĂ©es. La premiĂšre organisation qui acceptera la demande pourra en effectuer le traitement.

Demande postée par un collaborateur¶

Les members-collaborator peuvent poster des demandes de la mĂȘme façon que tous les utilisateurs. Cependant si la demande est rĂ©alisĂ©e par un collaborateur celle-ci pourra ĂȘtre traitĂ©e diffĂ©remment :

  • Si sa demande est positionnĂ©e dans une zone de responsabilitĂ© rĂ©gie par son organisation, la demande crĂ©Ă©e qui en dĂ©coule est automatiquement acceptĂ©e.
  • Si sa demande n’est pas positionnĂ©e dans une zone de responsabilitĂ© rĂ©gie par son organisation, alors sa demande n’est pas automatiquement acceptĂ©e.

RĂ©sumĂ© du cycle de vie d’une demande¶

_images/feedback_workflow.png

Récupération des demandes¶

Pour récupérer les demandes :

GET /feedbacks

Cette requĂȘte retourne uniquement les demandes dont le statut est DELIVERED.

Plusieurs critĂšres permettent de filtrer les demandes.

Par statut : paramĂštre state

Par exemple, pour filtrer les demandes dĂ©livrĂ©es, un utilisateur effectuera la requĂȘte :

GET /feedbacks?state=DELIVERED

Autour d’un point : paramùtre geo_near

Exemple :

GET /feedbacks?geo_near[radius]=1000&geo_near[geo_coordinates]=+44.8-0.5

retournera les demandes situées dans un rayon de 1000 mÚtres autour du point de latitude +44.8 et de longitude 0.5.

Dans un GeoHash : paramĂštre geo_hash

GeoHash est un systÚme de géocodage [
] basé sur une fonction de hachage qui subdivise la surface terrestre selon une grille hiérarchique. (Source : Wikipedia)

Pour plus d’informations sur GeoHash, voir :

Les demandes peuvent ĂȘtre filtrĂ©es par GeoHash de la façon suivante :

GET /feedbacks?geo_hash[]=ezzx&geo_hash[]=ezzz

retournera les demandes comprises dans les geo hash ezzx et ezzz.

Sur une période donnée : paramÚtres before et after

Exemple :

GET /feedbacks?after=2017-01-10T00:00:00+05:00&before=2017-02-22T23:59:59+05:00

retournera les demandes effectuées entre le 10/01/2017 et le 22/02/2017.

Les dates sont Ă©crites au format : ISO 8601.

Par organisation

GET /feedbacks?organization={organization}

Commentaires¶

Les utilisateurs de la communauté peuvent commenter une demande :

POST /feedbacks/{feedback}/comments
{
    "text":"Mon commentaire"
}

Pour rĂ©cupĂ©rer les commentaires d’une demande :

GET /feedbacks/{feedback}/comments

Soutiens¶

Un utilisateur peut soutenir une contribution en effectuant la requĂȘte suivante, sans paramĂštres :

POST /feedbacks/{feedback}/contributions

Pour récupérer tous les soutiens effectués sur une demande :

GET /feedbacks/{feedback}/contributions

Confidentialité des demandes¶

Cette page est en cours de rédaction. Cependant les données représentées dans les tableaux suivants sont correctes.

  Zone de responsabilitĂ© forcer en demande privĂ©e Zone de responsabilitĂ© forcer en demande publique Zone de responsabilitĂ© sans forcement
Demandes publiques Demandes privées Demandes publiques Demandes publiques
Demandes privées Demandes privées Demandes publiques Demandes privées
  Organisation publique Organisation privĂ©e
Demandes publiques Envoi possible par tous les utilisateurs Envoi uniquement par les membres d’une organisation
Demandes privĂ©es Envoi possible par tous les utilisateurs Envoi uniquement par les membres d’une organisation
  Organisation publique Organisation privĂ©e
Demandes publiques Demande visible par tous les utilisateurs Demande visible uniquement par l’émetteur, l’organisation rĂ©ceptrice et ses membres
Demandes privĂ©es Demande visible uniquement par l’émetteur et l’organisation rĂ©ceptrice Demande visible uniquement par l’émetteur et l’organisation rĂ©ceptrice

Rapports¶

Chaque fois qu’une demande est dĂ©livrĂ©e (voir : RĂ©sumĂ© du cycle de vie d’une demande), la demande est transmise Ă  l’organisation concernĂ©e.

Un Administrateur récupÚre les demandes concernant son organisation avec :

GET /organizations/{organization}/reports

Et une demande donné est récupéré avec :

GET /reports/{report}

Cycle de vie d’une demande¶

Quand une nouvelle demande est générée pour une organisation, elle possÚde le statut NEW.

Le schĂ©ma ci-dessous montre l’évolution du statut d’une demande en fonction des actions qui sont effectuĂ©es sur cette demande.

_images/report_workflow.png

Un endpoint unique permet de changer le statut d’une demande :

PATCH /reports/{report}/state

Par exemple, pour passer du statut NEW au statut ACCEPTED, l’administrateur de l’organisation effectuera un « accept Â» en passant dans le corps de la requĂȘte :

{
    "transition":"accept"
}

Une demande ne peut ĂȘtre clĂŽturĂ©e (statut CLOSED) que si :

  • Toutes les interventions associĂ©es Ă  cette demande ont Ă©tĂ© clĂŽturĂ©es ou refusĂ©es (voir ci-dessous le paragraphe reports-interventions).

Interventions¶

Une intervention est une action Ă  rĂ©aliser associĂ©e Ă  une demande et assignĂ©e Ă  un membre de l’organisation.

Pour rĂ©cupĂ©rer l’ensemble des interventions associĂ©es Ă  une demande :

GET /reports/{report}/operations

CrĂ©ation et modification d’une intervention

Un administrateur crĂ©e une intervention sur une demande en effectuant la requĂȘte :

POST /operations
{
    "description":"Description de l'intervention",
    "name":"Nom de l'intervention",
    "report":"cb7118b5-a821-4cf2-9475-0c0d0efdb8d0"
}

Une intervention nouvellement créée possÚde le statut NEW.

Une ou plusieurs images peuvent ĂȘtre ajoutĂ©es Ă  l’intervention :

POST /operations/{operation}/images
{
    "image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAIAAAACDbGyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIVDRUfvq7u+AAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAAUSURBVAjXY3wrIcGABJgYUAGpfABZiwEnbOeFrwAAAABJRU5ErkJggg=="
}

La description d’une intervention peut ĂȘtre modifiĂ©e avec la requĂȘte :

PATCH /operations/{operation}
{
    "description":"Nouvelle description"
}

Assignation

Pour assigner une intervention Ă  un membre de l’organisation, l’administrateur de l’organisation effectue la requĂȘte :

POST /operations/{operation}/assign
{
  "member":"{member}",
}

oĂč {member} est l’identifiant du membre Ă  qui est assignĂ©e l’intervention.

Intervention en cours et terminée

Une fois assignĂ©e, l’intervention peut-ĂȘtre passĂ©e « en cours Â» puis « terminĂ©e Â», soit par la personne Ă  qui l’intervention a Ă©tĂ© assignĂ©e, soit par un administrateur de l’organisation.

RĂ©sumĂ© du cycle de vie d’une intervention

_images/operation_workflow.png

Commentaires

Il est possible de commenter une intervention :

POST /operations/{operation}/comments
{
    "text":"Mon commentaire"
}

Pour rĂ©cupĂ©rer tous les commentaires d’une intervention :

GET /operations/{operation}/comments

Logs d’une intervention

Un administrateur peut consulter l’historique d’une intervention avec :

GET /operations/{operation}/logs

Délégation des demanes¶

Un administrateur d’une organisation peut dĂ©lĂ©guer une demande Ă  l’une des organisations partenaires.

Voir : Gestion des partenariats

Pour dĂ©lĂ©guer une demande, un administrateur de l’organisation effectue la requĂȘte :

POST /organizations/{organization}/delegates
{
  "report":"cb7118b5-a821-4cf2-9475-0c0d0efdb8d0",
  "organization":"a31d9ab7-9476-45f2-8cc7-033bf40bbcfa"
}

oĂč {organization} est l’identifiant de l’organisation courante (dont le membre est administrateur), et a31d9ab7-9476-45f2-8cc7-033bf40bbcfa est l’identifiant de l’organisation Ă  laquelle la demane est dĂ©lĂ©guĂ©e.

Cette demande est alors partagĂ©e entre l’organisation courante et l’organisation partenaire. Cette derniĂšre pourra effectuer les máșżmes actions que l’organisation dĂ©lĂ©gante sur cette demande.

L’organisation partenaire peut elle-mĂȘme dĂ©lĂ©guer la demande Ă  l’un de ses partenaires et ainsi de suite.

Export des demandes¶

Un administrateur peut exporter toutes les demanes de son organisation au format Excel :

POST /organizations/{organization}/reports/exports

Une archive contenant le fichier Excel listant tous les demandes et les images associĂ©es Ă  ces demandes est alors envoyĂ© par email Ă  l’administrateur authentifiĂ©.

Applications¶

Une application au cƓur du service Keyclic permet de cloisonner les demandes suivant des domaines applicatifs. Cela se traduit par l’utilisation d’applications clientes ou de sites internet spĂ©cifiques Ă  certains mĂ©tiers.

Pour le client Ă©ponyme du service, l’application dĂ©clarĂ©e est « com.keyclic.app Â», toutes les applications clientes ou sites internet utilisant cette clĂ© auront le mĂȘme cloisonnement. (Ici : l’application iPhone Keyclic, l’application Android Keyclic et le site internet https://app.keyclic.com pour les navigateurs.)

Il existe d’autres applications dĂ©clarĂ©es dans le service Keyclic avec d’autres clĂ©s, notamment « Jaidemaville Â» disponible sur iPhone et Android.

Par exemple, depuis « Jaidemaville Â» (la clĂ© est com.keyclic.city) :

  • il est impossible de lister les demandes dĂ©diĂ©es Ă  l’application Jaidemaville dĂ©clarĂ©e avec la clĂ© « com.keyclic.app Â» et inversement,
  • il est impossible de lister les organisations affiliĂ©es Ă  l’application Jaidemaville dĂ©clarĂ©e avec la clĂ© « com.keyclic.app Â» et inversement.

Notifications¶

Le service Keyclic peut notifier des utilisateurs aprÚs que certaines actions sont réalisées.

Type des notifications émises suivant les actions¶

Action Cible Push Mur Email
CrĂ©ation de compte L’utilisateur     ✓
Demande de changement de mot de passe L’utilisateur     ✓
Commentaire d’une demande

L’émetteur de la demande

Les personnes qui ont commenté ou soutenu la demande

✓ ✓  
Demande crĂ©Ă©e Les administrateurs ✓ ✓ ✓
Demande acceptée

L’émetteur de la demande

Les personnes qui ont commenté ou soutenu la demande

✓ ✓  
Demande clÎturée

L’émetteur de la demande

Les personnes qui ont commenté ou soutenu la demande

✓ ✓  
Demande refusée

L’émetteur de la demande

Les personnes qui ont commenté ou soutenu la demande

✓ ✓  
Demande delĂ©guĂ©e Les administrateurs ✓ ✓ ✓
Ajout d’un document Les administrateurs ✓ ✓  
Intervention assignĂ©e Le membre assignĂ© Ă  l’intervention ✓ ✓ ✓
Intervention terminĂ©e L’administrateur ayant assignĂ© l’intervention ✓ ✓  
Rappel d’intervention

Les intervenants

L’émetteur de la demande

✓ ✓  
Commentaire d’une intervention

Le membre assignĂ© Ă  l’intervention L’administrateur ayant assignĂ© l’intervention

Les members qui ont commentĂ© l’intervention

✓ ✓  
Demande Ă  Ă©valuer L’évaluateur ✓ ✓  

Lorsqu’une des cibles fait une action dĂ©clenchant une notification, il n’est lui-mĂȘme pas notifiĂ©. Par exemple, si l’émetteur d’une demande commente sa demande, il ne recevra pas de notification lui disant qu’il a commentĂ© sa propre demande.

Intégration¶

Webhooks¶

À la diffĂ©rence d’une API qui requiert des interrogations en continu, le service Keyclic propose des webhooks lorsque certains Ă©vĂ©nements se produisent (voir la liste plus bas).

C’est un moyen simple et efficace d’appeler un service ou une application tierce afin de recevoir des notifications et de s’affranchir d’une vĂ©rification continuelle.

Les Webhooks peuvent avoir de nombreux usages, tels que :

  • collecter les demandes crĂ©Ă©s pour votre data-warehouse,
  • synchroniser les demandes et interventions avec votre SI (ex: GMAO, 
),
  • envoyer des notifications.

Création et configuration de webhooks¶

Les webhooks peuvent ĂȘtre crĂ©Ă©s sur demande auprĂšs de notre service.

Un webhook est composĂ© de l’évĂšnement pour lequel vous souhaitez ĂȘtre notifiĂ© et d’une URL Ă  laquelle sera envoyĂ©e la notification.

Plusieurs webhooks peuvent ĂȘtre crĂ©Ă©s de façon illimitĂ©e pour chaque type d’évĂšnements.

Types d’évĂšnements¶

Évùnement Description
reportCreated CrĂ©ation d’une nouvelle demande
reportStateChanged Changement de statut d’une demand
operationCreated CrĂ©ation d’une nouvelle intervention
operationStateChanged Changement de statut d’une intervention
operationRemoved Suppression d’une intervention

RĂ©ception d’une notification de webhook¶

Une notification de webhook est envoyĂ©e au format JSON dans le corps d’une requĂȘte HTTP POST sur l’url configurĂ©e dans le webhook. Elle est composĂ©e du nom de l’évĂ©nement (event) et de la ressource concernĂ©e par l’évĂ©nement (payload), la ressource pouvant varier en fonction de l’évĂ©nement.

note : La ressource possĂšde la mĂȘme sĂ©rialisation que ce soit via une requĂȘte d’API ou lors d’une notification d’un webhook, il est donc possible de parcourir les ressources liĂ©es ou les propriĂ©tĂ©s embarquĂ©es grĂące Ă  la reprĂ©sentation HAL de notre API.

{
    "event": "reportCreated",
    "payload": {
        "type": "Report",
        "id": "b0e7e28f-5b91-4c73-875e-8f34aa03553a",
        "state": "NEW",
        "createdAt": "2018-02-27T10:00:00+02:00",
        "updatedAt": "2018-02-27T10:00:00+02:00",
        "_links": {
            "feedback": "...",
            "operations": "...",
            "organization": "...",
            "tracking": "...",
        },
        "_embedded": {
            "stateTransitions": "...",
            "tracking": "..",
        }
    }
}

Exemple de notification de webhook pouvant ĂȘtre reçue lors de la crĂ©ation d’une nouvelle demande (Exemple partiel).