Cette documentation a pour but de vous présenter les principaux concepts utilisés par GRC360 pour mettre à disposition des données.
\nPour commencer a utiliser l'API GRC360 vous avez besoin de :
\ntenantId.Si vous ne posséder pas ces éléments vous pouvez contacter votre administrateur ou le support GRC360.
\nGRC360 permet à un seul utilisateur de traiter les données de plusieurs collectivités.
\nPour simplifier l'utilisation de l'API et la répartition des données, l'utilisateur spécifie la collectivité sur laquelle il souhaite travailler dans le Header HTTP X-Tenant.
X-Tenant: <tenantId>\nCe header doit être fourni dans toutes les requêtes envoyées à GRC360.
\nUn compte utilisateur étant utilisé pour travailler sur plusieurs collectivités, il n'est pas nécessaire de fournir ce header lors de l'authentification par exemple.
\nS'il n'est pas fourni, GRC360 renvoie l'erreur suivante :
\n{\n \"message\": \"tenant header is needed\",\n \"success\": false,\n \"code\": 400\n}\nTous les messages de retour de l'API respectent le format suivant:
\nPour limiter le nombre d'éléments renvoyés pour chaque requête, la quasi totalité des endpoint de GRC360 renvoyant des données vont implémenter un mécanisme de pagination basé sur les paramètres suivants :
\nCes paramètres doivent être passés en tant que Query String.
\nSi aucun paramètre n'est spécifié, GRC360 renvoie par défaut les 10 premiers éléments.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"11624583","collectionId":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","publishedId":"TzCV24D9","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"212439","highlight":"2592f0"},"publishDate":"2021-04-12T12:23:18.000Z"},"item":[{"name":"Authentification","item":[{"name":"Authentification par mot de passe","id":"b8480df2-0390-4cb6-9296-8eec2669fd46","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"username\": \"paul.lagent@gmail.com\",\n \"password\": \"Ce endpoint permet d'obtenir un token valable sur l'environnement GRC360.
\nLes droits d'accès et les autorisations de votre compte sont attachées a ce token.
\nLe token obtenu doit être utilisé comme Bearer Token dans un header de type Authorization.
En cas d'erreur d'authentification, le serveur renvoie un code 401.
\n","urlObject":{"protocol":"https","path":["auth","password"],"host":["api","grc360","fr"],"query":[],"variable":[]}},"response":[{"id":"cc31dd99-8b8d-4d3b-8f86-460ec6266dcd","name":"Authentification réussie","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"username\": \"paul.lagent@gmail.com\",\n \"password\": \"Toutes les requêtes envoyées a GRC360 doivent être authentifiées. \nL'utilisateur qui souhaite utiliser l'API doit dans un premier temps récupérer un token qui lui donnera un certain nombre de droits à l'intérieur de l'infrastructure GRC360.
\nGRC360 compte différents types d'utilisateurs:
\nusers.staffUn staff peut générer un token qu'il devra ensuite fournir avec chacune de ses requêtes.
Il doit appeler le endpoint Authentification par mot de passe documenté ci dessous.
Le token obtenu doit être fourni dans chaque requête sous la forme d'un Bearer token dans l'entête HTTP Authorization.
Authorization: Bearer <token>\nLes données renvoyées par GRC360 représente généralement des objets correspondant a des entités. Ces objets peuvent être liés entre eux par des dépendances qu'il faut parcourir.
\nPar défaut, GRC360 renvoie uniquement des informations permettant d'identifier les objets imbriqués.
\nExemple : Une demande d'un citoyen renvoyées par l'API
\n{\n \"id\": 719,\n \"createdAt\": \"2020-10-30T14:22:03.000Z\",\n \"updatedAt\": \"2020-10-30T19:51:16.000Z\",\n \"title\": {\n \"en\": \"Signaler un incident dans l'espace public\",\n \"fr\": \"Signaler un incident dans l'espace public\"\n },\n \"scenario\": {\n \"uuid\": \"0781beae-db55-43f0-9060-bf637a937cfc\",\n \"tenant\": \"b5223afb-e7ae-4637-8c02-f66a409d756a\"\n },\n \"service\": {\n \"uuid\": \"92d02f24-a139-4a36-befe-0ca09698e4a7\",\n \"tenant\": \"b5223afb-e7ae-4637-8c02-f66a409d756a\"\n },\n ...\nLa demande du citoyen décrit également le service (Démarche en français) utilisé pour transmettre sa demande.\nSi l'on souhaite avoir des informations sur le nom de la démarche utilisé, il faut ensuite aller chercher ces informations en accédant à un autre endpoint.
\nPour simplifier l'accès aux éléments, il est possible de demander à GRC360 de charger le détails de certains champs avant de renvoyer le résultat. Il faut spécifier le header X-Preload.
Ce header doit contenir le chemin vers les champs à charger séparer par des ;. Il est également possible de charger tout ou parties des éléments d'un tableau.
L'exemple suivant va charger le contenu du scénario et du service :
\nX-Preload: service;scenario\nDans l'exemple précédent, si on effectue la même requête avec le header X-preload GRC360 nous renvoie le résultat suivant:
\"id\": 719,\n \"createdAt\": \"2020-10-30T14:22:03.000Z\",\n \"updatedAt\": \"2020-10-30T19:51:16.000Z\",\n \"title\": {\n \"en\": \"Signaler un incident dans l'espace public\",\n \"fr\": \"Signaler un incident dans l'espace public\"\n },\n \"scenario\": {\n \"id\": 101,\n \"uuid\": \"0781beae-db55-43f0-9060-bf637a937cfc\",\n \"publication\": \"public\",\n \"createdAt\": \"2020-10-30T19:12:29.000Z\",\n \"updatedAt\": \"2021-04-12T08:20:20.000Z\",\n \"slug\": \"75-signalements-usagers\",\n \"title\": {\n \"en\": \"Signalements usagers\",\n \"fr\": \"Signalements usagers\"\n },\n ...\n }\n \"service\" : {\n \"uuid\": \"92d02f24-a139-4a36-befe-0ca09698e4a7\",\n \"id\": 75,\n \"createdAt\": \"2020-10-30T19:06:47.000Z\",\n \"updatedAt\": \"2021-04-12T08:20:20.000Z\",\n \"title\": {\n \"en\": \"Signaler un incident dans l'espace public\",\n \"fr\": \"Signaler un incident dans l'espace public\"\n },\n ...\n }\n ...\nCette fonctionnalité est pratique mais il ne faut pas en abuser, elle augmente le temps nécessaire pour récupérer les données et la taille des messages de retour. Nous vous recommandons de précharger uniquement ce qui est nécessaire.
\nL'objet imbriqué ne sera chargé que si l'utilisateur possède les droits suffisants pour y accéder. Il est donc possible que malgré un header correctement spécifié, il ne soit pas possible d'accéder à d'avantage d'informations.
\ncc;aa.bb.bb;dd.bbarray[-1].secondArray[*].valueSur certains objets, il est possible d'utiliser certains champs invisible pour récupérer des informations supplémentaires ou déjà mises en forme.
\nCes éléments seront détaillés au cas par cas pour chaque type d'entité dans le chapitre correspondant.
\n","_postman_id":"d28cfcb5-b3c9-477b-a5fc-3f8b158f8ac8","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_token}}"}]},"isInherited":true,"source":{"_postman_id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","name":"GRC360 - Documentation Publique","type":"collection"}}},{"name":"Demandes des usagers (cases)","item":[{"name":"Recherche d'une ou plusieurs demandes /cases","event":[{"listen":"test","script":{"id":"1c787872-ff13-4935-ae79-54d377f5bc15","exec":["\r","pm.test(\"Successful request\", function () {\r"," pm.expect(pm.response.code).to.be.oneOf([200]);\r","});"],"type":"text/javascript"}}],"id":"8b562269-e12f-48c8-9165-791b70117539","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"X-Tenant","type":"text","value":"{{tenantId}}"},{"key":"X-Preload","type":"text","value":"statuses;form;history;submission"}],"body":{"mode":"raw","raw":""},"url":"https://api.grc360.fr/api/v1/cases?created_at[before]=2019-10-01T22:00:00.000Z&created_at[after]=2019-09-30T22:00:00.000Z&order[createdAt]=DESC&title_fr=Poser une question&status=statusDefault_new&identityUuid=b2266612-d435-4eb0-9608-a7eb018ee13e","description":"Ce endpoint permet d'accéder à une liste de demandes d'usagers.
\nL'utilisateur ne peux que rechercher parmi les demandes auxquelles il a accès.
\nIl est possible de spécifier des filtres sur certains champs de la demande au format QueryString.
\nLes exemples ci-contre vous montrent comment réaliser des recherches personnalisées.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_token}}"}]},"isInherited":true,"source":{"_postman_id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","name":"GRC360 - Documentation Publique","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v1","cases"],"host":["api","grc360","fr"],"query":[{"key":"created_at[before]","value":"2019-10-01T22:00:00.000Z"},{"key":"created_at[after]","value":"2019-09-30T22:00:00.000Z"},{"key":"order[createdAt]","value":"DESC"},{"description":{"content":"Titre de la demande, par defaut : Nom de la démarche utilisée pour réaliser la demande
\n","type":"text/plain"},"key":"title_fr","value":"Poser une question"},{"description":{"content":"Etat de la demande:
\nUUID d'une identité
\n","type":"text/plain"},"key":"identityUuid","value":"b2266612-d435-4eb0-9608-a7eb018ee13e"}],"variable":[]}},"response":[{"id":"1514f6e7-df99-4afe-9515-c38d1801f7a1","name":"Entre deux dates","originalRequest":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"X-Tenant","type":"text","value":"Ce endpoint permet d'accéder a l'historique des événements liés à une demande.
\nLe type de l'événement est déterminé par la valeur de son champ title.
\"title\": {\n \"en\": \"CaseUpdate\",\n \"fr\": \"CaseUpdate\"\n}\nLes valeurs pour fr et en sont identiques, vous pouvez donc utiliser l'une ou l'autre de ces valeurs.
Valeurs possibles :
\nDes données liées à chacun de ces événements sont présent dans data.fr.
UUID de la demande
\n","type":"text/plain"},"type":"string","value":"","key":"uuidCase"}]}},"response":[],"_postman_id":"c6f0c769-433d-49fc-9ed5-913959705139"},{"name":"Historique d'une demande filtré par type","id":"60bd4599-8877-4302-94da-888474e59c38","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-Tenant","type":"text","value":"{{current_tenant}}"}],"url":"{{api_gateway_urld}}/api/v1/cases/:uuidCase/history/:type","description":"Permet d'accéder à l'historique d'une demande en récupérant un seul type d'événement.
\nLes différents types d'événements sont détaillés dans la section précédente Historique d'une demande.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_token}}"}]},"isInherited":true,"source":{"_postman_id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","name":"GRC360 - Documentation Publique","type":"collection"}},"urlObject":{"path":["api","v1","cases",":uuidCase","history",":type"],"host":["{{api_gateway_urld}}"],"query":[],"variable":[{"description":{"content":"UUID de la demande
\n","type":"text/plain"},"type":"string","value":"","key":"uuidCase"},{"description":{"content":"Un type parmis :
\nCaseBegin\nCaseStatusChanged\nEmailIndividual\nValidateDocumentCase\nCaseUpdate\nCaseEnd\nreAffectTask\nNoteCase\nNoteCitizen\nCaseTask\nUpdateSubmission\nChangeTaskDueDate
\n","type":"text/plain"},"type":"string","value":"","key":"type"}]}},"response":[],"_postman_id":"60bd4599-8877-4302-94da-888474e59c38"}],"id":"04b2678e-4e5d-4b3a-ba99-7e7b0a669dfc","description":"Les usagers des collectivités peuvent faire remonter à l'administration de leur communes des demandes (appelés cases dans GRC360) directement via GRC360 ou par le biais des produits Attractive City ou Mon Espace Citoyen.
\nL'API GRC360 permet d'accéder au détail de ces demandes.
\nL'ensemble des endpoints associés aux cases respectent le scéma d'url suivant : \nhttps://api.grc360.fr/api/<version>/cases
Le champ sumup contient des informations clef/valeur regroupées dans un tableau.
\nLes valeurs présentent dans le sumup sont dynamiques en fonction du formulaire configuré pour réaliser la demande.
\n\n\"sumup\": [\n {\n \"label\": \"Catégorie\",\n \"type\": \"string\",\n \"value\": \"Propreté\"\n },\n {\n \"label\": \"Sous catégorie\",\n \"type\": \"string\",\n \"value\": \"Propreté du sol/Trottoirs sales\"\n },\n {\n \"label\": \"Adresse\",\n \"type\": \"address\",\n \"value\": \"2 Rue de la paix, 75001 Paris, France \"\n },\n {\n \"label\": \"Informations complémentaires\",\n \"type\": \"html\",\n \"value\": \"Bonjour, ...<Descriptif de la demande>\"\n },\n {\n \"label\": \"Priorité\",\n \"type\": \"string\",\n \"value\": \"Très gênant\"\n }\nCe champ renvoi l'historique de tout les événements liées à la demande.
\nIl est possible d'utiliser la valeur title de chacun des événements pour identifier leur type.
Les valeurs renvoyés dans le champs history sont identiques au retour du endpoint Historique d'une demande. Pour plus d'information sur la structure des données, merci de vous référer à ce endpoint.
\n","_postman_id":"04b2678e-4e5d-4b3a-ba99-7e7b0a669dfc","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_token}}"}]},"isInherited":true,"source":{"_postman_id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","id":"88561634-aafb-4f8e-bfa9-b99fd9f066b3","name":"GRC360 - Documentation Publique","type":"collection"}}},{"name":"Migration depuis l'API AttractiveCity","item":[],"id":"1709b1b3-4cbc-4c47-b625-68a224cd12eb","description":"Le produit Attractive City offrait la possibilité de collecter certaines données de votre collectivité via l'utilisation d'une API.\nVous retrouverez ci-dessous des instructions de migration pour réaliser l'équivalent de ces données dans GRC360.
\nLe tableau ci-dessous fait correspondre les champs d'une demande dans Attractive City vers ceux de GRC360.
\nLa notation suivante : sumup[label='Catégorie'].value désigne
sumup de type tableaulabel='CatégoriePour pouvoir accéder à l'ensemble de ces champs, vous devez utiliser un header X-Preload contenant au moins les valeurs suivantes : sumup.
Cette documentation est donnée à titre informatif. Dans GRC360 le contenu d'une demande est fonction du formulaire utilisé pour la créer. Lors de votre migration depuis Attractive City vers GRC360 nos équipes ont du essayer de coller au plus proche à ce modèle, cependant certaines différences peuvent exister pour votre cas.\nNos équipes peuvent vous fournir la configuration précise utilisée pour votre collectivité.\nVous retrouverez tous les champs du formulaire dans le sumup.
Vous pouvez accéder aux différents états pris par la demande directement depuis l'objet de la demande.
\nImportant : L'accès à ces données nécessite de spécifier au moins la valeur statuses dans le header de pré-chargement X-Preload, plusieurs valeurs doivent être séparée par des ;.
L'historique des états de la demande se trouve dans le champ statuses sous la forme d'un tableau. Chaque élément de ce tableau correspond à un changement d'état, la structure de ces changement d'état est spécifié ci-dessous.
Voici le tableau de correspondance entre Attractive City et GRC360 :
\nNote :
\ntitle.fr correspond au nom de l'état pour les agents utilisant GRC360 et traitant la demande.title.fr_public à celui qui sera visible par le citoyenIl est possible d'obtenir plus d'informations un historique plus précis des événements liés à la demande en utilisant la section Historique d'une demande.
\nImportant : N’oubliez pas de faire le nécessaire auprès de la CNIL pour être en conformité avec la protection des données de l’usager. (Régime de déclaration dite “normal“)
\nPour chaque demande, vous pouvez accéder aux informations de l'usager ayant réalisé la demande.
\nImportant : L'accès à ces données nécessite de spécifier au moins la valeur identity.personas dans le header de pré-chargement X-Preload, plusieurs valeurs doivent être séparée par des ;.