> For the complete documentation index, see [llms.txt](https://mipos.gitbook.io/public-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mipos.gitbook.io/public-api/logistic/logistic-integrations-management-1.md).

# 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

<mark style="color:green;">`POST`</mark> `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             |

{% tabs %}
{% tab title="201 " %}

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

{% endtab %}

{% tab title="409 " %}

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

{% endtab %}

{% tab title="422 " %}

```javascript
{
    "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."
    ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
These webhook requests will send a header called **X-Signature-Request**, as a security measure to confirm that the request came from our system.
{% endhint %}

### Webhook(Type 1 - Estimate Delivery Service)

{% hint style="info" %}
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
{% endhint %}

#### 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

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

```javascript
{
    "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)

{% hint style="info" %}
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
{% endhint %}

#### 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                                                             |

| <p>Object<br>(Origin/Destination)</p> | 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

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

```javascript
{
    "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

<mark style="color:green;">`POST`</mark> `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        |

{% tabs %}
{% tab title="204 " %}

```
```

{% endtab %}
{% endtabs %}

| 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

<mark style="color:green;">`POST`</mark> `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        |

{% tabs %}
{% tab title="204 " %}

```javascript
```

{% endtab %}
{% endtabs %}

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