NAV
shell

Introduction

This is the guide and API definition to integrate Deliverymates as a logistic partner.

Authentication

An authentication token will be provided to you at the beginning of our collaboration. Include it in an authorization HTTP header to authenticate all of your API calls.

Authorization: Token token=21dfdda6f27ffb9f4f4666d25c63b9a629d563274ea5638d2e

Conventions

A base URL will also be provided in conjunction with the authentication token. All requests have to be addressed to this base URL:

https://your-middlewaye-url

This API speaks JSON so a header has to be included in each request:

Content-Type: application/json

Reponse formats

Responses are commonly JSON objects. These objects will represent entities matching both fields and methods from the backend.

The next curl command represents a sample call

curl "http://server_url/path/to/api/endpoint"
  -X GET
  -H "Content-Type: application/json"
  -H "Authorization: Token token=04e59ae46203f6d1c218be75ea4ce76656fc5d5b2bf9fb99cf"

The above command will return a JSON represented as follows:

[
    {
        "field_1": "value 1",
        "field_2": "value 2",
        "field_3": "value 3"
    }
]

Errors

Each request may siply result in a 200 HTTP code and the resulting resource information.

For those situations in which something goes wrong, these are the common errors that the server may respond:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong or your token has expired
403 Forbidden – You don’t have permission to access this object
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The resource requested has been removed from our servers
418 I’m a teapot
422 Unprocessable entity – The server understands the content type of the request entity, and the syntax of the request entity is correct but was unable to process the contained instructions.
429 Too Many Requests – You’re requesting too many resources! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Orders

To push a new order the POST http method has to be used.

The typical workflow followed when managing an order using the dmates API is as follows :

Create an order

To create a new order

curl "http://server_url/api/ext/v1/orders"
  -X POST
  -H "Content-Type: application/json"
  -d "
      {
        'order': {
          'external_id': 'd6g7h3J8387g32jh003',
          'friendly_order_reference': 'FRIENDLY_ID',
          'source_provider': 'Burger King',
          'price': 15.75,
          'electric_vehicle_requested': true,
          'paid_at': '2017-10-02T14:23:22Z',
          'cash_on_delivery': false,
          'ready_for_pickup': true,
          'volume': '50',
          'transport_type': 'small_scooter',
          'basket_items':
            [
              {
                'name': 'Kids menu',
                'quantity': 1,
                'original_unit_price': 10,
                'discounted_unit_price': 8.5,
                'volume': '50',
                'barcode': '8888881112233',
                'note': 'shelf: 100',
                'sub_items':
                  [
                    {
                      'name': 'Pizza Margherita',
                      'quantity': 1,
                      'original_unit_price': 7,
                      'discounted_unit_price': 7,
                      'sub_items':
                        [
                          {
                            'name': 'Extra anxovies',
                            'quantity': 1,
                            'original_unit_price': 1,
                            'discounted_unit_price': 0.75
                          },
                          {
                            'name': 'Extra olives',
                            'quantity': 1,
                            'original_unit_price': 0.9,
                            'discounted_unit_price': 0.65
                          }
                        ]
                    }
                  ]
              }
            ],
         'jobs':
          [
            {
              'type': 'pickup',
              'time_window_start': '2017-10-02T14:00:00Z',
              'time_window_end': '2017-10-02T14:23:22Z',
              'note': 'Please do it as much toasted as possible',
              'place':
                {
                  'external_id': 'd7h3J8387g9876',
                  'address_line1': 'Somewhere addr',
                  'address_line2': 'Something else',
                  'postal_code': 'AR J354',
                  'city': 'London',
                  'country': 'GB',
                  'contact_name': 'Peter Petrelli',
                  'email': '[email protected]',
                  'mobile_phone_number': '556677889900',
                  'phone_number': '001122334455',
                  'position': [41.829709, 3.047605]
                }
            },
            {
              'type': 'delivery',
              'time_window_start': '2017-10-02T13:00:00Z',
              'time_window_end': '2017-10-02T15:00:27Z',
              'note': 'Please call if not at home',
              'place':
                {
                  'external_id': 'd6g7h3J8382346',
                  'address_line1': 'Somewhere',
                  'address_line2': 'On Earth',
                  'postal_code': 'AR J354',
                  'city': 'London',
                  'country': 'GB',
                  'contact_name': 'Jean Louis',
                  'email': '[email protected]',
                  'mobile_phone_number': '556677889900',
                  'phone_number': '001122334455',
                  'position': [41.82971, 3.047608]
                }
            }
          ],
          'callback_urls' : {
            'order_status': {
              'url': 'https://yourdomain.com/api/orders/:order_id/status'
            },
            'route_status': {
              'url': 'https://yourdomain.com/api/routes'
            },
            'driver_position': {
              'url': 'https://yourdomain.com/api/orders/:order_id/driver-position'
            }
          }
        }
      }
    "

The above command returns JSON structured like this:

{
    "id": "5981a5a82ade720001e571fd"
}

or if there is an error returns JSON structured like this:

{
  "errors": {
    "code": "other or bad_request",
    "message": "Not codified messages"
  }
}

HTTP Request

POST /api/ext/v1/orders

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
external_id yes String, The provider order Id
friendly_order_reference no String, Another provider id
source_provider yes String, The source provider
price yes Float number, the total price of the order
electric_vehicle_requested no Boolean value. Just set it to true to request an electric vehicle.
paid_at yes Iso8601 timestamp, The date when the order was paid. Set it to blank if you set cash_on_delivery as true.
cash_on_delivery yes Boolean
ready_for_pickup yes Boolean
volume no String, The packages volume of total order in cm3.
transport_type no String, the value can be: walker, bicycle, car, scooter, large_scooter, cargo_bicycle, small_van, medium_van and large_van. By default it will be used: small_scooter.

An order can contain one or multiple basket items. Each one can also contain zero, one or multiple sub items.

Parameter Mandatory Default Description
name yes String, The name of the item
quantity yes Integer, The amount of units of this item
volume no String, The volume of this item in cm3
barcode no String, The barcode identifier
note no String, A text note with extra information, like shelf number, etc.
original_unit_price no String, Original price for a unit of this item
discounted_unit_price no String, Item price with discount applied (if any)
sub_items no A recursive array of items included in this one

An order should contain at least two jobs (pickup and delivery)

Parameter Mandatory Default Description
type yes Job type: “pickup” or “delivery”
time_window_start yes/no* Iso8601 timestamp, The start time of pickup/delivery range (*Home delivery: mandatory field in delivery job)
time_window_end yes Iso8601 timestamp, “Food delivery”: ETA for when the driver is supposed to get to this place. “Home delivery”: maximum ETA to delivery the order.
note no String, A text note that the driver can show at the place
place yes An object representing a place (restaurant, customer house, etc…)

The place object contains the data for the pickup or the dropoff

Parameter Mandatory Default Description
external_id yes String, The place Id
address_line1 yes String, First line of place address
address_line2 no String, Complementary line of place address
postal_code yes String, Postal code
city yes String, The city name
first_name no String, Name for the person targeted at this place
last_name no String, Name for the person targeted at this place
contact_name yes String, Name for the contact person in this place, can be different from the main name (eg: name is for a final customer, contact name is for a restaurant)
email no String, Email
phone_number yes String, Contact phone number
mobile_phone_number yes String, Contact phone number (mobile one)
country yes String, the place country in 2-letter ISO format.
position no An array representing the geographical position for this place in the format [lat, long]. If you give us a position then we’ll trust it. If you don’t then we’ll automatically reverse geocode the address to get a position. This process is usually trustable if the address is correct, but may generate an incorrect position if the address is not exact.

These are the field for the callback_urls object

Parameter Mandatory Default Description
order_status no Object, the callback url. If you don’t send it to us, we will not send the status update for this order.
driver_position no Object, the callback url. If you don’t send it to us, we will not send the driver positions for this order.

Update order status

This endpoint allows to update an order status. This endpoint is waiting for:

HTTP Request

PUT /api/ext/v1/orders/:order_id

With :order_id being the id that was first returned upon order creation or you can use the external_id.

curl "http://server_url/api/ext/v1/orders/:order_id"
  -X POST
  -H "Content-Type: application/json"
  -d "
      {
        'order': {
          'status': 'ready_for_pickup',
          'timestamp': '2017-10-02T14:23:22Z',
          'message': 'test message'
        }
      }
    "

The above command returns a 200, 400 or 422 http code or if there is an error returns JSON structured like this:

{
  "errors": {
    "code": "other or bad_request",
    "message": "Not codified messages"
  }
}

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
message yes Reason to cancel

Order batches

Orders can be split into multiple parts in certain situations, such as:

In these cases, the order will pass through the integration as usual, but it will be split on the Delivery Mates side and treated as part of a batch.

The following fields are always present in the status callbacks and will provide information about the existence and size of the batches:

fled description
batch_id This will always match the ID of the original order.
batch_idx The sequence number of the order within the batch.
batch_count The total number of orders in the batch.

Batch example #1

A standalone order will include the fields as follows

Order id reference batch_id batch_idx batch_count
5981a5a82ade720001e571fd SOME_REF 5981a5a82ade720001e571fd 1 1

Batch example #2

An order came in, then it got split into 3 parts

Order id reference batch_id batch_idx batch_count
5981a5a82ade720001e571fd SOME_REF 5981a5a82ade720001e571fd 1 3
646c8fa80310e963b3ad195a SOME_REF/2 5981a5a82ade720001e571fd 2 3
646c8fb30310e963b3ad195b SOME_REF/3 5981a5a82ade720001e571fd 3 3

Batch example #3

In this example the order starts as standalone. Then it becomes part of a bigger batch in different steps.

An order came in and behaved as an ordinary standalone one

Order id reference batch_id batch_idx batch_count
5981a5a82ade720001e571fd SOME_REF 5981a5a82ade720001e571fd 1 1

At some moment, it got splitted into 2 parts

Order id reference batch_id batch_idx batch_count
5981a5a82ade720001e571fd SOME_REF 5981a5a82ade720001e571fd 1 2
646c8fa80310e963b3ad195a SOME_REF/2 5981a5a82ade720001e571fd 2 2

Finally it got splitted into 3 parts

Order id reference batch_id batch_idx batch_count
5981a5a82ade720001e571fd SOME_REF 5981a5a82ade720001e571fd 1 3
646c8fa80310e963b3ad195a SOME_REF/2 5981a5a82ade720001e571fd 2 3
646c8fb30310e963b3ad195b SOME_REF/3 5981a5a82ade720001e571fd 3 3

Delivery options

When an order is delivered or attempted the payload on the callbacks will contain valuable information on the finalisation status

The status delivery_done means that the order lifecycle got to an end. The delivery_option and delivery_sub_option give the information of what happened with that delivery.

Successful delivery

A successful delivery will contain the next piece of payload

"status": "delivery_done",
"delivery_option": {
  "code": "delivered",
  "description": "Delivered"
},
"delivery_sub_option": {
  "code": "delivered_to_recipient",
  "description": "Delivered to recipient"
},

Some additional information about the delivery can appear in the payload (called delivery_extra):

"delivery_extra": {
  "who": "John Doe",
  "where": "The door next to the main one",
  "safe": false    
}

None of the extras are mandatory, they can appear or not. The meaning of each one is as follows:

Parameter type Description
who string Normally the name of who picked the goods
where string If the delivery address was different from the provided one
safe boolean Whether the driver left a safe card or not

Attempt

When an order can’t be delivered then we call it an ATTEMPT. In this case the payload will look like this

"status": "delivery_done",
"delivery_option": {
  "code": "attempted",
  "description": "Attempted"
},
"delivery_sub_option": {
  "code": "customer_not_at_home",
  "description": "Customer not at home"
},

List of options and suboptions

This is the list of valid delivery_options

Code Description
delivered Parcel successfully delivered
attempted Could not deliver

This is the list of valid delivery_sub_options

Code Option Description
delivered_to_recipient delivered Delivered to recipient
delivered_to_neighbour delivered Delivered to neighbour
posted_through_letter_box delivered Posted through the letter box
left_on_doorstep delivered Left on doorstep
left_behind_bin delivered Left behind bin
left_with_concierge delivered Left with concierge
left_with_receptionist delivered Left with receptionist
left_in_postal_area delivered Left in postal area
left_behind_plant delivered Left behind plant pot
left_behind_bushes delivered Left behind bushes
left_by_gate delivered Left by gate
left_other delivered Other
customer_not_at_home attempted Customer not at home
address_not_found attempted Could not locate address
address_not_accessible attempted Unable to access address
incorrect_address attempted Incorrect address
no_safe_location attempted No safe location to leave
refused_by_customer attempted Refused by customer
parcel_damaged attempted Parcel was damaged
parcel_missing attempted Parcel was missing
poor_quality attempted Poor quality
ops_delayed attempted Ops delayed

Order Status Callbacks

We will perform 8 callbacks as the order progresses through its life-cycle. Those are:

All Callbacks will be performed to the url specified in the order request (field: order_status of object callback_urls).

Plaease make sure to check the Order Batches section to understand retries.

Order accepted

This callback is sent to tell you whether we accept the order

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'order_accepted',
          'timestamp': '2017-07-29T19:30:05.000Z',
          'message': '',
          'order_content': {
            'order': {
              'external_id': 'd6g7h3J8387g32jh003',
              'friendly_order_reference': 'FRIENDLY_ID',
              'source_provider': 'Burger King',
              'price': 15.75,
              'paid_at': '2017-10-02T14:23:22Z',
              'cash_on_delivery': false,
              'ready_for_pickup': true,
              'volume': '40x40x40cm',
              'basket_items':
                [
                  {
                    'name': 'Kids menu',
                    'quantity': 1,
                    'original_unit_price': 10,
                    'discounted_unit_price': 8.5,
                    'volume': '40x40x40cm',
                    'barcode': '8888881112233',
                    'note': 'shelf: 100',
                    'sub_items':
                      [
                        {
                          'name': 'Pizza Margherita',
                          'quantity': 1,
                          'original_unit_price': 7,
                          'discounted_unit_price': 7,
                          'sub_items':
                            [
                              {
                                'name': 'Extra anxovies',
                                'quantity': 1,
                                'original_unit_price': 1,
                                'discounted_unit_price': 0.75
                              },
                              {
                                'name': 'Extra olives',
                                'quantity': 1,
                                'original_unit_price': 0.9,
                                'discounted_unit_price': 0.65
                              }
                            ]
                        }
                      ]
                  }
                ],
            'jobs':
              [
                {
                  'type': 'pickup',
                  'time_window_start': '2017-10-02T14:00:00Z',
                  'time_window_end': '2017-10-02T14:23:22Z',
                  'note': 'Please do it as much toasted as possible',
                  'place':
                    {
                      'external_id': 'd7h3J8387g9876',
                      'address_line1': 'Somewhere addr',
                      'address_line2': 'Something else',
                      'postal_code': 'AR J354',
                      'city': 'London',
                      'country': 'GB',
                      'contact_name': 'Peter Petrelli',
                      'email': '[email protected]',
                      'mobile_phone_number': '556677889900',
                      'phone_number': '001122334455',
                      'position': [3.047605, 41.829709]
                    }
                },
                {
                  'type': 'delivery',
                  'time_window_start': '2017-10-02T13:00:00Z',
                  'time_window_end': '2017-10-02T15:00:27Z',
                  'note': 'Please call if not at home',
                  'place':
                    {
                      'external_id': 'd6g7h3J8382346',
                      'address_line1': 'Somewhere',
                      'address_line2': 'On Earth',
                      'postal_code': 'AR J354',
                      'city': 'London',
                      'country': 'GB',
                      'contact_name': 'Jean Louis',
                      'email': '[email protected]',
                      'mobile_phone_number': '556677889900',
                      'phone_number': '001122334455',
                      'position': [3.047608, 41.82971]
                    }
                }
              ],
              'callback_urls' : {
                'order_status': {
                  'url': 'https://yourdomain.com/api/orders/:order_id/status'
                },
                'driver_position': {
                  'url': 'https://yourdomain.com/api/orders/:order_id/driver-position'
                }
              }
            }
          }
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, (one of order_accepted, order_rejected, order_assigned, pickup_started, pickup_arrived, pickup_done, delivery_started, delivery_arrived, delivery_done)
timestamp yes Iso8601 timestamp, the timestamp at which the decision was taken (order could be rejected at moment t and accepted at moment t+1).
message no String, extra infos regarding the rejected reasons (could be too_busy, too_far, location_not_supported, bad_address etc..).
order_content yes Order that you sent to us.

Order rejected

This callback is sent to tell you whether we reject the order

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'order_rejected',
          'timestamp': '2017-07-29T19:30:05.000Z',
          'message': '',
          'order_content': {
            'order': {
              'external_id': 'd6g7h3J8387g32jh',
              'source_provider': 'Burger King',
              'price': 15.75,
              'paid_at': '2017-09-29T17:03:56Z',
              'cash_on_delivery': false,
              'ready_for_pickup': true,
              'basket_items':
                [
                  {
                    'name': 'Kids menu',
                    'quantity': 1,
                    'original_unit_price': 10,
                    'discounted_unit_price': 8.5,
                    'volume': '40x40x40cm',
                    'barcode': '8888881112233',
                    'sub_items':
                      [
                        {
                          'name': 'Pizza Margherita',
                          'quantity': 1,
                          'original_unit_price': 7,
                          'discounted_unit_price': 7,
                          'sub_items':
                            [
                              {
                                'name': 'Extra anxovies',
                                'quantity': 1,
                                'original_unit_price': 1,
                                'discounted_unit_price': 0.75
                              },
                              {
                                'name': 'Extra olives',
                                'quantity': 1,
                                'original_unit_price': 0.9,
                                'discounted_unit_price': 0.65
                              }
                            ]
                        }
                      ]
                  }
                ],
             'jobs':
              [
                {
                  'type': 'pickup',
                  'estimated_time': '2017-09-29T17:03:56Z',
                  'note': 'Please do it as much toasted as possible',
                  'place':
                    {
                      'external_id': 'd7h3J8387g9876',
                      'address_line1': 'Somewhere addr',
                      'address_line2': 'Something else',
                      'postal_code': 'AR J354',
                      'city': 'London',
                      'contact_name': 'Peter Petrelli',
                      'email': '[email protected]',
                      'mobile_phone_number': '556677889900',
                      'phone_number': '001122334455',
                      'position': [3.047605, 41.829709]
                    }
                },
                {
                  'type': 'delivery',
                  'estimated_time': '2017-09-29T17:03:56Z',
                  'note': 'Please call if not at home',
                  'place':
                    {
                      'external_id': 'd6g7h3J8382346',
                      'address_line1': 'Somewhere',
                      'address_line2': 'On Earth',
                      'postal_code': 'AR J354',
                      'city': 'London',
                      'email': '[email protected]',
                      'mobile_phone_number': '556677889900',
                      'first_name': 'Jean',
                      'last_name': 'Louis',
                      'phone_number': '001122334455',
                      'position': [3.047608, 41.82971]
                    }
                }
              ],
              'callback_urls' : {
                'order_status': {
                  'url': 'https://yourdomain.com/api/orders/:order_id/status'
                },
                'driver_position': {
                  'url': 'https://yourdomain.com/api/orders/:order_id/driver-position'
                }
              }
            }
          }
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, (one of order_accepted, order_rejected, order_assigned, pickup_started, pickup_arrived, pickup_done, delivery_started, delivery_arrived, delivery_done)
timestamp yes Iso8601 timestamp, the timestamp at which the decision was taken (order could be rejected at moment t and accepted at moment t+1).
message no String, extra infos regarding the rejected reasons (could be too_busy, too_far, location_not_supported, bad_address etc..).
order_content yes Order that you sent to us.

Order cancelled

This callback is sent when the order has been canceled.

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'order_cancelled',
          'timestamp': '2017-07-29T19:30:05.000Z',
          'message': ''
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
message no A String

Order assigned

This callback is sent when a driver is assigned to the order. It will communicate an ETA.

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'external_id': 'EXTERNAL_ID',
          'status': 'order_assigned',
          'timestamp': "2017-07-29T19:30:05.000Z",
          'eta': {
            'pickup_arrived': "2017-07-29T19:30:05.000Z",
            'delivery_arrived': "2017-07-29T19:30:05.000Z"
          },
          'driver_position': {
            'latitude': 2,
            'longitude': 3
          },
          'driver_infos': {
            'id': "5981a5a32ade720001e921fa",
            'name': "Moto driver Parker"
          },
          'batch_id': '644211566007421e866723df',
          'batch_idx': '1',
          'batch_count': '2'
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
eta yes Object, Contains ‘pickup_arrived’ and ‘delivery_arrived’
driver_position yes An Object containing ‘latitude’ and ‘longitude’.
driver_infos yes An Object containing ‘id’ and ‘name’.
batch_id no ID of the batch
batch_idx no Sequence number inside the batch
batch_count no Total amount of orders inside the batch

Pickup Started

This callback is sent when the driver is on its bike and underway

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'pickup_started',
          'timestamp': "2017-07-29T19:30:05.000Z",
          'eta': {
            'pickup_arrived': "2017-07-29T19:30:05.000Z",
            'delivery_arrived': "2017-07-29T19:30:05.000Z"
          },
          'driver_position': {
            'latitude': 2,
            'longitude': 3
          },
          'driver_infos': {
            'id': "5981a5a32ade720001e921fa",
            'name': "Moto driver Parker"
          },
          'batch_id': '644211566007421e866723df',
          'batch_idx': '1',
          'batch_count': '2'
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
eta yes Object, Contains ‘pickup_arrived’ and ‘delivery_arrived’
driver_position yes An Object containing ‘latitude’ and ‘longitude’.
driver_infos yes An Object containing ‘id’ and ‘name’.
batch_id no ID of the batch
batch_idx no Sequence number inside the batch
batch_count no Total amount of orders inside the batch

Pickup Arrived

This callback is sent when the driver arrives at the restaurant and is ready to collect the order.

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'pickup_arrived',
          'timestamp': "2017-07-29T19:30:05.000Z",
          'eta': {
            'delivery_arrived': "2017-07-29T19:30:05.000Z"
          },
          'driver_position': {
            'latitude': 2,
            'longitude': 3
          },
          'driver_infos': {
            'id': "5981a5a32ade720001e921fa",
            'name': "Moto driver Parker"
          },
          'batch_id': '644211566007421e866723df',
          'batch_idx': '1',
          'batch_count': '2'
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
eta yes Object, Contains ‘delivery_arrived’
driver_position yes An Object containing ‘latitude’ and ‘longitude’.
driver_infos yes An Object containing ‘id’ and ‘name’.
batch_id no ID of the batch
batch_idx no Sequence number inside the batch
batch_count no Total amount of orders inside the batch

Pickup Done

This callback is sent when the driver has successfully collected the order at the restaurant.

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'pickup_done',
          'timestamp': "2017-07-29T19:30:05.000Z",
          'eta': {
            'delivery_arrived': "2017-07-29T19:30:05.000Z"
          },
          'driver_position': {
            'latitude': 2,
            'longitude': 3
          },
          'driver_infos': {
            'id': "5981a5a32ade720001e921fa",
            'name': "Moto driver Parker"
          },
          'proof_of_collection': {
            'text': "Any collected text",
            'signature': "https://path.to/signature.png",
            'picture': "https://path.to/picture.png"
          },
          'batch_id': '644211566007421e866723df',
          'batch_idx': '1',
          'batch_count': '2'
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
eta yes Object, Contains ‘delivery_arrived’
driver_position yes An Object containing ‘latitude’ and ‘longitude’.
driver_infos yes An Object containing ‘id’ and ‘name’.
proof_of_collection no An Object containing text, signature and picture for the proff of collection
batch_id no ID of the batch
batch_idx no Sequence number inside the batch
batch_count no Total amount of orders inside the batch

Delivery Started

The driver has successfully collected the order and is on its bike underway.

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'delivery_started',
          'timestamp': "2017-07-29T19:30:05.000Z",
          'eta': {
            'delivery_arrived': "2017-07-29T19:30:05.000Z"
          },
          'driver_position': {
            'latitude': 2,
            'longitude': 3
          },
          'driver_infos': {
            'id': "5981a5a32ade720001e921fa",
            'name': "Moto driver Parker"
          },
          'batch_id': '644211566007421e866723df',
          'batch_idx': '1',
          'batch_count': '2'
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
eta yes Object, Contains ‘delivery_arrived’
driver_position yes An Object containing ‘latitude’ and ‘longitude’.
driver_infos yes An Object containing ‘id’ and ‘name’.
batch_id no ID of the batch
batch_idx no Sequence number inside the batch
batch_count no Total amount of orders inside the batch

Delivery Arrived

The driver thinks that he has arrived at the specified delivery address.

NB : This callback is distinct from the delivery_done callback, as we use this callback to understand how much time is spent locating the customer’s address.


      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'delivery_arrived',
          'timestamp': "2017-07-29T19:30:05.000Z",
          'eta': {
            'delivery_arrived': "2017-07-29T19:30:05.000Z"
          },
          'driver_position': {
            'latitude': 2,
            'longitude': 3
          },
          'driver_infos': {
            'id': "5981a5a32ade720001e921fa",
            'name': "Moto driver Parker"
          },
          'batch_id': '644211566007421e866723df',
          'batch_idx': '1',
          'batch_count': '2'
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, the current status of the order.
timestamp yes Iso8601 timestamp, the timestamp for the new status.
eta yes Object, Contains ‘delivery_done’
driver_position yes An Object containing ‘latitude’ and ‘longitude’.
driver_infos yes An Object containing ‘id’ and ‘name’.
batch_id no ID of the batch
batch_idx no Sequence number inside the batch
batch_count no Total amount of orders inside the batch

Delivery Done

This callback is sent when the driver has handed the food to the customer and completed the order.

      {
        'order': {
          'id': '5981a5a82ade720001e571fd',
          'external_id': 'EXTERNAL_ID',
          'status': 'delivery_done',
          'delivery_option': {
            'code': 'delivered',
            'description': 'Delivered successfully'
          },
          'delivery_sub_option': {
            'code': 'left_with_neighbour',
            'description': 'Successfully delivered to a neighbour'
          },
          'timestamp': "2017-07-29T19:30:05.000Z",
          'driver_position': {
            'latitude': 2,
            'longitude': 3
          },
          'driver_infos': {
            'id': "5981a5a32ade720001e921fa",
            'name': "Moto driver Parker"
          },
          'proof_of_delivery': {
            'text': "Any collected text",
            'signature': "https://path.to/signature.png",
            'picture': "https://path.to/picture.png"
          },
          'batch_id': '644211566007421e866723df',
          'batch_idx': '1',
          'batch_count': '2'
        }
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, Id.
external_id yes String, Id.
status yes String, the current status of the order.
delivery_option no An object containing a code and description of the delivery status
delivery_sub_option no An object containing a code and description of the sub option for the delivery status
timestamp yes Iso8601 timestamp, the timestamp for the new status.
driver_position yes An Object containing ‘latitude’ and ‘longitude’.
driver_infos yes An Object containing ‘id’ and ‘name’.
proof_of_delivery no An Object containing text, signature and picture for the proof of delivery
batch_id no ID of the batch
batch_idx no Sequence number inside the batch
batch_count no Total amount of orders inside the batch

Driver Position Callback

We will perform a request every 10 seconds to provide you with the exact driver GPS position.

The requests will be performed to the callback url (field: driver_position of object callback_urls) specified in the order.

Driver Location

This callback is sent to tell you the exact driver location

      {
        'id': '5981a5a82ade720001e571fd',
        'status': 'pickup_arrived',
        'driver_position': {
          'latitude': 2,
          'longitude': 3
        },
        'eta': {
          'pickup_arrived': "2017-07-29T19:30:05.000Z",
          'delivery_arrived': "2017-07-29T19:30:05.000Z"
        },
        'driver_infos': {
          'id': "5981a5a32ade720001e921fa",
          'name': "Moto driver Parker"
          'electric_vehicle: electric_vehicle': true
        },
        'timestamp': '2017-09-02T09:31:50Z'
      }

The above command returns a 200

Query Parameters

These are the field for the Order object

Parameter Mandatory Default Description
id yes String, the order Id
status yes String, the order status.
driver_position yes Object containing latitude and longitude
eta yes Object containing pickup and delivery etas
driver_infos yes Object containing ‘id’, ‘name’, and other informations of interest (ie: electric_vehicle)
timestamp yes Iso8601 Date Time timestamp

Route optimization callback

We will send you callbacks after optimizing a route. The callbacks will be sent to the url specified in the order request (field: route_status of object callback_urls). It’s a single callback and will inform all the stops in the route, with their ETA and sequence.

If the same route needs a latr optimization (ex: a new order is added, or it’s merged with another route) then we’ll send the callback again.

{
  "reference": "1727945562_AC7C540D1675",
  "id": "66fe5b595b85a4623a0bc41f",
  "timestamp": "1727945562",
  "run_status": "opened",
  "stops": [
    {
      "id": "66fe5b5a5b85a4623a0bc422",
      "order_id": "66fe5b325b85a43166f98775",
      "idx": "1",
      "estimated_time_for_arrival": "2024-10-03 08:54:28 UTC"
    },
    {
      "id": "66fe5b595b85a4623a0bc420",
      "order_id": "66fe5b585b85a4623a0bc416",
      "idx": "1",
      "estimated_time_for_arrival": "2024-10-03 08:52:40 UTC"
    },
    {
      "id": "66fe5b5a5b85a4623a0bc423",
      "order_id": "66fe5b3d5b85a43166f98776",
      "idx": "2",
      "estimated_time_for_arrival": "2024-10-03 08:59:28 UTC"
    },
    {
      "id": "66fe5b595b85a4623a0bc421",
      "order_id": "66fe5b585b85a4623a0bc416",
      "idx": "2",
      "estimated_time_for_arrival": "2024-10-03 08:57:40 UTC"
    },
    {
      "id": "66fe5b5a5b85a4623a0bc424",
      "order_id": "66fe4c405b85a43166f98762",
      "idx": "3",
      "estimated_time_for_arrival": "2024-10-03 09:04:28 UTC"
    }
  ]
}