Testez gratuitement notre nouvel outil d’optimisation de tournée ! 👉 Découvrir et tester
Bienvenue dans l’API de Moovago !
L’API Moovago vous permet de créer/lire/modifier/supprimer vos différentes données stockées dans Moovago, de façon programmatique (= échange de données avec votre ERP, vos serveurs…).
Ce guide vous présente comment configurer et utiliser notre API.
Il est utile de bien comprendre la dénomination de quelques éléments liés à l’application Moovago.
Nos points de terminaison (API Endpoint) nécessitent une authentification par clé API.
Si vous n’avez pas encore de clé API Moovago, merci de nous contacter à support@moovago.com.
Pour vous authentifier, il suffit d’ajouter votre clé API dans l’en-tête de vos requêtes.
(Consultez les indications fournies dans le mail que vous avez reçu comprenant votre clé API)
L’API Moovago fonctionne avec GraphQL.
Voici à quoi peut ressembler une requête GraphQL QUERY :
{ "query": "{ team { id name members { id alias } } }" }
ou (vous pouvez aussi spécifier un nom de requête personnalisé si vous préférez):
{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }
Parfois, vous pouvez fournir des paramètres d’entrée (= variables) pour filtrer les résultats (ici, un teamId par exemple):
Attention, vous devez échapper les guillemets des valeurs des variables !
{ "query": "{ companyList(filter: { teamId: \"XYZ\" }) { id name ownerIds } }" }
ou (vous pouvez aussi utiliser le champs variables dans une requête nommée si vous préférez):
Cela ne requiert pas d’échapper les guillemets => « doit être écrit \ »
{ "query": "query MyCompanyListQuery($filter: FilterManyCompanyInput!) { companyList(filter: $filter) { id name ownerIds } }", "variables": { "filter": { "teamId": "XYZ" } } }
Voici à quoi peut ressembler une requête GraphQL MUTATION :
{ "query": "mutation { company { create( input: { ownerIds: [\"XYZ\"], name: \"Moovago\", city: \"Niort\", address: \"46 Rue du 14 Juillet\", postalCode: \"79000\", phone: \"07 68 45 46 74\", email: \"support@moovago.com\", note: \"L application du commercial\" } ) { recordId } } }" }
ou (vous pouvez aussi utiliser le champs variables dans une requête nommée si vous préférez):
{ "query": "mutation MyCompanyCreate($input: CompanyCreateInput!) { company { create(input: $input) { recordId } } }", "variables": { "input": { "ownerIds": ["XYZ"], "name": "Moovago", "city": "Niort", "address": "46 Rue du 14 Juillet", "postalCode": "79000", "phone": "07 68 45 46 74", "email": "support@moovago.com", "note": "L application du commercial" } } }
Avant de continuer, vous pouvez consulter la documentation de graphql.org pour en apprendre d’avantage.
Nous vous recommandons d’utiliser un client GraphQL pour vous aider à écrire, envoyer et tester vos requêtes GraphQL comme : Altair GraphQL Client
L’introspection est désactivée sur notre serveur. Vous ne pouvez donc pas récupérer le schéma GraphQL directement depuis notre serveur.
Cependant, vous pouvez télécharger le fichier du schéma GraphQL de l’API Moovago ici : moovago_api_graphql_schema.gql
et l’importer dans le client Altair (Dans la fenêtre en haut à droite d’Altair, cliquez sur: Docs -> … -> Load Schema…)
Ci-dessous se trouvent également quelques exemples de requêtes QUERY et MUTATION avec l’outil en ligne de commande curl (remplacez <your-api-key> par la valeur de votre clé API).
Il faut également ajouter l’entête suivant à vos requêtes :
Content-Type: application/json
QUERY :
Récupérez votre équipe ainsi que les membres de l’équipe :
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }'
Récupérez la liste de vos mandants (remplacez ‘<your-teamId>’) :
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "query MyMandatorList($filter: FilterManyMandatorInput!) { mandatorList(filter: $filter) { id name } }", "variables": { "filter": { "teamId": "<your-teamId>" } } }'
MUTATION :
Création d’une nouvelle société (remplacez ‘<ownerId-value>’) :
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "mutation MyCompanyCreate($input: CompanyCreateInput!) { company { create(input: $input) { recordId } } }", "variables": { "input": { "ownerIds": ["<ownerId-value>"], "name": "Moovago", "city": "Niort", "address": "46 Rue du 14 Juillet", "postalCode": "79000", "phone": "07 68 45 46 74", "email": "support@moovago.com", "note": "L application du commercial" } } }'
Modifier un société existante (remplacez ‘<companyId-value>’) :
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "mutation MyCompanyUpdate($input: CompanyUpdateInput!) { company { update(input: $input) { recordId } } }", "variables": { "input": { "id": "<companyId-value>", "input": { "note": "Here is my new note"} } } }'
Consultez notre documentation référence API GraphQL pour retrouver la liste de toutes les requêtes possibles, ainsi que tout le détail de notre API.
Les API GraphQL peuvent renvoyer en parallèle des données correctes et des erreurs. C’est pour cette raison que l’API Moovago retournera des codes HTTP 200 même s’il y a des erreurs.
Les erreurs seront contenues dans un tableau errors s’il y en a. Vous trouverez une description de l’erreur dans le champ « message ».
C’est à vous de détecter et gérer ces erreurs. Par exemple en interceptant toutes les réponses de notre API et en vérifiant le tableau errors.
Voici à quoi peut ressembler une réponse GraphQL contenant une erreur :
{
"data": null,
"errors": [
{
"message": "You are not authorized to access this data",
"locations": [],
"errorType": "DataFetchingException",
"path": [
"companyList"
],
"extensions": null
}
]
}
Il est aussi possible que le serveur Moovago renvoie des codes HTTP
conventionnels pour indiquer le succès ou l’échec d’une requête.
De manière générale, les codes 2xx indiquent un succès (sauf si le tableau errors n’est pas vide).
Les codes 4xx indiquent qu’une erreur s’est produite par les données qui ont été fournies.
Les codes 5xx indiquent une erreur qui provient des serveurs Moovago.
200
Ok
Tout à fonctionné comme prévu.
429
Too Many Requests
Trop de requêtes ont atteint l’API trop rapidement. ( 5 requêtes max / seconde).
5xx
Server Errors
Quelque chose a dysfonctionné sur le serveur Moovago.
Lors de vos premiers tests, nous vous suggérons d’importer une par une quelques unes de vos données pour tester et vous assurer à chaque fois que les données ont bien été importées avec les valeurs exactes, et dans les bons champs. Et ensuite seulement d’importer en masse l’ensemble de vos données, tout en privilégiant une cadence raisonnable (idéalement 1 requête max / seconde).
La limite serveur est actuellement fixée à 5 requêtes max / seconde.
Si cette limite est dépassée, le serveur répondra avec un code statut 429 Too Many Requests
Sur le serveur de Production, merci de programmer vos traitements de masse pour qu’ils s’effectuent en dehors de la plage horaire :
lundi à vendredi de 8h à 18h30
L’API Moovago évolue régulièrement afin de proposer de nouvelles fonctionnalités, la plupart du temps sans incidence sur votre connecteur. Il arrive cependant que certaines évolutions nous obligent à rendre caduque des éléments de l’API. Ces éléments sont alors indiquées dans notre documentation de référence comme dépréciées (deprecated) quelques mois, de sorte que vous ayez le temps de mettre à jour votre connecteur. Les éléments dépréciés sont ensuite supprimés complètement.
Il est de votre responsabilité de faire évoluer et maintenir à jour votre connecteur. Vous ne devez plus utiliser d’éléments dépréciés avant leur suppression sans quoi votre connecteur ne fonctionnera plus.
Mentions légales, CGU et politique de confidentialité du site | CGU Politique de confidentialité du service – ©2024 Moovago
