¶ 1 - Qu'est-ce qu'une API ?
Une API ( « Application Programming Interface » ) permet de mettre à disposition des développeurs des fonctions permettant d’interagir avec une application tierce.
Dans le cas de Picto Access, grâce à notre API vous allez pouvoir vous authentifier et récupérer les informations des établissements liés à votre compte utilisateur.
Vous récupérerez des données brutes que vous pourrez comprendre à travers la documentation présente sur cette page.
Vous aurez également un ensemble de directives ("guidelines") qui vous permettront d’utiliser et d’intégrer au mieux les données sur vos systèmes (applications mobiles, web, autre … ).
API ou Widget ?
Si vous désirez uniquement présenter les données sur votre application, nous vous conseillons d’utiliser notre widget, qui est plus facile à mettre en place. Vous pourrez trouver la documentation associée ici.
Si vous voulez mettre en place un système plus « riche » (par exemple un filtrage des établissements que vous présentez sur base des niveaux d’accessibilité pour une fragilité donnée), l’API est la bonne solution.
Si vous rencontrez des problèmes lors de la mise en place de l'API, nous vous suggérons de consulter la section 6 - Dépannage. Si vos problèmes persistent, vous pouvez nous contacter à l'adresse mail qui figure dans cette même section.
¶ 2 - Environnement
¶ Serveur de Pré-production (recette)
Le serveur de recette permet de tester l'intégration de notre solution chez vous.
Si lors de nos échanges, vous avez émis l'envie de réaliser des tests dans un environement de pré-production, c'est avec cet environnement là que vous travaillerez.
Une fois que vous êtes satisfaits de l'intégration, vous pourrez changer d'environnement en mettant à jour l'URL de vos requêtes. ( Voir paragraphe suivant )
- Portail Web : https://recipe.pictoaccess.fr
- Serveur API : https://api.recipe.pictoaccess.fr
¶ Serveur de Production (live)
Le serveur de production correspond au service en ligne, vu par nos utilisateurs.
C'est cet environnement que vous devez utiliser pour vos services en production.
- Portail Web : https://pictoaccess.fr
- Serveur API : https://api.pictoaccess.fr
¶ 3 - Flow d'authentification
Pour rappel, l'URL de l'API Picto Access diffère selon l'environnement (voir paragraphe précédent)
Certains endpoints de l'API Picto Access nécessiteront l'utilisation d'un token d'authentification (à intégrer dans le header X-Auth-Token)
¶ 0 - Explication des en-têtes de requêtes HTTP (headers)
Pour utiliser l'API Picto, il est nécessaire de fournir les bons en-têtes (headers) dans vos requêtes HTTP. Définition des en-têtes HTTP (headers) : https://developer.mozilla.org/fr/docs/Web/HTTP/Headers
Voici les principaux en-têtes (headers) que vous allez devoir utiliser :
- Accept : Section et versionning de l'API picto. Peut prendre les valeurs suivantes selon l'endpoint (précisé dans la documentation) :
vnd.picto-users-v2+jsonvnd.picto-developer-v2+jsonvnd.picto-public-v2+json
- Authorization : code d'autorisation commune à toutes les requêtes.
Basic dW5pc2M6cGljdG90cmF2ZWw=
- Content-Type : Format de réponse de la requête.
application/json
- X-Auth-Token (obligatoire selon la requête) : obtenu grace à la requête de connexion. (voir paragraphe suivant)
La présence des en-têtes (headers) de chaque requête HTTP est très importante.
Sans ces en-têtes, vos requêtes HTTP retourneront des erreurs.
¶ A - Récupération d'un token d'authentification
Les "login / mots de passe" correspondent aux identifiants qui vous ont été communiqués par l'équipe Picto.
curl -X POST \
https://api.pictoaccess.fr/users/authentication_token \
-H 'accept: application/vnd.picto-users-v2+json' \
-H 'authorization: Basic dW5pc2M6cGljdG90cmF2ZWw=' \
-H 'content-type: application/json' \
-d '{
"user":{
"email": "[email protected]",
"password": "developer_password"
}
}'
Exemple de réponse :
{
"authentication_token": "XXXXXXXXXXXXXXXX"
}
Vous pouvez convertir la requête cURL dans votre langage de programmation grâce à ces sites : https://curl.trillworks.com, https://onlinedevtools.in/curl ou https://jhawthorn.github.io/curl-to-ruby/
Si toutefois votre langage ne figure pas dans les propositions de ces sites, n'hésitez pas à chercher un service similaire sur le net.
¶ 4 - Cas d'utilisation
¶ A - Récupération de tout les établissements associés à votre compte
Un token d'authentification est nécessaire pour utiliser cette requête.
GET https://api.pictoaccess.fr/cards/all_allowed
Vous pouvez utiliser cet endpoint pour récupérer une liste d'objets contenant les informations suivantes :
- uuid [STRING] : Identifiant unique picto qui sera utilisé pour trouver un établissement en particulier.
- metadata [HASH] :
- stream_id [STRING] : Identifiant du flux associé aux données client.
- original_id [STRING] : Identifiant original de l'objet venant du flux de données client.
- content [HASH] :
- title [STRING] : Titre de l'établissement
- accessibility_description [HASH] :
- handicaps [HASH] :
- moteur [INTEGER] : niveau d'accessibilité pour la fragilité moteur.
- senior [INTEGER] : niveau d'accessibilité pour la fragilité senior.
- psychique [INTEGER] : niveau d'accessibilité pour la fragilité psychique.
- mal-voyant [INTEGER] : niveau d'accessiblité pour la fragilité mal-voyant.
- mal-entendant [INTEGER] : niveau d'accessibilité pour la fragilité mal-entendant.
- femme-enceinte [INTEGER] : niveau d'accessibilité pour la fragilité femme-enceinte / poussette.
- mal-voyant-partiel [INTEGER] : niveau d'accessibilité pour la fragilité mal-voyant-partiel.
- mal-entendant-partiel [INTEGER] : niveau d'accessibilité pour la fragilité mal- entendant-partiel.
- handicaps [HASH] :
Valeurs possibles pour les champs de l'objet "handicaps" :
-2 : Inconnu ( page simplifiée uniquement )
-1 : Accessible avec accompagnement ou en autonomie ( page simplifiée uniquement )
0 : Inaccessible ( page enrichie uniquement )
1 : Accessible avec accompagnement ( page enrichie uniquement )
2 : Accessible en autonomie ( page enrichie uniquement )
curl -X GET \
https://api.pictoaccess.fr/cards/all_allowed \
-H 'accept: application/vnd.picto-developer-v2+json' \
-H 'authorization: Basic dW5pc2M6cGljdG90cmF2ZWw=' \
-H 'content-type: application/json' \
-H 'x-auth-token: XXXXXXXXXXXXXXXX'
Exemple de réponse :
[
{
"uuid": "a2f1b53-016f-4a7d-828e-904b49f373cf",
"slug": "nom-de-l-etablisement",
"metadata": {
"stream_id": "5981d97485216dd90b815751",
"original_id": "9510"
},
"content": {
"title": "Nom de l'établissement"
},
"accessibility_description": {
"handicaps": {
"moteur": -2,
"senior": -2,
"psychique": -2,
"mal-voyant": -2,
"mal-entendant": -2,
"femme-enceinte": -2,
"mal-voyant-partiel": -2,
"mal-entendant-partiel": -2
}
}
}
]
Vous pouvez convertir la requête cURL dans votre langage de programmation grâce à ces sites : https://curl.trillworks.com, https://onlinedevtools.in/curl ou https://jhawthorn.github.io/curl-to-ruby/
Si toutefois votre langage ne figure pas dans les propositions, n'hésitez pas à chercher un service similaire sur le net.
¶ B - Récupération de l'accessibilité d'un établissement associé à votre compte
Un token d'authentification est nécessaire pour utiliser cette requête.
GET https://api.pictoaccess.fr/cards/:uuid/accessibility
Vous pouvez utiliser cet endpoint pour récupérer l'accessibilité d'un établissement en précisant l'uuid Picto de celui-ci.
L'uuid d'un établissement peut être obtenu grâce à la requête [A].
Valeurs possibles pour les champs de l'objet "handicaps" :
-2 : Inconnu ( page simplifiée uniquement )
-1 : Accessible avec accompagnement ou en autonomie ( page simplifiée uniquement )
0 : Inaccessible ( page enrichie uniquement )
1 : Accessible avec accompagnement ( page enrichie uniquement )
2 : Accessible en autonomie ( page enrichie uniquement )
curl -X GET \
https://api.pictoaccess.fr/cards/:uuid/accessibility \
-H 'accept: application/vnd.picto-developer-v2+json' \
-H 'authorization: Basic dW5pc2M6cGljdG90cmF2ZWw=' \
-H 'content-type: application/json' \
-H 'x-auth-token: XXXXXXXXXXXXXXXX'
Exemple de réponse :
{
"moteur": 2,
"senior": 2,
"psychique": 2,
"mal-voyant": 1,
"mal-entendant": 1,
"femme-enceinte": 2,
"mal-voyant-partiel": 1,
"mal-entendant-partiel": 1
}
Vous pouvez convertir la requête cURL dans votre langage de programmation grâce à ces sites : https://curl.trillworks.com, https://onlinedevtools.in/curl ou https://jhawthorn.github.io/curl-to-ruby/
Si toutefois votre langage ne figure pas dans les propositions, n'hésitez pas à chercher un service similaire sur le net.
¶ C - Récupération du lien de la page d'un établissement Picto Access via son uuid
GET https://api.pictoaccess.fr/cards/:uuid/generate_link_via_uuid
Vous pouvez utiliser cet endpoint pour récupérer le lien de la page de l'établissement en précisant l'uuid Picto de celui-ci.
L'uuid d'un établissement peut être obtenu grâce à la requête [A].
Vous pouvez utiliser ce lien pour rendre les icônes d'accessibilité cliquables.
curl -X GET \
https://api.pictoaccess.fr/cards/:uuid/generate_link_via_uuid \
-H 'accept: application/vnd.picto-public-v2+json' \
-H 'authorization: Basic dW5pc2M6cGljdG90cmF2ZWw=' \
-H 'content-type: application/json'
{
"link": "https://pictoaccess.fr/cards/nom-de-l-etablissement"
}
Vous pouvez convertir la requête cURL dans votre langage de programmation grâce à ces sites : https://curl.trillworks.com, https://onlinedevtools.in/curl ou https://jhawthorn.github.io/curl-to-ruby/
Si toutefois votre langage ne figure pas dans les propositions, n'hésitez pas à chercher un service similaire sur le net.
¶ 5 - Ressources complémentaires
¶ A - Dominos d'accessibilité
Les dominos d'accessibilité sont disponibles au format SVG, ou au format PNG
Ces dossiers compressés contiennent les 24 variantes de dominos (8 dominos d'accessibilité, déclinés en 3 versions : Accessible (A), Accessible avec accompagnement (B), Innaccessible (C))
¶ B - Couleurs et notations textuelles
Le code couleur correspondant au niveau d'accessibilité d'une fragilité est le suivant :
- Inaccessible : #FF3981 et notation : C
- Accessible avec accompagnement : #FFE500 et notation : B
- Accessible en autonomie : #00FFA3 et notation : A
¶ C - Ordre d'apparition des dominos
- mal-entendant-partiel
- mal-entendant
- psychique
- moteur
- femme-enceinte
- senior
- mal-voyant-partiel
- mal-voyant
¶ D - Hover
Nous vous recommandons fortement de rajouter une partie textuelle explicative au passage de la souris sur le domino.
Les champs textuels associés à chaque domino sont à votre disposition, sous format word ou pdf.
¶ E - Logo
Il est important que le logo Picto Access figure à côté des dominos d'accessibilité :
Vous trouverez le logo Picto Access ici : 
¶ F - Lien cliquable
Nous vous recommandons d'insérer un lien cliquable au niveau de notre logo afin de maximiser l'engagement de vos utilisateurs, en les incitant à cliquer.
Ce lien redirige vos usagers vers la page Picto Access de l'établissement qu'ils consultent. Les pages Picto Access renseignent l'accessibilité des lieux de manière plus précise que le font les pictogrammes.
Ce lien cliquable peut prendre la forme d'un "En savoir plus" comme sur l'exemple ci-dessous :
<iframe
id="pictoAccess"
src="https://widget.pictoaccess.fr/accessibility?uid=0b1970b8-39eb-45da-bb75-bc2726539212&"
style="background: #FFFFFF; border: none;"
/>
¶ G - Où faire figurer les données d'accessibilité ?
Le but est d'intégrer les données d'accessiblité sur toutes les pages que vos usagers peuvent consulter, lorsqu'ils organisent leurs déplacements :
¶ 1 - Store Locator
L'intérêt principal de l'API réside dans la possibilité d'intégrer les données d'accessibilité dans votre store locator.
Grâce à l'API, vous pouvez par exemple mettre en place des vues filtrées selon le niveau d'accessibilité ou selon un type de fragilités, comme le fait le Crédit Agricole :
¶ 2 - Pages Etablissements / Agence
Nous vous incitons à intégrer chaque frise d'accessibilité sur les pages "Etablissement" de votre application. Elles seront mises en valeur au niveau des onglets "Informations pratiques", "Contacts" ou "Accès".
La Maïf renseigne par exemple son accessibilité sur ses pages "Agences" :
¶ 3 - Page "Accessibilité"
Vous pouvez recenser l'accessibilité des lieux diagnostiqués en créant une page "Accessibilité" sur votre application.
Pour ce faire, vous pouvez vous inspirer de la page "Accessibilité" du site internet du festival culturel Lille 3000 :
Faites attention à ne pas intégrer votre frise sur votre page d’accueil ou sur le bandeau de votre site : nous ne pouvons pas bien mesurer le nombre de clics dessus lorsqu’elle figure sur une page d’accueil.
N'oubliez pas d'accompagner votre frise d'un titre "Accessibilité". Vous pouvez complèter ce titre d'un sous-titre : "Nos équipes mettent tout en œuvre pour garantir l’accessibilité de l’établissement, ce que PictoAccess certifie."
¶ 6 - Dépannage
Nous souhaitons attirer votre attention sur les headers "Accept" qui ne sont pas pas identiques pour toutes les requêtes.
Les requêtes relatives à l'authentification sont dans le namespace "users" tandis que les autres requêtes sont dans le namespace "developer" ou "public".
Les login / mot de passe servent à obtenir un token d'authentification. Celui-ci est nécessaire pour plusieurs requêtes et doit être inclus dans le header X-Auth-Token.
Si vous obtenez une erreur de ce type :
curl: (1) Protocol "https" not supported or disabled in libcurl curl: (6) Could not resolve host: -H curl: (3) Port number ended with ' ‘curl: (6) Could not resolve host: -H curl: (3) Port number ended with '
Il est possible que des espaces / caractères invisibles se soient copiés sur votre terminal. Nous vous conseillons alors de copier la requête dans un IDE et de retirer les " \ ", les espaces et les passages à la ligne en trop.
Si vous désirez des informations supplémentaires, veuillez contacter votre référent par mail : [email protected]
¶ 7 - Informations supplémentaires et contact
-
Il est nécessaire d'avoir un lien Picto Access qui renvoie sur la page de l'établissement associée non loin des données d'accessibilité. Pour obtenir ce lien vous devez utiliser cet endpoint. (generate_link_via_uuid)
-
L'API est versionnée, garantissant une stabilité sur les endpoints. Toutefois la structuration des données reçues peut être sujette à modifications au cours du temps, car elle est fortement liée à nos modèles de données. Si une modification de ce type survient, nous vous informerons des changements afin d'en prendre compte.
-
Si vous désirez une modification ou de nouveaux endpoints, contactez votre référent pour en discuter.
Si vous désirez des informations supplémentaires, veuillez contacter votre référent par mail : [email protected]