Fonctionnement général

L’API easyReco est écrite en PHP. Les fonctionnalités d'easyReco utilisables via l'API easyReco sont publiées sous forme de web service via des API en architecture REST.

Vous pouvez y accéder via des requêtes HTTPS. À chaque fonctionnalité correspond une URL. L'API easyReco utilise les méthodes GET, POST, PUT et DELETE.

L' URL d'accès à l'API est :

https://www2.easyreco.com/api/[VERSION]/

où [VERSION] correspond au numéro de version de l'API utilisée.

 

À la suite de cette URL de base se positionne la fonctionnalité demandée. Par exemple, pour recevoir la liste des envois de votre compte easyReco, vous pouvez utiliser l'API "envois". L'URL à fournir sera alors :

GET https://www2.easyreco.com/api/2.2/envois

 

L'URL peut être ensuite complétée par des paramètres, au format query string. Par exemple, pour recevoir la liste des envois de votre compte easyReco, vous pouvez utiliser l'API "envois" avec un paramètre limit à 100 (on demande de ne renvoyer que 100 envois maximum) et un paramètre offset à 3 (on demande que l'index de début de pagination soit à 3) :

 GET https://www2.easyreco.com/api/2.2/envois?length=100&start=3

La liste des paramètres acceptés est défini dans la documentation détaillée de chaque API (voir Paramètres d'URL).

 

Pour les méthodes POST et UPDATE, des données supplémentaires peuvent être passées à la requête HTTP. Ces données doivent être structurées sous forme d'objets JSON.

Le détail de l'objet JSON attendu est défini dans la documentation détaillé de chaque API (voir Requête : Liste des propriétés)

Authentification

Pour utiliser l'API easyReco, vous devez avoir accès à un compte easyReco ainsi qu'à l'option d'accès à l'API (Pour d'obtenir l'accès à l'option API, prenez contact avec votre interlocuteur commercial easyReco afin de valider le périmètre de votre projet).
Lorsque cette option est activée, une clé API unique liée à votre compte vous sera transmise. Exemple de clé API :

Oono8eez7eez9NRZ3xaeFaeh8hee3u

Cette clé doit être envoyée à chaque requête envoyée à l'API easyReco, via une entête HTTP spécifique : API-Authorization
Si cette clé n'est pas fournie ou si la clé n'est pas correcte, une réponse HTTP 401 Unauthorized sera renvoyée.

Exemple de requête HTTP :

GET https://www2.easyreco.com/api/2.2/envois HTTP/1.1
API-Authorization: Oono8eez7eez9NRZ3xaeFaeh8hee3u

Codes Retour

Les codes retour standards HTTP sont utilisés, notamment :

  • 200 : OK. Une réponse normale est transmise.
  • 400 : Votre requête comporte une erreur ; vérifiez les paramètres obligatoires ainsi que le format des données. Un message d'erreur sera renvoyé avec le détail du problème. Corrigez votre requête et essayez à nouveau.
  • 404 : L'API demandé n'existe pas. Vérifiez l'URL.
  • 405 : La méthode n'est pas reconnue ; l'API easyReco n'utilise que les méthodes GET, POST, UPDATE, et DELETE.
  • 401 : Accès non autorisé ; l'authentification a échoué : la clé d'authentification n'a pas été envoyée ou n'est pas reconnue.
  • 500 : Erreur générale coté serveur. Un message d'erreur sera renvoyé avec le détail du problème.