Concepts

Mon A.E. vous propose une API XML de type REST, qui vous permet de manipuler les données de votre compte afin d’intégrer dans votre propre application un module de facturation pour votre entreprise.

Certaines parties de l’API peuvent être consultées à partir d’un navigateur (toutes les requêtes de type GET). En particulier, Firefox vous permet de voir correctement et facilement les réponses générées au format XML. La plupart des urls disponibles dans Mon A.E. sont visibles au format XML en ajoutant simplement l’extension .xml à la fin de l’url.
Par exemple, /account/customers/4 devient /account/customers/4.xml si vous souhaitez consulter la version XML d’une fiche client.

Chaque requête API doit être authentifiée à l’aide des informations ci-dessous, via le protocole HTTP Basic Authentication".

Vous devez vous connecter au service pour obtenir vos codes d’accès à l’API.

Vous pouvez utiliser un utilitaire tel que curl pour tester l’accès à l’API.
Exemple:

curl -u login:password \
http://www.monae.fr/account/customers.xml

Afin de vous permettre de tester votre application, nous vous conseillons de créer un compte gratuit séparé de votre compte principal, et de ne pas passer ce compte en production. Vous disposerez alors d’un compte au sein duquel vous pourrez faire vos tests librement, sans que cela n’impacte vos données de production.

L’API propose généralement deux types d’accès en lecture aux données: liste et détail. Les accès de type “détail” retourne un enregistrement unique, alors que les accès de type “liste” retournent un ensemble d’enregistrements.

Toutes ces requêtes sont faites avec la méthode GET, ce qui permet d’explorer facilement ces fonctionnalités à l’aide d’un navigateur comme expliqué plus haut.

Lorsque une requête de lecture réussi, vous obtenez une réponse XML accompagné du code HTTP “200 OK”

La création, la modification et la suppression de données est facile a implémenter, mais ne peut pas être réalisée directement depuis un navigateur. Quelque soit le language de développement que vous utilisez, un utilitaire tel que “curl” vous permet de faire facilement des essais et explorer l’API.

Lorsque vous créez ou modifier des données, vous transmettez du code XML, et vous devez le faire savoir au système en ajoutant à vos requêtes le header “Content-type: application/xml”. Il vous suffit alors d’inclure votre code XML dans votre requête pour que l’API effectue l’opération demandée.

Voici quelques exemples de création à l’aide de curl d’abord en transmettant le code XML directement sur la ligne de commande, ensuite en transmettant le code XML à partir d’un fichier:

curl -u login:password \
-H 'Content-Type: application/xml' \
-d '<customer><company>TOTO</company></customer>' \
http://www.monae.fr/account/customers.xml

curl -u login:password \
-H 'Content-Type: application/xml' -d @client.xml \
http://www.monae.fr/account/customers.xml

Si la création réussi, le code HTTP de retour est “201 Created” et le header contient une entrée “Location” indiquant l’url d’accès au nouvel élement créé. De plus, le résultat contient le detail XML de la ressource créée.

Sur un principe similaire, la mise à jour des enregistrements se fait à l’aide d’une requête de type PUT. Par exemple:

curl -u login:password -X PUT \
-H 'Content-Type: application/xml' \
-d '<customer><company>TOTO S.A.S</company></customer>' \
http://www.monae.fr/account/customers/1.xml

ou bien

curl -u login:password -X PUT \
-H 'Content-Type: application/xml' -d @client.xml \
http://www.monae.fr/account/customers/1.xml

Lorsque la mise à jour réussie, vous obtenez en retour le code HTTP “200 OK”

Enfin, pour supprimer un enregistrement (si cette fonction est disponible), vous devez utiliser une requête de type DELETE. Par exemple:

curl -u login:password -X DELETE \
http://www.monae.fr/account/customers/1.xml

Les requêtes de suppression ne nécessitent pas de “Content-Type” puisqu’elles en contiennent pas de XML. Si la suppression réussie, vous obtenez le code HTTP “200 OK”

Si une requête échoue, vous obtiendrez des codes d’erreurs HTTP spécifiques, accompagné d’un message d’erreur.
Par exemple, pour un enregistrement non trouvé, la réponse peut ressembler à:

HTTP/1.1 404 The record could not be found
Date: 2010-03-14 23:39:47 +0100
...

A noter que lorsque une requête est à l’origine d’une création d’enregistrement (création d’un client, d’un produit, etc), vous obtenez un code HTTP “201 Created” en cas de succès. Les autres opérations utilisent généralement le code “200 OK” pour indiquer que l’opération a réussie.

Si vous obtenez une erreur 501 lorsque vous créez ou modifiez un enregistrement, vérifiez que vous avez bien transmis votre demande avec le bon “Content-Type” (cf. plus haut)