Openapi For Warehouse Integration Process – OneWarehouse

This article is intended for warehouse partners who need to integrate their Warehouse Management System (WMS) with OneWarehouse (OW). After integration via OpenAPI, OneWarehouse can push products, inbound orders, return inbound orders, outbound orders, and cancellation instructions to the warehouse WMS; the warehouse can also synchronize processing results such as inbound, outbound, cancellation, and exceptions back to OneWarehouse through callback interfaces based on actual operations.

For complete fields, request examples, and error codes, please refer to the OneWarehouse OpenAPI documentation: OneWarehouse OpenAPI Documentation.

1. Overall Integration Process

The integration process for OpenAPI For Warehouse is divided into four phases:

Preparation
Confirm the responsibilities of both systems, business scenarios, and the scope of APIs to be integrated.
Interface Configuration
The warehouse provides the WMS receiving endpoints, and OneWarehouse configures the Webhook push addresses; at the same time, confirm the method and authentication information for warehouse callbacks to OneWarehouse.
Sandbox Joint Testing
Use the OneWarehouse sandbox environment to create test data such as products, inbound orders, return orders, outbound orders, and verify whether the data flow between both parties is correct.
Go Live
After completing all necessary API tests, switch to the production environment and complete the first online order verification.

2. System Data Flow Description

The data flow between OneWarehouse and warehouse WMS is divided into two directions:

1. OneWarehouse Pushes to Warehouse WMS

This direction involves OneWarehouse actively sending requests to the API URL provided by the warehouse. It is mainly used to create or update products, inbound orders, outbound orders, and cancellation instructions.

Example scenarios:

After the merchant creates a purchase inbound order in OneWarehouse, OW pushes the inbound order data to the WMS.
After the merchant executes outbound in OneWarehouse, OW pushes outbound order, recipient, product details, logistics method, and other data to the WMS.
When the merchant initiates interception of shipment or cancels inbound in OneWarehouse, OW pushes the cancellation request to the WMS.

2. Warehouse WMS Callbacks to OneWarehouse

This direction involves the warehouse WMS synchronizing processing results back to OneWarehouse after operation status changes.

Example scenarios:

After the warehouse completes inbound acceptance, it returns the actual received quantity and inbound status.
After the warehouse completes outbound, it returns outbound completion status, tracking number, package information, or shipping label information.
When the warehouse rejects cancellation, cancellation fails, or an exception occurs, it returns the corresponding processing result and reason.

For specific callback interfaces, request fields, and status codes, please refer to the latest specifications in the OpenAPI documentation.

3. API Receiving Endpoints Required from the Warehouse

Before establishing the sandbox environment, the warehouse must first provide the following API receiving endpoints. OneWarehouse will push JSON format data to the corresponding URLs based on business trigger points.

API Type	Function Description	Logic Description
Product Synchronization API	Synchronize basic product files	When a product is created for the first time or product data is updated, OneWarehouse pushes product data to WMS. If `sku_id` already exists, WMS should perform an update; if it does not exist, WMS should perform an addition.
Purchase Inbound Order API	Create purchase inbound task	Used for OneWarehouse to push purchase inbound order data to WMS, so the warehouse can establish inbound operation tasks accordingly.
Return Inbound Order API	Create return inbound task	When the merchant processes returns and executes inbound, OneWarehouse pushes return inbound data to WMS.
Inbound Order Cancellation API	Cancel unfinished inbound orders	When the merchant initiates inbound cancellation or interception, WMS needs to return whether cancellation is allowed based on the current operation status.
Outbound Order Placement API	Create outbound shipment order	Used for OneWarehouse to push outbound orders, recipient information, product details, logistics provider information, and other data to WMS.
Outbound Order Cancellation API	Cancel orders not yet outbound	When the merchant initiates shipment interception, WMS needs to return whether the interception was successful based on the current outbound progress.

⚠️ Note: The above API URLs are necessary prerequisites for establishing the sandbox testing environment. If not provided, OneWarehouse cannot complete Webhook configuration and cannot provide a complete sandbox joint testing environment.

4. Sandbox Environment Preparation

Before going live, please complete development and testing in the OneWarehouse sandbox environment.

1. Information Required from the Warehouse

Please provide the following information to the OneWarehouse integration team:

Product Synchronization API URL
Purchase Inbound Order API URL
Return Inbound Order API URL
Inbound Order Cancellation API URL
Outbound Order Placement API URL
Outbound Order Cancellation API URL
Warehouse code for testing
Technical contact person and contact information

2. Provided by OneWarehouse

The OneWarehouse integration team will provide the following after configuration is complete:

Sandbox client portal
Sandbox test account
Test AppSecret or other authentication information
Technical integration group

For security reasons, sensitive information such as AppSecret is recommended to be provided separately via the integration group or designated methods.

5. Integration and Testing Process

Step 1: Log in to the Sandbox Client to Trigger Tests

The warehouse can perform the following operations via the OneWarehouse sandbox client to trigger the corresponding API pushes.

Test Item	Trigger Method
Product Synchronization API	Initial product synchronization usually triggers when creating and saving a purchase inbound order; existing product updates can be triggered by editing the product and saving.
Purchase Inbound Order API	Triggered when creating and saving a purchase inbound order.
Return Inbound Order API	Triggered when processing a pending return order and executing inbound processing.
Inbound Order Cancellation API	Triggered when voiding, canceling, or intercepting inbound for a pending inbound order.
Outbound Order Placement API	Triggered when executing outbound for a pending order.
Outbound Order Cancellation API	Triggered when intercepting shipment or canceling outbound for a pending outbound order.

Step 2: Check WMS Reception Results

The warehouse must confirm whether WMS correctly received the data pushed by OneWarehouse and check the following items:

Whether the API received the request
Whether the Request Body is complete
Whether field formats meet expectations
Whether WMS successfully created the corresponding documents
Whether WMS correctly returned the Response
Whether OneWarehouse correctly displays the push results

Step 3: Test WMS Callbacks to OneWarehouse

If the integration scope includes warehouse callbacks, the warehouse must complete callback testing according to the OpenAPI documentation, including but not limited to:

Inbound completion callback
Outbound completion callback
Outbound logistics information callback
Cancellation result callback
Exception status callback

During callback testing, please confirm whether OneWarehouse can correctly update document status and logistics information.

Step 4: Troubleshooting

If data synchronization fails, statuses are inconsistent, fields are incorrect, or interface errors occur during testing, please provide the following information in the integration group:

OneWarehouse order number
Error screenshots
WMS system logs

The OneWarehouse technical team will assist in troubleshooting based on the logs.

6. Testing Acceptance Criteria

Before completing sandbox joint testing, it is recommended to pass at least the following test items:

Test Item	Acceptance Criteria
Product Synchronization	Products can be successfully pushed from OneWarehouse to WMS, with correct addition and update logic.
Purchase Inbound	Purchase inbound orders can be successfully created in WMS, with correct product details and quantities.
Return Inbound	Return inbound orders can be successfully created in WMS, with correct returned products and quantities.
Inbound Cancellation	WMS can return cancellation success or failure based on actual operation status.
Outbound Order Placement	Outbound orders can be successfully created in WMS, with correct recipient, product, and logistics information.
Outbound Cancellation	WMS can return interception success or failure based on outbound progress.
Warehouse Callback	WMS can successfully synchronize operation results back to OneWarehouse.
Exception Handling	When data errors or business status do not permit, WMS can return clear error messages.

7. Go Live Process

Go Live Application: When all required APIs pass joint testing and both parties confirm data flow accuracy, you may apply to switch to the production environment.
Parameter Switch: We will provide the production environment dedicated AppSecret and the official client link.
Official Launch: Please switch your WMS receiving address to the production domain name, complete the final first online order verification, and then officially go live.

If you have any technical questions, please feel free to contact the OneWarehouse technical integration team.