Logistic integrations management

Webhooks

You can receive different types of requirements to use your logistics system. The types of requests you can receive are:

• Type 1: Receive request to estimate the value of a route.

• Type 2: Receive the request of your logistics service for the delivery of an order.

Manage Webhook

POST https://integrations.mipos.shop/api/v1/logistic/system/webhook/manage

Create or update logistic system webhooks.

Headers

Name	Type	Description
Authorization	string	Bearer {access_token}
Content-type	string	application/json

Request Body

Name	Type	Description
type	string	Webhook type (1 or 2)
integration_id	string	Your Logistic System Id
url	string	Webhook URL

201

{
    "message": "Webhook successfully configured.",
    "data": null
}

409

{
    "message": [
        "This integration does not belong to you or does not exist."
    ],
    "data": null
}

422

{
    "type": [
        "The type field is required.",
        "The selected type is invalid."
    ],
    "integration_id": [
        "The integration id field is required.",
        "The selected integration id is invalid.",
        "The integration id must be a string."
    ],
    "url": [
        "The url field is required."
    ]
}

These webhook requests will send a header called X-Signature-Request, as a security measure to confirm that the request came from our system.

Webhook(Type 1 - Estimate Delivery Service)

The value of this field is a hexadecimal HMAC signature of the next json payload, using the client secret as a key(generated on account creation) and SHA256 as the hash function.

{"origin": {"address": "...", "reference": "...", "lat": ..., "lng": ..., "contact_phone": "...", "contact_name": ""}, "destination":{"address": "...", "reference": "...", "lat": ..., "lng": ..., "contact_phone": "...", "contact_name": "..."}, "integration_id": ...}

Example

json_payload:

{"origin":{"address":"Av. Las Aguas 1256","reference":"Cerca del centro comercial ....","lat":-2.1602453,"lng":-79.908075,"contact_phone":"0912345678","contact_name":"Gerente tienda Jos\u00e9"},"destination":{"address":"Urbanizaci\u00f3n Ficticia Solar 15","reference":"Cerca del malec\u00f3n ....","lat":-2.1617463,"lng":-79.9017235,"contact_phone":"0987654321","contact_name":"Camila", "integration_id": 8}}

client_secret:

08b707f3fa62d18df7dd5a12b5d169a22f372c25

Signature: c70400564e5440ea76ed1f0241965ff97515cfdfff71b05444f613a5bf43a8dd

Content Body

Key	Type	Value
origin	Object	Information where the order will be collected
destination	Object	Information where the order will be delivered
integration_id	Number	Id of your system

Key	Type	Value
address	String	Detailed address information
reference	String	Location help reference
lat	decimal number	Latitude
lng	decimal number	Longitude
contact_phone	String	-
contact_name	String	-

JSON received example

{
    "origin": {
        "address": "Av. Las Aguas 1256",
        "reference": "Cerca del centro comercial ....",
        "lat": -2.1602453,
        "lng": -79.908075,
        "contact_phone": "0912345678",
        "contact_name": "Gerente tienda José"
    },
    "destination": {
        "address": "Urbanización Ficticia Solar 15",
        "reference": "Cerca del malecón ....",
        "lat": -2.1617463,
        "lng": -79.9017235,
        "contact_phone": "0987654321",
        "contact_name": "Camila"
    },
    "integration_id":8
}

Expected response

Your service should POST a 200 response status code with the following json in the body. If the answer does not follow this format it will be ignored.

{
    "value": 1150, // Number that includes the 2 decimal places($11.50)
    "time": 65 // Time should be in minutes(1h 5min),
    "integration_id": 8, // Id of your system
}

Webhook(Type 2 - Request Delivery Service)

The value of this field is a hexadecimal HMAC signature of the next json payload, using the client secret as a key(generated on account creation) and SHA256 as the hash function.

{"origin": {"address": "...", "reference": "...", "lat": ..., "lng": ..., "contact_phone": "...", "contact_name": ""}, "destination":{"address": "...", "reference": "...", "lat": ..., "lng": ..., "contact_phone": "...", "contact_name": "..."}, "estimated_pickup": "...", "integration_id": "...", "webhook_url": "...", "webhook_location_url": "...", "order_id": "...", "store_id": "...", "third_party_id": "..."}

Example

json_payload:

{ "origin": { "address": "Av. Emilio Estrada, Dátiles 109 Y, 090511", "reference": "", "lat": "-2.1665922", "lng": "-79.9059292", "contact_phone": "XXXXXXXXXXXX", "contact_name": "Pick Up Store" }, "destination": { "address": "Dr. Alfredo Baquerizo Moreno 1007, Guayaquil 090313", "reference": "Cerca del Malecón 2000", "lat": "-2.1850754", "lng": "-79.8902651", "contact_phone": "YYYYYYYYYYYYY", "contact_name": "Customer name" }, "estimated_pickup": "2020-05-29 15:43:00", "integration_id": "8", "webhook_url": "http://localhost:8005/url/test4", "webhook_location_url": "http://localhost:8005/url/test7", "order_id": "12345678-123-1234-1234-123456789012", "store_id": "abc124..3312", "third_party_id": 7 }

client_secret:

08b707f3fa62d18df7dd5a12b5d169a22f372c25

Signature: 8182a41abbafbbb7bdf63d39e361ac04feebc7eb38bd4cf22f68f832cdc4313b

Content Body

Key	Type	Value
origin	Object	Information where the order will be collected
destination	Object	Information where the order will be delivered
estimated_pickup	String	Estimated time the order would be ready to pick up
integration_id	String	Id of your system
webhook_url	String	Endpoint that will receive the status changes that occur during the delivery of the order
webhook_url	String	Endpoint that will receive the events of the new location where the order is located
order_id	String	Id of the order
store_id	String	Id of the store
third_party_id	String	Id of the third party service

Object (Origin/Destination)	Type	Value
address	String	Detailed address information
reference	String	Location help reference
lat	decimal number	Latitude
lng	decimal number	Longitude
contact_phone	String	-
contact_name	String	-

JSON received example

{
    "origin": {
        "address": "Av. Emilio Estrada, Dátiles 109 Y, 090511",
        "reference": "",
        "lat": "-2.1665922",
        "lng": "-79.9059292",
        "contact_phone": "XXXXXXXXXXXX",
        "contact_name": "Pick Up Store"
    },
    "destination": {
        "address": "Dr. Alfredo Baquerizo Moreno 1007, Guayaquil 090313",
        "reference": "Cerca del Malecón 2000",
        "lat": "-2.1850754",
        "lng": "-79.8902651",
        "contact_phone": "YYYYYYYYYYYYY",
        "contact_name": "Customer name"
    },
    "estimated_pickup": "2020-05-29 15:43:00",
    "integration_id": "8",
    "webhook_url": "http://localhost:8005/url/test4",
    "webhook_location_url": "http://localhost:8005/url/test7",
    "order_id": "12345678-123-1234-1234-123456789012",
    "store_id": "abc124..3312",
    "third_party_id": 7
}

Expected response

Your service should POST a 200 response status code with the following json in the body. If the answer does not follow this format it will be ignored.

{
    "value": 1150, // Number that includes the 2 decimal places($11.50)
    "time": 65 // Time should be in minutes(1h 5min),
    "integration_id": "8", // Id of your system
    "service_identifier": "123ID123" // Id of the created service
}

Send status change in delivery service

To inform the other system, of the state changes that the delivery of the package may have, you can use this endpoint.

Send status updates

POST https://integrations.mipos.shop/api/v1/logistic/system/status/updates

Headers

Name	Type	Description
Content-type	string	application/json

Request Body

Name	Type	Description
service_identifier	string	Identifier of the service requested from your system
status	string	New delivery service status
location	object	Coordinates where the chage of state occurred

204

location(Object)	Type	Value
lat	decimal number	Latitude
lng	decimal number	Longitude

Send location of the person carrying the package

To inform the other system of the current location of the package, the frequency of sending this request will be your choice.

Send location updates

POST https://integrations.mipos.shop/api/v1/logistic/system/status/updates

Headers

Name	Type	Description
Content-type	string	application/json

Request Body

Name	Type	Description
service_identifier	string	Identifier of the service requested from your system
location	object	Coordinates where the chage of state occurred

204

location(Object)	Type	Value
lat	decimal number	Latitude
lng	decimal number	Longitude