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.

Liens utiles¶

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

Liens utiles¶

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=="
}

Pagination¶

Tous les endpoints permettant de récupérer une collection de ressources peuvent être paginés avec les filtres page et limit. Par exemple, pour récupérer la deuxième page des demandes à raison de 5 observations par page :

POST /feedbacks?page=2&limit=5

Par défaut, page a la valeur 1 et limit a la valeur 10. Ainsi le endpoint

POST /feedbacks

retourne les 10 premières demandes.

Le retour d’une collection contient les informations et liens nécessaires pour naviguer entre les pages de cette collection. Exemple de retour (partiel) de la liste des demandes :

{
    "page": 2,
    "limit": 10,
    "pages": 8,
    "total": 72,
    "_links": {
        "self": {
            "href": "/feedbacks?page=2&limit=10"
        },
        "first": {
            "href": "/feedbacks?page=1&limit=10"
        },
        "last": {
            "href": "/feedbacks?page=8&limit=10"
        },
        "next": {
            "href": "/feedbacks?page=3&limit=10"
        },
        "previous": {
            "href": "/feedbacks?page=1&limit=10"
        }
    }
}

Dans cette documentation, nous ne rappellerons pas systématiquement qu’il est possible de paginer avec les filtres page et limit, ceux-ci étant communs à tous les endpoints retournant une collection.

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¶

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.

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

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