Guía de pruebas de fulfillment WH-DEV

Test the complete HIOBuy warehouse fulfillment workflow before going live.

This page is a workflow guide, not an API reference. Each step links to the endpoint documentation you need for that step.

WH-DEV is a controlled integration testing environment

Some physical warehouse operations — receiving parcels, packing, weighing, dispatching, and tracking progression — may require simulation by the HIOBuy team while you test.

In production these operations run through normal HIOBuy warehouse workflows. You do not need to contact support for each shipment.

Before you start

Requirement	How to get it
Active developer subscription with warehouse fulfillment access	Growth or Enterprise plan — see Warehouse authorization
WH-DEV warehouse developer code	Provided by HIOBuy after approval
App configured for HIOBuy warehouse fulfillment	Portal → Authorizations
Production API key (`hio_live_*`)	Authentication
Test wallet balance	Wallet balance — top up before paying a shipment
Test destination address and available shipping channels	Configured by HIOBuy on your WH-DEV warehouse

Do not use a Sandbox key (hio_test_*) to test WH-DEV. Sandbox returns fixtures that are unrelated to your assigned warehouse. WH-DEV integration testing uses hio_live_* + WH-DEV code, which is still a test warehouse configuration — not live fulfillment. See Sandbox.

No WH-DEV code yet? Start at Warehouse authorization.

End-to-end testing flow

#	Step	API	Doc
1	Bind the WH-DEV code to your app	— (portal)	Warehouse authorization
2a	Create a procurement order so the seller ships to the warehouse	`POST /v1/orders/create`	Create order
2b	Or declare a parcel you already control	`POST /v1/fulfillment/inbounds/create`	Inbound notice
3	Poll the package until it is `RECEIVED`	`GET /v1/fulfillment/packages/{package_id}`	Packages
4	Quote international freight	`POST /v1/fulfillment/shipping/quotes`	Shipping quotes
5	Create the shipment with `tracking_numbers[]`, `receiver`, `shipping_channel_code`	`POST /v1/fulfillment/shipments/create`	Shipments · create
6	Poll the shipment while the warehouse packs and measures	`GET /v1/fulfillment/shipments/{id}`	Shipments · detail
7	Pay once the shipment is ready	`POST /v1/fulfillment/shipments/{id}/pay`	Shipments · pay
8	Read scan events after dispatch	`GET /v1/fulfillment/shipments/{id}/tracking`	International tracking

Shipment status progression: PENDING → WAIT_PAYMENT → WAIT_SHIP → SHIPPED → SIGNED.

Developer actions vs warehouse actions

Stage	You (developer)	HIOBuy WH-DEV
Warehouse authorization	Configure the app	Provide the WH-DEV code
Procurement / inbound notice	API call	—
Parcel arrival	Poll package status	Simulate warehouse receiving
Package received	Query package detail	Update warehouse status
Shipping quote	API call	—
Create shipment	API call	—
Retrieve packages from storage	—	Warehouse simulation
Consolidation / packing	—	Warehouse simulation
Final weighing and measurement	Poll shipment detail	Warehouse simulation
Settlement	Pay API	—
Dispatch	Poll shipment detail	Warehouse simulation
Tracking progression	Tracking API	Simulated scan events

Shipment packing and payment

Why can’t I pay immediately after creating a shipment?

A new shipment normally starts in PENDING:

{
  "id": "115",
  "status": "PENDING",
  "payment_status": "UNPAID",
  "boxes": [],
  "times": {
    "packed_at": null
  }
}

That is expected. The warehouse still has to:

Retrieve the packages from storage
Consolidate the selected packages
Pack the shipment
Measure the final weight
Measure the final dimensions
Calculate the final freight

Only then does the shipment become payable (WAIT_PAYMENT).

If you call pay too early:

POST /v1/fulfillment/shipments/115/pay
Authorization: Bearer hio_live_...

you may get:

HTTP	`error.code`
409	`SHIPMENT_NOT_READY_FOR_PAYMENT`

This is not an integration bug. It means warehouse packing and final measurement are not finished yet.

Poll shipment detail and retry pay once the shipment is ready. Useful signals:

Signal	Ready for payment
`status`	`WAIT_PAYMENT`
`payment_status`	`UNPAID` with `total.outstanding` > 0
`times.packed_at`	Not `null`
`boxes[]`	Non-empty, with final `weight` / `dimensions`

Other pay errors: 404 NOT_FOUND (unknown shipment), 409 SHIPMENT_ALREADY_PAID, 402 INSUFFICIENT_BALANCE — top up via Wallet balance. Full list: Shipments · pay and Errors.

WH-DEV warehouse simulation

WH-DEV is not a continuously running production warehouse. These events may need HIOBuy to simulate them while you test:

Package received
Package inspection
Package storage
Shipment packing
Final weight measurement
Final dimension measurement
Shipment dispatch
Tracking progression
Delivery completion

If your test is waiting on one of these, email support@hiobuy.com or open a support ticket.

Support request format

Subject: WH-DEV Fulfillment Test Assistance

Application:
WH-DEV Code:

Package ID:
Shipment ID:
Order SN:

Current Status:

Expected Next Test Step:

Request ID:

Every API response carries a request_id. Including it helps HIOBuy developer support locate your exact request.

What changes in production?

In WH-DEV some physical events are simulated on request. In production a real parcel moves through the normal warehouse workflow:

These are routine warehouse operations. You do not contact HIOBuy support for each shipment. Your app only needs to:

Monitor shipment status
Query shipment detail
Wait until payment becomes available
Complete settlement
Monitor tracking

Webhooks

Instead of tight polling loops you can subscribe to fulfillment events in the portal . Events relevant to this flow today:

Event type	When it fires
`package.received`	Domestic parcel received at the warehouse
`package.exception`	Inbound package exception
`consolidation.completed`	Packages consolidated for outbound
`shipment.created`	International shipment created
`shipment.dispatched`	Shipment handed to the carrier
`shipment.delivered`	Delivered to the recipient
`shipment.exception`	Outbound exception
`balance.low`	Wallet below your threshold

There is no “ready for payment” event today. Detect payability from shipment detail as described above.

Recommended pattern:

HIOBuy warehouse
        ↓
Webhook (package.received / shipment.dispatched / …)
        ↓
Your system
        ↓
GET shipment detail
        ↓
Business logic → pay / notify customer

Sandbox resources do not auto-emit webhooks; use Send test in the portal. Full catalog, signature verification, and retries: Webhooks.

Test shipping channels

Shipping channels returned in WH-DEV are for integration testing:

Shipping quote integration
Channel selection
Shipment creation
Settlement testing
Tracking workflow testing

Do not use WH-DEV shipping channel data as production logistics specifications. Channel names, prices, delivery times, customs models, tax models, and last-mile services in a test warehouse are not commercial commitments. Production channels may differ in pricing, service areas, customs clearance models, tax rules, restrictions, and delivery requirements.

Shipping channel rules — coming soon

Coming soon

HIOBuy plans to expose richer channel rules so applications can select a lane automatically: service scope, destination coverage, delivery method, last-mile delivery, charging rules, estimated delivery time, customs clearance model, tax model (DDP / DAP / DDU), whether duties and taxes are included, product restrictions, and weight / dimension limits.

These fields and endpoints are not available yet. Build against the documented shipping quotes response for now.

Warehouse authorization — get and bind your WH-DEV code
Fulfillment overview — endpoint map
Shipments · Packages · Inbound notice
Sandbox — hio_test_* fixtures vs WH-DEV
Errors · Support tickets

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support