Opollo Open API (1.0.0)

Welcome to the Opollo Open API Documentation. Our platform revolutionizes e-commerce businesses by seamlessly connecting their operations with numerous selling platforms, online stores, warehouses, and third-party logistics providers. This guide is designed for partners like you, providing elaborate instructions on how to integrate with the Opollo system

To begin using Opollo's Open API, you need to register for API access by contacting your brand team to create an API application on Opollo with the right API scopes related to your integration data such as warehousing fulfillment, delivery, selling channel or reporting.

After that, we recommend starting with these documents:

1. Development Guide - Learn the process of API calling.
2. API Best Practices - Learn how your system interacts with Opollo.
3. Integration Workflow - Learn how Opollo interacts with your system and platforms.
4. Webhook - Learn how to receive latest changes.
5. Testing Guide - Learn how to test your integration.

APIs are called through HTTP requests. The process of calling an API is as follows:

• Generate signature
• Assemble the HTTP request
• Get the HTTP response

Headers

Business parameters

The process of generating the signature for each request is as follows:

• Use dots (.) to concatenate the query string, the minified JSON request body, and the current epoch time.
• Use the provided secret key and SHA-256 to compute the HMAC of the concatenated string.

For example:

Give the following request information:

• Query: query_foo=1&query_bar=abc
• Minified request body: {"foo":"abc","bar":2}
• Secret key: secret-key
• Current epoch time is 1704067200 (2024-01-01T00:00:00.00Z)

The computed HMAC is d12f057453d9462860bfe21b8120b16dc31f11e31315588666f72f67a5ea6fcc (try it on https://www.devglan.com/online-tools/hmac-sha256-online).

Give a request with the following information:

• Endpoint: POST http://example.com/example-enpoint
• Query: query_foo=1&query_bar=abc
• Minified request body: {"foo":"abc","bar":2}

The provided keys:

• API key: api-key
• Secret key: secret-key

The current epoch time is 1704067200 (2024-01-01T00:00:00.00Z).

Generate signature

The process of generating the signature is as follows:

• Concatenated request information: query_foo=1&query_bar=abc.{"foo":"abc","bar":2}.1704067200
• Compute HMAC: d12f057453d9462860bfe21b8120b16dc31f11e31315588666f72f67a5ea6fcc
• Uppercase the HMAC: D12F057453D9462860BFE21B8120B16DC31F11E31315588666F72F67A5EA6FCC

Assemble the HTTP request

curl --location 'http://example.com/example-enpoint?query_foo=1&query_bar=abc' \
--header 'x-api-key: api-key' \
--header 'x-timestamp: 1704067200' \
--header 'x-signature: D12F057453D9462860BFE21B8120B16DC31F11E31315588666F72F67A5EA6FCC' \
--header 'Content-Type: application/json' \
--data '{"foo":"abc","bar":2}'

Status flow

B2C outbound request status flow

B2B outbound request status flow

API call flow

B2C outbound request statuses and API call flow

B2B outbound request statuses and API call flow

Status flow

API call flow

Updating...

Whenever the warehouse has a change in inventory, the WMS needs to send a signal to update the inventory in Opollo. We recommend that the WMS update the inventory at a high frequency to ensure real-time inventory synchronization across platforms.

B2C outbound request workflow

Workflow steps:

1. Customer places an order on the selling platform.
2. Opollo receives the order, locks the product stock, and sends a signal to the WMS for the new outbound request (OR).
3. The WMS receives an OR from Opollo, locks the warehouse product stock, and updates the inventory in Opollo. When the OR is successfully created at the WMS, Opollo will decrease the committed stock.
4. After packing the OR, the WMS sends a signal to confirm it is packed to Opollo. Our system will then confirm the packing on the selling platform to obtain the shipping label and send it to the WMS.
5. The WMS receives the label, completes the packing process, and sends a signal to confirm it is ready to ship. Opollo will then send a signal to the Platform (or the Delivery partner) to pick up the goods from the warehouse.
6. After handing over the package to the third-party logistics (3PL) provider, the warehouse needs to send a confirmation of the handover action and update the inventory in Opollo.
7. Optional - If the package fails to be delivered, the delivery partner sends the package back to the warehouse. After receiving the package, the WMS sends a signal to confirm that the package has been returned.

B2B outbound request workflow

Workflow steps:

1. After an outbound request has been created, Opollo will send a signal to the WMS for the new outbound request.
2. The WMS receives an OR from Opollo, locks the stock at the warehouse, and updates the inventory in Opollo.
3. After each packing session, the warehouse needs to send a signal to confirm processing, update the status, and provide the last actual outbound quantity to Opollo. (Outbound processing can be triggered multiple times).
4. After handing over the package to the 3PL, the warehouse needs to confirm the handover and update the inventory in Opollo.

Outbound Request cancellation

For B2B outbound requests, Opollo only cancels warehouse orders that are not confirmed as "processing". The cancellation signal will be sent via webhook.

For B2C outbound requests, please refer to the workflow below:

Workflow steps:

1. Opollo sends a signal to cancel a B2C outbound request (OR) to the WMS.

2. If the OR has not been confirmed as ready to ship (RTS), it will be successfully canceled.

3. If the OR has been confirmed as ready to ship:

   • If the cancellation request fails and the package has been handed over to the 3PL, WMS will take action to confirm the handover and update the inventory in Opollo.
   • If the OR has not yet been handed over to the 3PL, WMS will confirm the cancellation and perform the re-inbound process to update the inventory in Opollo.

An Inbound request (IR) can originate from either Opollo or WMS.

Inbound request created by Opollo

Workflow steps:

1. After an IR has been created, Opollo will send a signal to WMS for the new IR.
2. WMS receives the IR from Opollo.
3. The warehouse sends a "start processing" signal to Opollo upon the arrival of the supplier or delivery partner at the warehouse. The purpose of this signal is to confirm that the warehouse has received the goods and that Opollo cannot the IR anymore.
4. The warehouse proceeds with QC, inbound, and putaway. For each batch received, the warehouse sends a partial inbound signal to update the actual received quantity and inbound status.
5. In parallel, the warehouse updates the inventory of the SKU after stock synchronization.
6. After completing the receiving process, the warehouse sends a "complete an inbound" signal to Opollo.

Inbound request created by WMS

Workflow steps:

1. The user creates an IR on WMS.
2. WMS sends a signal to create an IR with type "standard" to Opollo.
3. The warehouse sends a "start processing" signal to Opollo upon the arrival of the supplier or delivery partner at the warehouse.
4. The warehouse proceeds with QC, inbound, and putaway. For each batch received, the warehouse sends a partial inbound signal to update the actual received quantity and inbound status.
5. In parallel, the warehouse updates the inventory of the SKU after stock synchronization.
6. After completing the receiving process, the warehouse sends a "complete an inbound" signal to Opollo."

Inbound request cancellation

Inbound request cancellation is separated into two types:

Inbound request created by Opollo:

Opollo will send a signal to WMS via webhook when a user cancels an inbound request.

Inbound request created by WMS:

1. When an inbound request is canceled in WMS, WMS sends a signal to cancel the inbound request to Opollo.
2. Opollo performs validation of the inbound request's source, whether it is from Opollo or WMS:
   • If the IR's source is Opollo, Opollo will reject the cancellation request.
   • Otherwise, Opollo will check if the IR has not sent the "start processing" signal. If it has not, Opollo will accept the cancel signal from WMS.

The return order is an inbound request with the type "return" and can be created by Opollo or WMS.

Return order created by Opollo

Workflow steps:

1. Customers directly contact Customer Service (CS) for returns. After verifying, CS creates an IR for returning.
2. The warehouse receives the IR from Opollo.
3. The warehouse sends a "start processing" signal to Opollo upon the arrival of the delivery partner at the warehouse.
4. When the delivery partner hands over the goods to the warehouse, the warehouse receives the goods according to the IR.
5. The warehouse proceeds with QC, inbound, and putaway.
6. In parallel, the warehouse updates the inventory of the SKU after stock synchronization.
7. When the inbound request is completed, the warehouse sends a "complete an inbound" signal to Opollo.

Return order created by WMS

Workflow steps:

1. Delivery sends the package to the warehouse.
2. The warehouse receives and checks the package's appearance.
3. If the QC process fails, the warehouse can reject receiving the package.
4. If the QC process passes, the warehouse checks if the order exists in WMS.
5. If the order exists, the warehouse creates the return order and calls the API to "create an inbound request" with the type "return" and inputs one of two fields: "shipped_tracking_code" or "shipped_or_code".
6. If the order doesn't exist, the warehouse needs to check with your brand team to identify Opollo's package.
7. If the order doesn't exist in Opollo, return to step 3.
8. If the order exists in Opollo, the brand team provides either the "shipped_or_code" (the original warehouse outbound request code) or the "shipped_tracking_code" (the original tracking code) for the warehouse to create a return order.
9. Then, the warehouse follows the inbound request process to complete the inbound request with the type "return".

Webhook provides a method to notify latest changes in the Opollo system to your system immediatetely.

To use this feature, you need to register by contacting your brand team to configure the Webhook URL for your application.

Request structure

Request headers

For security purposes, we use the method described in the API calling process section to generate the signature for each request. For each request, we use your provided API key and secret key to generate the signature. The signature does not include the request query string.

Request body

For all webhook requests, we use the POST method with the following structure:

{
  "topic": "[the webhook topic]",
  "data": {
    // The notified change
  }
}

Common payload structure:

{
  "data": {
    "or_code": "[the outbound request code]",
    "ref_or_code": "[the warehouse reference outbound request code]",
    "status": "[the updated status]",
    "updated_at": "[the updated time in ISO-8601 format]",
    "warehouse_code": "[the warehouse code]"
  },
  "topic": "[the webhook topic]",
}

For the warehouse_outbound_request_delivery_informed, the payload is descrisbe by this structure:

{
  "data": {
    "delivery_name": "[the delivery service name]",
    "or_code": "[the outbound request code]",
    "pickup_name": "[the pickup service name]",
    "ref_or_code": "[the warehouse reference outbound request code]",
    "status": "[the updated status]",
    "shipping_label_url": "[the shipping label URL]",
    "tracking_code": "[the delivery tracking code]",
    "updated_at": "[the updated time in ISO-8601 format]",
    "warehouse_code": "[the warehouse code]"
  },
  "topic": "warehouse_outbound_request_delivery_informed"
}

List of topics:

Common payload structure:

{
  "data": {
    "ir_code": "[the inbound request code]",
    "ref_ir_code": "[the warehouse reference inbound request code]",
    "status": "[the updated status]",
    "updated_at": "[the updated time in ISO-8601 format]",
    "warehouse_code": "[the warehouse code]"
  },
  "topic": "[the webhook topic]",
}

List of topics:

Common payload structure:

{
  "data": {
    "sku": "[the product SKU]",
    "updated_at": "[the updated time in ISO-8601 format]"
  },
  "topic": "[the webhook topic]",
}

List of topics:

For each partner who needs to integrate with the Opollo system, we provide a testing environment to ensure the integration is successful. The testing guide includes the following steps:

We use Postman for testing the Opollo Open API. To start testing, you need to follow these steps:

1. Open URL: https://open.onpoint.vn

2. Download the Postman collection by clicking on the Download button

3. After downloading, you can import the collection to your Postman application.

4. Create a new environment with the following variables:

• api_key: your provided API key
• secret_key: your provided secret key

Now you are ready to test the Opollo Open API.

Create a new outbound request

1. Open the provided sample store to create a new order.

2. Select quantity to buy by clicking the + button for each product.

3. Click the Buy (or Mua ngay) button to create a new order.

4. Enter your information and complete your order

View outbound requests

1. Log into the Opollo Admin with your provided testing account via this URL:

https://stg-admin.onpoint.vn/sign_in

2. To view your B2C outbound request, you should go to the B2C Order page via this URL

https://stg-admin.onpoint.vn/orders?utm_source=sidebar

3. An order may take 5-10 minutes to be processed in multiple steps (for example: applying promotions, checking stock, etc.) before it is successfully pushed to the warehouse when its status is wh_processing.

4. Now you can see your B2C order via the Listing oubound request API

Note:

• After you confirm packing an order and Opollo acknowledges the confirmation by confirming the order is packed on the platform, the platform will create a delivery order.
• Depending on the platform, Opollo will receive the tracking code and shipping label from the platform and send them to the warehouse within 5-10 minutes after confirming packing.
• After receiving the tracking code and shipping label, you can use the Confirming ready to ship API to confirm ready to ship the B2C outbound request.

Cancel an outbound request

1. Find your order on Opollo

2. Click the Show more button to show order's fulfillments

3. Click the Cancel button to cancel an order fulfillment (the B2C outbound request in the warehouse)

1. Access this URL to open the Purchase Orders page: https://stg-admin.onpoint.vn/purchase_order_v2/

2. Click the Create New button to create a new purchase order

3. Fill in the highlighted fields in the image below

4. Add purchase order items by filling their SKU information

5. Click the Submit button to save the purchase order.

6. Click the Approve button, enter your password, and click the Confirm button to approve the purchase order.

Now you can see your purchase order inbound request via the Listing inbound requests API.

1. Create a B2C order with virtual delivery as the delivery type

2. After the B2C outbound request is pushed to the warehouse, use the outbound request update API to update the ref_or_code value before packing.

3. Access this URL to open the B2C orders page: https://stg-admin.onpoint.vn/orders?utm_source=sidebar

4. Find your B2C order and click the Complete this order button to complete.

5. After completing the order, click the "Create return order" button to create a B2C return order

6. You will be navigated to the B2C return order detail page.

7. Add B2C return order information by completing the highlighted fields and items shown in the image below.

8. Click the "Push Order" button. Once pushed successfully, your order will appear in the Listing inbound requests API.

If you have any concerns, please feel free to contact our Tech team via email: opollo-tech@onpoint.vn.