en | fr

General

Resources

Autre

Webservice My Flying Box : documentation de référence

Le Webservice My Flying Box (MFB) 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 MFB 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 tech@myflyingbox.com 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, Prestashop et WooCommerce.

Client Ruby pour l'API de MY FLYING BOX Client PHP pour l'API de MY FLYING BOX Plugin Prestashop pour l'API de MY FLYING BOX Plugin WooCommerce pour l'API de MY FLYING BOX

Comment utiliser les exemples de code ?

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

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 à tech@myflyingbox.com.

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 MFB 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 MFB.
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 MFB 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"
}

  failure
  
    access_denied
    Unauthorized
  
  api.myflyingbox.com/v2/v2

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 MFB, 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 MFB.
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).

parcel_type
string package ou document Le type des éléments contenus dans l'expédition. Si absent, package sera utilisé par défaut. Doit avoir la même valeur que parcels[0][type]. Pour les documents, il n'y peut y avoir qu'un seul parcel par expédition.
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).
type
chaîne de caractères package ou document Le type des éléments contenus dans l'expédition. Si absent, package sera utilisé par défaut. Doit avoir la même valeur que parcels[0][type]. Pour les documents, il n'y peut y avoir qu'un seul parcel par expédition.
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é.
offers_sort_attributes
hash exemple : {"total_price": "asc"} Les attributs et les directions utilisés pour trier les offres. Pour l'instant, seulement l'attribut total_price est utilisable. Les directions de tri peuvent être "asc" et "desc" pour ascendant et descendant respectivement.
offers_filters
hash (masquer/afficher les attributs) Filtrer les offres par transporteur ou par produits.
with_drop_off
boolean Inclure les offres avec le flag "drop off" à true. Les offres disponibles pourront être utilisées pour déposer les colis dans un point du transporteurs (par exemple, dans un magasin partenaire près de l'expéditeur).
with_pick_up
boolean Inclure les offres avec le flag "pick up" à true. Les offres disponibles pourront être utilisées pour un enlèvements des colis chez l'expéditeur.
with_preset_delivery_location
boolean Inclure les offres avec le flag "preset delivery location" à true. Les offres disponibles pourront être utilisées pour livrer les colis dans un point du transporteurs (par exemple, dans un magasin partenaire près du destinataire).
with_carrier_codes
tableau de chaîne de caractères Limiter les offres à cette liste de transporteurs
with_product_codes
tableau de chaîne de caractères Limiter les offres à cette liste de produits
without_carrier_codes
tableau de chaîne de caractères Exclure les offres correspodannt à cette liste de code transporteur
without_product_codes
tableau de chaîne de caractères Exclure les offres correspodannt à cette liste de code produit

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 en JSON avec les filtres d'offres

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {login}:{password} \
-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
          }
        ],
        "offers_filters": {
          "with_carrier_codes": ["ups"]
          "without_product_codes": ["ups_access_point_standard"]
        }
      }}'

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"

Exemple de requête en JSON pour une expédition de document

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {identifiant}:{mot_de_passe} \
-H "Content-Type:application/json" \
-d '{
      "quote": {
          "parcel_type": "document",
          "parcels": [
              {
                  "type": "document",
                  "weight": 0.5
              }
          ],
          "recipient": {
              "city": "Toulouse",
              "country": "FR",
              "is_a_company": false,
              "postal_code": "31300"
          },
          "shipper": {
              "city": "Nice",
              "country": "FR",
              "postal_code": "06000"
          }
      }
  }'

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",
        "carrier_code":"dhl",
        "code":"dhl_worldwide_express",
        "name":"Worldwide 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":"2017-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2017-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2017-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",
        "carrier_code":"dpd",
        "code":"dpd_air_express",
        "name":"Air Express",
        "delay":"72",
        "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":"2017-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2017-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2017-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 MFB, 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 MFB 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 MFB.
vat_scheme_code
string exemples : FR_20, reverse_charge, exempted_exportation, exempted_importation... Code interne exprimant la règle de TVA applicable à la facturation des frais d'expédition. La liste pouvant évoluer, assurez-vous d'avoir des mécanismes d'auto-détection si vous utilisez cette information dans des processus automatisés.
product
hash (masquer/afficher les attributs) Caractéristiques du produit de transport proposé.
id
uuid exemple : 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID du produit MFB 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 MFB.
code
chaîne de caractères exemple : dhl_express_worldwide Code produit MFB, servant d'identifiant unique pour un service donné.
carrier_code
chaîne de caractères exemple : dhl Code du transporteur pour ce service. Vous pouvez utiliser ce code pour déterminer quel logo utiliser, par exemple.
name
chaîne de caractères exemple : Worldwide Express Dénomination textuel du produit, telle que présentée par le transporteur. Si vous souhaitez traduire les noms de produit, utiliser le code produit comme clé (le nom peut potentiellement changer).
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.
support_delayed_pickup
booléen e.g. true, false Indique si le produit permet les enlèvements différés.
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.

Points de dépôt

Pour les offres avec collecte en point de dépot (par opposition à l'enlèvement à domicile), le Webservice MFB 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 'drop_off' sur le produit associé à l'offre. S'il est à 'true', le dépôt peut se faire dans un dépôt.

Pour obtenir les points de dépôts les plus pertinent, vous devez passer une adresse complète dans la requête. Une liste de dépôts 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_drop_off_locations Remplacez :id par l'UUID de l'offre concernée.

Paramètres de la requête

location
hash (masquer/afficher les attributs) Adresse de l'expéditeur, pour déterminer le point de dépôt le plus proche.
street
chaîne de caractères Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) pour la recherche. Les retours à la ligne sont reconnus (\n).
postal_code
chaîne de caractères Code postal du relais.
city
chaîne de caractères Ville de l'expéditeur.
country
chaîne de caractères Code ISO 3166-1 alpha-2 du pays.

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.
country
chaîne de caractères Code ISO 3166-1 alpha-2 du pays.
latitude
decimal La latitude de la position du point de dépôt.
longitude
decimal La longitude de la position du point de dépôt.
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.

Relais de livraison

Pour les offres avec livraison en point relais (par opposition à la livraison à domicile), le Webservice MFB 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
chaîne de caractères Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) pour la recherche. Les retours à la ligne sont reconnus (\n).
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!
delay_pickup_order
booléen e.g. true, false Si 'true', l'enlèvement ne sera pas commandé en même temps que la commande. Vous devrez appeler la requête de création d'enlèvement. Cela ne fonctionnera qu'avec les produits dont l'attribut support_delayed_pickup est 'true'.
ecommerce_order_platform
string exemple: shopify Le nom de la plateforme d'ecommerce que vous utilisez. Uniquement shopify pour le moment.
ecommerce_order_identifier
string L'identifiant de l'expédition sur la plateforme d'ecommerce.
ecommerce_order_reference
string La référence de l'expédition sur la plateforme d'ecommerce.
inform_shipper_about_insurance
booléen exemples : true, false Si c'est applicable, cette option permet d'informer l'expéditeur sur l'assurance (dans les étiquette et/ou par email).
inform_recipient_about_insurance
booléen exemples : true, false Si c'est applicable, cette option permet d'informer le destinataire sur l'assurance (dans les étiquette et/ou par email).
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.

Exemple de requête en JSON

curl https://test.myflyingbox.com/v2/orders -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{
      "order": {
        "offer_id": "b26115b4-1852-4937-be54-a65c510744bb",
        "shipper": {
          "name": "Lce Test collection",
          "company": "MY FLYING BOX SAS",
          "street": "15 route de France",
          "state": "Alpes-Maritimes",
          "phone": "+33622123613",
          "email": "test@test.com"
        },
        "recipient": {
          "name": "Lce Test delivery",
          "company": "MY FLYING BOX SAS",
          "street": "15 route de France",
          "state": "Alpes-Maritimes",
          "phone": "+33622123613",
          "email": "test@test.com"
        },
        "parcels": [
          {
            "value": "15",
            "currency": "EUR",
            "description": "Books",
            "shipper_reference": "4684-0770",
            "recipient_reference": "AB-3072"
          }
        ]
      }
    }'

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 cette 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.
vat_scheme_code
string exemples : FR_20, reverse_charge, exempted_exportation, exempted_importation... Code interne exprimant la règle de TVA applicable à la facturation des frais d'expédition. La liste pouvant évoluer, assurez-vous d'avoir des mécanismes d'auto-détection si vous utilisez cette information dans des processus automatisés.
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": "MY FLYING BOX 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": "MY FLYING BOX 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}

Programmer un enlèvement (Seulement disponible pour les commandes avec enlèvement différée [delayed_pickup]).

Programmer un enlèvement veut dire que vous demander au transporteur d'envoyer un camion pour récupérer vos paquets. Cette fonctionnalité est uniquement disponilbe pour les commandes créées avec enlèvement différé (delayed pickup).

URL de la requête

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

Paramètres de la requête

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

order_id
uuid e.g. a3dd9019-df68-486b-9817-0a2cc6f3747c ID de la commande pour laquelle vous programmez un enlèvement.
collection_date
string (date or datetime) e.g. 2013-10-01 Date d'enlèvement demandée (norme ISO-8601).
collection_instructions
string Instruction pour le livreur collectant l'expédition.
address
hash (hide/show attributes) Détails sur l'expéditeur
name
string Nom du contact à l'adresse d'expédition.
company
string Optionel: nom de la société expéditrice.
street
string 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
string Etat/Comté/Département (subdivision régionale pertinente pour le système postal du pays).
postal_code
string Le code postal de l'adresse d'enlèvement.
city
string La ville de l'adresse d'enlèvement.
country
string Code ISO 3166-1 alpha-2 du pays.
phone
string e.g. +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
string e.g. example-address@example.com Adresse email de l'expéditeur. Vérifiez bien la validité de l'adresse en amont.

Consulter un enlèvement existant

URL de la requête

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

Attributs de l'enlèvement

id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Identifiant unique interne pour cette enlèvement.
order_id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Identifiant unique interne de la commande.
reference
string e.g. MFB-PU-200420-OQT La référence d'enlèvement créée par MFB.
supplier_reference
string e.g. 123456789 La référence d'enlèvement fournie par le transporteur.
collection_date
string (date or datetime) e.g. 2013-10-01 La date d'enlèvement
created_at
timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 La date de création.
total_price
price hash Le prix de l'enlèvement.
address
hash (hide/show attributes) L'adresse d'enlèvement
name
string Nom du contact à l'adresse d'expédition.
company
string Optionel: nom de la société expéditrice.
street
string (multiline) 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
string Ville de l'expéditeur.
postal_code
string e.g. SW1A 0AA, NY 10001, 79450 Code postal de l'expéditeur.
state
string Etat/Comté/Département (subdivision régionale pertinente pour le système postal du pays).
country
string e.g. FR, UK, NZ Code du pays de l'expéditeur, norme ISO 3166-1 alpha2 (2 lettres).
phone
string e.g. +33123456789 Numéro de téléphone de l'expéditeur, avec le préfix international.
email
string e.g. example-address@example.com Adresse email de l'expéditeur. Vérifiez bien la validité de l'adresse en amont.

Commander automatiquement la meilleur offre sans faire de demande devis.

Cette action combine et remplace la création de devis et la création de commande présentées ci-dessus. Pour cette requête, vous devez fournir les données et les informations pour trier et filtrer les offres en une unique requête. Le premier service correspondant aux attributs fournis sera sélectionné et commandé.

URL de la requête

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

Paramètres de la requête

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

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!
delay_pickup_order
booléen e.g. true, false Si 'true', l'enlèvement ne sera pas commandé en même temps que la commande. Vous devrez appeler la requête de création d'enlèvement. Cela ne fonctionnera qu'avec les produits dont l'attribut support_delayed_pickup est 'true'.
parcel_type
string package ou document Le type des éléments contenus dans l'expédition. Si absent, package sera utilisé par défaut. Doit avoir la même valeur que parcels[0][type]. Pour les documents, il n'y peut y avoir qu'un seul parcel par expédition.
ecommerce_order_platform
string exemple: shopify Le nom de la plateforme d'ecommerce que vous utilisez. Uniquement shopify pour le moment.
ecommerce_order_identifier
string L'identifiant de l'expédition sur la plateforme d'ecommerce.
ecommerce_order_reference
string La référence de l'expédition sur la plateforme d'ecommerce.
shipper
hash (hide/show attributes) Details regarding the location of departure of the shipment.
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).
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
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.
collection_instructions
string Instruction pour le livreur collectant l'expédition.
recipient
hash (hide/show attributes) Information regarding the destination of the shipment.
name
chaîne de caractères Nom du contact à destination.
is_a_company
booléen (true/false) L'adresse de destination est-elle une adresse d'entreprise ?
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 !
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
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
array (hide/show attributes)
type
chaîne de caractères package ou document Le type des éléments contenus dans l'expédition. Si absent, package sera utilisé par défaut. Doit avoir la même valeur que parcels[0][type]. Pour les documents, il n'y peut y avoir qu'un seul parcel par expédition.
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é.
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.
offers_sort_attributes
hash exemple : {"total_price": "asc"} Les attributs et les directions utilisés pour trier les offres. Pour l'instant, seulement l'attribut total_price est utilisable. Les directions de tri peuvent être "asc" et "desc" pour ascendant et descendant respectivement.
offers_filters
hash (masquer/afficher les attributs) Filtrer les offres par transporteur ou par produits.
with_drop_off
boolean Inclure les offres avec le flag "drop off" à true. Les offres disponibles pourront être utilisées pour déposer les colis dans un point du transporteurs (par exemple, dans un magasin partenaire près de l'expéditeur).
with_pick_up
boolean Inclure les offres avec le flag "pick up" à true. Les offres disponibles pourront être utilisées pour un enlèvements des colis chez l'expéditeur.
with_preset_delivery_location
boolean Inclure les offres avec le flag "preset delivery location" à true. Les offres disponibles pourront être utilisées pour livrer les colis dans un point du transporteurs (par exemple, dans un magasin partenaire près du destinataire).
with_carrier_codes
tableau de chaîne de caractères Limiter les offres à cette liste de transporteurs
with_product_codes
tableau de chaîne de caractères Limiter les offres à cette liste de produits
without_carrier_codes
tableau de chaîne de caractères Exclure les offres correspodannt à cette liste de code transporteur
without_product_codes
tableau de chaîne de caractères Exclure les offres correspodannt à cette liste de code produit

Exemple de requête en JSON

curl https://test.myflyingbox.com/v2/orders/automatic -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{
      "order": {
          "shipper": {
              "company": "test",
              "name": "test",
              "street" :"test",
              "phone": "+33600000000",
              "email": "support@myflyingbox.com",
              "collection_date": "2022-10-20",
              "country": "FR",
              "postal_code": "31300",
              "city": "Toulouse"
          },
          "recipient": {
              "company": "test",
              "name": "test",
              "street": "test",
              "phone": "+33600000000",
              "email": "support@myflyingbox.com",
              "country": "FR",
              "postal_code": "06000",
              "city": "Nice",
              "is_a_company": "false"
          },
          "parcels": [
              {
                  "description": "description",
                  "length": "15",
                  "height": "15",
                  "width": "15",
                  "weight": "1"
              }
          ],
          "offers_sort_attributes": {
              "total_price": "asc"
          },
          "offers_filters": {
              "with_preset_delivery_location": false,
              "with_pick_up": true,
              "with_drop_off": false,
              "with_carrier_codes": ["dhl", "ups", "fedex"]
          }
      }
  }'

Derniers changements

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

2022-11-02
Ajout de l'action de commande automatique, des informations de plateformes d'ecommerce, tris/filtres d'offres.
2022-09-30
Ajout des instructions d'enlèvement.
2022-08-03
Ajout des expéditions de documents.
2020-04-20
Ajout de la création des enlèvements différés.
2019-11-29
Ajout de available_drop_off_locations aux offres pour permettre la recherche de points de dépôts.
2018-08-03
Retrait de mentions obsolètes aux logos et dénominations des produits V1. Ajout du carrier_code sur product, dans les offres.
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.