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

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

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

{
    "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.

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

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

location(Object)

Type

Value

lat

decimal number

Latitude

lng

decimal number

Longitude

PreviousPOS sync inventory NextPOS integrations management

Last updated 4 years ago

Was this helpful?