Curl Ruby

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.

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.

Préparation des caractéristiques minimales de l'expédition (villes d'expédition et de livraison, dimensions des colis).
Demander un devis (envoi des informations minimales de l'expédition).
Sélection d'une offre
Si nécessaire, récupération de la liste des relais de livraison disponibles.
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).
Téléchargement des étiquettes
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'.

insurable

booléen (true/false) Indique si cette offre est assurable par notre assureur.

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'.

extended_cover_available

booléen (true/false) Indique si cette offre peut-être couverte par la Garantie Complémentaire de My Flying Box.

price_with_extended_cover

hash (prix) Prix de l'offre incluant la Garantie Complémentaire hors TVA .
Pour le détail du formattage et des sous-attributs, consultez ci-dessus l'attribut 'price'.

price_vat_with_extended_cover

hash (prix) Montant de la TVA sur le prix de l'offre incluant la Garantie Complémentaire.
Pour le détail du formattage et des sous-attributs, consultez ci-dessus l'attribut 'price'.

total_price_with_extended_cover

hash (prix) Prix total incluant la Garantie Complémentaire et la TVA.
Pour le détail du formattage et des sous-attributs, consultez ci-dessus l'attribut 'price'.

extended_cover_max_liability

hash (prix) Le montant maximum de responsabilité couvert par la Garantie Complémentaire pour cette offre.
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.

support_electronic_customs

booléen e.g. true, false Indique si l'offre permet la déclaration douanière électronique.

mandatory_electronic_customs

booléen e.g. true, false Indique si la déclaration douanière électronique est obligatoire.

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!

with_extended_cover

booléen exemples : true, false Si 'true', l'expédition sera couverte par la Garantie Complémentaire, sur la base de la valeur spécifiée au moment de la demande de devis.

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

declare_customs_electronically

booléen exemples : true, false Le cas échéant, vous pouvez demander de déclarer les douanes par voie électronique. support_electronic_customs doit être vrai dans l'offre.

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.
vat_number: chaîne de caractères exemple : FR12345678901 Numéro de TVA de l'expéditeur (UE/GB). L'identifiant TVA de l'entreprise pour la déclaration douanière électronique.
eori_number: chaîne de caractères exemple : GB123456123456 Numéro EORI de l'expéditeur (UE/GB). L'identifiant EORI de l'entreprise pour la déclaration douanière électronique.
ein: chaîne de caractères exemple : 12-3456789 Numéro EIN de l'expéditeur pour les Etats-Unis (US). L'identifiant EIN de l'entreprise pour la déclaration douanière électronique.
business_number: chaîne de caractères exemple : 123456789 Numéro BN de l'expéditeur pour le Canada (CA). Le numéro d'entreprise de l'entreprise pour la déclaration douanière électronique.
ide: chaîne de caractères exemple : CHE-123.456.789 Numéro IDE de l'expéditeur pour la Suisse (CH). L'identifiant IDE de l'entreprise pour la déclaration douanière électronique.
ioss: chaîne de caractères exemple : IM0123456789 L'identifiant IOSS utilisé pour la déclaration de TVA si le destinataire est dans l'UE et n'est pas une entreprise.
hmrc: chaîne de caractères exemple : k1234567890123 L'identifiant HMRC utilisé pour la déclaration de TVA si le destinataire est au Royaume-Uni (GB) et n'est pas une entreprise.
voec: chaîne de caractères exemple : 2123456 L'identifiant VOEC utilisé pour la déclaration de TVA si le destinataire est en Norvège (NO) et n'est pas une entreprise.
business_identification_number: chaîne de caractères exemple : 123456789 Identifiant local de la société de l'entreprise expéditrice - si rien ci-dessus ne s'applique.
tax_identification_number: chaîne de caractères exemple : 123456789 Identifiant fiscal local de la société expéditrice - si rien ci-dessus ne s'applique

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.
vat_number: chaîne de caractères exemple : FR12345678901 Numéro de TVA de l'expéditeur (UE/GB). L'identifiant TVA de l'entreprise pour la déclaration douanière électronique.
eori_number: chaîne de caractères exemple : GB123456123456 Numéro EORI de l'expéditeur (UE/GB). L'identifiant EORI de l'entreprise pour la déclaration douanière électronique.
ein: chaîne de caractères exemple : 12-3456789 Numéro EIN de l'expéditeur pour les Etats-Unis (US). L'identifiant EIN de l'entreprise pour la déclaration douanière électronique.
business_number: chaîne de caractères exemple : 123456789 Numéro BN de l'expéditeur pour le Canada (CA). Le numéro d'entreprise de l'entreprise pour la déclaration douanière électronique.
ide: chaîne de caractères exemple : CHE-123.456.789 Numéro IDE de l'expéditeur pour la Suisse (CH). L'identifiant IDE de l'entreprise pour la déclaration douanière électronique.
business_identification_number: chaîne de caractères exemple : 123456789 Identifiant local de la société de l'entreprise expéditrice - si rien ci-dessus ne s'applique.
tax_identification_number: chaîne de caractères exemple : 123456789 Identifiant fiscal local de la société expéditrice - si rien ci-dessus ne s'applique

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 incluse 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 incluse 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 incluse 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.

customs_details

hash (masquer/afficher les attributs) Attributs de la facture commerciale pour la déclaration électronique de douane.

invoice_number: chaîne de caractères INV-FSD-4389 Numéro de la facture commerciale.
reason_for_export: chaîne de caractères exemple : commercial Raison de l'export. Doit être une des valeurs suivantes : commercial, gift, personal, return_for_repair, return_after_repair, warranty_replacement, sample
ship_price: décimale exemple : 11.67 Prix du transport tel que vous l'avez vendu à votre client.
ship_currency: chaîne de caractères (ISO 4217) exemple : EUR Code de la devise pour le prix du transport (EUR, USD, CAD, ...)
insurance_price: décimale exemple : 3.23 Prix de l'assurance tel que vous l'avez vendu à votre client.
insurance_currency: chaîne de caractères (ISO 4217) exemple : EUR Code de la devise pour le prix de l'assurance (EUR, USD, CAD, ...)
remarks: chaîne de caractères exemple : Additional remarks. Informations complémentaires a afficher sur la facture commerciale.
aes_number: chaîne de caractères exemple : AES X20080930987654 Déclaration d'export AES (US).
itn_number: chaîne de caractères exemple : X20080930987654 Déclaration d'export ITN (US).
ftr_number: chaîne de caractères exemple : 30.37(a) Déclaration d'export FTR (US).
por_number: chaîne de caractères exemple : RC1234 20070512345 Déclaration d'export POR (CA).
mrn_number: chaîne de caractères exemple : 24DE1234567890ABCD Déclaration d'export MRN (DE).
eur1_number: chaîne de caractères exemple : B 432 654 Déclaration d'export EUR1 (CH & EU).

customs_items

tableau (masquer/afficher les attributs) Tableau détaillant les items de la facture commerciale utilisée pour la déclaration de douane électronique.

quantity: décimale exemple : 3 La quantité pour cet item.
unit_value: décimale exemple : 12.54 La valeur unitaire de cet item. Sera multiplié par la quantité pour déterminer la valeur totale de la ligne.
value_currency: chaîne de caractères (ISO 4217) exemple : USD Devise de la valeur unitaire.
country_of_origin: chaîne de caractères (ISO 3166-1 alpha-2) exemple : FR Pays d'origine de l'item.
customs_code: chaîne de caractères exemple : 0304870090 Code SH de l'item.
description: chaîne de caractères exemple : Hexagonal aluminum bicycle nuts Description détaillée de l'item.
unit_weight: décimale exemple : 0.243 Le poids unitaire de l'item. Il sera multiplié par la quantité afin de déterminer le poids total de la ligne.
mass_unit: chaîne de caractères (kg ou lbs) exemple : kg L'unité de poids de l'item.

exporter

hash (masquer/afficher les attributs) Détails sur l'exportateur. A utiliser uniquement si l'exportateur est différent de l'expéditeur.

name: chaîne de caractères Nom du contact de l'exportateur.
company: chaîne de caractères Nom de la société exportatrice.
street: chaîne de caractères Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) de l'exportateur. 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'exportateur, 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'exportateur. Vérifiez bien la validité de l'adresse en amont.
vat_number: chaîne de caractères exemple : FR12345678901 Numéro de TVA de l'exportateur (UE/GB). L'identifiant TVA de l'entreprise pour la déclaration douanière électronique.
eori_number: chaîne de caractères exemple : GB123456123456 Numéro EORI de l'expédexportateuriteur (UE/GB). L'identifiant EORI de l'entreprise pour la déclaration douanière électronique.
ein: chaîne de caractères exemple : 12-3456789 Numéro EIN de l'exportateur pour les Etats-Unis (US). L'identifiant EIN de l'entreprise pour la déclaration douanière électronique.
business_number: chaîne de caractères exemple : 123456789 Numéro BN de l'exportateur pour le Canada (CA). Le numéro d'entreprise de l'entreprise pour la déclaration douanière électronique.
ide: chaîne de caractères exemple : CHE-123.456.789 Numéro IDE de l'exportateur pour la Suisse (CH). L'identifiant IDE de l'entreprise pour la déclaration douanière électronique.
ioss: chaîne de caractères exemple : IM0123456789 L'identifiant IOSS utilisé pour la déclaration de TVA si le destinataire est dans l'UE et n'est pas une entreprise.
hmrc: chaîne de caractères exemple : k1234567890123 L'identifiant HMRC utilisé pour la déclaration de TVA si le destinataire est au Royaume-Uni (GB) et n'est pas une entreprise.
voec: chaîne de caractères exemple : 2123456 L'identifiant VOEC utilisé pour la déclaration de TVA si le destinataire est en Norvège (NO) et n'est pas une entreprise.
business_identification_number: chaîne de caractères exemple : 123456789 Identifiant local de la société de l'entreprise exportatrice - si rien ci-dessus ne s'applique.
tax_identification_number: chaîne de caractères exemple : 123456789 Identifiant fiscal local de la société exportatrice - si rien ci-dessus ne s'applique

importer

hash (masquer/afficher les attributs) Détails sur l'importateur. A utiliser uniquement si l'exportateur est différent de l'expéditeur.

name: chaîne de caractères Nom du contact de l'importateur.
company: chaîne de caractères Nom de la société importatrice.
street: chaîne de caractères Adresse détaillée (nom de rue, numéro, détails additionnels, etc.) de l'importateur. 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'importateur, 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'importateur. Vérifiez bien la validité de l'adresse en amont.
vat_number: chaîne de caractères exemple : FR12345678901 Numéro de TVA de l'importateur (UE/GB). L'identifiant TVA de l'entreprise pour la déclaration douanière électronique.
eori_number: chaîne de caractères exemple : GB123456123456 Numéro EORI de l'importateur (UE/GB). L'identifiant EORI de l'entreprise pour la déclaration douanière électronique.
ein: chaîne de caractères exemple : 12-3456789 Numéro EIN de l'importateur pour les Etats-Unis (US). L'identifiant EIN de l'entreprise pour la déclaration douanière électronique.
business_number: chaîne de caractères exemple : 123456789 Numéro BN de l'importateur pour le Canada (CA). Le numéro d'entreprise de l'entreprise pour la déclaration douanière électronique.
ide: chaîne de caractères exemple : CHE-123.456.789 Numéro IDE de l'importateur pour la Suisse (CH). L'identifiant IDE de l'entreprise pour la déclaration douanière électronique.
business_identification_number: chaîne de caractères exemple : 123456789 Identifiant local de la société de l'entreprise importatrice - si rien ci-dessus ne s'applique.
tax_identification_number: chaîne de caractères exemple : 123456789 Identifiant fiscal local de la société importatrice - si rien ci-dessus ne s'applique

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"
          }
        ]
      }
    }'

Exemple pour la douane électronique ( FR -> US )

curl https://test.myflyingbox.com/v2/orders -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{
      "order": {
        "declare_customs_electronically": true,
        "offer_id": "625d4079-f0dd-470f-bc37-31582ad14fd8",
        "shipper": {
          "company": "test",
          "name": "test",
          "street": "test",
          "phone": "0123456789",
          "email": "email@test.com",
          "eori_number": "FR35819137589",
          "vat_number": "FR35819137589",
          "collection_date": "2024-09-05"
        },
        "recipient": {
          "name": "test",
          "street": "test",
          "state": "NY",
          "phone": "0123456789",
          "email": "email@test.com",
          "ein": "EIN123456"
        },
        "parcels": [
          {
            "description": "test",
            "country_of_origin": "FR",
            "value": "150.0",
            "currency": "EUR"
          }
        ],
        "customs_details": {
          "invoice_number": "INV312312",
          "reason_for_export": "commercial",
          "ship_price": 49.78,
          "ship_currency": "EUR"
        },
        "customs_items": [
          {
            "description": "description article",
            "customs_code": "4201003000",
            "quantity": 1,
            "currency_code": "EUR",
            "mass_unit": "kg",
            "country_of_origin": "FR",
            "unit_value": 150.0,
            "unit_weight": 3.0,
            "value_currency": "EUR"
          }
        ]
      }
    }'

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

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 incluse 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 incluse 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 incluse 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

insure_shipment

delay_pickup_order

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 incluse 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 incluse 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 incluse 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

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.