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