en | fr

General

Resources

Other

My Flying Box Web Service Reference documentation

The My Flying Box (MFB) Web Service provides an interface to request shipment offers from multiple carriers in an homogenous way and place bookings for these offers.

By implementing this web service you will have access to a wide range of competitive rates without needing to implement other APIs, saving you time and money.

This documentation is meant for technical people implementing the MFB Web Service on their systems. It provides an exhaustive description of all exposed resources and the way to manipulate them, with corresponding code examples in several languages.

Please note that you can contact us at tech@myflyingbox.com if you need any help. We can also provide you with integration services if needed.

For direct use in your application and for example purposes, we also provide some client libraries for PHP, Prestashop and WooCommerce.

Ruby client for the MY FLYING BOX API PHP client for the MY FLYING BOX API Prestashop plugin for the MY FLYING BOX API Prestashop plugin for the MY FLYING BOX API

How to use the code examples?

This column contains code examples for most features of the MFB Web Service.

Supported languages are listed on top of the column. You can dynamically switch depending on your needs.

We tried to make 'copy/paste'-friendly examples (for instance curl commands) to ease your development and testing process. Feel free to contact us at tech@myflyingbox.com with feedback or improvement suggestions.

Getting started

Workflow

Before diving into technical details, here is a summary of the general workflow of the web service. Items corresponding to a request to the webservice are linked to the corresponding section of the documentation; other items are actions to be performed on your side only.

  1. Prepare your shipment information: shipper, recipient, pack-list.
  2. Request a quote (passing shipment information).
  3. Select an offer.
  4. If necessary request a list of available delivery locations.
  5. Place a booking on your selected offer (passing complementary shipment details: shipper and recipient details, extra pack-list details).
  6. Download labels
  7. Track your parcels

Test server

When your account is registered on the web service, you will receive an ID and password for a test server only. You must use the test server to fully implement the web service. When your implementation is ready, contact us to obtain ID and password for the production server.

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

REST services

The MFB Web Service uses REST resources in a standardized way throughout the API. All request declarations are semantically meaningful:

  • POST requests to create a new object
  • GET requests to retrieve an existing object

At the moment we have no use for PUT, PATCH and DELETE requests.

Available routes

The base URL for all your requests is the following : https://api.myflyingbox.com/v2

All the URIs below should be appended to the base URL.

GET
/ Access some basic information about the MFB Web Service.
POST
/quotes Request a new quote, returning a set of offers.
GET
/quotes Retrieve a collection of all your past quotes.
GET
/quotes/:id Retrieve a specific quote with its ID.
GET
/offers/:id Returns a particular offer (received within a quote).
GET
/offers/:id/available_delivery_locations Returns a set of relevant delivery locations, for offers that do not propose at-the-door delivery.
POST
/orders Book an offer (returns an order object).
GET
/orders/:id Returns an existing order.
GET
/orders/:id/labels Download the raw PDF of the generated labels for an order.
GET
/orders/:id/tracking Returns the current tracking status of an existing order, for each parcel.

Authentication

You cannot use the MFB Web Service without authentication.

Authentication is stateless (there is no persistence), so you will need to include your credentials on every request.
Authentication is done through the HTTP Basic Access Authentication method.

Example request

curl https://api.myflyingbox.com/v2/ -u login:password
require 'net/http' # Or 'net/https' for ruby version < 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.request :basic_auth, 'login', 'password'
  response = http.request request # Net::HTTPResponse object
end

Response with failed authentication (HTTP response code 401)

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

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

Requests

All requests use the HTTP protocol.

Content must be encoded in UTF-8.

The web service supports two formats for passing request attributes:

JSON
JSON is the preferred format to send request attributes.
Plain form fields
This format is similar to what is sent by a traditional web form.

Whatever format you use, make sure that the proper "content-type" header is used.

Check out the code example for quote requests for an example of curl requests using each format approach.

Responses

Response format

Responses are sent in JSON format.

Most programming languages include well supported JSON libraries, which you can use to manipulate the response data.

All text is encoded in UTF-8 character set. If your system is not using UTF-8, make sure that you use proper conversion methods for all interactions with the web service.

Response attributes

Responses are encapsulated in a basic envelop described below.

  • All responses contain the 'status' and 'self' attributes.
  • Responses with errors (status = failure) also contain an 'error' attribute containing an explanation on why the request failed.
  • Responses for successful requests also contain a 'data' attribute containing the actual data pertaining to your request. If the root data is an array of objects (e.g. if you query the index of a given resource, like a list of past orders), a 'count' attribute will also be present.
self
string (URL) Returns the complete URL which was queried to generate this response.
status
string Possible values: failure, success When 'failure' is returned, the 'error' attribute is populated with the cause of the failure.
data
array or hash Possible values: array of objects, quote, order, etc. This attribute is only present for successful requests (status = success). It is populated with objects (single or in an array), depending on your request. Please go to the resources section for details on all object attributes.
count
integer Possible values: 1, 15, etc. (any integer superior or equal to 1) This attribute is only present when the 'data' attribute contains an array of objects, and contains the total number of objects in the array.
error
hash (hide/show attributes) Only returned when the request 'status' attribute is set to 'failure'.
type
string An string-formatted error code.
message
string Human readable error message. Always returned in English. If you wish to implement translations, you can base them on the 'type' attribute.

Error codes

When sending a query to the MFB Web Service, you have access to three sources of information to interpret the success or failure of your request:

  • The HTTP response code and description
  • The 'status' attribute, containing either 'success' or 'failure'
  • The 'error' node and its 'type' attribute, only if 'status' returns 'failure'

Please note that two other attributes are available for debugging purposes if you get query errors:

  • error:message contains a string in English with generic details about the error. If your system is implemented only in English language, you may use the error:message directly. Otherwise, we recommend that you ignore this attribute for any automated mechanism, and use it only for debugging or logging purposes.
  • error:details is returned only with HTTP code 422 (error while creating a resource). It contains a detailed description of while the saving failed. Use it only for debug purposes.

Below are presented the different HTTP response codes with corresponding error types. You can base your implementation on these codes.

200
Request successful. Successful queries do not transmit an 'error' node. Only the 'status' attribute is present, with the value 'success'.
201
Resource created successfully. Successful queries do not transmit an 'error' node. Only the 'status' attribute is present, with the value 'success'.
401
access_denied You do not have access to the queried resource, either because you are not authenticated or because you do not have sufficient access rights.
404
not_found The queried URI does not correspond to any known path in the MFB Web Service.
404
resource_not_found The query corresponds to a known path, but the corresponding resource could not be found (wrong ID, for instance).
404
labels_not_ready The PDF containing labels to be printed is not yet available. You should try again later.
This error code is specific to the route GET /orders/:id/labels.
422
resource_not_created The query attempted to create a resource, but the creation failed. Check the 'details' attribute of the response for detailed error messages.
500
internal Catch-all error code for server malfunction. Encountering such an error does not mean that you are doing anything wrong, but rather that the web service is not working properly.

Response for non-existent quote with ID 3 (HTTP code 404)

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

Request a quote

A quote contains a set of transportation offers. When requesting a new quote, you must send your shipment requirements (packages specifications, dates, shipper and recipient information) in the expected format (see 'Request parameters' below).

After you have received a quote, you can order any offer returned within this quote (see place an order below). Please note that when placing the order you cannot change the country or postal code of the shipper and recipient, and you cannot change the pack-list either. If you need to alter these details, you must request a new quote with the correct information.

Request URL

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

Request parameters

Parameters must be encapsulated within a root element 'quote' (see code example on the right).

parcel_type
string package or document The type of parcel you are shipping. If not present package will be used by default. Must the same value as parcels[0][type]. Document will only work with 1 parcel.
shipper
hash (hide/show attributes) Information regarding the location of departure of the shipment.
country
varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code
string Postal code of the collection location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city
string City name
recipient
hash (hide/show attributes) Information regarding the destination of the shipment.
is_a_company
boolean (true/false) Is the delivery location a company place?
country
varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code
string Postal code of the delivery location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city
string City name
parcels
array (hide/show attributes) A collection of parcels, forming the pack-list of your shipment. When specifying more than one parcel, make sure that you have the capacity to submit the list in the same order when booking an offer (see place an order below).
type
string package or document The type of parcel you are shipping. If not present, package will be used by default. Must the same value as parcel_type in the quote. Only 1 parcel is allowed for documents.
length
integer e.g. 153 Length of the parcel, in centimeters (cm). Only integers are allowed.
width
integer e.g. 82 Width of the parcel, in centimeters (cm). Only integers are allowed.
height
integer e.g. 55 Height of the parcel, in centimeters (cm). Only integers are allowed.
weight
float e.g. 12.5 Weight of the parcel, in kilograms (kg). You can only use '.' (dot) as decimal separator. If there is anything else than numbers and a dot separator (e.g. 1,400.5) an error will be returned.
insured_value
float e.g. 30.25 Value of parcel to insure. If specified, offers will include (separately) the price of the 'ad valorem insurance' option. This value is not used to fill the parcel's customs value when ordering an offer, and works therefore in a totally independent manner.
insured_currency
string e.g. EUR Currency for the value specified in 'insured_value'. Mandatory if the field 'insured_value' is specified.
offers_sort_attributes
hash e.g. {"total_price": "asc"} The attributes and directions used for sorting offers. For now, only the total_price attribute is supported. The directions for sorting are "asc" and "desc" for ascending and descending respectively.
offers_filters
hash (hide/show attributes) Filter offers by carriers or product codes.
with_drop_off
boolean Includes offers for the product with the "drop off" flag set to to true. The available offers will support drop-off to carrier locations (for example in a partnered shop near the shipper).
with_pick_up
boolean Includes offers for the product with the "pick up" flag set to to true. The available offers will support pick up at the shipper location by the carrier.
with_preset_delivery_location
boolean Includes offers for the product with the "preset delivery location" flag set to to true. The available offers will support delivery at carrier locations (for example in a partnered shop near the recipient).
with_carrier_codes
array of strings Limit offers to this list of carrier codes
with_product_codes
array of strings Limit offers to this list of product codes
without_carrier_codes
array of strings Exclude offers matching this list of carrier codes
without_product_codes
array of strings Exclude offers matching this list of product codes

Example request with JSON

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

Example request with offers_filters in JSON

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

Example request with plain fields

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"

Example request with JSON for document shipment

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {login}:{password} \
-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"
          }
      }
  }'

Retrieve an existing quote

Request URL

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

Quote attributes

id
uuid e.g. 4d6cc11f-8552-4497-bb24-d715b93ccfa9 Internal unique identifier for this quote.
created_at
timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of creation.
shipper
hash (hide/show attributes) All relevant information regarding the collection of the parcels.
postal_code
string e.g. SW1A 0AA, NY 10001, 79450
country
string e.g. FR, UK, NZ Country code of collection address, on two letters (norm ISO 3166-1 alpha-2)
recipient
hash (hide/show attributes) All relevant information regarding the delivery of the parcels.
is_a_company
boolean Tells whether the delivery location is a company location (true) or a residential location (false).
postal_code
string e.g. SW1A 0AA, NY 10001, 79450
country
string e.g. FR, UK, NZ Country code of delivery address, on two letters (norm ISO 3166-1 alpha-2)
parcels
array (hide/show attributes) A collection of parcels, forming the pack-list of your shipment.
length
integer e.g. 153 Length of the parcel, in centimeters (cm).
width
integer e.g. 82 Width of the parcel, in centimeters (cm).
height
integer e.g. 55 Height of the parcel, in centimeters (cm).
weight
float e.g. 12.5 Weight of the parcel, in kilograms (kg).
offers
array A collection of offers from different carriers and levels of service. You can choose any offer by placing an order.
Jump to offer attributes for details on offer formatting and attributes.

Example representation of a quote in JSON

{
  "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":"2013-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2013-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2013-11-18",
          "cutoff":"If you book before 1pm on Monday, or book up to a week in advance"
        }
      ]
    },
    {
      "id":"33a60039-ea0c-4855-b9aa-616690288a4a",
      "quote_id":"270cf4a5-e99f-45a5-9dca-1bf75cd3ca64",
      "product_id":"46dc8970-c48a-4420-a85c-6dd31becba00",
      "product":{
        "id":"46dc8970-c48a-4420-a85c-6dd31becba00",
        "carrier_code":"dpd",
        "code":"dpd_air_express",
        "name":"Air Express",
        "delay":"96",
        "pick_up":true,
        "drop_off":false,
        "preset_delivery_location":false
      },
      "price":{
        "formatted":"€240.74",
        "currency":"EUR",
        "amount":240.74,
        "amount_in_cents":24074
      },
      "price_vat":{
        "formatted":"€47.19",
        "currency":"EUR",
        "amount":47.19,
        "amount_in_cents":4719
      },
      "total_price":{
        "formatted":"€287.93",
        "currency":"EUR",
        "amount":287.93,
        "amount_in_cents":28793
      },
      "collection_dates":[
        {
          "date":"2013-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2013-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2013-11-18",
          "cutoff":"If you book before 1pm on Monday, or book up to a week in advance"
        }
      ]
    }
  ]
}

Offers

An offer is proposed by a carrier with a price and some conditions. Offers are sold under MFB product names, with corresponding logos and several variants.

Offers returned by the web service cannot be accessed independently from the quote or order they are linked to; they are returned as a collection in quotes or as single objects in orders.

Offer attributes

id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for this offer.
quote_id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID of the quote to which this offer belongs.
product_id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID of the MFB product for this offer (see below for product details). In most cases you should no need to do anything with this ID, and should rather rely on the product code.
vat_scheme_code
string e.g. FR_20, reverse_charge, exempted_exportation, exempted_importation... Internal code expressing the applicable VAT rule for the invoicing of the shipping costs. As the list may change, make sure to implement auto-discover mechanisms if you use this information in any automated process.
product
hash (hide/show attributes) Characteristics of the transport product proposed.
id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID of the MFB product. In most cases you should no need to do anything with this ID, and should rather rely on the product code.
code
string e.g. dhl_express_worldwide MFB product code. This is the unique identifier for a given service.
carrier_code
string e.g. dhl Code of the carrier for this service. You could use this to determine what logo to use, for instance.
name
string e.g. Worldwide Express Textual denomination of the product as defined by the carrier. If you plan to translate product names, use the product code as key (the name might change).
delay
integer or interval e.g. 24, or 48-72 Estimated delivery delay for this product. This is NOT a guaranteed delay and should only be considered as an estimation. The format is either an integer (hours) or an interval (shortest possible delivery delay in hours, hyphen, theoretical longest delivery delay in hours, eg. 24-48).
pick_up
boolean e.g. true, false Indicates whether this product allows for parcel pick-up at the shipper's address.
drop_off
boolean e.g. true, false Indicates whether this product allows for parcel drop-off at a carrier-defined drop-off location.
preset_delivery_location
boolean e.g. true, false Indicates whether this product allows for parcel delivery at a predifined location.
support_delayed_pickup
boolean e.g. true, false Indicates whether this product allows for delayed pickups.
price
price hash (hide/show attributes) Price without VAT.
formatted
string e.g. 56,50€ Price formatted as a string with currency symbol, for direct display.
currency
string e.g. EUR Currency code, as per ISO 4217.
amount
float e.g. 56.50 Amount returned as a float (with dot separator).
amount_in_cents
integer e.g. 5650 Amount returned as an integer, in cents (the two last digits of the integer are cents). You should favor this attribute if you need to manipulate prices, as it is the most neutral.
price_vat
price hash VAT amount of the offer. This is *only* the VAT part.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.
total_price
price hash Total price, including VAT. Does NOT include insurance price (when applicable)!
For detailed formatting and sub-attributes, please look at the 'price' attribute above.
insurance_price
price hash Price of the insurance option, when applicable (only present when the quote request parcels include a value to insure [insured_value/insured_currency]). The price is BEFORE VAT. The VAT rate of the shipment will be applied when booking.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.
collection_dates
array (hide/show attributes) List of possible dates for collection of your parcels (for pickup only).
date
date e.g. 2013-10-07 Collection date.
cutoff
string e.g. If you book before 1pm today, or book up to a week in advance Description of conditions for pickup at this date.

Delivery locations

For offers where parcels are delivered at a predefined delivery location (as opposed to at-the-door delivery), the MFB Web Service gives you access to the list of predefined locations available for this offer.

To know which offers are concerned, you must check the offer's product attribute 'preset_delivery_location'. If set to true, the delivery will be done at a preset location, and not at the recipient's address.

To get the most relevant locations, you must pass a detailed address in your request. A set of available delivery locations will be returned, sorted by relevance (most relevant first).

Request URL

GET
https://api.myflyingbox.com/v2/offers/:id/available_delivery_locations Replace :id with the UUID of the offer.

Request parameters

location
hash (hide/show attributes) Address of the recipient, to determine the nearest delivery location available.
street
string Street details (name, number, additional details) used by the seartch. If you need multiline addresses, please use line-breaks.
city
string City of the recipient.

Response attributes

The request will return a collection of locations. Each location has the following attributes:

company
string Name of the company.
street
string (multiline) Lines of address, as a string with line-break (\n).
postal_code
string Postal code of the location.
city
string City of the location.
opening_hours
array Information regarding the opening hours of the location. Contains a list of weekdays with corresponding opening times.
day
integer Number of the day, between 1 (Monday) and 7 (Sunday).
hours
string e.g. 09:00-12:00 15:15-19:00 Opening hours, in a format which should be displayable as is.

Drop-off locations

For offers where parcels are dropped off at a predefined drop-off location (as opposed to a pickup), the MFB Web Service gives you access to the list of predefined locations available for this offer.

To know which offers are concerned, you must check the offer's product attribute 'drop_off'. If set to true, the collection can be done at a preset drop-off location, and not at the shipper's address.

To get the most relevant locations, you must pass a detailed address in your request. A set of available drop-off locations will be returned, sorted by relevance (most relevant first).

Request URL

GET
https://api.myflyingbox.com/v2/offers/:id/available_drop_off_locations Replace :id with the UUID of the offer.

Request parameters

location
hash (hide/show attributes) Address of the shipper, to determine the nearest drop-off location available.
street
string Street details (name, number, additional details) used by the seartch. If you need multiline addresses, please use line-breaks.
postal_code
string Postal code of the shipper.
city
string City of the shipper.
country
string ISO 3166-1 alpha-2 code for the country of the shipper.

Response attributes

The request will return a collection of locations. Each location has the following attributes:

company
string Name of the company.
street
string (multiline) Lines of address, as a string with line-break (\n).
postal_code
string Postal code of the location.
city
string City of the location.
country
string country of the location.
latitude
decimal Latitude of the location.
longitude
decimal Longitude of the location.
opening_hours
array Information regarding the opening hours of the location. Contains a list of weekdays with corresponding opening times.
day
integer Number of the day, between 1 (Monday) and 7 (Sunday).
hours
string e.g. 09:00-12:00 15:15-19:00 Opening hours, in a format which should be displayable as is.

Place an order (= book an offer)

Creating an order object means that you are booking a transport on the basis of an offer and its corresponding quote attributes (collection and delivery postal codes and countries, pack-list). A successfully created order is contractually binding: you will be invoiced for all orders you created, on the basis of the final price transmitted by the carrier.

Request URL

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

Request parameters

Parameters must be encapsulated within the root element 'order'.

Please note that the following data will be automatically retrieved from the original quote and cannot be changed while placing the order: postal code and country of the shipper and recipient, list of parcels and their characteristics. If you need to change these data, you must first request a new quote, and place a new order for the corresponding offer. You can use the product code of the offer to make sure that you order the same service as initially intended.

offer_id
uuid e.g. a3dd9019-df68-486b-9817-0a2cc6f3747c The ID of the offer for which you place this order.
thermal_labels
boolean e.g. true, false If true, the API will try to return the labels in a thermal printer-friendly format. This is not possible for all services.
insure_shipment
boolean e.g. true, false If true, the shipment will be insured 'ad valorem', based on the value specified during the quote request. Warning: the insured value is NOT the customs value specified during the order booking!
delay_pickup_order
boolean e.g. true, false If true, the pickup will not be requested at the same time as the order. You will neet to call pickup creation request. This can only work on the products with the attribut support_delayed_pickup is 'true'.
ecommerce_order_platform
string e.g. shopify The name of ecommerce platform that you are using. Only shopify is supported for now.
ecommerce_order_identifier
string The identifier of the shipment on the ecommerce platform.
ecommerce_order_reference
string The reference of the shipment on the ecommerce platform.
inform_shipper_about_insurance
boolean e.g. true, false If applicable, this will inform the shipper about insurance. (In the label and/or by email)
inform_recipient_about_insurance
boolean e.g. true, false If applicable, this will inform the recipient about insurance. (In the label and/or by email)
shipper
hash (hide/show attributes) Details regarding the location of departure of the shipment.
name
string Name of a contact at the collection location.
company
string Optional company name for the collection location.
street
string Street details (name, number, additional details) for the pickup location. If you need multiline addresses, please use line-breaks (cf. code example).
state
string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
phone
string e.g. +33123456789 Phone number of the shipper, with international prefix. No extra characters or spaces allowed.
email
string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.
collection_date
string (date or datetime) e.g. 2013-10-01 or 2013-10-01T10:41:14+03:00 Requested collection date (norm ISO-8601).
Used only for offers where the product includes pickup at the shipper's address (see offer attributes above).
If the offer for which you place a booking contained a set of proposed collection dates, you must use the exact same string. Otherwise you must manually put a date/datetime. Remember that the exact pickup date and time depends on the time of the booking and the product. Most products have strict deadlines for same-day pickups.
recipient
hash (hide/show attributes) Information regarding the destination of the shipment.
name
string Name of a contact at the delivery location.
company
string Company name for the delivery location.
Mandatory if the quote request has a recipient attribute 'is_a_company' at true, optional otherwise.
location_code
string Code of pickup location, when delivery occurs at a predetermined pickup point (opposed to home delivery). When a location code is specified, the attributes company, street, city and state are totally ignored by the web service (they will be overridden by the address of the pickup point).
street
string Street details (name, number, additional details) for the delivery location. If you need multiline addresses, please use line-breaks (cf. code example).
Will be ignored if location_code is set!
state
string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
Will be ignored if location_code is set!
phone
string e.g. +33123456789 Phone number of the recipient, with international prefix. No extra characters or spaces allowed.
email
string e.g. example-address@example.com Email address of the recipient. Make sure you check the validity of the email address.
parcels
array (hide/show attributes) Complementary information regarding the parcels.
Please note that the API expects to receive exactly the same number of parcels as in the quote request, in the same order.
Do not send again the dimensions or the parcels (the dimensions passed in the quote request are used). Only send the attributes specified below, if necessary.
shipper_reference
string e.g. Parcel 3, CS_03758 Optional reference used by the shipper. In some cases, this reference will be included on the labels.
recipient_reference
string e.g. Parcel 3, CS_03758 Optional reference used by the recipient. In some cases, this reference will be included on the labels.
customer_reference
string e.g. Parcel 3, CS_03758 Optional customer reference used by the recipient. In some cases, this reference will be included on the labels.

The following four attributes are mandatory only if your parcels need to proceed through customs (export or other regulatory obligations):
value
integer e.g. 15 Value of the content of the parcel, rounded to the nearest integer (currency is specified separately). Used for customs.
currency
string e.g. EUR Currency of the value specified above.
description
string e.g. Books, Clothes, Gift, etc. Description of the content of the parcel (used for customs).
country_of_origin
varchar(2) e.g. FR, UK, NZ Country code of the origin country of the parcel's content, on two letters (norm ISO 3166-1 alpha-2). Used for customs.

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

Get an existing order

Request URL

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

Order attributes

id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for this order.
created_at
timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of creation.
vat_scheme_code
string e.g. FR_20, reverse_charge, exempted_exportation, exempted_importation... Internal code expressing the applicable VAT rule for the invoicing of the shipping costs. As the list may change, make sure to implement auto-discover mechanisms if you use this information in any automated process.
shipper
hash (hide/show attributes) All relevant information regarding the collection of the parcels.
name
string Name of the person responsible at the collection point
company
string Optional company name for collection point
street
string (multiline) Lines of address, as a string with linebreaks (\n).
city
string City name
postal_code
string e.g. SW1A 0AA, NY 10001, 79450
state
string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
country
string e.g. FR, UK, NZ Country code of collection address, on two letters (norm ISO 3166-1 alpha-2)
phone
string e.g. +33123456789 Phone number of contact at collection address, with international prefix.
recipient
hash (hide/show attributes) All relevant information regarding the delivery of the parcels.
name
string Name of the person responsible at the delivery point
is_a_company
boolean Tells whether the delivery location is a company location (true) or a residential location (false).
company
string Company name for delivery address. Always set if 'is_a_company' is true.
street
string (multiline) Lines of address, as a string with linebreaks (\n).
city
string City name
postal_code
string e.g. SW1A 0AA, NY 10001, 79450
country
string e.g. FR, UK, NZ Country code of delivery address, on two letters (norm ISO 3166-1 alpha-2)
phone
string e.g. +33123456789 Phone number of contact at delivery address, with international prefix.
parcels
array (hide/show attributes) A collection of parcels, forming the pack-list of your shipment.
length
integer e.g. 153 Length of the parcel, in centimeters (cm).
width
integer e.g. 82 Width of the parcel, in centimeters (cm).
height
integer e.g. 55 Height of the parcel, in centimeters (cm).
weight
float e.g. 12.5 Weight of the parcel, in kilograms (kg) with '.' (dot) as decimal separator.
value
float e.g. 15.35 Value of the content of the parcel (currency is specified separately). Used for customs. Note: this value must be identical to the value specified on the customs invoice attached to the shipment.
currency
string e.g. EUR Currency of the value specified above.
description
string e.g. Parcel 3 Brief description of content of the parcel (will be used for customs).
shipper_reference
string e.g. Parcel 3, CS_03758 Optional reference used by the shipper. In some cases, this reference will be included on the labels.
recipient_reference
string e.g. Parcel 3, CS_03758 Optional reference used by the recipient. In some cases, this reference will be included on the labels.
customer_reference
string e.g. Parcel 3, CS_03758 Optional reference used by the customer. In some cases, this reference will be included on the labels.
offer
hash The offer booked in this order.
Go to offer attributes for details on offer formatting and attributes.

Example representation of an order

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

Download parcel labels

After creating an order, in most cases, labels will need to be printed by the shipper and affixed on the parcels.

Labels are available almost immediately after placing the order, by sending a request to the URL specified below. The labels are returned in the form of a unique PDF file. When the order includes several parcels, or when more than one label needs to be printed, all relevant documents are included in the one PDF returned.

Request URL

GET
https://api.myflyingbox.com/v2/orders/:id/labels Replace :id with the UUID of the order.

Request parameters and response

No parameters are expected in this request. Only the UUID of the order must be passed in the request URL.

A raw PDF file is returned in response to the request if the labels are available.

If for some reasons the labels are not yet available, you will receive a 404 status code and a generic error response, with error code labels_not_ready.

Tracking parcels

After an order is placed, you have immediate access to tracking information for all parcels.

Request URL

GET
https://api.myflyingbox.com/v2/orders/:id/tracking Replace :id with the UUID of the order.

Request parameters and response

No parameters are expected in this request. Only the UUID of the order must be passed in the request URL.

The response returns all event information for each parcel of this order, sorted in the same order as they were submitted when requesting the initial quote.

Please note that tracking information may vary from carrier to carrier. We forward it through our API in an homogenous way but with a lot of flexibility: many attributes are optional and when we get some non-standard information we try to forward it nevertheless. Make sure that your implementation fits this flexibility.

Response attributes

The root level ('data' node) contains an array of tracking information for each parcel. The attributes below correspond to one entry of the array. Check the example on the right for a complete response example.

parcel_index
integer (starts at 0) Index of the parcel (starts at zero). The API is expected to return tracking info for all packages, but to be on the safe side please use the parcel_index attribute to associate the tracking data to the correct package on your side, so that your code will work even if some packages are missing in the response.
events
array Array of tracking events for this parcel.
code
string Code of the event.
You can rely on these codes for your implementation. However, please take into account that new codes may be added later.
If you want to implement the 'unknown' code, you can use the 'label' node for a direct display of the message (see below).
shipment_created : the order was confirmed
picked_up : parcel has been picked up at collection point
departed_from_facility : parcel has left the hub (cf. location)
arrived_at_facility : parcel arrived at the hub (cf. location)
at_departure_hub : parcel has arrived at the departure hub
in_transit : parcel is in transit between two hubs
at_arrival_hub : parcel is at the arrival hub
delivery_in_progress : parcel is being delivered
delivery_exception : delivery was attempted but failed
delivered : parcel has been delivered successfully
unknown : special code to handle non-standard carrier event codes corresponding to none of the above.
happened_at
timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of the event.
label
hash Returns a hash of translated strings containing a human-readable description of the event, corresponding to the event code. When the event code is 'unknown', the label will change depending on the message returned by the carrier.
The key of each hash element is the language code (ISO 639-1 alpha-2), and the value is the string.
English language is always present. We currently also return event labels in French language, except for the 'unknown' event, which is English-only. Other languages may be supported later.
location
hash Returns a hash of information regarding the location of the event.
Please note that none of the attributes are mandatory, which means that this node is not always returned.
The API will always try to return as many location details as possible through the available attributes.
name
string Descriptive name of the location (can be abstract, e.g. "Web service").
postal_code
string Postal code of the location.
city
string City of the location.
state
string State of the location.
country
varchar(2) e.g. FR, UK, NZ Country code of the location, on two letters (norm ISO 3166-1 alpha-2).
details
hash For some event codes, more detailed information is sometimes returned in this node.
If no extra information is available, this node will not be returned at all in the response.
code
string Code of the extra information. At the moment, only one code is supported:
not_available_or_closed : returned only along with the event code delivery_exception
label
hash Returns a hash of translated strings containing a human-readable description of the information.
The key of each hash element is the language code (ISO 639-1 alpha-2), and the value is the string.
English language is always present. We currently also return event labels in French language. Other languages may be supported later.

Example of tracking request

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

Example response of a tracking request

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

Cancel an order

If needed, after placing an order, you can cancel it. The order must still have the state "created".

Request URL

PUT
https://api.myflyingbox.com/v2/orders/:id/cancel Replace :id with the UUID of the order.

Request parameters and response

No parameters are expected in this request. Only the UUID of the order must be passed in the request URL.

The response contains the order.

Example of cancel request

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

Schedule a pickup (Only avaialble for orders with delayed pickups).

Scheduling a pickup means that you are requesting the carrier to send a truck to collect your packages. This is only available for orders created with the 'delay_order flag'.

Request URL

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

Request parameters

Parameters must be encapsulated within the root element 'pickup'.

order_id
uuid e.g. a3dd9019-df68-486b-9817-0a2cc6f3747c The ID of the order for which you are scheduling a pickup.
collection_date
string (date or datetime) e.g. 2013-10-01 Requested collection date (norm ISO-8601).
collection_instructions
string Instruction for the driver collecting the shipment.
address
hash (hide/show attributes) Details regarding the location of departure of the shipment. This is only needed if you want to override the shipper from the order.
name
string Name of a contact at the collection location.
company
string Optional company name for the collection location.
street
string Street details (name, number, additional details) for the pickup location. If you need multiline addresses, please use line-breaks (cf. code example).
state
string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
postal_code
string Postal code of the location.
city
string City of the location.
country
string ISO 3166-1 alpha-2 code for the country of the shipper.
phone
string e.g. +33123456789 Phone number of the shipper, with international prefix. No extra characters or spaces allowed.
email
string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.

Get an existing pickup

Request URL

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

Pickup attributes

id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for this pickup.
order_id
uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for the order.
reference
string e.g. MFB-PU-200420-OQT The pickup reference created by MFB.
supplier_reference
string e.g. 123456789 The pickup reference provided by the carrier.
collection_date
string (date or datetime) e.g. 2013-10-01 Requested collection date (norm ISO-8601).
created_at
timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of creation.
total_price
price hash Total price, including VAT.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.
address
hash (hide/show attributes) All relevant information regarding the collection of the parcels.
name
string Name of the person responsible at the collection point
company
string Optional company name for collection point
street
string (multiline) Lines of address, as a string with linebreaks (\n).
city
string City name
postal_code
string e.g. SW1A 0AA, NY 10001, 79450
state
string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
country
string e.g. FR, UK, NZ Country code of collection address, on two letters (norm ISO 3166-1 alpha-2)
phone
string e.g. +33123456789 Phone number of contact at collection address, with international prefix.
email
string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.

Automaticaly order the best offer without requesting a quote.

This action combine and replace the quote creation and the order creation actions presented above. For this request, you will need to provide all the data and a way to sort and filter offers in one request. The first service matching your parameters will be selected and ordered.

Request URL

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

Request parameters

Parameters must be encapsulated within the root element 'order'.

thermal_labels
boolean e.g. true, false If true, the API will try to return the labels in a thermal printer-friendly format. This is not possible for all services.
insure_shipment
boolean e.g. true, false If true, the shipment will be insured 'ad valorem', based on the value specified during the quote request. Warning: the insured value is NOT the customs value specified during the order booking!
delay_pickup_order
boolean e.g. true, false If true, the pickup will not be requested at the same time as the order. You will neet to call pickup creation request. This can only work on the products with the attribut support_delayed_pickup is 'true'.
parcel_type
string package or document The type of parcel you are shipping. If not present package will be used by default. Must the same value as parcels[0][type]. Document will only work with 1 parcel.
ecommerce_order_platform
string e.g. shopify The name of ecommerce platform that you are using. Only shopify is supported for now.
ecommerce_order_identifier
string The identifier of the shipment on the ecommerce platform.
ecommerce_order_reference
string The reference of the shipment on the ecommerce platform.
shipper
hash (hide/show attributes) Details regarding the location of departure of the shipment.
name
string Name of a contact at the collection location.
company
string Optional company name for the collection location.
street
string Street details (name, number, additional details) for the pickup location. If you need multiline addresses, please use line-breaks (cf. code example).
state
string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
country
varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code
string Postal code of the collection location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city
string City name
phone
string e.g. +33123456789 Phone number of the shipper, with international prefix. No extra characters or spaces allowed.
email
string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.
collection_date
string (date or datetime) e.g. 2013-10-01 or 2013-10-01T10:41:14+03:00 Requested collection date (norm ISO-8601).
Used only for offers where the product includes pickup at the shipper's address (see offer attributes above).
If the offer for which you place a booking contained a set of proposed collection dates, you must use the exact same string. Otherwise you must manually put a date/datetime. Remember that the exact pickup date and time depends on the time of the booking and the product. Most products have strict deadlines for same-day pickups.
collection_instructions
string Instruction for the driver collecting the shipment.
recipient
hash (hide/show attributes) Information regarding the destination of the shipment.
name
string Name of a contact at the delivery location.
is_a_company
boolean (true/false) Is the delivery location a company place?
company
string Company name for the delivery location.
Mandatory if the quote request has a recipient attribute 'is_a_company' at true, optional otherwise.
location_code
string Code of pickup location, when delivery occurs at a predetermined pickup point (opposed to home delivery). When a location code is specified, the attributes company, street, city and state are totally ignored by the web service (they will be overridden by the address of the pickup point).
street
string Street details (name, number, additional details) for the delivery location. If you need multiline addresses, please use line-breaks (cf. code example).
Will be ignored if location_code is set!
state
string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
Will be ignored if location_code is set!
country
varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code
string Postal code of the delivery location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city
string City name
phone
string e.g. +33123456789 Phone number of the recipient, with international prefix. No extra characters or spaces allowed.
email
string e.g. example-address@example.com Email address of the recipient. Make sure you check the validity of the email address.
parcels
array (hide/show attributes)
type
string package or document The type of parcel you are shipping. If not present, package will be used by default. Must the same value as parcel_type in the quote. Only 1 parcel is allowed for documents.
length
integer e.g. 153 Length of the parcel, in centimeters (cm). Only integers are allowed.
width
integer e.g. 82 Width of the parcel, in centimeters (cm). Only integers are allowed.
height
integer e.g. 55 Height of the parcel, in centimeters (cm). Only integers are allowed.
weight
float e.g. 12.5 Weight of the parcel, in kilograms (kg). You can only use '.' (dot) as decimal separator. If there is anything else than numbers and a dot separator (e.g. 1,400.5) an error will be returned.
insured_value
float e.g. 30.25 Value of parcel to insure. If specified, offers will include (separately) the price of the 'ad valorem insurance' option. This value is not used to fill the parcel's customs value when ordering an offer, and works therefore in a totally independent manner.
insured_currency
string e.g. EUR Currency for the value specified in 'insured_value'. Mandatory if the field 'insured_value' is specified.
shipper_reference
string e.g. Parcel 3, CS_03758 Optional reference used by the shipper. In some cases, this reference will be included on the labels.
recipient_reference
string e.g. Parcel 3, CS_03758 Optional reference used by the recipient. In some cases, this reference will be included on the labels.
customer_reference
string e.g. Parcel 3, CS_03758 Optional customer reference used by the recipient. In some cases, this reference will be included on the labels.

The following four attributes are mandatory only if your parcels need to proceed through customs (export or other regulatory obligations):
value
integer e.g. 15 Value of the content of the parcel, rounded to the nearest integer (currency is specified separately). Used for customs.
currency
string e.g. EUR Currency of the value specified above.
description
string e.g. Books, Clothes, Gift, etc. Description of the content of the parcel (used for customs).
country_of_origin
varchar(2) e.g. FR, UK, NZ Country code of the origin country of the parcel's content, on two letters (norm ISO 3166-1 alpha-2). Used for customs.
offers_sort_attributes
hash e.g. {"total_price": "asc"} The attributes and directions used for sorting offers. For now, only the total_price attribute is supported. The directions for sorting are "asc" and "desc" for ascending and descending respectively.
offers_filters
hash (hide/show attributes) Filter offers by carriers or product codes.
with_drop_off
boolean Includes offers for the product with the "drop off" flag set to to true. The available offers will support drop-off to carrier locations (for example in a partnered shop near the shipper).
with_pick_up
boolean Includes offers for the product with the "pick up" flag set to to true. The available offers will support pick up at the shipper location by the carrier.
with_preset_delivery_location
boolean Includes offers for the product with the "preset delivery location" flag set to to true. The available offers will support delivery at carrier locations (for example in a partnered shop near the recipient).
with_carrier_codes
array of strings Limit offers to this list of carrier codes
with_product_codes
array of strings Limit offers to this list of product codes
without_carrier_codes
array of strings Exclude offers matching this list of carrier codes
without_product_codes
array of strings Exclude offers matching this list of product codes

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

Changelog

Below are listed the latest changes made to the documentation, sorted by reverse chronological order (latest on top).

2022-11-02
Adds automatic order action, ecommerce plateform informations, offers filtering/sorting.
2022-09-30
Adds instruction for pickups.
2022-08-03
Adds support for documents.
2020-04-20
Adds delayed pickup creation.
2019-11-29
Adds available_drop_off_locations to offers to look up for drop-off locations.
2018-08-03
Removed obsolete branding and mentions to V1 product logos. Added carrier_code attribute to product, in offers.
2017-01-10
Update to version 2 of the API. Version 2 keeps the same set of features as version 1, but service coding has changed, breaking backward compatibility.
2015-12-04
Added documentation about ad valorem insurance. No compatibility issues.
2014-01-15
Added documentation about tracking.