Delivery Service Integration Module

Introduction

Connect your on-demand delivery company to Sinqro (consuming Sinqro APIs and listening Sinqro webhooks)

Getting started

The developer account is automatically created when your company's account is created.

In order to create your POS, marketplace, app or any other platform account, please go to our main site, select your company type and follow the instructions.

If your company's account was already created and you have problems to access your account, contact us through the chat in this site or by email at integrations@sinqro.com

API Environments

As you are going to develop using test accounts, you can work directly in production:

https://api.sinqro.com/delivery-platform/v1

API Security

About your credentials

You can find your credentials in your developer panel.

Authorization

All services of this API require an authorization token sent in headers ‘x-api-server-access-token’.

You can get your integration module assigned token in your developer panel.

Authentication

All services of this API require an authentication token sent in headers 'x-api-user-access-token'.

You can get your integration module assigned token in your developer panel.

API SERVICES REFERENCE

DRIVER

Services to manage driver user data

Create new driver

POST /drivers

Create new driver for given delivery account

REQUEST parameters

x-api-server-access-token	string	header	Authorization token
x-api-user-access-token	string	header	Authentication token
deliveryAccountId	integer	formData	Delivery account identifier
name	string	formData	Driver name
lastname	string	formData	Driver last name
phone ( optional )	string	formData	Driver phone number
email ( optional )	string	formData	Driver email

POSSIBLE RESPONSES

HTTP Code	Description	Body
200	Ok	object Driver
400	Error/s	object ErrorResponse

DELIVERY

Services to manage deliveries

Post delivery status

POST /deliveries/status

Post delivery status

REQUEST parameters

x-api-server-access-token	string	header	Authorization token
x-api-user-access-token	string	header	Authentication token
externalDeliveryId	string	formData	Delivery external identifier
statusCode	string	formData	New delivery status code

POSSIBLE RESPONSES

HTTP Code	Description	Body
200	Ok	object Delivery
400	Error/s	object ErrorResponse

Post delivery driver location

POST /deliveries/location

Update delivery driver location

REQUEST parameters

x-api-server-access-token	string	header	Authorization token
x-api-user-access-token	string	header	Authentication token
externalDeliveryId	string	formData	Delivery external identifier
latitude	string	formData	Driver latitude position
longitude	string	formData	Driver longitude position

POSSIBLE RESPONSES

HTTP Code	Description	Body
200	Ok	object Delivery
400	Error/s	object ErrorResponse

Assign delivery driver

POST /deliveries/assign

Assign driver to delivery

REQUEST parameters

x-api-server-access-token	string	header	Authorization token
x-api-user-access-token	string	header	Authentication token
externalDeliveryId	string	formData	Delivery external identifier
driverId	integer	formData	Driver identifier

POSSIBLE RESPONSES

HTTP Code	Description	Body
200	Ok	object Delivery
400	Error/s	object ErrorResponse

NOTIFICATIONS REFERENCE

We have two options for you to receive our notifications:

Option 1. WEBHOOKS TRANSPORT

If you can provide an endpoint for us to send you the notifications there, we understand it as the best option.
Be careful, we'll process the response, reading ONLY the HTTP STATUS CODE of your server's response, and understanding any status code different than 2XX as an error.
You can set your webhook endpoint in your developer panel.

Option 2. WEBSOCKET TRANSPORT

If you don't have a (cloud) server to receive the webhooks, we ask you to please avoid polling our servers and work in real-time context. This can be done listening our websocket notifications server.
In your app, you need to implement a websocket client and listen the notifications following the instructions in this test tool
You can enable websocket notifications in your developer panel.

Notification Title	Notification Event Code	Model of the payload	Expected OK response
Delivery created	new_delivery	object Delivery	200 - 299 HTTP Status
Delivery cancelled	delivery_cancellation	Empty body	200 - 299 HTTP Status

MODELS REFERENCE

We show the definition of all the models used in the previous API services and notifications:

Delivery

MODEL ATTRIBUTES

Delivery

id	integer (int64)	Delivery identifier
pickupAddress	object PickupAddress	Delivery pickup address
deliveryAddress	object DeliveryAddress	Delivery address
pickupAgreedAt	string (date-time)	Pickup agreed time
pickupConfirmedAt	string (date-time)	Confirmed pickup time
deliveryAgreedAt	string (date-time)	Delivery agreed time
deliveryConfirmedAt	string (date-time)	Confirmed delivery time
pickupInstructions	string	Pickup instructions
deliveryInstructions	string	Driver instructions
forSenderInstructions	string	Instructions for the person or company that will hand the order to the driver
linearDistance	number (float)	Linear distance between pickup and delivery points
realDistance	number (float)	Real distance between pickup and delivery points
estimatedDeliveryDuration	number (float)	Estimated delivery duration in minutes
status	object Status	Current delivery status
pickupContactName	string	Pickup contact name
pickupContactPhone	string	Pickup contact phone number
pickupContactEmail	string	Pickup contact email
destinationContactEmail	string	Destination contact email
destinationContactName	string	Destination contact name
destinationContactPhone	string	Destination contact phone number
deliveryDescription	string	Delivery description
onPickupPayments	array Payment	Payments required on pickup action
onDeliveryPayments	array Payment	Payments required on delivery action
newStatusOptions	array Status	Array with new possible statuses for delivery
driver	object driver	Driver
deliveryPrice	number (float)	Delivery price without taxes

MODEL EXAMPLES

Example

{
    "id": 1003,
    "pickupAddress": {
        "id": 1003,
        "street": "C/ Example, 23",
        "details": "Canada building",
        "city": "City name",
        "province": "Province name",
        "postalCode": "12345",
        "latitude": 41.308166,
        "longitude": 2.019725,
        "googlePlaceId": "xxxxxxxxxxxx",
        "placeName": "C/ Example, 23, City name"
    },
    "deliveryAddress": {
        "id": 1003,
        "street": "C/ Example, 23",
        "details": "Canada building",
        "city": "City name",
        "province": "Province name",
        "postalCode": "12345",
        "latitude": 41.308166,
        "longitude": 2.019725,
        "googlePlaceId": "xxxxxxxxxxxx",
        "placeName": "C/ Example, 23, City name"
    },
    "pickupAgreedAt": "2017-02-09T12:00:00+0000",
    "pickupConfirmedAt": "2017-02-09T12:00:00+0000",
    "deliveryAgreedAt": "2017-02-09T12:15:00+0000",
    "deliveryConfirmedAt": "2017-02-09T12:15:00+0000",
    "pickupInstructions": null,
    "deliveryInstructions": null,
    "forSenderInstructions": null,
    "linearDistance": "1.56",
    "realDistance": "1.97",
    "estimatedDeliveryDuration": "15",
    "status": {
        "code": "PICKING",
        "name": "Picking",
        "color": "blue",
        "isFinalStatus": false,
        "callToAction": "Start picking"
    },
    "pickupContactName": "John",
    "pickupContactPhone": "600000000",
    "pickupContactEmail": "john@example.com",
    "destinationContactEmail": "jane@example.com",
    "destinationContactName": "Jane",
    "destinationContactPhone": "600000000",
    "deliveryDescription": "Selling point order delivery",
    "onPickupPayments": [
        {
            "id": 1003,
            "amount": "28.60",
            "paymentMethodName": "Cash"
        }
    ],
    "onDeliveryPayments": [
        {
            "id": 1003,
            "amount": "28.60",
            "paymentMethodName": "Cash"
        }
    ],
    "newStatusOptions": [
        {
            "code": "PICKING",
            "name": "Picking",
            "color": "blue",
            "isFinalStatus": false,
            "callToAction": "Start picking"
        }
    ],
    "driver": {
        "id": 1003,
        "email": "john@example.com",
        "name": "John",
        "lastname": "Doe",
        "image": "https://cdn.sinqro.com/assets/images/placeholder_image.jpg",
        "phone": "+34600000000",
        "transport": {
            "code": "SCOOTER",
            "name": "Scooter"
        },
        "status": {
            "code": "onduty",
            "name": "En servicio",
            "color": "#5aac44"
        },
        "lastGeolocation": {
            "latitude": 41.308166,
            "longitude": 2.019725,
            "createdAt": "2018-03-015T12:15:00+0000"
        }
    },
    "deliveryPrice": 5
}

DeliveryAddress

MODEL ATTRIBUTES

Delivery address

id	integer (int64)	Address identifier
street	string	Address street with number
details	string	Extra address information
city	string	Address city name
province	string	Address province name
postalCode	string	Address postal code
latitude	number (float)	Address latitude
longitude	number (float)	Address longitude
googlePlaceId	string	Google place identifier
placeName	string	Place name

MODEL EXAMPLES

Example

{
    "id": 1003,
    "street": "C/ Example, 23",
    "details": "Canada building",
    "city": "City name",
    "province": "Province name",
    "postalCode": "12345",
    "latitude": 41.308166,
    "longitude": 2.019725,
    "googlePlaceId": "xxxxxxxxxxxx",
    "placeName": "C/ Example, 23, City name"
}

Driver

MODEL ATTRIBUTES

id	integer (int64)	Driver identifier
email	string	Driver email
name	string	Driver name
lastname	string	Driver last name
image	string	Driver image url
phone	string	In international format. Ex. +34600000000
transport	object TransportType
status	object Status	Current driver status

MODEL EXAMPLES

Example

{
    "id": 1003,
    "email": "john@example.com",
    "name": "John",
    "lastname": "Doe",
    "image": "https://cdn.sinqro.com/assets/images/placeholder_image.jpg",
    "phone": "+34600000000",
    "transport": {
        "code": "SCOOTER",
        "name": "Scooter"
    },
    "status": {
        "code": "onduty",
        "name": "En servicio",
        "color": "#5aac44"
    }
}

Error

MODEL ATTRIBUTES

Error

code	string		Error code identifier
message	string		Error description

MODEL EXAMPLES

Example

{
    "code": "ERROR_CODE_EXAMPLE",
    "message": "Error message"
}

ErrorResponse

MODEL ATTRIBUTES

Error response

errors	array Error	Errors
code	string	Error code identifier
message	string	Error description
httpResponseCode	string	HTTP response code

MODEL EXAMPLES

Example

{
    "errors": [
        {
            "code": "ERROR_CODE_EXAMPLE",
            "message": "Error message"
        }
    ],
    "code": "ERROR_CODE_EXAMPLE",
    "message": "Error message",
    "httpResponseCode": "400"
}

Geolocation

MODEL ATTRIBUTES

Driver last geolocation

latitude	number (float)	Geolocation latitude
longitude	number (float)	Geolocation longitude
createdAt	string (date-time)	Geolocation creation time

MODEL EXAMPLES

Example

{
    "latitude": 41.308166,
    "longitude": 2.019725,
    "createdAt": "2018-03-015T12:15:00+0000"
}

Payment

MODEL ATTRIBUTES

Payments required on pickup action

id	integer (int64)	Payment identifier
amount	number (float)	Payment amount
paymentMethodName	string	Payment method name

MODEL EXAMPLES

Example

{
    "id": 1003,
    "amount": "28.60",
    "paymentMethodName": "Cash"
}

Payment

MODEL ATTRIBUTES

Payments required on delivery action

id	integer (int64)	Payment identifier
amount	number (float)	Payment amount
paymentMethodName	string	Payment method name

MODEL EXAMPLES

Example

{
    "id": 1003,
    "amount": "28.60",
    "paymentMethodName": "Cash"
}

PickupAddress

MODEL ATTRIBUTES

Delivery pickup address

id	integer (int64)	Address identifier
street	string	Address street with number
details	string	Extra address information
city	string	Address city name
province	string	Address province name
postalCode	string	Address postal code
latitude	number (float)	Address latitude
longitude	number (float)	Address longitude
googlePlaceId	string	Google place identifier
placeName	string	Place name

MODEL EXAMPLES

Example

{
    "id": 1003,
    "street": "C/ Example, 23",
    "details": "Canada building",
    "city": "City name",
    "province": "Province name",
    "postalCode": "12345",
    "latitude": 41.308166,
    "longitude": 2.019725,
    "googlePlaceId": "xxxxxxxxxxxx",
    "placeName": "C/ Example, 23, City name"
}

Status

MODEL ATTRIBUTES

Current driver status

code	string	Status identifier code Possible values offduty onduty pending disabled
name	string	Status name
color	string	HEX color code for the status

MODEL EXAMPLES

Example

{
    "code": "onduty",
    "name": "En servicio",
    "color": "#5aac44"
}

Status

MODEL ATTRIBUTES

Current delivery status

code	string	Delivery status identifier code Possible values WAITING_DRIVER_ACCEPTANCE PICKING WAITING_SELLING_POINT_ACCEPTANCE WAITING_SELLING_POINT_PREPARATION DELIVERING WAITING_CUSTOMER DELIVERED CANCELLED INCIDENT ACCEPTED_BY_DRIVER
name	string	Delivery status name
color	string	HEX color code for the status
isFinalStatus	boolean	Return if is the last possible status
callToAction	string	Delivery status call to action message

MODEL EXAMPLES

Example

{
    "code": "PICKING",
    "name": "Picking",
    "color": "blue",
    "isFinalStatus": false,
    "callToAction": "Start picking"
}

Status

MODEL ATTRIBUTES

New possible delivery status

code	string	Delivery status identifier code Possible values WAITING_DRIVER_ACCEPTANCE PICKING WAITING_SELLING_POINT_ACCEPTANCE WAITING_SELLING_POINT_PREPARATION DELIVERING WAITING_CUSTOMER DELIVERED CANCELLED INCIDENT ACCEPTED_BY_DRIVER
name	string	Delivery status name
color	string	HEX color code for the status
isFinalStatus	boolean	Return if is the last possible status
callToAction	string	Delivery status call to action message

MODEL EXAMPLES

Example

{
    "code": "PICKING",
    "name": "Picking",
    "color": "blue",
    "isFinalStatus": false,
    "callToAction": "Start picking"
}

TransportType

MODEL ATTRIBUTES

code	string		Transport type identifier code Possible values BIKE SCOOTER MOTORBIKE CAR VAN WALKING
name	string		Transport type name

MODEL EXAMPLES

Example

{
    "code": "SCOOTER",
    "name": "Scooter"
}

driver

MODEL ATTRIBUTES

Driver

id	integer (int64)	Driver identifier
email	string	Driver email
name	string	Driver name
lastname	string	Driver last name
image	string	Driver image url
phone	string	In international format. Ex. +34600000000
transport	object TransportType
status	object Status	Current driver status
lastGeolocation	object Geolocation	Driver last geolocation

MODEL EXAMPLES

Example

{
    "id": 1003,
    "email": "john@example.com",
    "name": "John",
    "lastname": "Doe",
    "image": "https://cdn.sinqro.com/assets/images/placeholder_image.jpg",
    "phone": "+34600000000",
    "transport": {
        "code": "SCOOTER",
        "name": "Scooter"
    },
    "status": {
        "code": "onduty",
        "name": "En servicio",
        "color": "#5aac44"
    },
    "lastGeolocation": {
        "latitude": 41.308166,
        "longitude": 2.019725,
        "createdAt": "2018-03-015T12:15:00+0000"
    }
}