en | fr

General

Resources

Autre

Webservice LCE : documentation de référence

Le Webservice LCE fournit une interface (API) pour obtenir des offres de transports de multiples transporteurs de manière homogène et passer commande des offres qui vous intéressent.

En intégrant ce webservice à votre plateforme, vous aurez accès à des tarifs compétitifs sans avoir à implémenter séparément les webservice de chaque transporteur individuellement. Vous économisez ainsi du temps et de l'argent.

Cette documentation est destinée à un public de techniciens dont l'objectif est de mettre en oeuvre le Webservice LCE sur leur système. Elle présente de manière exhaustive les spécifications de toutes les resources exposées par le webservice et la manière de les utiliser, avec des exemples de code dans plusieurs languages.

N'hésitez pas à nous contacter à l'adresse support@lce.io si vous avez la moindre question. Nous pouvons aussi fournir des services d'intégration si nécessaire.

Pour une intégration directe dans vos applications et pour servir d'exemples, nous fournissons également des librairies clientes pour PHP et Prestashop.

Client Ruby pour l'API de Low Cost Express Client PHP pour l'API de Low Cost Express Plugin Prestashop pour l'API de Low Cost Express

Comment utiliser les exemples de code ?

Cette colonne contient des exemples de code pour la plupart des fonctionnalités du Webservice LCE.

Les languages supportés sont listés en haut de la colonne, et vous pouvez changez le language actif à la volée, selon vos besoins.

Nous avons essayé de produire des exemples pouvant être facilement copiés/collés pour faciliter vos tests. Vous n'aurez en général qu'à remplacer vos identifiants de connexions. Si vous avez des suggestions d'amélioration pour les exemples de code, n'hésitez pas à nous envoyer un message à support@lce.io.

Premiers pas

Etapes

Avant d'entrer dans les détails techniques, voici un résumé des étapes d'un scénario classique d'utilisation du webservice. Chaque ligne faisant référence à une requête vers le webservice contient un lien vers la documentation correspondante ; les autres lignes correspondent à des étapes qui sont à effectuer de votre côté uniquement.

  1. Préparation des caractéristiques minimales de l'expédition (villes d'expédition et de livraison, dimensions des colis).
  2. Demander un devis (envoi des informations minimales de l'expédition).
  3. Sélection d'une offre
  4. Si nécessaire, récupération de la liste des relais de livraison disponibles.
  5. Commande de l'offre retenue (envoi de tous les détails supplémentaires de l'expédition: détails de l'expéditeur et du destinataire, informations supplémentaires sur la pack-list).
  6. Téléchargement des étiquettes
  7. Suivi des colis

Serveur de test

Lorsque votre compte est enregistré sur le webservice, un email vous sera adressé avec vos coordonnées de connexion pour le serveur de test. Vous devez utiliser le serveur de test uniquement pour la mise en place intégrale du service web. Lorsque votre implémentation est fonctionnelle, contactez nous pour obtenir vos coordonnées de connexion au serveur de production et commander à passer des commandes réelles.

  • TEST server base URL: https://test.myflyingbox.com/v2
  • PRODUCTION server base URL: https://api.myflyingbox.com/v2

Services REST

Le Webservice LCE utilise des ressources REST de manière standard dans toute l'API. Toutes les déclarations de requêtes ont donc un sens:

  • Les requêtes POST servent à créer de nouveaux objets.
  • Les requêtes GET servent à récupérer des objets existants.

Pour le moment nous n'utilisons pas les verbes HTTP PUT, PATCH et DELETE.

Routes disponibles

L'URL de base pour toutes les requêtes est : https://api.myflyingbox.com/v2

Toutes les URIs ci-dessous doivent être apposées à cette URL de base.

GET
/ Accès à des informations de base sur le Webservice LCE.
POST
/quotes Demande de devis. Retourne un ensemble d'offres.
GET
/quotes Récupération de la liste des devis passés.
GET
/quotes/:id Récupération d'un devis spécifique grâce à son ID.
GET
/offers/:id Récupération d'une offre spécifique (reçu au sein d'un devis), grâce à son ID.
GET
/offers/:id/available_delivery_locations Récupération de la liste des relais de livraison disponibles pour une offre donnée (valide uniquement pour les offres avec livraison en point relais).
POST
/orders Commander une offre (renvoie un objet 'commande').
GET
/orders/:id Récupération d'une commande existante.
GET
/orders/:id/labels Téléchargement des étiquettes pour une commande donnée (renvoie un PDF brut).
GET
/orders/:id/tracking Récupération du statut de suivi d'une commande donnée, pour chaque colis.

Authentification

Vous ne pouvez pas utiliser le Webservice LCE sans authentification.

L'authentification n'est pas persistante ; il vous faudra donc inclure les identifiants de connexion à chaque requête.
L'authentification fonctionne selon la méthode HTTP Basic Access Authentication .

Exemple de requête

curl https://api.myflyingbox.com/v2/ -u identifiant:mot_de_passe
require 'net/http' # Ou 'net/https' pour ruby < 2.0.0

uri = URI('https://api.myflyingbox.com/v2/quotes')

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  request = Net::HTTP::Get.new uri
  request.basic_auth 'identifiant', 'mot_de_passe'
  response = http.request request # Net::HTTPResponse object
end

Réponse avec une authentification erronée (Code HTTP 401)

{
  "status":"failure",
  "error":{
    "type":"access_denied",
    "message":"Unauthorized"
  },
  "self":"https://api.myflyingbox.com/v2"
}
<response>
  <status>failure</status>
  <error>
    <type>access_denied</type>
    <message>Unauthorized</message>
  </error>
  <self>api.myflyingbox.com/v2/v2</self>
</response>

Requêtes

Toutes les requêtes utilisent le protocole HTTP.

Le contenu des requêtes doit être encodé en UTF-8.

Le webservice supporte deux formats pour passer les paramètres de requêtes :

JSON
JSON est le format préféré.
Champs de formulaire
Ce format est similaire à ce qui est envoyé par un formulaire web traditionnel.

Quel que soit le format que vous décidez d'utiliser, assurez-vous de passer la bonne en-tête HTTP "content-type".

Vous pouvez consulter l'exemple de code pour les demandes de devis pour des modèles de requêtes curl utilisant chacun de ces deux formats.

Réponses

Format des réponses

Les réponses sont transmises au format JSON.

La plupart des languages de programmation proposent des bibliothèques JSON maintenues, que vous pouvez utiliser pour manipuler les réponses transmises par le webservice.

Tous les textes sont encodés en UTF-8. Si votre système n'utilise pas UTF-8, assurez-vous de convertir correctement les chaînes de caractères afin que toutes les interactions avec le webservice se fassent bien en UTF-8. Ce point est particulièrement important pour le bon rendu des adresses d'expédition/de livraison.

Attributs des réponses

Les réponses sont encapsulées dans une enveloppe de base décrite ci-dessous.

  • Toutes les réponses contiennent les attributs 'status' et 'self'.
  • Les réponses avec erreurs (status = failure) contiennent également un attribut 'error' qui apporte des détails sur la raison de l'erreur.
  • Les réponses pour des requêtes exécutées avec succès incluent un attribut 'data' qui contient les données en réponse à la requête. Si les données renvoyées à la racine constituent une collection d'objets (un tableau), un attribut 'count' est également transmis, contient le nombre total d'objets dans le tableau.
self
chaîne de caractères (URL) Retourne l'URL complète visée par la requête.
status
chaîne de caractères Valeurs possibles : failure, success Lors 'failure' est retournée, l'attribut 'error' est renseigné avec les causes de l'erreur.
data
tableau ou hash Valeurs possibles : tableau d'objets, devis, commande, etc. Cet attribut n'est présent que si la requête a été exécutée avec succès (status == success). Il est renseigné avec les objets (soit un objet unique soit un tableau), selon la requête. Rendez-vous dans la section ressources pour les détails sur les différents objets et leurs attributes.
count
entier Valeurs possibles : 1, 15, etc. (entier supérieur ou égal à 1) Cet attribut n'est présent que si l'attribut 'data' contient un tableau d'objets. Il contient dans le cas le nombre total d'objets dans ce tableau.
error
hash (masquer/afficher les attributs) Seulement retourné lorsque l'attribut 'status' de la requête est 'failure'.
type
chaîne de caractères Un code d'erreur, sous forme de chaîne de caractère.
message
chaîne de caractères Message d'erreur sous forme textuelle. Renvoyé systématiquement en anglais. Si vous souhaitez mettre en oeuvre des traductions des messages d'erreur, n'utilisez pas ce message comme clé de traduction mais plutôt l'attribut 'type', contient un code stable et fiable.

Codes d'erreur

Lorsque vous envoyez une requête au Webservice LCE, vous avez accès à trois sources d'information pour interpréter le succès ou l'échec de la requête :

  • Le code de la réponse HTTP et sa description
  • L'attribut 'status', qui contient soit 'success' (succès) soit 'failure' (échec)
  • Le noeud 'error' et son attribut 'type' (seulement si 'status' renvoie 'failure')

Notez que deux autres attributs sont disponibles à fin de débug si vous rencontrez des erreurs sur vos requêtes :

  • error:message contient une chaîne de caractères en anglais avec un message générique à propos de l'erreur. Si votre système est en anglais, vous pouvez éventuellement envisager d'afficher cette erreur directement. Sinon, nous recommandons que vous ignoriez cet attribut dans le cadre d'un mécanisme automatisé, et que vous ne l'utilisiez donc que pour débugger ou enregistrer des logs.
  • error:details est retourné seulement avec le code d'erreur HTTP 422 (erreur à la création d'une ressource). Il contient une description détaillée des raisons de l'échec de création de la ressource. Ne l'utilisez que pour débugger vos requêtes. Son format est susceptible d'évoluer dans l'avenir.

Ci-dessous sont présentés les différents codes de réponse HTTP avec les codes d'erreur correspondants. Vous pouvez appuyer votre implémentation sur ces codes.

200
Requête exécutée avec succès. Les requêtes réussies ne transmettent pas de noeud 'error'. Seul l'attribut 'status' est présent, avec la valeur 'success'.
201
Ressource créée avec succès. Resource created successfully. Les requêtes réussies ne transmettent pas de noeud 'error'. Seul l'attribut 'status' est présent, avec la valeur 'success'.
401
access_denied Vous n'avez pas accès à la ressource demandée, soit parce que vous n'êtes pas authentifié soit parce que vous ne disposez pas de droits suffisants.
404
not_found L'URI interrogée ne correspond à aucune route connue dans le Webservice LCE.
404
resource_not_found La requête correspond à un chemin de ressource connue, mais la ressource correspondante n'a pas pu être trouvée (mauvais ID par exemple).
404
labels_not_ready Le PDF contenant les étiquettes à imprimer n'est pas encore disponible. Vous devez essayer à nouveau plus tard.
Ce code d'erreur est spécifique à la route GET /orders/:id/labels.
422
resource_not_created La requête a essayé de créer une ressource, mais la création a échoué. Vérifiez l'attribut 'details' du noeud 'error' de la réponse pour voir le détail des erreurs d'enregistrement.
500
internal Code d'erreur générique pour indiquer un dysfonctionnement du serveur. Si vous obtenez une erreur 500, cela ne signifie pas nécessairement que vous avez une erreur dans votre intégration mais plutôt que le webservice ne fonctionne pas correctement.

Réponse pour un devis non existant avec l'ID 3 (code HTTP 404)

{
  "status":"failure",
  "error":{
    "type":"resource_not_found",
    "message":"Quote not found"
  },
  "self":"https://api.myflyingbox.com/v2/quotes/3"
}

Demander un devis

Un devis contient une collection d'offres de transports. Lorsque vous demandez un nouveau devis, vous devez transmettre les caractéristiques de base de votre expédition (pack-liste, ville de départ et destination) dans le format attendu (voir 'paramètres de la requête' ci-dessous).

Après avoir reçu un devis, vous pouvez commander toute offre transmise dans le devis (voir section commander plus bas). Notez que lorsque vous passez commande vous ne pouvez pas modifier les caractéristiques de base (codes postaux, pays, dimension des colis) de l'expédition. Si vous devez modifier ces informations, il vous faudra alors demander un nouveau devis avec les bonnes informations.

URL de la requête

POST
https://api.myflyingbox.com/v2/quotes

Paramètres de la requête

Les paramètres doivent être encapsulés dans un élément racine 'quote' (voir exemple de code à droite).

shipper
hash (masquer/afficher les attributs) Informations sur le lieu de départ de l'expédition.
country
chaîne de caractères (2) Code du pays de départ de l'expédition, norme ISO 3166-1 alpha2 (2 lettres).
postal_code
chaîne de caractères Code postal de l'adresse de départ de l'expédition. Pour les rares cas où l'adresse ne possède pas de code postal, mettez un tiret "-".
city
chaîne de caractères Nom de la ville
recipient
hash (masquer/afficher les attributs) Informations sur la destination de l'expédition.
is_a_company
booléen (true/false) L'adresse de destination est-elle une adresse d'entreprise ?
country
chaîne de caractères (2) Code du pays de destination de l'expédition, norme ISO 3166-1 alpha2 (2 lettres).
postal_code
chaîne de caractères Code postal de l'adresse de destination de l'expédition. Pour les rares cas où l'adresse ne possède pas de code postal, mettez un tiret "-".
city
chaîne de caractères Nom de la ville
parcels
tableau (masquer/afficher les attributs) Liste de colis, formant la pack-liste de l'expédition. Lorsque vous spécifiez plus d'un colis, assurez-vous de pouvoir reconstruire la liste exactement dans le même ordre lorsque vous passerez la commande et devrez spécifier des détails complémentaires (voir commander plus bas).
length
entier exemple : 153 Longueur du colis, en centrimètres (cm). Seul un entier non nul est autorisé.
width
entier exemple : 82 Largeur du colis, en centrimètres (cm). Seul un entier non nul est autorisé.
height
entier exemple : 55 Hauteur du colis, en centrimètres (cm). Seul un entier non nul est autorisé.
weight
décimale exemple : 12.5 Poids du colis, en kilogrammes (kg). Le séparateur de décimal doit être un point '.'. Si la chaîne transmise contient autre chose que des nombres et un point séparateur de décimal (par exemple 1,400.5), une erreur sera renvoyée.
insured_value
décimale exemple : 30.25 Valeur du contenu du colis à assurer. Permet d'obtenir le tarif de l'option "assurance ad-valorem" dans les offres. Cette valeur n'est pas reprise pour la valeur douanière du colis au moment de la commande, et fonctione donc de manière totalement indépendante.
insured_currency
chaîne de caractères exemple : EUR Devise pour la valeur spécifiée dans le champ 'insured_value'. Obligatoire si le champ 'insured_value' est spécifié.

Exemple de requête en JSON

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {identifiant}:{mot_de_passe} \
-H "Content-Type:application/json" \
-d '{"quote": {
        "shipper": {
          "country":"GB",
          "postal_code": "SW1A 1AA",
          "city": "London"
        },
        "recipient": {
          "is_a_company": "false",
          "country": "FR",
          "postal_code": "31300",
          "city": "Toulouse"
        },
        "parcels": [
          {
            "weight": 1,
            "length": 60,
            "width": 60,
            "height": 40
          },
          {
            "weight": 2.5,
            "length": 30,
            "width": 30,
            "height": 20
          }
        ]
      }}'

Exemple de requête au format champs de formulaire

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {login}:{password} \
-d "quote[shipper][country]=GB" \
-d "quote[shipper][postal_code]=SW1A 1AA" \
-d "quote[shipper][city]=London" \
-d "quote[recipient][country]=FR" \
-d "quote[recipient][postal_code]=31300" \
-d "quote[recipient][city]=Toulouse" \
-d "quote[recipient][is_a_company]=false" \
-d "quote[parcels][][weight]=1" \
-d "quote[parcels][][length]=60" \
-d "quote[parcels][][width]=60" \
-d "quote[parcels][][height]=40" \
-d "quote[parcels][][weight]=2.5" \
-d "quote[parcels][][length]=30" \
-d "quote[parcels][][width]=30" \
-d "quote[parcels][][height]=20"






Récupérer un devis existant

URL de la requête

GET
https://api.myflyingbox.com/v2/quotes/:id

Attributs d'un devis

id
uuid exemple : 4d6cc11f-8552-4497-bb24-d715b93ccfa9 Identifiant unique interne pour ce devis.
created_at
timestamp avec fuseau horaire (ISO 8601) exemple : 2013-10-01T10:41:14+03:00 Date et heure de création du devis.
shipper
hash (masquer/afficher les attributs) Informations sur le lieu de départ de l'expédition.
postal_code
chaîne de caractères exemple : 79450, SW1A 0AA, NY 10001 Code postal de l'adresse de départ de l'expédition.
country
chaîne de caractères exemple : FR, UK, NZ Code du pays de départ de l'expédition, norme ISO 3166-1 alpha2 (2 lettres).
recipient
hash (masquer/afficher les attributs) Informations sur le lieu de destination de l'expédition.
is_a_company
booléen Indique si l'adresse de livraison est une adresse d'entreprise (true) ou individuelle (false).
postal_code
chaîne de caractères exemple : SW1A 0AA, NY 10001, 79450 Code postal de l'adresse de destination de l'expédition.
country
chaîne de caractères exemple : FR, UK, NZ Code du pays de destination de l'expédition, norme ISO 3166-1 alpha2 (2 lettres).
parcels
tableau (masquer/afficher les attributs) Liste des colis, formant la pack-liste de l'expédition.
length
entier exemple : 153 Longueur du colis, en centrimètres (cm).
width
entier exemple : 82 Largeur du colis, en centrimètres (cm).
height
entier exemple : 55 Hauteur du colis, en centrimètres (cm).
weight
décimale exemple : 12.5 Poids du colis, en kilogrammes (kg).
offers
tableau Liste d'offres de différents transporteurs et différents niveaux de service. Vous pouvez passer commande pour toute offre de cette liste.
Aller à attributs des offres pour consulter le détail des attributs d'une offre.

Exemple de représentation JSON d'un devis

{
  "id": "2a4a628c-e541-4571-b817-a57cc3f89a1b",
  "shipper": {
    "postal_code": "AB1 6CC",
    "country": "GB"
  },
  "recipient": {
    "is_a_company": "true",
    "postal_code": "06800",
    "country": "FR"
  },
  "parcels": [
    {
      "weight": 3,
      "length": 40,
      "width": 30,
      "height": 10,
    },
    {
      "weight": 1.75,
      "length": 50,
      "width": 10,
      "height": 10,
    }
  ],
  "offers": [
    {
      "id":"6d37b0ed-833d-4a59-9e57-d6bd7d935c9b",
      "quote_id":"270cf4a5-e99f-45a5-9dca-1bf75cd3ca64",
      "product_id":"732e50b7-ed0e-424a-8631-51c5135d2b23",
      "product":{
        "id":"732e50b7-ed0e-424a-8631-51c5135d2b23",
        "logo":"lce_orange",
        "code":"lce_orange_express",
        "name":"LCE Orange Express",
        "delay":"24",
        "pick_up":true,
        "drop_off":false,
        "preset_delivery_location":false
      },
      "price":{
        "formatted":"€293.68",
        "currency":"EUR",
        "amount":293.68,
        "amount_in_cents":29368
      },
      "price_vat":{
        "formatted":"€57.56",
        "currency":"EUR",
        "amount":57.56,
        "amount_in_cents":5756
      },
      "total_price":{
        "formatted":"€351.24",
        "currency":"EUR",
        "amount":351.24,
        "amount_in_cents":35124
      },
      "collection_dates":[
        {
          "date":"2013-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2013-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2013-11-18",
          "cutoff":"If you book before 1pm on Monday, or book up to a week in advance"
        }
      ]
    },
    {
      "id":"33a60039-ea0c-4855-b9aa-616690288a4a",
      "quote_id":"270cf4a5-e99f-45a5-9dca-1bf75cd3ca64",
      "product_id":"46dc8970-c48a-4420-a85c-6dd31becba00",
      "product":{
        "id":"46dc8970-c48a-4420-a85c-6dd31becba00",
        "logo":"lce_red",
        "code":"lce_red_classic",
        "name":"LCE Red Classic",
        "delay":"96",
        "pick_up":true,
        "drop_off":false,
        "preset_delivery_location":false
      },
      "price":{
        "formatted":"€240.74",
        "currency":"EUR",
        "amount":240.74,
        "amount_in_cents":24074
      },
      "price_vat":{
        "formatted":"€47.19",
        "currency":"EUR",
        "amount":47.19,
        "amount_in_cents":4719
      },
      "total_price":{
        "formatted":"€287.93",
        "currency":"EUR",
        "amount":287.93,
        "amount_in_cents":28793
      },
      "collection_dates":[
        {
          "date":"2013-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2013-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2013-11-18",
          "cutoff":"If you book before 1pm on Monday, or book up to a week in advance"
        }
      ]
    }
  ]
}

Offres

Une offre est proposée par un transporteur avec un prix et des conditions. Les offres sont vendues sous différents noms de produit LCE, qui disposent de logos spécifiques et différentes variantes (classique, économie, express, etc.).

Les offres retournées par le webservice ne peuvent pas être accédées séparément du devis ou de la commande à laquelle elles sont rattachées. Elles sont retournées sous forme de collection dans les devis ou comme objet unique dans les commandes.

Attributs d'une offre

id
uuid exemple : 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Identifiant unique interne pour cette offre.
quote_id
uuid exemple : 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID du devis auquel cette offre appartient.
product_id
uuid exemple : 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID du produit LCE pour cette offre (voir ci-dessous le détail des produits). Dans la plupart des cas vous n'avez pas besoin d'utiliser cet identifiant interne, et pouvez utiliser à la place le code produit LCE.
product
hash (masquer/afficher les attributs) Caractéristiques du produit de transport proposé.
id
uuid exemple : 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID du produit LCE pour cette offre (voir ci-dessous le détail des produits). Dans la plupart des cas vous n'avez pas besoin d'utiliser cet identifiant interne, et pouvez utiliser à la place le code produit LCE.
code
chaîne de caractères exemple : lce_yellow Code produit LCE.
logo
chaîne de caractères exemple : lce_yellow Nom du fichier (sans extension) à utiliser comme logo pour ce produit. Consulter la section logos pour obtenir les fichiers de logos et les règles d'utilisation.
name
chaîne de caractères exemple : LCE Yellow Express Dénomination textuel du produit en anglais. Si vous souhaitez traduire les noms de produit, utiliser le code produit comme clé (le nom peut potentiellement changer) et contactez-nous pour validation de la traduction.
delay
chaîne de caractère (entier ou interval) exemple : 24, or 48-72 Délai de livraison estimé pour ce produit. Ce n'est PAS un délai garanti et ne devrait donc être considéré que comme estimation. Le format est soit un entier (nombre d'heures) ou un interval (délai le plus court possible en heures, tiret, délai théoriquement maximum en heure ; par exemple 24-48).
pick_up
booléen (true/false) Indique si ce produit propose l'enlèvement des colis à l'adresse de l'expéditeur.
drop_off
booléen (true/false) Indique si ce produit propose le dépôt des colis à un point de dépôt.
preset_delivery_location
booléen (true/false) Indique si le produit propose une livraison à un point relai.
price
hash (prix) (masquer/afficher les attributs) Prix hors TVA.
formatted
chaîne de caractères exemple : 56,50€ Prix formatté comme chaîne de caractère avec le symbôle de la devise, pour un affichage tel quel.
currency
chaîne de caractères exemple : EUR Code de la devise (norme ISO 4217).
amount
décimale exemple : 56.50 Montant, sous forme décimal, avec point '.' comme séparateur de décimale.
amount_in_cents
entier exemple : 5650 Montant en centimes, retourné en tant qu'entier (les deux derniers digits de l'entier correspondent aux centimes). Vous devriez privilégier cet attribut si vous avez besoin de manipuler les prix, car c'est le plus neutre en terme de format.
price_vat
hash (prix) Montant de la TVA pour cette offre. Il s'agit *seulement* de la TVA.
Pour le détail du formattage et des sous-attributs, consultez ci-dessus l'attribut 'price'.
total_price
hash (prix) Prix total, incluant la TVA.
Pour le détail du formattage et des sous-attributs, consultez ci-dessus l'attribut 'price'.
insurance_price
hash (prix) Tarif de l'option assurance, si applicable (présent seulement si les colis de la demande de devis incluent la valeur à assurer [insured_value/insured_currency]). Le tarif est transmis HT. La TVA sera appliquée au moment de la commande sur la base du taux applicable au transport.
Pour le détail du formattage et des sous-attributs, consultez ci-dessus l'attribut 'price'.
collection_dates
tableau (masquer/afficher les attributs) Liste des dates disponibles pour l'enlèvement des colis (seulement pour les produits proposant l'enlèvement).
date
date exemple : 2013-10-07 Date d'enlèvement.
cutoff
chaîne de caractères exemple : If you book before 1pm today, or book up to a week in advance Description des conditions d'enlèvement pour cette date.

Relais de livraison

Pour les offres avec livraison en point relais (par opposition à la livraison à domicile), le Webservice LCE vous donne accès à une liste d'adresses disponibles pour l'offre en question.

Pour savoir si une offre est concernée ou non, testez l'attribut booléen 'preset_delivery_location' sur le produit associé à l'offre. S'il est à 'true', la livraison se fera en point relais, sinon elle se fera à l'adresse du destinataire.

Pour obtenir les points relais les plus pertinent, vous devez passer une adresse complète dans la requête. Une liste de relais vous sera retournée, classée par pertinence (la plus pertinente en premier).

URL de la requête

GET
https://api.myflyingbox.com/v2/offers/:id/available_delivery_locations Remplacez :id par l'UUID de l'offre concernée.

Paramètres de la requête

location
hash (masquer/afficher les attributs) Adresse du destinataire, pour déterminer le relai le plus proche.
street
tableau de chaînes de caractères Lignes d'adresses (jusqu'à 3, de haut en bas). Au moins une ligne doit être présente.
city
chaîne de caractères Ville du destinataire.

Attributs de la réponse.

La requête retourne une collection de lieux. Chaque lieu comporte les attributs suivants :

company
chaîne de caractères Nom de l'entreprise/enseigne.
street
chaîne de caractère (multiligne) Lignes d'adresses, en tant que chaîne de caractère et contenant des caractères de fin de ligne (\n).
postal_code
chaîne de caractères Code postal du relais.
city
chaîne de caractères Ville du relais.
opening_hours
tableau Informations sur les horaires d'ouverture. Contient une liste de jours de la semaine avec les horaires correspondant.
day
entier Numéro du jour de la journée, entre 1 (lundi) et 7 (dimanche).
hours
chaîne de caractères exemple : 09:00-12:00 15:15-19:00 Horaires d'ouverture, dans un format affichable tel quel.

Commander une offre

La création d'une commande signifie que vous réservez un transport sur la base d'une offre et des attributs du devis. La création avec succès d'une commande constitue un lien contractuel ferme : vous serez facturé pour toutes les commandes créées avec succès, sur la base du coût final transmis par le transporteur après exécution de la prestation.

URL de la requête

POST
https://api.myflyingbox.com/v2/orders

Paramètres de la requête

Les paramètres doivent être encapsulé dans un élément racine 'order'.

Notez que les données suivantes seront automatiquement récupérées depuis le devis et ne peuvent pas être modifiée au moment de la commande : codes postaux et pays de l'expéditeur et du destinataire, dimensions des colis. Si vous devez modifier ces informations, vous devrez passer par un nouveau devis et passer commande sur une offre équivalente du nouveau devis ; vous ouvez utiliser le code produit pour vous assurer dans ce cas que vous commandez bien un service identique.

offer_id
uuid exemple : a3dd9019-df68-486b-9817-0a2cc6f3747c ID de l'offre pour laquelle vous passez commande.
thermal_labels
booléen exemples : true, false Si 'true', l'API va retourner de préférence des étiquettes dans un format compatible avec les imprimantes thermiques. Ce n'est toutefois pas possible pour tous les services.
insure_shipment
booléen exemples : true, false Si 'true', l'expédition sera assurée 'ad valorem', sur la base de la valeur spécifiée au moment de la demande de devis. Attention: la valeur assurée n'est PAS la valeur douanière déclarée lors de la confirmation de commande!
shipper
hash (masquer/afficher les attributs) Détails sur l'expéditeur.
name
chaîne de caractères Nom du contact à l'adresse d'expédition.
company
chaîne de caractères Optionel: nom de la société expéditrice.
street
chaîne de caractères Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) de l'expéditeur. Les retours à la ligne sont reconnus (\n).
state
chaîne de caractères Etat/Comté/Département (subdivision régionale pertinente pour le système postal du pays).
Vous devez spécifier un code officiel standard et non le nom complet de la région (par exemple 'CA' pour Californie, '31' pour Haute-Garonne).
phone
chaîne de caractères exemple : +33123456789 Numéro de téléphone de l'expéditeur, avec le préfix international. Aucun caractère supplémentaire ou espace n'est autorisé.
email
chaîne de caractères exemple : example-address@example.com Adresse email de l'expéditeur. Vérifiez bien la validité de l'adresse en amont.
collection_date
chaîne de caractère (date ou datetime) exemple : 2013-10-01 or 2013-10-01T10:41:14+03:00 Date d'enlèvement demandée (norme ISO-8601).
Utilisée seulement pour les offres dont le produit propose l'enlèvement sur site (voir attributs des offres plus haut).
Si l'offre pour laquelle vous passez commande contient une liste de dates d'enlèvement, vous devez utiliser la même chaîne de caractère. Sinon, vous devrez manuellement renseigner une date/datetime au format attendu. Ayez bien conscience que la date et heure exacte d'enlèvement dépend de l'heure de la commande et du type de produit. La plupart des produits ont des conditions strictes pour les enlèvements le même jour.
recipient
hash (masquer/afficher les attributs) Détails sur le destinataire
name
chaîne de caractères Nom du contact à destination.
company
chaîne de caractères Nom de la société destinataire.
Obligatoire si le devis contient l'attribut 'recipient:is_a_company' à 'true', optionnel sinon.
location_code
chaîne de caractères Code de l'adresse du relais de livraison, lorsque la livraison ne s'effectue pas à domicile. Lorsqu'un code relai est spécifié, les attributs company, street, city et state sont totalement ignorés par le webservice (ils seront écrasés par l'adresse du relais de livraison).
street
chaîne de caractères Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) du destinataire. Les retours à la ligne sont reconnus (\n).
Sera ignoré si location_code est défini !
state
chaîne de caractères Etat/Comté/Département (subdivision régionale pertinente pour le système postal du pays).
Vous devez spécifier un code officiel standard et non le nom complet de la région (par exemple 'CA' pour Californie, '31' pour Haute-Garonne).
Sera ignoré si location_code est défini !
phone
chaîne de caractères exemple : +33123456789 Numéro de téléphone du destinataire, avec le préfix international. Aucun caractère supplémentaire ou espace n'est autorisé.
email
chaîne de caractères exemple : example-address@example.com Adresse email du destinataire. Vérifiez bien la validité de l'adresse en amont.
parcels
tableau (masquer/afficher les attributs) Informations complémentaires sur les colis.
Le webservice s'attend à recevoir exactement le même nombre de colis que dans la demande de devis, dans le même ordre.
N'envoyez pas à nouveau les dimensions des colis (les dimensions passées dans la demande de devis sont utilisées). Vous ne devez donc envoyer que les attributs spécifiés ci-dessous, si nécessaire.
shipper_reference
chaîne de caractères exemple : Parcel 3, CS_03758 Optionnel : référence du colis pour l'expéditeur. Dans certains cas, cette référence sera inclue sur les étiquettes.
recipient_reference
chaîne de caractères exemple : Parcel 3, CS_03758 Optionnel : référence du colis pour le destinataire. Dans certains cas, cette référence sera inclue sur les étiquettes.
customer_reference
chaîne de caractères exemple : Parcel 3, CS_03758 Optionnel : référence du colis pour un tiers (client). Dans certains cas, cette référence sera inclue sur les étiquettes.

Les quatre attributs ci-dessous ne sont obligatoires que si les colis doivent passer par la douane (export ou autres obligations légales) :
value
décimale exemple : 15.35 Valeur du contenu du colis (la devise est spécifiée séparément). Utilisé pour la documentation douanière. Attention, la valeur doit correspondre à ce qui est présent sur la facture douanière attachée à l'envoi !
currency
chaîne de caractères exemple : EUR Devise pour la valeur spécifiée dans le champ 'value'. Utilisé pour la documentation douanière.
description
chaîne de caractères exemple : Books, Clothes, Gift, etc. Description du type de contenu pour le colis. Utilisé pour la documentation douanière.
country_of_origin
varchar(2) exemple : FR, UK, NZ Code du pays d'origine du contenu du colis, norme ISO 3166-1 alpha2 (2 lettres). Utilisé pour la documentation douanière.

Consulter une commande existante

URL de la requête

GET
https://api.myflyingbox.com/v2/orders/:id

Attributs d'une commande

id
uuid exemple : 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Identifiant unique interne pour cett commande.
created_at
timestamp with timezone (ISO 8601) exemple : 2013-10-01T10:41:14+03:00 Date et heure de création de la commande.
shipper
hash (masquer/afficher les attributs) Informations sur l'expéditeur.
name
chaîne de caractères Nom du contact à l'adresse d'expédition.
company
chaîne de caractères Optionel: nom de la société expéditrice.
street
chaîne de caractères Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) de l'expéditeur. Les retours à la ligne sont reconnus (\n).
city
chaîne de caractères Ville de l'expéditeur.
postal_code
chaîne de caractères exemple : SW1A 0AA, NY 10001, 79450 Code postal de l'expéditeur.
state
chaîne de caractères Etat/Comté/Département (subdivision régionale pertinente pour le système postal du pays).
country
chaîne de caractères exemple : FR, UK, NZ Code du pays de l'expéditeur, norme ISO 3166-1 alpha2 (2 lettres).
phone
chaîne de caractères exemple : +33123456789 Numéro de téléphone de l'expéditeur, avec le préfix international.
recipient
hash (masquer/afficher les attributs) Détails sur le destinataire
name
chaîne de caractères Nom du contact à destination.
is_a_company
boolean Indique si l'adresse de livraison est une adresse d'entreprise (true) ou individuelle (false).
company
chaîne de caractères Nom de la société destinataire. Toujours défini si 'is_a_company' est à 'true'.
street
chaîne de caractère Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) du destinataire. Les retours à la ligne sont reconnus (\n).
city
chaîne de caractères Ville du destinataire.
postal_code
chaîne de caractères exemple : SW1A 0AA, NY 10001, 79450 Code postal du destinataire.
country
chaîne de caractères exemple : FR, UK, NZ Code du pays du destinataire, norme ISO 3166-1 alpha2 (2 lettres).
phone
chaîne de caractères exemple : +33123456789 Numéro de téléphone du destinataire, avec le préfix international.
parcels
tableau (colis) (masquer/afficher les attributs) Liste des colis, qui forment la pack-liste de l'expédition.
length
entier exemple : 153 Longueur du colis, en centrimètres (cm).
width
entier exemple : 82 Largeur du colis, en centrimètres (cm).
height
entier exemple : 55 Hauteur du colis, en centrimètres (cm).
weight
decimal exemple : 12.5 Poids du colis en kilogrammes (kg), avec un point '.' comme séparateur de décimale.
value
entier exemple : 15 Valeur du contenu du colis, arrondi à l'entier le plus proche (la devise est spécifiée séparément).
currency
chaîne de caractères exemple : EUR Devise pour la valeur spécifiée dans le champ 'value'.
description
chaîne de caractères exemple : Parcel 3 Description du type de contenu pour le colis.
country_of_origin
varchar(2) exemple : FR, UK, NZ Code du pays d'origine du contenu du colis, norme ISO 3166-1 alpha2 (2 lettres).
shipper_reference
chaîne de caractères exemple : Parcel 3, CS_03758 Référence du colis pour l'expéditeur. Dans certains cas, cette référence sera inclue sur les étiquettes.
recipient_reference
chaîne de caractères exemple : Parcel 3, CS_03758 Référence du colis pour le destinataire. Dans certains cas, cette référence sera inclue sur les étiquettes.
customer_reference
chaîne de caractères exemple : Parcel 3, CS_03758 Référence du colis pour un tiers (client). Dans certains cas, cette référence sera inclue sur les étiquettes.
offer
hash L'offre pour laquelle la commande est passée.
Aller à la section attributs de l'offre pour les détails sur le formattage des attributs.

Exemple de représentation JSON d'une commande

{
  "uuid": "1471b700-1c14-4076-ade5-861798844129",
  "shipper": {
    "name": "Lce Test collection",
    "company": "Low Cost Express SAS",
    "street": ["15 route de France"],
    "city": "Cagnes-sur-Mer",
    "state": "Alpes-Maritimes",
    "postal_code": "AB1 6CC",
    "phone": "+33622123613",
    "country": "UK"
  },
  "recipient": {
    "name": "Lce Test delivery",
    "is_a_company": "true",
    "company": "Low Cost Express SAS",
    "street": ["15 route de France"],
    "city": "Cagnes-sur-Mer",
    "state": "Alpes-Maritimes",
    "postal_code": "06800",
    "phone": "+33622123613",
    "country": "FR"
  },
  "parcels": [
    {
      "weight": '3',
      "length": '40',
      "width": '30',
      "height": '10',
      "value": "15",
      "currency": "EUR",
      "description": "Books",
      "shipper_reference": "4684-0770",
      "recipient_reference": "AB-3072"            
    },
    {
      "weight": '1.75',
      "length": '50',
      "width": '10',
      "height": '10',
      "value": "15",
      "currency": "EUR",
      "description": "Books",
      "shipper_reference": "4684-0773",
      "recipient_reference": "AB-3073"
    }
  ]
}

Télécharger les étiquettes de colis

Après création de la commande, dans la plupart des cas, des étiquettes devront être imprimées par l'expéditeur et correctement apposées sur les colis.

Les étiquettes sont disponibles presque immédiatement après avoir passé commande, en envoyant une requête à l'URL spécifiée ci-desous. Les étiquettes sont retournées sous forme d'un unique fichier PDF. Lorsque la commande inclut plusieurs colis, ou si plusieurs étiquettes doivent être imprimées pour un même colis, tous les documents nécessaires sont inclut dans le PDF transmis.

URL de la requête

GET
https://api.myflyingbox.com/v2/orders/:id/labels Remplacez :id par l'UUID de la commande.

Paramètres de la requête et réponse

Aucun paramètre n'est attendu pour cette requête. Seul l'UUID de la commande doit être passée dans l'URL.

Un fichier PDF brut est retourné dans la réponse à la requête si les étiquettes sont disponibles.

Si pour quelque raison que ce soit les étiquettes ne sont pas encore disponibles, vous recevrez un code d'erreur HTTP 404 avec un code d'erreur 'labels_not_ready'. Dans ce cas, prévoyez d'effectuer à nouveau la requête ultérieurement.

Suivi des colis

Après confirmation d'une commande, vous avez immédiatement accès aux informations de suivi de tous les colis concernés.

URL de la requête

GET
https://api.myflyingbox.com/v2/orders/:id/tracking Remplacez :id par l'UUID de la commande.

Paramètres de la requête et réponse

Aucun paramètre n'est attendu pour cette requête. Seul l'UUID de la commande doit être passée dans l'URL.

La réponse renvoie toutes les informations concernant les événements de suivi pour chaque colis, ordonnés de la même manière que lors de la demande de devis initiale.

Notez que les informations de suivi varient d'un transporteur à l'autre. Nous faisons suivre ces informations de manière homogène à travers cette API, avec un maximum de flexibilité : beaucoup d'attributs sont optionels et lorsque nous recevons des informations non standard nous essayons néanmoins de les faire suivre. Assurez-vous d'implémenter cette fonctionnalité avec le même niveau de flexibilité, pour ne pas générer de blocage.

Attributs de la réponse

Le niveau racine (noeud 'data') contient un tableau d'informations de suivi pour chaque colis. Les attributs ci-dessous correspondent à une entrée de ce tableau. Vous trouverez dans la colonne de droite un exemple de réponse complète.

parcel_index
entier (commence à 0) Index du colis (débute à zéro). L'API retourne la totalité des colis de l'expédition dans le même ordre que dans le devis à l'origine de la commande.
events
tableau Tableau des événements de suivi pour ce colis.
code
chaîne de caractères Code de l'événement.
Vous pouvez vous appuyer sur ces codes pour votre mise en oeuvre. Néanmoins, prenez en compte la possibilité d'ajout de nouveaux codes dans l'avenir.
Si vous souhaitez prendre en compte explicitement le code 'unknown' (inconnu), vous pouvez utiliser les informations contenues dans le hash 'label' pour afficher directement le message (voir 'label' plus bas).
shipment_created : la commande a été confirmée
picked_up : colis récupéré au point d'enlèvement
departed_from_facility : colis parti de la plateforme (cf. location)
arrived_at_facility : colis arrivé à la plateforme (cf. location)
at_departure_hub : colis à la plateforme de départ
in_transit : colis en transit entre deux plateformes
at_arrival_hub : colis à la plateforme d'arrivée
delivery_in_progress : livraison en cours
delivery_exception : livraison tentée sans succès
delivered : livraison effectuée avec succès
unknown : code spécial pour la prise en compte des code transporteurs non standards, n'ayant aucune correspondance avec les codes ci-dessus
happened_at
timestamp avec fuseau horaire (ISO 8601) ex: 2013-10-01T10:41:14+03:00 Date et heure de l'événement.
label
hash Retourne un tableau associatif contenant une description textuelle de l'événement, correspondant au code. Lorsque le code de l'événement est 'unkown', les descriptions présentes dans 'label' changent en fonction du message transmis par le transporteur.
La clé de chaque élément du tableau associatif est le code language (ISO 639-1 alpha-2), et la valeur est la chaîne de caractère.
L'anglais est systématiquement présent. Actuellement le français est également retourné, sauf pour l'événement 'unknown', qui est en anglais uniquement. D'autres langues seront sans doute supportées dans l'avenir.
location
hash Retourne un tableau associatif d'informations à propos de la localisation de l'événement.
Notez qu'aucun des attributs n'est obligatoire, donc ce noeud n'est pas systématiquement inclus dans la réponse.
L'API essaiera toujours de transmettre autant d'informations de localisation que possible, en fonction des attributs disponibles.
name
chaîne de caractères Nom descriptif de la localisation (peut être abstrait, par exemple "Web service").
postal_code
chaîne de caractères Code postal.
city
chaîne de caractères Ville.
state
chaîne de caractères Etat.
country
varchar(2) ex: FR, UK, NZ Code pays, sur deux lettres (norme ISO 3166-1 alpha-2).
details
hash Pour certains types d'événement, fournit des informations plus détaillées.
Si aucune information supplémentaire n'est disponible, ce noeud ne sera pas retourné dans la réponse.
code
chaîne de caractères Code de l'information supplémentaire. A l'heure actuelle, seul un code est utilisé :
not_available_or_closed : retourné éventuellement en complément de l'événement 'delivery_exception', pour indiquer l'impossibilité d'effectuer la livraison (personne au point de livraison, ou entreprise fermée).
label
hash Retourne un tableau associatif de chaînes de caractères traduires, contenant une description directement lisible de l'information supplémentaire.
La clé de chaque élément du tableau est le code langue (ISO 639-1 alpha-2), et la valeur est la chaîne de caractère.
L'anglais est toujours présent. Nous retournons également les chaînes en français si possible. D'autres langues pourront être ajoutées ultérieurement.

Exemple de requête de suivi

curl https://test.myflyingbox.com/v2/orders/eb27ff8e-b353-4a3f-8e7e-69576e64ee1a/tracking \
  -i -u {identifiant}:{mot_de_passe}

Exemple de réponse pour une requête de suivi

{
  "status":"success",
  "self":"https://test.myflyingbox.com/v2/orders/eb27ff8e-b353-4a3f-8e7e-69576e64ee1a/tracking.json",
  "data":[
    {
      "parcel_index":0,
      "events":[
        {
          "code":"shipment_created",
          "happened_at":"2013-12-10T11:26:23+01:00",
          "label":{
            "fr":"Expédition créée",
            "en":"Shipment created"
          }
        },
        {
          "code":"picked_up",
          "happened_at":"2013-12-11T11:24:00+01:00",
          "label":{
            "fr":"Paquet enlevé",
            "en":"Package picked up"
          },
          "location":{
            "city":"NICE CEDEX 3",
            "postal_code":"06284",
            "country":"FR"
          }
        },
        {
          "code":"in_transit",
          "happened_at":"2013-12-12T03:43:00+01:00",
          "label":{
            "fr":"En transit",
            "en":"In transit"
          },
          "location":{
            "city":"ROISSY CHARLES DE GAULLE CEDEX",
            "postal_code":"95702",
            "country":"FR"
          }
        },
        {
          "code":"arrived_at_facility",
          "happened_at":"2013-12-12T05:11:00+01:00",
          "label":{
            "fr":"Arrivé à la plateforme",
            "en":"Arrived at hub"
          },
          "location":{
            "city":"STANSTED",
            "state":"ES",
            "postal_code":"CM24",
            "country":"GB"
          }
        },
        {
          "code":"delivery_in_progress",
          "happened_at":"2013-12-12T10:39:00+01:00",
          "label":{
            "fr":"Livraison en cours",
            "en":"Delivery in progress"
          },
          "location":{
            "city":"ENFIELD",
            "state":"MI",
            "postal_code":"EN3",
            "country":"GB"
          }
        },
        {
          "code":"delivery_exception",
          "happened_at":"2013-12-12T11:48:00+01:00",
          "label":{
            "fr":"Problème de livraison",
            "en":"Delivery exception"
          },
          "location":{
            "city":"ENFIELD",
            "state":"MI",
            "postal_code":"EN3",
            "country":"GB"
          },
          "details":{
            "code":"not_available_or_closed",
            "label":{
              "fr":"Client non disponible ou entreprise fermée",
              "en":"Customer not available or business closed"
            }
          }
        }
      ]
    }
  ]
}

Annulation de commande

Si nécessaire, après avoir placé une commande, vous pouvez l'annuler. La commande doit toujours être dans l'état "created".

URL de la requête

PUT
https://api.myflyingbox.com/v2/orders/:id/cancel Remplacez :id par l'UUID de la commande.

Paramètres de la requête et de la réponse.

Aucun paramètre n'est nécessaire pour cette requête. Seul l'UUID de la commande doit être passé dans l'URL de la requête.

La réponse contient la commande.

Exemple de la requête d'annulation.

curl -X PUT https://test.myflyingbox.com/v2/orders/eb27ff8e-b353-4a3f-8e7e-69576e64ee1a/cancel \
  -i -u {login}:{password}

Logos LCE

Si vous avez besoin de visuels pour afficher les offres sur vos pages web, vous pouvez utiliser les logos de produits LCE fournit ci-dessous. Chaque logo correspond à un code produit renvoyé avec les offres de transport (lce_blue, lce_orange, lce_green, lce_purple, etc.). L'attribut produit 'filename' correspond directement à un nom de fichier de log, sans l'extension.

Bien que chaque produit LCE corresponde à un transporteur spécifique, notez que vous n'êtes pas autorisé à afficher directement le nom ou logo du transporteur en question directement. Toutes les offres en provenance du Webservice LCE doivent être publiée en tant qu'offre LCE, même si vous avez connaissance du transporteur exact soit à travers des données de l'API soit de toute autre source.

Les logos standards fournis ci-dessous ont une taille de 350x170px. Vous pouvez les réduire pour répondre à vos besoins, à conditions que vous respectiez le ratio original. N'hésitez pas à nous solliciter si vous avez besoin de logos dans une taille spécifique : nous pourrons les générer directent à partir de nos originaux en format vectoriel.

Télécharger tous les logos produits LCE (fichier zip)

Derniers changements

Ci-dessous sont listés les derniers changement effectués sur la documentation, par ordre chronologique inversé (plus récent en premier).

2017-01-10
Mise à jour vers la version 2 de l'API. La version 2 conserve les mêmes fonctionnalités que la version 1, mais la codification des services a changé, ce qui constitue une rupture de compatibilité avec la version précédente.
2015-12-04
Ajout de la documentation des mécanismes d'assurance ad valorem. Aucune rupture de compatibilité.
2014-01-15
Ajout de la documentation des fonctionnalités de suivi.