API - Les bonnes pratiques de l'API Commandes

Si vous récupérez vos commandes en utilisant l'API Commandes de Lengow, assurez-vous de suivre nos conseils pour une utilisation optimale :

Token d'authentification

Le token de session retourné par "access/get_token" est valable pendant une heure. Vous ne devez pas demander un token avant chaque requête : vous pourriez atteindre les "rate-limit" et être bloqué dans vos requêtes.

Pour savoir combien de temps il reste pour un token, vous pouvez utiliser l'API /me, qui fournit le temps d'expiration du token actuel.

Pour connaître le temps de validité restant sur un token, vous pouvez utiliser l'API /me qui indique l'heure d'expiration du token en cours.

Exemple :

curl --request GET \
 --url 'https://api.lengow.io/me' \
 --header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

{
"token": "69946b78-edae-49b8-8874-6fb025e09a58",
"expire_at": "2022-12-21T13:56:08+00:00",
"account_id": 1,
"scopes": {
"feed_id": "*",
"account_id": 1,
"catalog_id": "*",
"product_id": "*"
}
}

Récupération des commandes

L’API de liste des commandes dispose de filtres permettant plusieurs approches qui sont complémentaires.

Découverte de nouvelles commandes

Le paramètre de filtre "merchant_order_id=None" renverra uniquement les commandes pour lesquelles le "merchant_order_id" est vide.
On peut également limiter la période de recherche pour accélérer la requête (par exemple, sur les trois dernières heures).

Exemple :

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/?account_id=1&merchant_order_id=None&marketplace_order_date_from=2022-12-21T12%3A22%2B01%3A00' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

Chaque commande peut alors être marquée comme "vue" avec un identifiant propre au marchand en utilisant l'API moi (= merchant order id - Consultez notre documentation API). Ainsi, les commandes marquées seront absentes de la prochaine requête.

Recherche de mises à jour

Les commandes disposent d'un champ "updated_at" qui est mis à jour dès qu'une information sur la commande est modifiée.
Cette date peut être utilisée pour récupérer les commandes mises à jour, en filtrant grâce à "updated_from" et "updated_to".

Exemple :

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/?account_id=1&updated_from=2022-12-21T14%3A22%2B01%3A00&updated_to=2022-12-21T15%3A22%2B01%3A00' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

Pagination

La liste des commandes est paginée par 100 maximum.

Si une page supplémentaire est disponible, la clé "next" dans le contenu JSON contient l'URL de la page suivante.
Sinon, la clé "next" est null, ce qui signifie que la page en cours est la dernière.

Par conséquent, assurez-vous d'interroger la page suivante uniquement si "next" n'est pas null.

 Veuillez éviter de simplement itérer sur le numéro de page jusqu'à obtenir une page 404 (Not found), ce qui se produit lorsqu'on demande une page au-delà de celles existantes.
Encore plus, évitez d'itérer sur un nombre fini de pages, ce qui multiplie les requêtes inutiles menant à des erreurs 404.

Exemple de la clé "next" contenant l'URL de la page suivante :

{
"count": 4481,
"next": "https://api.lengow.io/v3.0/orders/?account_id=1&merchant_order_id=None&page=2",
"previous": null,
"results": [
    [...]

Actions sur les commandes

Le traitement des actions sur les commandes est asynchrone. L'envoi d'une mise à jour de statut crée une tâche qui est mise en file d'attente, puis traitée par un processus distinct.

La réponse à l'appel de l'API retourne l'identifiant de la tâche, qui peut ensuite être utilisé pour obtenir l'état et le résultat de la tâche.

Exemple d'une action qui a été traitée ("processed") :

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/actions/?account_id=1&id=81982959' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

 "results": [
{
"id": 81982959,
"marketplace_order_id": "221219V2102418423",
"account_id": 1,
"marketplace": "veepee_pink_fr",
"action_type": "ship",
"processed": true,
"queued": false,
"tracking_number": "8G48609462340",
"tracking_url": "https://www.laposte.fr/outils/suivre-vos-envois?code=8G48609462340",
"carrier": "La Poste",
[...]
"created_at": "2022-12-21T11:17:47.353491Z",
"updated_at": "2022-12-21T11:17:48.408401Z",
[...]
}
]

On peut suivre le statut de chaque action avec les champs "queued" et "processed":

• "queued" est "true" lorsque l'action est en attente de traitement (ou en réessai en cas d'échec), et "false" lorsqu'elle est traitée;
• "processed" est "true" lorsque l'action a été réussie.

Plutôt que de rechercher individuellement les actions passées, il est plus efficace de récupérer uniquement les actions qui nécessitent un traitement.

Dans l'exemple suivant, une recherche est effectuée sur les actions Veepee qui n'ont pas abouti :

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/actions/?account_id=1&marketplace=veepee_pink_fr&processed=False&queued=False' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

{
"count": 16778,
"next": "https://api.lengow.io/api/v3.0/orders/actions/?account_id=1&marketplace=veepee_pink_fr&page=2&processed=False&queued=False",
"previous": null,
"results": [
{
"id": 81428959,
"marketplace_order_id": "221211V1101346433",
"account_id": 223,
"marketplace": "veepee_pink_fr",
"action_type": "ship",
"processed": false,
"queued": false,
[...]
"errors": "Rate limit exceeded.",

Note : la réponse est paginée comme une liste de commandes, utilisez "next" pour suivre la page suivante.

API Marketplaces

Les données fournies par l'API Marketplaces changent très peu.

Il est donc superflu d'en faire la requête plus d'une fois par heure, voire moins.