Bien commencer avec l'API

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

Terminologie

Il est utile de bien comprendre la dénomination de quelques éléments liés à l’application Moovago.

Company : « Société » qui peut être un client, un prospect ou un suspect.
Elle peut contenir un ou plusieurs interlocuteurs (CompanyContact).
Il peut exister des Etiquettes appelées Mandant (Mandator) selon le type d’équipe concernée. Une société peut alors avoir 0 à plusieurs étiquettes Mandant.
CompanyContact : « Interlocuteur », personne physique au sein d’une société (Company) avec laquelle on est en relation.

Mandator : « Mandant », organisation (fournisseur ou marque) qui confie une mission de représentation ou de vente de ses produits ou services.
Elle peut être rattachée à plusieurs sociétés (Company).
Segmentation : Une segmentation permet de classer les sociétés (Company) selon des critères définis par l’équipe (ex: catégories, activités, …). Il existe une segmentation (et donc une liste de plusieurs critères) par équipe. Un critère est l’équivalent d’une question à choix unique.
Généralement, une société (Company) n’appartient qu’à une seule équipe et est donc caractérisée par une seule segmentation. Mais il existe des configurations (si la société a aussi des mandants de type Equipe (Team)) qui font que la société peut être caractérisée par plusieurs segmentations.
Team : « Equipe », groupe d’un ou plusieurs utilisateurs qui utilisent l’application et qui appartienne à une même entité.
Turnover : « Chiffre d’affaires », facture gagnée, perdu ou commande enregistrée à une date donnée.
ID : Un identifiant qui référence les différents éléments dans notre système.

Authentification

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)

GraphQL

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

Référence API GraphQL

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.

Erreurs

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

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.

Usages, limites et quotas

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 à :

1 seule requête à la fois
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

Mises à jour de l'API

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.