Partner API

Version 0.4 (02/07/2025)

Basic information:

Sandbox:

https://gateway-dev.palm.id.vn/api/private/partner/

Authenticating Requests with an API Key

To authenticate requests with an API key, follow these steps:

Retrieve your API key from the developer portal or your account settings.
Include the API key in the headers of your HTTP request. Typically, this is achieved by adding a header fieldx-api-key.
Ensure the API key is kept secure to prevent unauthorized access.

Example in a cURL command:

curl -X GET "https://gateway-dev.palm.id.vn/private/api/partner/locker" -H "x-api-key: YOUR_API_KEY"

Replace YOUR_API_KEY with your actual API key.

Webhook with Secret Key and HMAC-SH256 Signature

To ensure secure communication when receiving webhooks, you can use HMAC-SHA256 signatures. This approach allows you to verify the integrity and authenticity of the payload using a secret key shared between you and the sender.

Generating a Signature

When a webhook is sent, the payload is signed using your secret key. This signature is typically included in the request headers.

Verifying the Signature in Node.js

To verify the HMAC-SHA512 signature in Node.js:

Collect the incoming payload and the signature from the request header.
Use the secret key to generate a hash of the payload.
Compare the generated hash with the signature from the header.

Here's an example:

const crypto = require('crypto');

const secretKey = 'YOUR_SECRET_KEY';
const receivedSignature = req.headers['x-signature'];
const payload = JSON.stringify(req.body);

const hash = crypto
  .createHmac('sha256', secretKey)
  .update(payload)
  .digest('hex');

if (hash === receivedSignature) {
  console.log('Signature is valid.');
} else {
  console.log('Invalid signature.');
}

Replace YOUR_SECRET_KEY with your actual secret key. Make sure to handle the payload and signature verification securely to prevent unauthorized access.

List devices

API Description: List Devices

This API endpoint allows you to retrieve a list of devices. It is designed following RESTful principles.

Endpoint

GET /locker

Parameters

size (optional): The number of records to return per page for pagination. Default is 10.
page (optional): The index of the page to retrieve for pagination, starting at 0.
longtitude (optional) longtitude to search
latitude (optional) latitude to search
distance (optional) the radius (in km) to search with center point is (latitude, longtitude). Default value is 5
city (optional) city
dist (optional) district
ward (optional) ward
format (optional) format of data. You can use compact or full format. Default value is compact .

Note:

You must search by [longtitude, latitude, distance] or [city, dist, ward]
System will use [longtitude, latitude, distance] if you send both param groups.
If search by [longtitude, latitude, distance] does not return the result, you can try again by increase distance value.

Response

Returns a JSON object containing device details and pagination information.

Example Response of compact format

{
    "data": {
        "items": [
            {
                "id": "131f3e80-29f7-49e9-bd1d-3c8ae5a766b6",
                "name": "Tủ đồ iHub 2",
                "address": "Park 5, 458 Minh Khai",
                "city": "Hà Nội",
                "dist": "Hai Bà Trưng",
                "ward": "Vĩnh Tuy",
                "longtitude": 105.794,
                "latitude": 21.0027,
                "createdAt": "2025-06-28T03:41:57.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 0,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 0,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "8677c797-c7d0-4b92-b5bb-ead8d6a5980f",
                "name": "Tủ đồ 01",
                "address": "Chân toà nhà SHOW TIME",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-05-14T02:09:05.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 0,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 0,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "585f7d7c-af7a-4892-b1a9-95dba4545040",
                "name": "chi chi",
                "address": "123123",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-03-26T14:33:57.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 4,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 0,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "eb60ef05-5e7f-49c1-a564-11d4fe184cef",
                "name": "chindl tủ A",
                "address": "test",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-03-26T14:29:17.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 0,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 0,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "59e83826-796b-420c-ac68-9c2ffc3e8000",
                "name": "thêm tủ mới",
                "address": "201 trường chinh",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-03-26T13:43:22.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 4,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 2,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "cfa88e99-4aa7-4ad0-8512-5bf4850621f4",
                "name": "New Locker - ttyS4",
                "address": "Showtimes-F3",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-03-21T07:05:16.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 0,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 1,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "4b20b55e-b0e2-48d1-b269-82cdc2039288",
                "name": "Test 125HN",
                "address": "125HN",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-03-18T04:32:27.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 36,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 25,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 6,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 2,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "84ae520e-0b72-4f8d-b68f-dd0f104e9af1",
                "name": "tesst",
                "address": "1",
                "city": "Hà Nội",
                "dist": "Quận Hai Bà Trưng",
                "ward": "Bạch Đằng",
                "longtitude": 105.821,
                "latitude": 21.0272,
                "createdAt": "2025-03-16T14:17:29.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 27,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 0,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "bf4b1f7d-0cbc-4e41-b7d2-9001ace6cd44",
                "name": "test",
                "address": "qweqưe",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-03-13T15:09:55.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 0,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 0,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            },
            {
                "id": "72238f70-1f36-4ab6-8f30-d19d2d246ba8",
                "name": "Tủ đồ sảnh",
                "address": "Sảnh",
                "city": null,
                "dist": null,
                "ward": null,
                "longtitude": null,
                "latitude": null,
                "createdAt": "2025-03-12T02:00:14.000Z",
                "stacks": [
                    {
                        "boxSize": "s",
                        "availableBox": 4,
                        "info": "24x12x48 cm"
                    },
                    {
                        "boxSize": "m",
                        "availableBox": 0,
                        "info": "55x12x48 cm"
                    },
                    {
                        "boxSize": "l",
                        "availableBox": 0,
                        "info": "55x24x48 cm"
                    },
                    {
                        "boxSize": "xl",
                        "availableBox": 0,
                        "info": "55x50x48 cm"
                    }
                ]
            }
        ],
        "page": 0,
        "size": 10,
        "total": 24
    }
}

Example Response of full format

{
    "data": {
        "items": [
            {
                "id": "083c5896-a074-4ede-92de-fe9b74aca3d7",
                "name": "Tủ 001",
                "address": "289 Khuất Duy Tiến",
                "city": "Hà Nội",
                "dist": "Cầu Giấy",
                "ward": "Trung Hòa",
                "longtitude": 105.794,
                "latitude": 21.0026,
                "distance_km": 9.721785537106374,
                "stacks": [
                    {
                        "id": "207cbd4e-2969-46fb-8d75-584aef0a2a16",
                        "size": "m",
                        "position": 4,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "0892384f-9e76-4da9-ba1e-fdbef40f86c6",
                        "size": "m",
                        "position": 5,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "ceceff85-697f-4132-a8e2-659e30ef440d",
                        "size": "s",
                        "position": 6,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "5fe52a78-af1c-4e48-a2bf-edd954426815",
                        "size": "l",
                        "position": 7,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "c443985c-c38a-48bb-a593-64c31cc91b09",
                        "size": "l",
                        "position": 8,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "0807dd5c-42c2-443e-b280-45ee4bc9a0d5",
                        "size": "l",
                        "position": 9,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "aecc7cc9-5873-440f-b89d-c02c0a332d94",
                        "size": "l",
                        "position": 10,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "48006f1e-ffdc-442f-b6fc-0e99441010ad",
                        "size": "m",
                        "position": 11,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "bd4a1a82-77f9-4cf6-9d7b-cc57e872e204",
                        "size": "m",
                        "position": 12,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "e62b5bdf-fa3c-4a55-bbd8-5764df8f841b",
                        "size": "m",
                        "position": 13,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "abb39f55-5f93-4b1e-b844-16019b36ceb0",
                        "size": "m",
                        "position": 14,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "f815b823-515c-4321-9b7c-9a6d49c3da13",
                        "size": "m",
                        "position": 15,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "400d9585-feb4-45f9-8766-5e38afc3ffd8",
                        "size": "m",
                        "position": 16,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "324e186a-d413-4f92-b45a-d699379bb33e",
                        "size": "m",
                        "position": 17,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "580a2043-ce84-45b8-b1b6-7337ddecdcd8",
                        "size": "m",
                        "position": 18,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "ddcf082b-4e7e-4668-91d5-ae82d6985f1f",
                        "size": "m",
                        "position": 19,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "8668b95f-786f-4206-88f6-db28f927667d",
                        "size": "m",
                        "position": 21,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "690d44ac-e16f-4412-9728-f62c608cb70c",
                        "size": "m",
                        "position": 22,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "f29a62fa-2828-4bd5-aaa8-f25f26a03776",
                        "size": "m",
                        "position": 25,
                        "isUsed": false,
                        "status": true
                    },
                    {
                        "id": "48af7432-8c87-4268-a7ca-eeb288310186",
                        "size": "s",
                        "position": 31,
                        "isUsed": false,
                        "status": true
                    }
                ],
                "stackCount": 20,
                "sizeStack": {
                    "s": "24x12x48 cm",
                    "m": "55x12x48 cm",
                    "l": "55x24x48 cm",
                    "xl": "55x50x48 cm"
                }
            },
            {
                "id": "131f3e80-29f7-49e9-bd1d-3c8ae5a766b6",
                "name": "Tủ đồ iHub 2",
                "address": "Park 5, 458 Minh Khai",
                "city": "Hà Nội",
                "dist": "Hai Bà Trưng",
                "ward": "Vĩnh Tuy",
                "longtitude": 105.794,
                "latitude": 21.0027,
                "distance_km": 9.734654071951898,
                "stacks": [],
                "stackCount": 0,
                "sizeStack": {
                    "s": "24x12x48 cm",
                    "m": "55x12x48 cm",
                    "l": "55x24x48 cm",
                    "xl": "55x50x48 cm"
                }
            }
        ],
        "page": 0,
        "size": 10
    }
}

Get device's detail

Get Device Details by ID

This API endpoint retrieves detailed information about a specific device using its unique device ID.

Endpoint

GET /locker/{lockerId}

Parameters

lockerIdId (string, required): The unique identifier of the device whose details are to be retrieved.

Response

Returns a JSON object containing details of the specified device including its name, address, and geographical location.

Example Request

GET /locker/131f3e80-29f7-49e9-bd1d-3c8ae5a766b6

Example Response

{
    "data": {
        "id": "083c5896-a074-4ede-92de-fe9b74aca3d7",
        "shortId": "083c5896a0744ede92defe9b74aca3d7",
        "name": "Tủ 001",
        "address": "289 Khuất Duy Tiến",
        "city": "Hà Nội",
        "dist": "Cầu Giấy",
        "ward": "Trung Hòa",
        "longtitude": "106.00000000",
        "latitude": "21.00000000",
        "createdAt": "2025-02-13T10:16:38.000Z",
        "stacks": [
            {
                "id": "207cbd4e-2969-46fb-8d75-584aef0a2a16",
                "shortId": "207cbd4e296946fb8d75584aef0a2a16",
                "size": "m",
                "position": 4,
                "isUsed": false,
                "status": true
            },
            {
                "id": "0892384f-9e76-4da9-ba1e-fdbef40f86c6",
                "shortId": "0892384f9e764da9ba1efdbef40f86c6",
                "size": "m",
                "position": 5,
                "isUsed": false,
                "status": true
            }
        ]
    }
}

Use this API to access the device information conveniently by its ID.

Create new order

This API allows you to create a new order by providing relevant details about the sender, receiver, and package.

Endpoint

POST /order

Parameters

Field

Type

Required

Description

receiverPhone

string

The phone number of the receiver

receiverName

string

The name of the receiver

cost

integer

The total cost associated with the order

lockerId

string

The ID of the locker that get from device's detail request

senderPhone

string

The phone number of the sender

stackPosition

number

The stack's position in this device. You must use eithersize or stackPosition when create order

orderType

enum

The orderType of order. Default is locker

partnerCode

string(6)

The code to open stack in case Partner want to retrieve the order. Must using only number [0-9]

partnerOutdateThreshold

number

The maximum time in millisecond that Partner wants to keep the order in locker before we start to count fee

size

enum(s,m,l,xl)

size of stack. You must use eithersize or stackPosition when create order

partnerOrderCode

string(256)

OrderCode of partner's order

partnerRentCode

string(256)

partner's rentCode

Example Request and Response

Request

POST /order
Content-Type: application/json

{
  "receiverPhone": "1234567890",
  "receiverName": "John Doe",
  "cost": 150,
  "lockerId": "131f3e80-29f7-49e9-bd1d-3c8ae5a766b6",
  "senderPhone": "0987654321",
  "stackPosition": 1,
  "description": "Test package",
  "orderType": "locker",
  "partnerCode": "123456",
  "partnerOutdateThreshold": "10000" //10s
}

Response

{
    "data": {
        "id": "ceba7403-69d6-46ea-97b8-b4165cff76a7",
        "paymentStatus": false,
        "deliveryStatus": false,
        "orderStatus": "init",
        "outdateLength": 0,
        "outdateFee": 0,
        "outdateFeePaid": 0,
        "partnerOutdateThreshold": 0,
        "senderPhone": "0948170098",
        "receiverPhone": "0948170099",
        "cost": 1000,
        "lockerId": "c1568a91-f44b-47f2-b8fe-bfd9292e8ace",
        "orderType": "locker",
        "partnerId": "d4735dce-525d-41fb-931e-52761bd7f723",
        "orderCode": "O1Y2GAEP",
        "orderPass": "548067",
        "updatedAt": "2025-07-01T19:23:53.081Z",
        "createdAt": "2025-07-01T19:23:53.081Z"
    }
}

Get order's information

This API allows you to retrieve detailed information about a specific order using a tracking order parameter.

Endpoint

GET /order/{orderId}

Parameter:

orderId: A unique identifier for the order you want to retrieve. This parameter is required to fetch the order's details.

Example

GET /order/ceba7403-69d6-46ea-97b8-b4165cff76a7

Replace {orderId} with the actual order's ID.

Response Example

{
    "data": {
        "id": "ceba7403-69d6-46ea-97b8-b4165cff76a7",
        "paymentStatus": false,
        "deliveryStatus": false,
        "orderStatus": "init",
        "outdateLength": 0,
        "outdateFee": 0,
        "outdateFeePaid": 0,
        "partnerOutdateThreshold": 0,
        "senderPhone": "0948170098",
        "receiverPhone": "0948170099",
        "cost": 1000,
        "lockerId": "c1568a91-f44b-47f2-b8fe-bfd9292e8ace",
        "orderType": "locker",
        "partnerId": "d4735dce-525d-41fb-931e-52761bd7f723",
        "orderCode": "O1Y2GAEP",
        "orderPass": "548067",
        "updatedAt": "2025-07-01T19:23:53.081Z",
        "createdAt": "2025-07-01T19:23:53.081Z"
    }
}

List orders

The List Orders API allows you to retrieve a collection of orders based on specified criteria. You can filter orders by status, purpose, and date range, facilitating effective order management. The response will include details of each order, such as the order ID, status, receiver's information, and timestamps.

Endpoint

GET /order

Parameters

Field

Type

Require

Description

page

number

The index of request's item. Default is 0

size

number

The number item that client want to get per page. Default is 2o

orderStatus

enum[success,failed,init]

Order's status. Init - new order, success - user've got order, failed - order is cancelled

receiverPhone

string

Phone number of receiver

Response Example

The response will include the list of orders matching the specified criteria. Each order in the list will contain details similar to the following:

{
  "orders": [
    {
      "id": "123456",
      "orderStatus": "Delivered",
      "orderType": "Standard",
      "receiverName": "John Doe",
      "receiverPhone": "+1234567890",
      "cost": 10000,
      "orderCode": "ORD789",
      "trackingCode": "TRACK123",
      "createdAt": "2023-10-01T12:34:56Z",
      "updatedAt": "2023-10-02T09:21:18Z"
    },
    ...
  ],
  "totalOrders": 150,
  "currentPage": 1,
  "totalPages": 15
}

Notes

Ensure date and time are in ISO 8601 format when specifying the startTime and endTime.
The status and purpose parameters help in filtering the orders based on their current status and intended use.
Pagination allows you to manage and display orders effectively with the pageSize and pageIndex parameters.

Cancel order

The Cancel Order API allows you to cancel an existing order by specifying the order's unique identifier.

Endpoint

PUT /order/cancel

Parametersa

id (string, required): The unique identifier of the order that needs to be canceled.

Example Request

{
  "orderId": "123456"
}

Response

A successful cancellation will return a confirmation with the order details, including its updated status.

Renew Partner Code

This API endpoint allows you to renew the partner code for a specific order by providing the orderId. Upon successful renewal, it will return the order details, including the new partner code and the updated status.

Endpoint

PUT /orders/partnerCode/renew

Request Parameters

orderId (string, required): The unique identifier of the order for which the partner code needs to be renewed.

Example Request

{
  "orderId": "123456"
}

Response

A successful request will yield a response containing the order details along with the new partner code and a flag indicating whether the update was successful.

Example Response

{
    "data": {
            "id": "fcbc1454-b148-4ecd-ad02-525afbc7c910",
            "lockerId": "84ae520e-0b72-4f8d-b68f-dd0f104e9af1",
            "orderCode": "I8ULO36D",
            "remainCost": 0,
            "orderType": "locker",
            "partnerId": "d4735dce-525d-41fb-931e-52761bd7f723",
            "partnerCode": "132592"
    }
}

Renew Order pass

To renew an order code, a POST API is available that takes the parameter orderId. This API will return the following:

orderPass: The updated order code after renewal.
createdAt: The timestamp indicating when the new order code was created.
updatedAt: The timestamp showing the last update to the order code.
id: The unique identifier for the renewed order.

Example Request

POST /partner/order/renew

Headers:
- Content-Type: application/json
- x-api-key: api-key

Body:
```json
{
    "orderId": "fcbc1454-b148-4ecd-ad02-525afbc7c910"
}

Example Response

{
    "id": "ab123456-1a2b-3c4d-5e6f-7890ghijklmn",
    "orderPass": "NEWCODE123",
    "createdAt": "2023-09-21T10:15:30Z",
    "updatedAt": "2023-09-21T10:15:30Z"
}

Open stack api

Notice:

Only partner who is granted permission can call this API.

To initiate the process of opening a stack, the POST API can be employed, which requires two essential parameters: orderId and lockerId, both of which are strings. When making a request using this API, these parameters must be included to identify the specific order and locker involved in the transaction. Upon successful execution, the API will return a boolean result of true, indicating that the stack has been opened successfully, allowing authorized users or systems to perform further operations with the locker.

POST /partner/locker/open

Headers:
- Content-Type: application/json
- x-api-key: api-key

Body:
```json
{
    "orderId": "fcbc1454-b148-4ecd-ad02-525afbc7c910",
    "lockerId": "84ae520e-0b72-4f8d-b68f-dd0f104e9af1"
}

Response:

{
    "result": true
}

Make sure your partner ID is authorized for this API.
Ensure orderId and lockerId are correctly provided to successfully open the locker.

Update Payment status

To update the payment status of an order, you can use the following API endpoint.

Endpoint

PUT /partner/payment

Headers

Content-Type: application/json
x-api-key: your-api-key

Parameters

orderId (string): The unique identifier of the order.
paymentStatus (boolean): The new payment status to be set (e.g., true for paid, false for unpaid).

Example Request

{
    "orderId": "example-order-id",
    "paymentStatus": true
}

Response

{
    "result": true
}

This response indicates whether the payment status was successfully updated.

User Token Retrieval API

This API allows partners to obtain a user token by providing two parameters: phoneNumber and partnerDetail.

Request

Method: POST
Endpoint: /partner/user/token
Headers:
- Content-Type: application/json
Request Body
```
{
    "phoneNumber": "string",
    "partnerDetail": "object"
}
```
Response
The response includes the following fields to inform the partner about the token and permission status.
Successful Response Example
```
{
    "token": "string", // Token for accessing user's orders
    "needRequestPermission": false // Indicates if permission from the user is required
}
```
- token: The access token the partner can use to retrieve user's order data.
- needRequestPermission: A boolean flag indicating whether the partner must wait for user consent to access order data.

Webhook

A webhook is a mechanism that allows you to receive real-time data updates as soon as an event occurs. For order information, your system can subscribe to a webhook that sends data whenever there is a change or update in an order's status.

Example Payload

When an order is created or updated, a webhook payload like the following might be sent to your specified URL:

{
    "id": "12345",
    "orderStatus": "success",
    "cost": 10000,
    "paymentStatus": true,
    "deliveryStatus": true,
    "receiverPhone": "0123456789",
    "receiverName": "Nguyen van a",
    "orderCode": "12345",
    "orderType": "locker",
    "senderPhone": "012345678",
    "descripion": "test",
    "createdAt": "2025-02-01",
    "updatedAt": "2025-02-02",
    "userToken": "",//token for owner of this order
    "partnerLocationId": "" //ID of partner's project
}

Note: userToken is current token of owner of this order. It's used to open a webview that help owner can access all his orders these have not been openned. This token is valid until the next webhook of this owner is created.

Verifying the Signature

To ensure the data integrity and authenticity of the received webhook, you should verify its signature using a shared secret key. Here's a basic example of how to check the signature:

Calculate the HMAC SHA256 hash of the payload using your secret key.
Compare the calculated hash with the signature sent in the webhook headers.

import hmac
import hashlib

secret = 'your-secret-key'
payload = b'{"orderId": "12345", "status": "shipped", "items": [{"itemId": "67890", "quantity": 2}], "total": 100.50, "currency": "USD"}'
signature = 'expected-signature-from-header'

# Generate hash
calculated_signature = hmac.new(bytes(secret, 'utf-8'), payload, hashlib.sha256).hexdigest()

# Verify signatures match
if hmac.compare_digest(calculated_signature, signature):
    print("Signature verified.")
else:
    print("Signature verification failed.")

By following these steps, you can ensure that the data received is from a trusted source and hasn't been tampered with.

PreviousAPI document

Last updated 5 months ago

hashtagBasic information:

hashtagAuthenticating Requests with an API Key

hashtagWebhook with Secret Key and HMAC-SH256 Signature

hashtagGenerating a Signature

hashtagVerifying the Signature in Node.js

hashtagList devices

hashtagAPI Description: List Devices

hashtagExample Response of compact format

hashtagExample Response of full format

hashtagGet device's detail

hashtagGet Device Details by ID

hashtagCreate new order

hashtagEndpoint

hashtagParameters

hashtagExample Request and Response

hashtagGet order's information

hashtagEndpoint

hashtagParameter:

hashtagExample

hashtagResponse Example

hashtagList orders

hashtagEndpoint

hashtagParameters

hashtagCancel order

hashtag Renew Partner Code

hashtagRenew Order pass

hashtagOpen stack api

hashtagUpdate Payment status

hashtagEndpoint

hashtagHeaders

hashtagParameters

hashtagExample Request

hashtagResponse

hashtagUser Token Retrieval API

hashtagRequest

hashtagResponse

hashtagWebhook

hashtagExample Payload

hashtagVerifying the Signature

Basic information:

Authenticating Requests with an API Key

Webhook with Secret Key and HMAC-SH256 Signature

Generating a Signature

Verifying the Signature in Node.js

List devices

API Description: List Devices

Example Response of compact format

Example Response of full format

Get device's detail

Get Device Details by ID

Create new order

Endpoint

Parameters

Example Request and Response

Get order's information

Endpoint

Parameter:

Example

Response Example

List orders

Endpoint

Parameters

Cancel order

Renew Partner Code

Renew Order pass

Open stack api

Update Payment status

Endpoint

Headers

Parameters

Example Request

Response

User Token Retrieval API

Request

Response

Webhook

Example Payload

Verifying the Signature