Testez gratuitement notre nouvel outil d’optimisation de tournée ! 👉 Découvrir et tester
Bienvenue dans le Guide de démarrage de 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.
Les éléments actuellement proposés par l’API sont ceux demandés par nos clients. Si vous avez d’autres besoins ou avez des questions/remarques, n’hésitez pas à nous en faire part à support@moovago.com
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 sont contenues par défaut dans un tableau errors. Vous trouverez une description de chaque 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
}
]
}
Erreurs retournées par les mutations
Par défaut, les erreurs retournées par les mutations le sont comme décrit dans la section précédente.
Mais les mutations peuvent aussi retourner les erreurs utilisateurs et de logique métier, directement dans les sous-données de « data ». Cela vous permet de séparer ces erreurs spécifiques propres à chaque mutation des erreurs de niveau global vues précédemment (utilisées alors uniquement pour les erreurs d’analyse et d’autres erreurs côté serveur plus générales).
Toutes ces erreurs propres aux mutations sont nommées avec le suffixe « Problem » (équivalent d’un code erreur). Chaque mutation peut retourner une ou plusieurs erreurs. Et chaque mutation décrit les types d’erreurs qu’elle peut retourner. Vous pouvez ensuite l’utiliser côté client si besoin pour facilement identifier les erreurs. Certains types d’erreurs peuvent également être accompagnés de métadonnées supplémentaires sur l’erreur.
Exemple
La récupération des erreurs propres aux mutations se fait en demandant le champs « message » pour récupérer les messages d’erreurs textuels et le champ « __typename » contenant le code d’erreur (de type Problem).
On ajoutera donc le code suivant dans les requêtes pour récupérer les valeurs de ces 2 champs (pour chacune des erreurs retournées) :
errors {
__typename
... on Problem {
message
}
}
Ce qui donne par exemple pour la mutation company create :
{ "query": "mutation { company { create( input: { ownerIds: [\"Space caracter is not allow here\"], 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 errors { __typename ... on Problem { message } } } } }" }
et la réponse contenant une erreur de type MalformedParameterProblem avec un message textuel décrivant l'erreur de façon plus détaillée :
{
"data": {
"company": {
"create": {
"recordId": null,
"errors": [
{
"__typename": "MalformedParameterProblem",
"message": "An input parameter is empty, or contains an illegal character."
}
]
}
}
},
"errors": null
}
Codes de réponse HTTP
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).
Les limites serveur concernant l’API sont actuellement fixées à :
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
