# Inventory system management

To start with the integration of your inventory system you must start by registering your system on our platform. The generated id will be used by the others involved to communicate with your inventory system.

## Create Inventory System

<mark style="color:green;">`POST`</mark> `https://integrations.mipos.shop/api/v1/inventory/system/create`

Registration of a new inventory system within this platform

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-type  | string | application/json       |

#### Request Body

| Name | Type   | Description                      |
| ---- | ------ | -------------------------------- |
| name | string | Name of the new inventory system |

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

```javascript
{
    "message": "Success.",
    "data": {
        "inventory_system_id": "3d40a24e-d570-4598-ae68-e20687edd1f9",
        "inventory_system_details": {
            "name": "Inventario mipOS"
        }
    }
}
```

{% endtab %}

{% tab title="409 " %}

```javascript
{
    "message": [
        "You do not have the permissions to access this resource.",
        "The Inventory System already exists."
    ],
    "data": null
}
```

{% endtab %}

{% tab title="422 " %}

```javascript
{
    "name": [
        "The name field is required."
    ]
}
```

{% endtab %}
{% endtabs %}

## Webhooks

The POS can send different types of data about its inventory items, the inventory system that you have registered can receive this data by registering the urls of the webhooks where it wants to receive each of these types.\
\
Types of information that the POS sends:

* Type 1: Receive the POS item data list
* &#x20;Type 2: Receive the stock updates of POS items

## Manage Webhook

<mark style="color:green;">`POST`</mark> `https://integrations.mipos.shop/api/v1/inventory/system/webhook/manage`

Create or update inventory 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)    |
| inventory\_system\_id | string | Your Inventory System Id |
| url                   | string | Webhook URL              |

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

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

{% endtab %}

{% tab title="409 " %}

```javascript
{
    "message": [
        "Your user does not have this inventory system.",
        "The webhook url of this type already exists, use the update endpoint webhook, if you want to change the url."
    ],
    "data": null
}
```

{% endtab %}

{% tab title="422 " %}

```javascript
{
    "type": [
        "The type field is required.",
        "The selected type is invalid."
    ],
    "inventory_system_id": [
        "The inventory system id field is required.",
        "The selected inventory system id is invalid."
    ],
    "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 - Receive POS items)

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

{"url": "your\_webhook\_url", "inventory\_system\_id": "id\_of\_your\_inventory\_system", "store\_id": "id\_store\_on\_your\_inventory\_system", "now": "date\_sent\_in\_body\_request"}

Example

json\_payload:

{"url": "localhost:8003/testurl", "inventory\_system\_id": "3d40a24e-d570-4598-ae68-e20687edd1f9", "store\_id": "testst123", "now": "2020-05-31 09:15:38"}

client\_secret:

9468da7ccaed13055abcf183fb05c73e8cfc48c5

Signature: 7c38c67ad234c4cdbe71425b5c961805ac3955d87de40d1d63e09f1f76d1ff61
{% endhint %}

#### Content Body

| Key                   | Value                                    |
| --------------------- | ---------------------------------------- |
| inventory\_system\_id | Id of your inventory system              |
| units                 | POS unit of measurement array            |
| items                 | POS item array                           |
| suppliers             | POS suppliers array                      |
| now                   | Date sent to generate the signature      |
| store\_id             | Id of the store in your inventory system |

#### JSON received example

```javascript
{
    "items": [
        {
            "name": "Testing item 1",
            "external_id": "item_abc123",
            "purchase_unit_external_id": "pos_u1",
            "consumption_unit_external_id": "pos_u2",
            "supplier_external_id": "pos_sup_1",
            "cost": "1250",
            "stock": "11.22"
        },
        {
            "name": "Testing item 2",
            "external_id": "item_abc456",
            "purchase_unit_external_id": "pos_u2",
            "consumption_unit_external_id": "pos_u2",
            "supplier_external_id": "pos_sup_1",
            "cost": "100",
            "stock": "5.50"
        }
    ],
    "inventory_system_id": "3d40a24e-d570-4598-ae68-e20687edd1f9",
    "units": [
        {
            "name": "Unit 1",
            "short_name": "u1",
            "external_id": "pos_u1"
        },
        {
            "name": "Unit 2",
            "short_name": "u2",
            "external_id": "pos_u2"
        }
    ],
    "suppliers": [
        {
            "name": "supplier 1",
            "external_id": "pos_sup_1"
        }
    ],
    "now": "2020-05-31 09:21:27",
    "store_id": "testst123"
}
```

#### Expected response

Due to the response times that may occur for this webhook, the returned response will not be used.

### Webhook(Type 2 - Receive POS stock updates)

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

{"url": "your\_webhook\_url", "inventory\_system\_id": "id\_of\_your\_inventory\_system", "store\_id": "id\_store\_on\_your\_inventory\_system", "now": "date\_sent\_in\_body\_request"}

Example

json\_payload:

{"url": "localhost:8003/testurl", "inventory\_system\_id": "3d40a24e-d570-4598-ae68-e20687edd1f9", "store\_id": "testst123", "now": "2020-05-31 09:15:38"}

client\_secret:

9468da7ccaed13055abcf183fb05c73e8cfc48c5

Signature: 7c38c67ad234c4cdbe71425b5c961805ac3955d87de40d1d63e09f1f76d1ff61
{% endhint %}

#### Content Body

| Key                   | Value                                       |
| --------------------- | ------------------------------------------- |
| inventory\_system\_id | Id of your inventory system                 |
| current\_stock        | Current stock of the item in the POS system |
| quantity              | Stock movement quantity                     |
| date                  | Movement date                               |
| movement\_type        | Movement type(1: add, 2: remove)            |
| now                   | Date sent to generate the signature         |
| store\_id             | Id of the store in your inventory system    |

#### JSON received example

```javascript
{
    "inventory_system_id": "4344be8c-c6b9-4c51-88a6-d620144ab406",
    "current_stock": "12.44",
    "quantity": "1.25",
    "date": "2020-05-30 12:45:03",
    "movement_type": 2,
    "now": "2020-06-01 12:28:00",
    "store_id": "testst456"
}
```

#### Expected response

Your service should POST a `204` response status code with an empty response body to acknowledge receipt of the webhook event. If an error occurs in your inventory system, the response must be returned with the respective status code and the body must include a field called message, this will be taken to show it to the POS user.

## Send stock updates from your inventory system to the POS

## Send update of stock of an item

<mark style="color:green;">`POST`</mark> `https://integrations.mipos.shop/api/v1/inventory/system/store/{store_id}/pos/stock/update`

#### Path Parameters

| Name      | Type   | Description                                     |
| --------- | ------ | ----------------------------------------------- |
| store\_id | string | Id of the store wich you want to sync inventory |

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-type  | string | application/json       |

#### Request Body

| Name                  | Type    | Description                                         |
| --------------------- | ------- | --------------------------------------------------- |
| inventory\_system\_id | string  | ID of your inventory system                         |
| pos\_id               | string  | ID of the POS system                                |
| current\_stock        | string  | Current stock of the item in your inventory system. |
| quantity              | string  | Stock movement quantity.                            |
| date                  | string  | Movement date.                                      |
| movement\_type        | integer | Movement type(1: add, 2: remove)                    |
| external\_id          | string  | ID of the item in the POS system                    |

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

```javascript
```

{% endtab %}

{% tab title="409 " %}

```javascript
{
    "message": [
        "This user_id does not own this inventory system.",
        "No integration record was found between this user store and the third party system.",
        "External id not found for this store in the inventory system.",
        "This type of webhook is not available.",
        "This POS system does not have this type of webhook available."

    ],
    "data": null
}
```

{% endtab %}

{% tab title="422 " %}

```javascript
{
    "pos_id": [
        "The pos id field is required."
    ],
    "inventory_system_id": [
        "The inventory system id field is required."
    ],
    "current_stock": [
        "The current stock field is required."
    ],
    "quantity": [
        "The quantity field is required."
    ],
    "date": [
        "The date field is required."
    ],
    "movement_type": [
        "The movement type field is required.",
        "The selected movement type is invalid."
    ],
    "external_id": [
        "The external id field is required"
    ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Any other error response you receive from this endpoint comes directly from the POS system.
{% endhint %}

### Body example

```javascript
{
	"pos_id": "1",
	"inventory_system_id": "4344be8c-c6b9-4c51-88a6-d620144ab406",
	"current_stock": "12.44",
	"quantity": "1.25",
	"date": "2020-05-30 12:45:03",
	"movement_type": 1,
	"external_id": "avcc123"
}
```