API - Cas d'usages

Retrouvez ici quelques astuces et cas d'utilisation de l'API Lengow pour vous aider à construire vos requêtes et actions avec notre API.

Afin d'illustrer ces cas d'utilisation nous avons choisi de faire appel à un marchand test.

Appelons notre marchand de test "Julia" et disons que son numéro de compte est "1".
Veuillez noter qu'elle utilise Postman pour passer tous ses appels API.
Les résultats ou exemple de requête seront affichés au format JSON si cela est possible,
Ce sont de purs exemples ils doivent être adaptés à votre compte utilisateur.

Plus d'informations sur Postman et comment créer une collection (groupe de requêtes enregistrées) ici.

Se connecter à l'API Lengow : Get Access Token

La première étape avant d'effectuer un appel ou toute action au sein de l'API Lengow consiste à entrer dans l'API.

Pour ce faire, Julia (notre marchand test) va récupérer ses informations d'identification Lengow depuis son profil sur la plateforme qui sont :

- Lengow account ID

- secret token

- token

Puis elle va ouvrir Postman.

Ensuite, une fois qu'elle a défini un nouvel environnement dans Postman avec ses informations d'identification, elle peut continuer et envoyer le premier appel (POST) pour récupérer un token d'accès à l'API.

Cet appel se construit comme ici :

POST /access/get_token

L'API renvoie le jeton d'accès (token) tel que celui-ci :

{
    "token": "69946b78-edae-49b8-8874-6fb025e09a58",
    "account_id": 1
}

Elle ajoute ce token à son environnement dans Postman sous la variable LENGOW_AUTH (voir image).

Conseil Lengow : avec l'aide de vos développeurs, vous pouvez configurer un script qui effectue cet appel automatiquement toutes les heures.

Remarque : le "token" envoyé par l'API Lengow est valide 3600 secondes et peut être utilisé comme Lengow_AUTH dans Postman.

Vérifier ses actions effectuées sur une commande

Julia a corrigé une de ses actions d'expédition "ship" sur une commande. Elle souhaite vérifier que sa correction est correcte et que l'action qu'elle a envoyée a été correctement traitée par l'API Lengow.

GET /orders/actions/

Depuis l'API Lengow, elle interroge cette commande à l'aide du paramètre "& marketplace_order_id" et utilise l'ID de sa commande (voir ci-dessous).

-- endpoint /orders/actions --

-- GET method --

GET /orders/actions/?account_id=1&marketplace_order_id=12-05319-12345

-- API response --

{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": 13244460,
"marketplace_order_id": "12-05319-123452",
"account_id": 1,
"marketplace": "ebay_fr",
"action_type": "ship",
"processed": true,
"queued": false,
"tracking_number": "2L01286914523",
"tracking_url": null,
"carrier": "FR_ColiposteColissimoRecommended",
"custom_carrier": null,
"line": "193393034918-1749999860009",
"declared_value": null,
"currency_code": null,
"invoice_number": null,
"shipping_method": null,
"shipping_date": null,
"shipping_service_id": null,
"shipping_service_offer_id": null,
"created_at": "2020-07-02T08:03:37.912433Z",
"updated_at": "2020-07-02T08:03:39.262053Z",
"weight": null,
"weight_unit": null,
"comment": null,
"delay": null,
"reason": null,
"charges": null,
"errors": null,
"delivery_date": null,
"delivery_experience": null,
"return_tracking_number": null,
"refund_price": null,
"refund_shipping_price": null,
"refund_mode": null,
"refund_reason": null,
"refund_quantity": null,
"refund_shipping": null,
"refund_shipping_taxes": null,
"refund_taxes": null,
"carrier_name": null,
"carrier_pickup": null,
"package_dimension_length": null,
"package_dimension_width": null,
"package_dimension_height": null,
"package_dimension_unit": null,
"from_address_name": null,
"from_address_line": null,
"from_address_city": null,
"from_address_state_province": null,
"from_address_postal_code": null,
"from_address_country_code": null,
"from_address_mail": null,
"from_address_phone": null,
"pickup_id": null,
"refund_id": null,
"return_carrier": null
},
{
"id": 13244455,
"marketplace_order_id": "12-05319-123452",
"account_id": 1,
"marketplace": "ebay_fr",
"action_type": "ship",
"processed": false,
"queued": false,
"tracking_number": null,
"tracking_url": null,
"carrier": "FR_ColiposteColissimoRecommended",
"custom_carrier": null,
"line": "193393034918-1749999860009",
"declared_value": null,
"currency_code": null,
"invoice_number": null,
"shipping_method": null,
"shipping_date": null,
"shipping_service_id": null,
"shipping_service_offer_id": null,
"created_at": "2020-07-02T08:02:50.609088Z",
"updated_at": "2020-07-02T08:02:50.681358Z",
"weight": null,
"weight_unit": null,
"comment": null,
"delay": null,
"reason": null,
"charges": null,
"errors": "Tracking needs number AND carrier for ship order action",
"delivery_date": null,
"delivery_experience": null,
"return_tracking_number": null,
"refund_price": null,
"refund_shipping_price": null,
"refund_mode": null,
"refund_reason": null,
"refund_quantity": null,
"refund_shipping": null,
"refund_shipping_taxes": null,
"refund_taxes": null,
"carrier_name": null,
"carrier_pickup": null,
"package_dimension_length": null,
"package_dimension_width": null,
"package_dimension_height": null,
"package_dimension_unit": null,
"from_address_name": null,
"from_address_line": null,
"from_address_city": null,
"from_address_state_province": null,
"from_address_postal_code": null,
"from_address_country_code": null,
"from_address_mail": null,
"from_address_phone": null,
"pickup_id": null,
"refund_id": null,
"return_carrier": null
}
]
}

Réponse de l'API

La réponse de l'API indique que 2 actions ont été effectuées sur cette commande:

"count": 2

Dans les résultats, on peut voir que l'ID de commande apparaît deux fois. Cela signifie que le serveur affiche la même commandes deux fois car deux actions ont été effectuées.
La dernière action est affichée en haut de la réponse.

En bas de la réponse API (la première action de Julia), examinez les paramètres suivants:

"action_type"
"processed"
"queued"
"error"

1 / La première action "ship" (expédition), envoyée plus tôt par Julia (celle tout en bas de la réponse API), n'est pas valide car on voit dans la réponse de l'API:

"processed": false
"error": "Tracking needs number AND carrier for ship order action"

Ici, l'API eBay indique à l'API de Lengow, que cette action "ship" de Julia est incomplète car un ou plusieurs paramètres manquent.

Vous pouvez voir que le paramètre "tracking_number" est vide ("null") dans la première action "ship".

2/ La deuxième action "ship" que Julia a renvoyé est valide et a bien été envoyée à l'API eBay car on peut voir :

"processed": true
"queued": false
"error": null

Plus d'informations sur les paramètres "processed" et "queued" ici.

Trouver les informations de livraison sur une commande

Julia, notre marchand test, a reçu une nouvelle commande pour le canal La Redoute. Elle souhaite trouver les informations de livraison pour pouvoir l'expédier.

C'est à dire, qu'elle cherche à savoir quelles sont les informations qu'elle doit compléter pour correctement envoyer sa commande.

Voici les étapes qu'elle suit dans l'API Lengow :

ETAPE 1

Une fois connectée à l'API, elle interroge sa commande (voir ci-dessous) en utilisant le endpoint orders comme ceci :

GET /orders/?account_id=1&marketplace_order_id=2020.111.123456789

{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"marketplace": "laredoute",
"account_id": 1,
"marketplace_country_iso2": "FR",
"marketplace_order_id": "2020.111.123456789",
"merchant_order_id": [
"1234567"
],
"marketplace_status": "ToShip",
"lengow_status": "waiting_shipment",
"workflow_rank": 5,
"marketplace_order_date": "2020-11-12T15:23:18Z",
"total_order": 74.8,
"total_tax": "0.00",
"shipping": 9.9,
"discount": 0.0,
"commission": null,
"processing_fee": null,
"currency": {
"iso_a3": "EUR",
"symbol": "€",
"name": "Euro"
},
"original_currency": {
"iso_a3": "EUR",
"symbol": "€",
"name": "Euro"
},
"original_total_order": 74.8,
"original_total_tax": "0.00",
"original_shipping": 9.9,
"original_discount": 0.0,
"original_commission": null,
"original_processing_fee": null,
"comments": null,
"invoice_number": null,
"invoice_url": null,
"payments": [],
"packages": [
{
"cart": [
{
"id": 8623271,
"marketplace_order_line_id": "2020.111.123456789-1",
"marketplace_product_id": "4001072020053",
"merchant_product_id": {
"field": "ID_PRODUCT",
"id": "111111"
},
"feed_id": 12345,
"marketplace_package_id": null,
"marketplace_status": "ToShip",
"lengow_status": "waiting_shipment",
"title": "Visionneuse diapositive automatique - Diascop 3",
"category": "Accueil > Accessoires > Visionneuses",
"url_product": null,
"url_image": null,
"order_line_meta": {
"DeliveryMode": "Home",
"DeliveryType": "Regular"
},
"amount": "64.90",
"tax": "0.00",
"discount": null,
"shipping": null,
"original_amount": "64.90",
"original_tax": "0.00",
"original_discount": null,
"original_shipping": null,
"quantity": 1,
"documents": [],
"created_at": null,
"updated_at": null,
"orderline_types": []
}
],
"delivery": {
"id": 151186892,
"type": "delivery",
"first_line": "500 AVENUE TEST",
"zipcode": "69300",
"city": "CALUIRE ET CUIRE",
"vat_number": null,
"company": null,
"civility": "Monsieur",
"first_name": null,
"last_name": null,
"second_line": "",
"complement": "ETAGE 3E",
"phone_home": null,
"phone_office": null,
"phone_mobile": "06700000000",
"full_address": null,
"full_name": "TEST BOB DUPONT",
"email": "*****.fr",
"metas": null,
"state_region": null,
"common_country_iso_a2": "FR",
"trackings": [
{
"number": null,
"method": "Home / Regular",
"carrier": null,
"url": null,
"is_delivered_by_marketplace": null,
"parcel_weight": null,
"shipped_at": null,
"pickup_store": {
"id": null
},
"relay": {
"id": null,
"name": null
},
"marketplace_order_line_ids": [
"2020.111.123456789-1"
]
}
]
}
}
],
"billing_address": {
"id": 151198390,
"type": "billing",
"first_line": "500 AVENUE TEST",
"zipcode": "69300",
"city": "CALUIRE ET CUIRE",
"vat_number": null,
"company": null,
"civility": "Monsieur",
"first_name": null,
"last_name": null,
"second_line": "",
"complement": "ETAGE 3E",
"phone_home": null,
"phone_office": null,
"phone_mobile": "06700000000",
"full_address": null,
"full_name": "TEST BOB DUPONT",
"email": "*****.fr",
"metas": null,
"state_region": null,
"common_country_iso_a2": "FR"
},
"contact_address": null,
"documents": [],
"imported_at": "2020-11-12T16:09:07.256186Z",
"updated_at": "2020-11-12T16:32:15.849000Z",
"order_meta": {
"checksum": "b4aa946ef504ed758359db880c03bd62"
},
"anonymized": false,
"order_types": []
}
]
}

La commande est bien au statut "waiting_shipment".

Depuis le paramètre "delivery" > "trackings" de la réponse API, Julia prend connaissance de la méthode de livraison choisie par le client (ici envoi à domicile) :

"method": "Home / Regular"

Depuis ce paramètre "tracking" on trouve d'autres informations qui peuvent être complétées en fonction de la méthode de livraison choisie par le client :

"is_delivered_by_marketplace": null,
"pickup_store": { "id": null },

"relay": { "id": null, "name": null

Note : Si la méthode "Relais / Regular" avait été choisie, la balise "relay" de la commande aurait été complétée avec un Identifiant et un nom de point relais.

ETAPE 2

Julia interroge ensuite les informations globales de la marketplace afin de savoir quels sont les éléments obligatoires à renseigner pour correctement expédier sa commande.

Depuis l'API, elle utilise cette fois le endpoint /marketplace et le paramètre ?marketplace=laredoute

GET /marketplaces/?marketplace=laredoute

Dans la réponse que lui retourne l'API Lengow, elle trouve les informations de

statuts des commandes
action autorisées sur les commandes et les paramètres obligatoires à renseigner pour effectuer l'action
transporteurs autorisés par la marketplace dans la balise "carriers"

Ici, pour La Redoute, on trouve l'information :

 "actions": {
                "ship": {
                    "args": [
                        "carrier",
                        "tracking_number"
                    ],

Puis elle consulte l'élément "carrier" pour savoir comment renseigner cette valeur et savoir si une liste est donnée par la marketplace :

"carrier": {
                            "type": "string",
                            "valid_values": {},
                            "default_value": "",
                            "accept_free_values": true

Cela signifie que pour valider l'expédition de sa commande La Redoute (envoi à domicile), Julia doit fournir

les informations de "carrier" (transporteur)
un "tracking_number" (numéro de tracking colis).

Comme il n'y a pas de liste de transporteurs imposés, elle peut utiliser le transporteur de son choix.

Récupération de documents

Julia, notre marchand test, a reçu une nouvelle commande pour le canal Zalando. Elle veut télécharger les documents qu'elle doit joindre au colis : facture, bon de livraison et bon de retour.

Note : Ces documents sont édités par Lengow et peuvent aussi être téléchargés sur la plateforme Lengow, comme expliqué dans notre guide Zalando.

ETAPE 1

Une fois connectée à l'API Lengow, elle interroge sa commande en utilisant le endpoint /orders comme ceci :

GET /orders/?account_id=1&marketplace_order_id=10987654321

Dans la réponse que lui retourne l'API Lengow, elle trouve la section "documents", où sont donnés les IDs de ces documents :

"documents": [
{
"id": 2111112,
"marketplace_doc_id": "DELIVERY_NOTE_123fc456-f789-101b-b12g-a134c1235678",
"url": "http://api.lengow.io/v3.0/document/2111112",
"created_at": "2022-05-14T06:26:19.479581Z",
"doc_type": {
"lengow_type": "DELIVERY",
"marketplace_code": "DELIVERY_NOTE",
"marketplace_label": "Zalando delivery notes"
}
},
{
"id": 2111111,
"marketplace_doc_id": "RETURN_123fc456-f789-101b-b12g-a134c1235678",
"url": "http://api.lengow.io/v3.0/document/2111111",
"created_at": "2022-05-14T06:26:19.478343Z",
"doc_type": {
"lengow_type": "RETURN",
"marketplace_code": "RETURN",
"marketplace_label": "Zalando return form"
}
},
{
"id": 2111110,
"marketplace_doc_id": "BILL_123fc456-f789-101b-b12g-a134c1235678",
"url": "http://api.lengow.io/v3.0/document/2111110",
"created_at": "2022-05-14T06:26:19.475280Z",
"doc_type": {
"lengow_type": "BILL",
"marketplace_code": "BILL",
"marketplace_label": "Zalando invoice"
}
}
]

ETAPE 2

A partir des IDs trouvés (2111110, 2111111 et 2111112 dans cet exemple), Julia télécharge les documents correspondants en utilisant le endpoint /document (un appel par document):

GET /document/2111110?account_id=1

Résultat visible dans Postman:

Lengow

Mise à jour 1 juillet 2024 10:03

Se connecter à l'API Lengow : Get Access Token

Vérifier ses actions effectuées sur une commande

Trouver les informations de livraison sur une commande

Récupération de documents

Articles dans cette section