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.

post
Manage Webhook

https://integrations.mipos.shop/api/v1/logistic/system/webhook/manage
Create or update logistic system webhooks.
Request
Response
Request
Headers
Authorization
required
string
Bearer {access_token}
Content-type
required
string
application/json
Body Parameters
type
required
string
Webhook type (1 or 2)
integration_id
required
string
Your Logistic System Id
url
required
string
Webhook URL
Response
201: Created
{
"message": "Webhook successfully configured.",
"data": null
}
409: Conflict
{
"message": [
"This integration does not belong to you or does not exist."
],
"data": null
}
422: Unprocessable Entity
{
"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.

post
Send status updates

https://integrations.mipos.shop/api/v1/logistic/system/status/updates
Request
Response
Request
Headers
Content-type
required
string
application/json
Body Parameters
service_identifier
required
string
Identifier of the service requested from your system
status
required
string
New delivery service status
location
optional
object
Coordinates where the chage of state occurred
Response
204: No Content

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.

post
Send location updates

https://integrations.mipos.shop/api/v1/logistic/system/status/updates
Request
Response
Request
Headers
Content-type
required
string
application/json
Body Parameters
service_identifier
required
string
Identifier of the service requested from your system
location
optional
object
Coordinates where the chage of state occurred
Response
204: No Content

location(Object)

Type

Value

lat

decimal number

Latitude

lng

decimal number

Longitude