NAV Navbar
Logo
curl

Introduction

The Fleeters.io API is organized around REST and permits to create an retrieve resources of your Fleeters.io environment.

We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API requests and responses, including errors.

Topics

Environments

To make the API as explorable as possible, two environments are available :

URL strategy

API endpoint

'https://rest.api.fleeters-preprod.io'

The API endpoints URL are constructed with this following pattern : endpoint/resource/service/{optionalParameter}

Finally, the verb of HTTP method (GET, PUT, POST, DELETE) is necessary to get the complete URL.

If we use the previous example, Get availabilities use the HTTP verb GET.
Thus, the final URL will be :

GET https://rest.api.fleeters-preprod.io/informations/availabilities/{postalCode}

IMPORTANT : both HTTP and HTTPS protocols are supported. If you have some problem with HTTPS connection (certificate, proxy, etc…) you can use the HTTP insecure protocol.

Authentication

Example request with URL parameters

$ curl --request GET \ 
       --url 'https://rest.api.fleeters-preprod.io/informations/availabilities?accessKeyId=YouAccessKeyId&secretAccessKey=YouSecretAccessKey'

Example request for HTTP headers

$ curl --request GET \ 
       --url 'https://rest.api.fleeters-preprod.io/informations/availabilities' \
       --header 'Access-Key-Id: YouAccessKeyId' \
       --header 'Secret-Access-Key: YouSecretAccessKey'

Authenticate your account when using the API by including your secret accessKeyId and secretAccessKey.

You can manage your API keys on Fleeters Dashboard at url http://dashboard.fleeters-preprod.io. If you don’t have an account, you can sign up for a developer key here.

Your API keys carry many privileges, so be sure to keep them secret ! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Then you need to provide the unique ID (accessKeyId) and the secret key (secretAccessKey) every time you have to request the REST API methods, using one of these two methods :

Feel free to implement the prefered method based on your own obligations.

Errors

Fleeters API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an technical error with Fleeters servers (these are rare).

Each service contains his own specific error codes, and the general error codes are describe bellow.

Error name HTTP status Code Description
internal_error 500
Internal Server Error
Internal server error
not_found 404
Not found
No service found for request URL
not_implemented 404
Not found
Not implemented, available in further release
request_content_type_invalid 400
Bad Request
Invalid request content type, header “Content-Type” is probably not specified with value “application/json”
access_key_id_missing 401
Unauthorized
The Access Key is missing
secret_access_key_missing 401
Unauthorized
The Secret Access Key is missing
credentials_invalid 401
Unauthorized
Invalid credential, Access Key Id or/and Secret Access Key is/are invalid
not_sufficient_rights_invalid 401
Unauthorized
Authenticated API account has not sufficient rights
account_blocked 403
Forbidden
Authenticated API account is blocked
invalid_json 400
Bad Request
Json request content is not valid

Date and time format

Fleeters API uses conventional Epoch timestamp (how much miliseconds passed from the 1st of January 1970 at 00:00:00 UTC) to be able to manage requests on multiple time zones across the world.

For example, an order delivery start timestamp for Sunday, 21 May 2:00 PM in Europe/Paris which give the value of 1495368000. This value is different depending time zone :

Time zone Value
Europe/Paris Sunday May 21, 2017 14:00:00 (PM)
America/Los Angeles Sunday May 21 2017 05:00:00 (AM)

Units of measure

Fleeters API uses international standard units, except the distance witch is defined in kilometers.

Units used by the REST API are described below :

Time zone Value
Dimensions package dimensions are defined in meters
Weight package weight is defined in kilograms
Distance the distance for an order is defined in kilometers
Duration the duration for an order is defined in seconds

Content type

Example request

$ curl --request GET \ 
       --url 'https://rest.api.fleeters-preprod.io/informations/version' \
       --header 'content-type: application/json'

Fleeters API uses JSON for requests and responses, so all HTTP requests must specify content-type header with value application/json.

All JSON responses will be encoded in UTF-8, so response header content-type is defined with value application/json; charset=utf-8.

Pagination

Example request

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/orders?limit=10&startingAfter=591b1ab3cde8190b67000001' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

All top-level API resources have support for bulk fetches via “list” API methods. For instance you can list vehicles types, packages types and orders.

These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before. Fleeters utilizes cursor-based pagination via the starting_after and ending_before parameters.

Both take an existing object ID value (see below) and return objects in reverse chronological order.

Parameters

Name Description
limit
optional, default is 10
A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.
starting_after
optional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before
optional
A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

List reponse format

Attribute name Type Description
hasMore boolean Whether or not there are more elements available after this set. If false, this set comprises the end of the list.
data array An array containing the actual response elements, paginated by any request parameters

Errors

Pagination contains own specific error codes, describe bellow.

Error name HTTP status Code Description
pagination_starting_after_invalid 400
Bad Request
Pagination starting_after parameter is invalid
pagination_ending_before_invalid 400
Bad Request
Pagination ending_before parameter is invalid

Auto-pagination

Most of our libraries support auto-pagination. This feature easily handles fetching large lists of resources without having to manually paginate results and perform subsequent requests. Since curl simply emits raw HTTP requests, it doesn’t support auto-pagination.

Versioning

Example request

$ curl --request GET \ 
       --url 'https://rest.api.fleeters-preprod.io/informations/version' \
       --header 'Fleeters-Version: v1'

When we make backwards-incompatible changes to the API, we release new, annotated versions. The current version is v1. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests will use the version configured with your API account (API key). The changelog lists every available version.

To set the API version manually and on a specific request, send a Fleeters-Version header.

You can visit your Dashboard at url http://dashboard.fleeters-preprod.io to change or upgrade the API version associated with your API key. As a precaution, use API versioning to test a new API version on test environment (preproduction) before committing to an upgrade.

General API

With this API you can general information about :

Get status

Example request

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/general/status' \
       --header 'content-type: application/json'

Example response

{
  "environment": "PREPRODUCTION",
  "status": "OK"
}

Returns the current REST API status.

Request

GET https://rest.api.fleeters-preprod.io/general/status

Response

Attribute name Type Description
environment String Environment name
status String Status of API (OK or KO)

Get version

Example request

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/general/version' \
       --header 'content-type: application/json'

Example response

{
  "buildDate" : "22/05/2017 10:11:42 +02:00",
  "buildVersion" : "1.1.2",
  "apiVersion" : "v1"
}

Returns current API version.

Request

GET https://rest.api.fleeters-preprod.io/general/version

Response

Attribute name Type Description
buildDate String Build date
buildVersion String Build version
apiVersion String API version

Vehicles types API

With this API, you can :

You can manage your vehicles types on Fleeters Dashboard at url http://dashboard.fleeters-preprod.io. If you don’t have an account, you can sign up for a developer key here.

The vehicle type object

Attribute name Type Description
id String Unique technical identifier
companyId String Id of company associated with vehicle
name String Name of vehicle
maxLength double Max length capacity of vehicle (in meters)
maxWidth double Max width capacity of vehicle (in meters)
maxHeight double Max height capacity of vehicle (in meters)
maxWeight double Max weight capacity of vehicle (in kilograms)

List all vehicles types

Example request

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/vehicles_types?limit=2' \
       --header 'Access-Key-Id: YouAccessKeyId' \
       --header 'Secret-Access-Key: YouSecretAccessKey' \
       --header 'content-type: application/json'

Example response

{
  "hasMore": true,
  "data": 
  [
      {
        "id": "58b44f75b3e1460008c50cef",
        "companyId": "58af79b621b366000724ef80",
        "name": "Moto",
        "maxWidth": 0.4,
        "maxLength": 0.4,
        "maxHeight": 0.4,
        "maxWeight": 4.0
      },
      {
         "id": "58b44f75b3e1460008c50ceg",
         "companyId": "58af79b621b366000724ef80",
         "name": "Utilitaire",
         "maxWidth": 2.0,
         "maxLength": 2.0,
         "maxHeight": 2.0,
         "maxWeight": 800.0
      }
  ]
}

Returns the list of vehicle types.

Request

GET https://rest.api.fleeters-preprod.io/vehicles_types

Parameters

Name Description
limit
optional
A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.
starting_after
optional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before
optional
A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

Response

A dictionary with a data property that contains an array of up to limit vehicles types, starting after vehicle type starting_after. Each entry in the array is a separate Vehicle type object. If no more vehicles types are available, the resulting array will be empty.

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
pagination_starting_after_invalid 400
Bad Request
Pagination starting_after parameter is invalid
pagination_ending_before_invalid 400
Bad Request
Pagination ending_before parameter is invalid

Packages types API

With this API, you can :

You can manage your packages types on Fleeters Dashboard at url http://dashboard.fleeters-preprod.io. If you don’t have an account, you can sign up for a developer key here.

The package type object

Attribute name Type Description
id String Unique technical identifier
companyId String Id of company associated with package type
name String Name of package type
maxLength double Max length of package type (in meters)
maxWidth double Max width of package type (in meters)
maxHeight double Max height pf package type (in meters)
maxWeight double Max weight of package type (in kilograms)

List all packages types

Example request

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/packages_types?limit=3' \
       --header 'Access-Key-Id: YouAccessKeyId' \
       --header 'Secret-Access-Key: YouSecretAccessKey' \
       --header 'content-type: application/json'

Example response

{
  "hasMore": false,
  "data": 
  [
      {
        "id": "58b44f75b3e1460008c50cef",
        "companyId": "58af79b621b366000724ef80",
        "name": "Petit colis",
        "maxWidth": 0.4,
        "maxLength": 0.3,
        "maxHeight": 0.2,
        "maxWeight": 4.0
      },
      {
        "id": "58b44f75b3e1460008c50ceg",
        "companyId": "58af79b621b366000724ef80",
        "name": "Moyen colis",
        "maxWidth": 1.0,
        "maxLength": 0.5,
        "maxHeight": 0.5,
        "maxWeight": 300.0
      },
      {       
        "id": "58b44f75b3e1460008c50ceh",
        "companyId": "58af79b621b366000724ef80",
        "name": "Grand colis",
        "maxWidth": 1.5,
        "maxLength": 1.5,
        "maxHeight": 1.5,
        "maxWeight": 600.0
      }
  ]
}

Returns the list of packages types.

Request

GET https://rest.api.fleeters-preprod.io/packages_types

Parameters

Name Description
limit
optional
A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.
starting_after
optional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before
optional
A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

Response

A dictionary with a data property that contains an array of up to limit packages types, starting after package type starting_after. Each entry in the array is a separate Package type object. If no more packages types are available, the resulting array will be empty.

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
pagination_starting_after_invalid 400
Bad Request
Pagination starting_after parameter is invalid
pagination_ending_before_invalid 400
Bad Request
Pagination ending_before parameter is invalid

Orders API

In Fleeters, an order can be a delivery, a carrier course, etc.

You can create and retrieve individual orders, as well as list all orders. Orders are identified by a unique random ID and tracking reference.

With this API, you can :

The order object

Attribute name Type Description
id String Unique technical identifier
trackingReference String Delivery tracking reference
customerReference String Customer own tracking reference
status Order status Delivery status
ownerCompanyName String Name of owner company (the ordering customer)
vehicleTypeId String Identifier of vehicle type (if the order has a driver from another company, this id would reference a vehicle type they have created, so it is hidden)
vehicleTypeName String Name of vehicle type
creationTimestamp long Date and time of creation of the order (timestamp)
updateTimestamp long Date and time of last order update (timestamp)
distance double Estimated distance of the delivery, corresponding to the most optimized path (not used for the moment)
duration double Estimated duration of the delivery, based on the most optimized route (not used for the moment)
price double You can indicate how much your customer was charged here, and use this for accounting later. Only you can see the price you set, your customers and subcontractors may see a different price.
deliveryStartTimestamp long Date and time of the beginning of the delivery schedule slot (timestamp)
deliveryEndTimestamp long Date and time of the end of the delivery time slot (timestamp)
notes String Specific delivery notes
pickupContact Contact object Pickup contact
deliveryContact Contact object Delivery contact
driverCompanyName String Name of company this order was dispatched to
carrierPhoneNumber String Phone number of the company in charge of the delivery (it may be different from the company this order was dispatched to). This field was named driverCompanyPhoneNumber previously, but that name is now deprecated. We currently provide the information under both names, to ensure backwards compatibility.
driverAccountName String First name and last name of driver. Only the first name appears if the driver is from another company than yours.
driverAccountEmail String Email of driver (only shown if the driver is a user your company created)
driverPhoneNumber String Phone number of driver. It is only shown while the order is in progress, so from the DRIVER_ASSIGNED state to either the FINISHED, the CANCELLED or the FAILED state.
driverLocation Location object GPS coordinates of driver (only if status is “ARRIVE_PICKUP_SITE” or “ARRIVE_DELIVERY_SITE”)
trackingEvents List of Tracking event object Tracking history
trackingUrl String Public link to track order, can be used for final customers
packages List of Package object Packaging
returnToSender Boolean If set to true, the driver will receive three tasks (pick up, deliver, return) instead of two (pick up, deliver)
progress Integer Percentage of progress of the order, between 0 and 100. Read-only property calculated from the order’s status.
disableTaskOptimization Boolean Ensure that tasks of order are subsequent and grouped, and not mixed with others orders tasks (read Create an order for more information)
metadata Map of <String, String> Custom metadata , a dictionary of key and values of type string, to store and share custom information

The order statuses

Status Description
PENDING_PAYMENT The order was created but a payment is required
SCHEDULED The order is scheduled and waiting to start
HIRING_DRIVER The order is starting and matching to the most efficient available driver
CARRIER_ASSIGNED The order is accepted or assigned to a carrier company, but no driver is assigned
DRIVER_ASSIGNED The order is accepted or assigned to a driver and paused until the driver start the pickup or delivery process
ARRIVE_PICKUP_SITE The driver is “en route” to the pickup location
PICKED_UP The order is picked up and paused until the driver start the delivery process.
ARRIVE_DELIVERY_SITE The driver is “en route” to the delivery location
DELIVERED The order is delivered and paused until the driver starts the planned return
RETURN_TO_SENDER The order has started to return the packages after a delivery failure
FINISHED The order pickup and/or delivery process is finished successfully
CANCELLED The order is cancelled by the customer or the driver company
FAILED The order is failed. If it has failed after the pick up, the driver will have to return the packages to the sender
RETURNED The order is returned to the sender

The order lifecycles

In Fleeters, orders are flexible objects that can handle a variety of different scenarii.

Each scenario will result in a slightly different lifecycle, meaning the order will go through different statuses.

Classic order lifecycle

This scenario occurs when the order’s pickupContact and deliveryContact fields are complete.

After the order is created, and a driver assigned, that driver will receive two tasks: a pick up step, and a delivery step.

The driver has to manually start each of those steps using the Fleeters mobile application. Each step is made up of two statuses (not started yet/started).

If the driver indicates that the delivery step failed, a new return step will automatically be generated. If that return step fails, no new return step will be generated. Note that this is different from a planned return step.

At any point, unless the order has failed or has finished already, the driver’s company can cancel it.

Alternate lifecycle: Pickup only

This scenario occurs when the order’s pickupContact field is left blank.

The PICKED_UP and ARRIVE_DELIVERY_SITE statuses are skipped.

Alternate lifecycle: Delivery only

This scenario occurs when the order’s deliveryContact field is left blank.

The ARRIVE_PICKUP_SITE and PICKED_UP statuses are skipped, and no return step will be generated if the delivery step fails.

Alternate lifecycle: Planned return

This scenario occurs when the order’s pickupContact and deliveryContact fields are complete, and the returnToSender flag is set to true.

As you can see below, the order will receive the ARRIVE_PICKUP_SITE twice, since the driver will have to return to the pickup location.

You can differentiate between the two by checking the order’s tracking events. If an event with the DELIVERED type is present, the driver is currently returning to the pickup location.

Estimate an order

Example request

$ curl --request POST --url 'https://rest.api.fleeters-preprod.io/orders' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json' \
 --data '
   {
     "vehicleTypeId": "58e3778887a73d0ecd000001",
     "pickupContact":
     {
       "address":
       {
          "formattedAddress" : "102 Boulevard du montparnasse 75014 Paris",
       }       
     },
     "deliveryContact":
     {
       "address":
       {
         "location" :
         {
           "latitude" : 48.853081,
           "longitude" : 2.353388
         }
       }
     }
     "deliveryStartTimestamp": 1442916000000,
     "deliveryEndTimestamp": 1442926800000
   }'

Example response

{
  "vehicleTypeId" : "58e3778887a73d0ecd000001",
  "vehicleTypeName" : "Moto",
  "distance" : 4.780,
  "duration" : 2700,
  "price" : 6.5,
  "priceWithTaxes" : 7.8,
  "deliveryStartTimestamp" : 1442916000000,
  "deliveryEndTimestamp" : 1442926800000,
  "pickupInformations":
  {
    "address":
    {
      "streetNumber": "102",
      "route": "BOULEVARD DU MONTPARNASSE",
      "locality": "PARIS",
      "postalCode": "75014",
      "country": "FRANCE",
      "formattedAddress" : "102 BOULEVARD DU MONTPARNASSE, 75014 PARIS, FRANCE",
      "location" :
      {
        "latitude" : 48.84234,
        "longitude" : 2.328129
      }
    }       
  },
  "deliveryInformations":
  {
    "address":
    {
      "streetNumber": "55",
      "route": "QUAI DE BOURBON",
      "locality": "PARIS",
      "postalCode": "75004",
      "country": "FRANCE",
      "formattedAddress" : "55 QUAI DE BOURBON, 75004 PARIS, FRANCE",
      "location" :
      {
        "latitude" : 48.853081,
        "longitude" : 2.353388
      }
    }
  }
}

Estimate an order to get price.

Important : this service is not implemented for the moment and will be available in further release.

Request

POST https://rest.api.fleeters-preprod.io/orders/estimate

Response

An Order with :

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
request_json_content_invalid 400
Bad Request
Invalid JSON content
vehicle_type_id_invalid 400
Bad Request
Vehicle type id is invalid
vehicle_type_not_found 400
Bad Request
No vehicle type found with id
customer_reference_already_exist 400
(Bad Request)
Customer reference already exist
pickup_address_invalid 400
(Bad Request)
Pickup address is invalid : location field, formatted address field, or all other address fields must be defined
pickup_location_invalid_geocode 400
(Bad Request)
Pickup address is invalid : location can’t be geocoded
pickup_formatted_address_invalid_geocode 400
(Bad Request)
Pickup address is invalid : formatted address can’t be geocoded
pickup_address_components_invalid_geocode 400
(Bad Request)
Pickup address is invalid : address components can’t be geocoded
delivery_address_invalid 400
(Bad Request)
Delivery address is invalid : location field, formatted address field, or all other address fields must be defined
delivery_location_invalid_geocode 400
(Bad Request)
Delivery address is invalid : location can’t be geocoded
delivery_formatted_address_invalid_geocode 400
(Bad Request)
Delivery address is invalid : formatted address can’t be geocoded
delivery_address_components_invalid_geocode 400
(Bad Request)
Delivery address is invalid : address components can’t be geocoded
delivery_start_timestamp_invalid 400
(Bad Request)
Delivery start timestamp is invalid
delivery_end_timestamp_invalid 400
(Bad Request)
Delivery end timestamp is invalid
delivery_start_timestamp_not_future 400
(Bad Request)
Delivery start timestamp is not in future
delivery_end_timestamp_not_after_start_timestamp 400
(Bad Request)
Delivery end timestamp is not after start timestamp

Create an order

Example request

$ curl --request POST --url 'https://rest.api.fleeters-preprod.io/orders' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json' \
 --data '
   { 
       "customerReference": "1234XYZ",
       "packages":
       [
         {
           "packageTypeId": "59a802c90fdd9f3df792c25d",
           "quantity": 2
         },
         {           
           "name": "A custom package",
           "quantity": 1,
           "length": 0.4,
           "width": 0.3,
           "height": 0.1,
           "weight": 4.5
         }
       ],     
       "vehicleTypeId": "58e3778887a73d0ecd000001",
       "pickupContact":
       {
           "name": "John DOE",
           "company": "Awesome Company",
           "phoneNumber": "0612345678",
           "email": "john.doe@example.com",
           "address":
           {
              "location":
              {
                 "latitude": 48.8530818,
                 "longitude": 2.3533905
              }
           }       
       },
       "deliveryContact":
       {
           "name": "Jane DOE",
           "phoneNumber": "0698765432",
           "email": "jane.doe@example.com",
           "additionalInformation": "Deposit to neighbour if absent",
           "address":
           {
              "formattedAddress": "102 Boulevard du Montparnasse, 75014 Paris, France"
           }
       },
       "deliveryStartTimestamp": 1504857600000,
       "deliveryEndTimestamp": 1504857601000,
       "notes" : "No specific information about order",
       "returnToSender" : true,
       "price" : 15.0,
       "metadata":
       {
            "custom_key": "custom_value"
       }
   }'

Example response

{
  "id" : "554f8a092027ae914a1771c6",
  "trackingReference" : "2NXZMNMEURNQLA70J5T",
  "customerReference" : "1234XYZ",
  "status" : "SCHEDULED",
  "ownerCompanyName" : "Fleeters",
  "packages":
  [
    {
      "packageTypeId": "59a802c90fdd9f3df792c25d",
      "name": "Très petit colis",
      "quantity": 2,
      "length": 0.4,
      "width": 0.3,
      "height": 0.2,
      "weight": 4
    },
    {      
      "name": "A custom package",
      "quantity": 1,
      "length": 0.4,
      "width": 0.3,
      "height": 0.1,
      "weight": 4.5
    }
  ],       
  "vehicleTypeId" : "58e3778887a73d0ecd000001",
  "vehicleTypeName" : "Moto",
  "creationTimestamp" : 1502216644907,
  "updateTimestamp" : 1502216644907,
  "notes": "No specific information about order",
  "deliveryStartTimestamp": 1504857600000,
  "deliveryEndTimestamp": 1504857601000,
  "pickupContact":
  {
      "name": "John DOE",
      "company": "Awesome Company",
      "phoneNumber": "+33612345678",
      "email": "john.doe@example.com",
      "additionalInformation": "john.doe@example.com",
      "address":
      {
          "streetNumber": "55",
          "route": "Quai de Bourbon",
          "locality": "Paris",
          "postalCode": "75004",
          "formattedAddress": "55 Quai de Bourbon, 75004 Paris, France",
          "location":
          {
              "latitude": 48.8530818,
              "longitude": 2.3533905
          }
      }
  },
  "deliveryContact":
  {
     "name": "Jane DOE",
     "phoneNumber": "+33698765432",
     "email": "jane.doe@example.com",
     "additionalInformation": "jane.doe@example.com",
     "address":
     {
        "streetNumber": "102",
        "route": "Boulevard du Montparnasse",
        "locality": "Paris",
        "postalCode": "75014",
        "formattedAddress": "102 Boulevard du Montparnasse, 75014 Paris, France",
        "location":
        {
            "latitude": 48.8422598,
            "longitude": 2.3282832
        }
     }
  },
  "distance": 0,
  "duration": 0,
  "price": 0,
  "trackingEvents":
  [
    {
      "id" : "591b2ad5cde8190c434ca9dc", 
      "timestamp" : 1442918731888, 
      "type" : "CREATED"
    }
  ],
  "trackingUrl": "http://dashboard.fleeters-preprod.io/tracking/2NXZMNMEURNQLA70J5T",
  "returnToSender": true,
  "progress": 10,
  "price": 15.0,
  "metadata":
  {
    "custom_key": "custom_value"
  }
}

Create an new order.

Request

POST https://rest.api.fleeters-preprod.io/orders

Order parameters

Name Mandatory / optional Details
deliveryStartTimestamp mandatory deliveryStartTimestamp must be in future
deliveryEndTimestamp mandatory deliveryEndTimestamp must be in future and after deliveryStartTimestamp
pickupContact optional An order can be created without a pickup contact (can be updated later)
deliveryContact optional An order can be created without a pickup contact (can be updated later)
customerReference optional The customer reference must be unique
packages optional A list of packages
vehicleTypeId optional An existing vehicle type id. If vehicleTypId is defined explicitly, it’s override packages most optimized vehicle search (more info below in “Package parameters”)
notes optional Specific delivery notes. Not shown to the driver.
returnToSender optional If set to true, and if pickupContact and deliveryContact are present, a return step will be created
metadata optional Use this to store any data you might need later, that doesn’t already appear in the order object. It is never used by Fleeters.
price optional Must be positive or zero.

Contact parameters

Name Mandatory / optional Details
address mandatory
name optional
company optional
phoneNumber optional
email optional
additionalInformation optional Is displayed in the driver’s mobile application

Address parameters

It is possible to define an address with three different ways. These different ways are classified by priority (highest to lowest):

Only one way is possible, for example if you define GPS coordinate with full formatted address, only GPS coordinates will be used. Each address is geocoded and verified, so all fields returned in each address object in response will be valid and defined.

Package parameters

Name Mandatory / optional Details
quantity mandatory
packageTypeId optional
name optional Ignored if packageTypeId defined
length optional Ignored if packageTypeId defined
width optional Ignored if packageTypeId defined
height optional Ignored if packageTypeId defined
weight optional Ignored if packageTypeId defined

It is possible to define a package with two different ways. These different ways are classified by priority (highest to lowest):

If field packageTypeId is defined, the corresponding package type will be used, other fields will be ignored. Otherwise, a custom package will be defined for this order.

Important - 1 : if order contains packages but vehicleTypeId not defined explicitly, the most optimized vehicle type will be automatically assigned to order.

Important - 2 : By default, Fleeters optimizes the driver’s route as much as possible, which means that several tasks from multiple orders are mixed to get the best optimized route, and the driver can have subsequent tasks from different orders. If flag disableTaskOptimization is set to true for an order, the Fleeters route optimizer will ensure that tasks of this order are subsequent and grouped, and not mixed with others orders tasks. Notice that :

Response

An Order with :

Important : price, duration and distance are not implemented for the moment and available in further release.

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
request_json_content_invalid 400
Bad Request
Invalid JSON content
vehicle_type_id_invalid 400
Bad Request
Vehicle type id is invalid
vehicle_type_not_found 400
Bad Request
No vehicle type found with id
customer_reference_already_exist 400
(Bad Request)
Customer reference already exist
pickup_address_invalid 400
(Bad Request)
Pickup address is invalid : location field, formatted address field, or all other address fields must be defined
pickup_location_invalid_geocode 400
(Bad Request)
Pickup address is invalid : location can’t be geocoded
pickup_formatted_address_invalid_geocode 400
(Bad Request)
Pickup address is invalid : formatted address can’t be geocoded
pickup_address_components_invalid_geocode 400
(Bad Request)
Pickup address is invalid : address components can’t be geocoded
delivery_address_invalid 400
(Bad Request)
Delivery address is invalid : location field, formatted address field, or all other address fields must be defined
delivery_location_invalid_geocode 400
(Bad Request)
Delivery address is invalid : location can’t be geocoded
delivery_formatted_address_invalid_geocode 400
(Bad Request)
Delivery address is invalid : formatted address can’t be geocoded
delivery_address_components_invalid_geocode 400
(Bad Request)
Delivery address is invalid : address components can’t be geocoded
delivery_start_timestamp_invalid 400
(Bad Request)
Delivery start timestamp is invalid
delivery_end_timestamp_invalid 400
(Bad Request)
Delivery end timestamp is invalid
delivery_start_timestamp_not_future 400
(Bad Request)
Delivery start timestamp is not in future
delivery_end_timestamp_not_after_start_timestamp 400
(Bad Request)
Delivery end timestamp is not after start timestamp
missing_contact_information 400
(Bad Request)
The returnToSender flag is enabled, but the order has no pickupContact and/or no deliveryContact
invalid_price 400
(Bad Request)
The price you provided was negative

Retrieve an order

Example request with id

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/orders/554f8a092027ae914a1771c6' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

Example request with tracking reference

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/orders/2NXZMNMEURNQLA70J5T' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

Example request with customer reference

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/orders/1234XYZ' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

Example response

{
  "id" : "554f8a092027ae914a1771c6",
  "trackingReference" : "2NXZMNMEURNQLA70J5T",
  "customerReference" : "1234XYZ",
  "status" : "SCHEDULED",
  "ownerCompanyName" : "Fleeters",
  "packages":
  [
    {
      "packageTypeId": "59a802c90fdd9f3df792c25d",
      "name": "Très petit colis",
      "quantity": 2,
      "length": 0.4,
      "width": 0.3,
      "height": 0.2,
      "weight": 4
    },
    {      
      "name": "A custom package",
      "quantity": 1,
      "length": 0.4,
      "width": 0.3,
      "height": 0.1,
      "weight": 4.5
    }
  ],         
  "vehicleTypeId" : "58e3778887a73d0ecd000001",
  "vehicleTypeName" : "Moto",
  "creationTimestamp" : 1502216644907,
  "updateTimestamp" : 1502216644907,
  "notes": "No specific information about order",
  "deliveryStartTimestamp": 1504857600000,
  "deliveryEndTimestamp": 1504857601000,
  "pickupContact":
  {
      "name": "John DOE",
      "company": "Awesome Company",
      "phoneNumber": "+33612345678",
      "email": "john.doe@example.com",
      "additionalInformation": "john.doe@example.com",
      "address":
      {
          "streetNumber": "55",
          "route": "Quai de Bourbon",
          "locality": "Paris",
          "postalCode": "75004",
          "formattedAddress": "55 Quai de Bourbon, 75004 Paris, France",
          "location":
          {
              "latitude": 48.8530818,
              "longitude": 2.3533905
          }
      }
  },
  "deliveryContact":
  {
     "name": "Jane DOE",
     "phoneNumber": "+33698765432",
     "email": "jane.doe@example.com",
     "additionalInformation": "jane.doe@example.com",
     "address":
     {
        "streetNumber": "102",
        "route": "Boulevard du Montparnasse",
        "locality": "Paris",
        "postalCode": "75014",
        "formattedAddress": "102 Boulevard du Montparnasse, 75014 Paris, France",
        "location":
        {
            "latitude": 48.8422598,
            "longitude": 2.3282832
        }
     }
  },
  "distance": 0,
  "duration": 0,
  "price": 0,
  "trackingEvents":
  [
    {
      "id" : "591b2ad5cde8190c434ca9dc", 
      "timestamp" : 1442918731888, 
      "type" : "CREATED"
    }
  ],
  "trackingUrl": "http://dashboard.fleeters-preprod.io/tracking/2NXZMNMEURNQLA70J5T",
  "returnToSender": false,
  "progress": 13,
  "metadata":
  {
    "custom_key": "custom_value"
  }
}

Retrieves an order with the given id, tracking reference or customer reference.

Request

GET https://rest.api.fleeters-preprod.io/orders/{id}

GET https://rest.api.fleeters-preprod.io/orders/{trackingReference}

GET https://rest.api.fleeters-preprod.io/orders/{customerReference}

Response

An Order with :

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
order_not_found 400
(Bad Request)
No order found with id, tracking reference or customer reference

Update an order

Example request

$ curl --request PUT --url 'https://rest.api.fleeters-preprod.io/orders/2NXZMNMEURNQLA70J5T' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json' \
 --data '
   { 
       "customerReference": "UpdatedCustomerReference",
       "packages":
       [
         {
           "packageTypeId": "59a802c90fdd9f3df792c25d",
           "quantity": 2
         },
         {           
           "name": "A custom package",
           "quantity": 1,
           "length": 0.4,
           "width": 0.3,
           "height": 0.1,
           "weight": 4.5
         }
       ],       
       "vehicleTypeId": "58e3778887a73d0ecd000002",
       "pickupContact":
       {
           "name": "Updated name",
           "company": "Updated Company",
           "phoneNumber": "Update phone number",
           "email": "updated.email@example.com",
           "additionalInformation": "Updated additional information",
           "address":
           {
                "location":
               {
                   "latitude" : 48.862743,
                   "longitude" : 2.335284
               }
           }       
       },
       "deliveryContact":
       {
           "address":
           {
                "formattedAddress": "46 rue rené clair, 75018 Paris, France"
           }
       },
       "deliveryStartTimestamp": 1536393600000,
       "deliveryEndTimestamp": 1536400800000,
       "notes" : "Updated notes",
       "returnToSender": false,
       "price": 15.0,
       "metadata":
       {
           "custom_key": "custom_value"
       }
   }'

Example response

{
  "id" : "554f8a092027ae914a1771c6",
  "trackingReference" : "2NXZMNMEURNQLA70J5T",
  "customerReference" : "UpdatedCustomerReference",
  "status" : "SCHEDULED",
  "ownerCompanyName" : "Fleeters",
  "packages":
  [
    {
      "packageTypeId": "59a802c90fdd9f3df792c25d",
      "name": "Très petit colis",
      "quantity": 2,
      "length": 0.4,
      "width": 0.3,
      "height": 0.2,
      "weight": 4
    },
    {      
      "name": "A custom package",
      "quantity": 1,
      "length": 0.4,
      "width": 0.3,
      "height": 0.1,
      "weight": 4.5
    }
  ],
  "vehicleTypeId" : "58e3778887a73d0ecd000002",
  "vehicleTypeName" : "Van",
  "creationTimestamp" : 1502216644907,
  "updateTimestamp" : 1502216644907,
  "notes": "No specific information about order",
  "deliveryStartTimestamp": 1536393600000,
  "deliveryEndTimestamp": 1536400800000,
  "pickupContact":
  {
      "name": "Updated name",
      "company": "Updated Company",
      "phoneNumber": "Update phone number",
      "email": "updated.email@example.com",
      "additionalInformation": "Updated additional information",
      "address":
      {
          "streetNumber": "172a",
          "route": "Rue de Rivoli",
          "locality": "Paris",
          "postalCode": "75001",
          "formattedAddress": "172a Rue de Rivoli, 75001 Paris, France",
          "location":
          {
              "latitude": 48.86275939999999,
              "longitude": 2.3354788
          }
      }
  },
  "deliveryContact":
  {
      "address":
      {
          "streetNumber": "46",
          "route": "Rue René Clair",
          "locality": "Paris",
          "postalCode": "75018",
          "formattedAddress": "46 Rue René Clair, 75018 Paris, France",
          "location":
          {
              "latitude": 48.8939624,
              "longitude": 2.3540829
          }
      }
  },
  "distance": 0,
  "duration": 0,
  "price": 15.0,
  "trackingEvents":
  [
    {
      "id" : "591b2ad5cde8190c434ca9dc", 
      "timestamp" : 1442918731888, 
      "type" : "CREATED"
    }
  ],
  "trackingUrl": "http://dashboard.fleeters-preprod.io/tracking/2NXZMNMEURNQLA70J5T",
  "returnToSender": false,
  "metadata":
  {
    "custom_key": "custom_value"
  }
}

Update an existing order with the given id, tracking reference or customer reference.

Request

PUT https://rest.api.fleeters-preprod.io/orders/{id}

PUT https://rest.api.fleeters-preprod.io/orders/{trackingReference}

PUT https://rest.api.fleeters-preprod.io/orders/{customerReference}

Order parameters

Name Mandatory / optional Details
deliveryStartTimestamp optional deliveryStartTimestamp must be in future
deliveryEndTimestamp optional deliveryEndTimestamp must be in future and after deliveryStartTimestamp
pickupContact optional
deliveryContact optional
customerReference optional The customer reference must be unique
packages optional A list of packages
vehicleTypeId optional An existing vehicle type id. If vehicleTypId is defined explicitly, it’s override packages most optimized vehicle search (more info below in “Package parameters”)
notes optional
metadata optional All previous metadata will be replace by new one
price optional Must be positive or zero.

Contact parameters

Name Mandatory / optional Details
address mandatory
name optional
company optional
phoneNumber optional
email optional

Address parameters

It is possible to define an address with three different ways. These different ways are classified by priority (highest to lowest):

Only one way is possible, for example if you define GPS coordinate with full formatted address, only GPS coordinates will be used. Each address is geocoded and verified, so all fields returned in each address object in response will be valid and defined.

Package parameters

Name Mandatory / optional Details
quantity mandatory
packageTypeId optional
name optional Ignored if packageTypeId defined
length optional Ignored if packageTypeId defined
width optional Ignored if packageTypeId defined
height optional Ignored if packageTypeId defined
weight optional Ignored if packageTypeId defined

It is possible to define a package with two different ways. These different ways are classified by priority (highest to lowest):

If field packageTypeId is defined, the corresponding package type will be used, other fields will be ignored. Otherwise, a custom package will be defined for this order.

Important : if order contains packages but vehicleTypeId not defined explicitly, the most optimized vehicle type will be automatically assigned to order.

Response

The updated Order.

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
order_not_found 400
(Bad Request)
No order found with id, tracking reference or customer reference
order_cant_be_updated 400
(Bad Request)
Order can’t be updated (for example, only carrier company can update an order which is affected to a driver)
invalid_price 400
(Bad Request)
The price you provided was negative

Cancel an order

Example request with id

$ curl --request POST --url 'https://rest.api.fleeters-preprod.io/orders/554f8a092027ae914a1771c6/cancel' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

Example request with tracking reference

$ curl --request POST --url 'https://rest.api.fleeters-preprod.io/orders/2NXZMNMEURNQLA70J5T/cancel' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

Example request with customer reference

$ curl --request POST --url 'https://rest.api.fleeters-preprod.io/orders/1234XYZ/cancel' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

Example response

{
  "id" : "554f8a092027ae914a1771c6",
  "trackingReference" : "2NXZMNMEURNQLA70J5T",
  "customerReference" : "1234XYZ",
  "status" : "SCHEDULED",
  "ownerCompanyName" : "Fleeters",
  "vehicleTypeId" : "58e3778887a73d0ecd000001",
  "vehicleTypeName" : "Moto",
  "creationTimestamp" : 1502216644907,
  "updateTimestamp" : 1502216644907,
  "notes": "No specific information about order",
  "deliveryStartTimestamp": 1504857600000,
  "deliveryEndTimestamp": 1504857601000,
  "pickupContact":
  {
      "name": "John DOE",
      "company": "Awesome Company",
      "phoneNumber": "+33612345678",
      "email": "john.doe@example.com",
      "additionalInformation": "john.doe@example.com",
      "address":
      {
          "streetNumber": "55",
          "route": "Quai de Bourbon",
          "locality": "Paris",
          "postalCode": "75004",
          "formattedAddress": "55 Quai de Bourbon, 75004 Paris, France",
          "location":
          {
              "latitude": 48.8530818,
              "longitude": 2.3533905
          }
      }
  },
  "deliveryContact":
  {
     "name": "Jane DOE",
     "phoneNumber": "+33698765432",
     "email": "jane.doe@example.com",
     "additionalInformation": "jane.doe@example.com",
     "address":
     {
        "streetNumber": "102",
        "route": "Boulevard du Montparnasse",
        "locality": "Paris",
        "postalCode": "75014",
        "formattedAddress": "102 Boulevard du Montparnasse, 75014 Paris, France",
        "location":
        {
            "latitude": 48.8422598,
            "longitude": 2.3282832
        }
     }
  },
  "distance": 0,
  "duration": 0,
  "price": 0,
  "trackingEvents":
  [
    {
      "id" : "591b2ad5cde8190c434ca9dc", 
      "timestamp" : 1442918731888, 
      "type" : "CREATED"
    },
    {
      "id" : "591b2ad5cde8190c434ca9dd", 
      "timestamp" : 144291891888, 
      "type" : "CANCELLED"
    }
  ],
  "trackingUrl": "http://dashboard.fleeters-preprod.io/tracking/2NXZMNMEURNQLA70J5T",
  "returnToSender": false
}

Cancel an existing order with the given id, tracking reference or customer reference.

Request

POST https://rest.api.fleeters-preprod.io/orders/{id}/cancel

POST https://rest.api.fleeters-preprod.io/orders/{trackingReference}/cancel

POST https://rest.api.fleeters-preprod.io/orders/{customerReference}/cancel

Response

The cancelled Order.

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
order_not_found 400
(Bad Request)
No order found with id, tracking reference or customer reference
order_cant_be_cancelled 400
(Bad Request)
Order can’ be cancelled (for example, only carrier company can cancel an order which is affected to a driver)

List all orders

$ curl --request GET --url 'https://rest.api.fleeters-preprod.io/orders?limit=1' \
 --header 'Access-Key-Id: YouAccessKeyId' \
 --header 'Secret-Access-Key: YouSecretAccessKey' \
 --header 'content-type: application/json'

Example response

{
  "hasMore": true,
  "data": 
  [
     {
       "id" : "554f8a092027ae914a1771c6",
       "trackingReference" : "2NXZMNMEURNQLA70J5T",
       "customerReference" : "1234XYZ",
       "status" : "SCHEDULED",
       "ownerCompanyName" : "Fleeters",
       "packages":
       [
          {
            "packageTypeId": "59a802c90fdd9f3df792c25d",
            "name": "Très petit colis",
            "quantity": 2,
            "length": 0.4,
            "width": 0.3,
            "height": 0.2,
            "weight": 4
          },
          {      
            "name": "A custom package",
            "quantity": 1,
            "length": 0.4,
            "width": 0.3,
            "height": 0.1,
            "weight": 4.5
          }
       ],  
       "vehicleTypeId" : "58e3778887a73d0ecd000001",
       "vehicleTypeName" : "Moto",
       "creationTimestamp" : 1502216644907,
       "updateTimestamp" : 1502216644907,
       "notes": "No specific information about order",
       "deliveryStartTimestamp": 1504857600000,
       "deliveryEndTimestamp": 1504857601000,
       "pickupContact":
       {
           "name": "John DOE",
           "company": "Awesome Company",
           "phoneNumber": "+33612345678",
           "email": "john.doe@example.com",
           "additionalInformation": "john.doe@example.com",
           "address":
           {
               "streetNumber": "55",
               "route": "Quai de Bourbon",
               "locality": "Paris",
               "postalCode": "75004",
               "formattedAddress": "55 Quai de Bourbon, 75004 Paris, France",
               "location":
               {
                   "latitude": 48.8530818,
                   "longitude": 2.3533905
               }
           }
       },
       "deliveryContact":
       {
          "name": "Jane DOE",
          "phoneNumber": "+33698765432",
          "email": "jane.doe@example.com",
          "additionalInformation": "jane.doe@example.com",
          "address":
          {
             "streetNumber": "102",
             "route": "Boulevard du Montparnasse",
             "locality": "Paris",
             "postalCode": "75014",
             "formattedAddress": "102 Boulevard du Montparnasse, 75014 Paris, France",
             "location":
             {
                 "latitude": 48.8422598,
                 "longitude": 2.3282832
             }
          }
       },
       "distance": 0,
       "duration": 0,
       "price": 0,
       "trackingEvents":
       [
         {
           "id" : "591b2ad5cde8190c434ca9dc", 
           "timestamp" : 1442918731888, 
           "type" : "CREATED"
         }
       ],
       "trackingUrl": "http://dashboard.fleeters-preprod.io/tracking/2NXZMNMEURNQLA70J5T",
      "returnToSender": false,
       "metadata":
       {
         "custom_key": "custom_value"
       }
     }  
  ]
}

Returns the list of orders.

Request

GET https://rest.api.fleeters-preprod.io/orders

Parameters

Name Description
limit
optional
A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.
starting_after
optional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before
optional
A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

Response

A dictionary with a data property that contains an array of up to limit orders, starting after order starting_after. Each entry in the array is a separate Order object. If no more orders are available, the resulting array will be empty.

Error codes

In addition to General errors, the specific following error codes are returned by the service.

Error name HTTP status Code Description
pagination_starting_after_invalid 400
Bad Request
Pagination starting_after parameter is invalid
pagination_ending_before_invalid 400
Bad Request
Pagination ending_before parameter is invalid

WebHook

Use webhooks to be notified about events that happen during order process.

Webhook terminology

An event is an order creation, an order update (when driver start to pickup or delivery an order), or a driver location update. Each occurrence has a corresponding Event object. Webhook endpoint is an unique URL defined by users to which Fleeters sends events. Webhooks refers to the overall concept of sending notifications to webhook endpoints.

Interacting with a third-party API like Fleeters can introduce two problems:

Webhooks solve these problems by letting you register a URL that we will notify anytime an event happens associated with your orders. When the event occurs (for example when an order is delivered), Fleeters creates an Event object. This object contains all the relevant information about what just happened, including the type (order or driver), the event (create or update) and the data associated with that event (the complete updated order object, same result of retrieve an order). Fleeters then sends the Event object to URL of your account’s webhooks settings via an HTTP POST request.

All event types are descibed in WebHook event type section.

When to use webhooks

Webhooks are only necessary for behind-the-scenes delivery process. The results of most Fleeters requests (for example creating or getting an order) are reported synchronously to your code and don’t require webhooks.

When an order is in delivery process by a driver, you can do polling at fixed interval to get status update and driver location.

Sometimes polling are not adapted, and a lot of request are send uselessly to get only few order updates : in this case webhook are perfectly adapted to send only update in asynchronous way.

Configuring your webhook settings

The two most common mistakes with webhooks are providing the wrong URL in the Dashboard and the webhook endpoint not returning a 200 status code. Webhooks are configured inside API REST account settings of the Dashboard :

You can enter any URL you’d like to have events sent to, but this should be a dedicated page on your server, coded per the instructions below. You can have multiple API keys with different Webhook URL.

Receiving webhooks with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, Fleeters will not currently verify if the server is secure (SSL/TLS server certificate) before sending your webhook data.

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code.

Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to Fleeters that you did not receive the webhook.

No retry policy when HTTP status code is differrent of 2xx are currently supported, this feature will be available in further release of REST API.

Best practices

Before going live, test that your webhook is working properly on pre-production by creating test command to receiving webhook create events.

If your webhook script performs complex logic, or makes network calls, it’s possible the script would timeout before Fleeters sees its complete execution. For that reason, you may want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

The webhook event object

Attribute name Type Description
type WebHook event type Type of event
operation WebHook event operation Type of operation
order Order object Order updated object

The webhook event type

Webhook event type Description
ORDER All events concerning order (for example when a new order is created)
DRIVER All events concerning driver activity (for example when driver location is updated and order status is ARRIVE_PICKUP_SITE or ARRIVE_DELIVERY_SITE)

The webhook event operation

Webhook event operation Description
CREATE Create operation (for example when a new order is created)
UPDATE Update operation (for example when an order status was updated)

Types

To be more clear and readable, child object types are described in this section.

The contact object

Attribute name Type Description
name String Name (first name and/or last name)
company String Company name
phoneNumber String Phone number
email String Email
additionalInformation String Additional information, displayed in the driver’s mobile application
address Address object Geographic address

The address object

Attribute name Type Description
streetNumber String Street number
route String Street name
locality String City or locality
postalCode String Postal code
country String Country
formattedAddress String Formatted address
location Location object GPS coordinates

The location object

Attribute name Type Description
latitude double Latitude
longitude double Longitude

The tracking event object

Attribute name Type Description
id String Unique technical identifier of event
timestamp long Date and time of the beginning of the event (timestamp)
type Tracking event type Type of event
errorCode Tracking error code Error code associated is some error occurred during dispatch process. For pure delivery errors, consider
errorMessage String Error message associated with “errorCode”
driverRemark Tracking driver_remark object Driver remark about pickup or delivery step : name of signatory, issue code, etc…
attachments List of Tracking attachment object List of attachments (photo, signatures, etc…)

The tracking driver remark object

Attribute name Type Description
signatoryName String Signatory name which validates pickup or delivery step
signatoryScore double Signatory score about driver (default value is -1.0 if no score is available)
issueCode Tracking driver_remark issue_code Code which indicates anomaly during pickup or delivery step
comments String Comments written by driver during pickup or delivery step

The tracking attachment object

Attribute name Type Description
type Tracking attachment type Type of attachment
url String Photo or signature URL
thumbnailUrl String Photo or signature thumbnail URL

The tracking event type

Tracking event type Description
CREATED Order created
PAYED Order payed
STARTED Order started
ACCEPTED Order accepted by driver or carrier
ASSIGNED Order assigned to a driver (manually or automatically)
PICKUP_STARTED Order pickup step started
PICKUP_STOPPED Order pickup step stopped
PICKUP_FAILED Order pickup step failed
PICKED_UP Order pickup step finished
DELIVERY_STARTED Order delivery step started
DELIVERY_STOPPED Order delivery step stopped
DELIVERY_FAILED Order delivery step failed
DELIVERED Order delivery step finished
RETURN_TO_SENDER_STARTED Order return to sender step started
RETURN_TO_SENDER_STOPPED Order return to sender step stopped
RETURN_FAILED Order return to sender failed
RETURNED Order returned to sender successfully
CANCELLED Order cancelled

The tracking error code

Tracking event error code Description
DISPATCH_WAITING_PAYMENT_EXPIRED Payment delay expired
DISPATCH_NO_ROUTE No route found when dispatching order
DISPATCH_CANCELLED_BY_DRIVER Order cancelled by driver

The tracking driver remark issue code

Tracking remark driver issue code Description
PACKAGE_DAMAGED The package was damaged
PACKAGE_REFUSED_BY_DRIVER The driver refused to take package at pickup
PACKAGE_NOT_RECEIVED The driver unable to get package at pickup
PACKAGE_REFUSED_BY_CUSTOMER The recipient refused to take package
PACKAGE_DELIVERED_BAL The driver has deposit the delivery to the recipient mailbox
PACKAGE_DELIVERED_OTHER_PEOPLE The driver has deposit the delivery to another person
ACCESS_PROBLEM The driver encountered many difficulties regarding to access pickup or delivery address
CUSTOMER_ABSENT The sender or recipient was absent
ADDRESS_KO The pickup or delivery address was invalid
CANCELLED_INVALID_ADDRESS The driver has cancelled step because pickup address was invalid

The tracking attachment type

Tracking attachment type Description
GENERIC_PHOTO Default photo
GENERIC_SIGNATURE Default signature
CUSTOMER_PHOTO Complementary Photo

The package object

Attribute name Type Description
packageTypeId double Identifier of existing package type, can be null if package is custom and specified manually at order creation or update.
quantity double Quantity
name double Name
length double Length in meters
width double Width in meters
height double Height in meters
weight double Weight in kilograms