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

POST 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

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

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
Type 2: Receive the stock updates of POS items

Manage Webhook

POST 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

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

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

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

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 - Receive POS items)

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

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

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

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

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

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

POST 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

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

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

Any other error response you receive from this endpoint comes directly from the POS system.

Body example

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

PreviousThird Party Webhooks Content NextPOS sync inventory

Last updated 5 years ago

Was this helpful?

hashtagCreate Inventory System

hashtagHeaders

hashtagRequest Body

hashtagWebhooks

hashtagManage Webhook

hashtagHeaders

hashtagRequest Body

hashtagWebhook(Type 1 - Receive POS items)

hashtagContent Body

hashtagJSON received example

hashtagExpected response

hashtagWebhook(Type 2 - Receive POS stock updates)

hashtagContent Body

hashtagJSON received example

hashtagExpected response

hashtagSend stock updates from your inventory system to the POS

hashtagSend update of stock of an item

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagBody example

Create Inventory System

Headers

Request Body

Webhooks

Manage Webhook

Headers

Request Body

Webhook(Type 1 - Receive POS items)

Content Body

JSON received example

Expected response

Webhook(Type 2 - Receive POS stock updates)

Content Body

JSON received example

Expected response

Send stock updates from your inventory system to the POS

Send update of stock of an item

Path Parameters

Headers

Request Body

Body example