Packages (list & detail)

Warehouse packages after inbound notice.

Availability: Sandbox / Gateway MOCK is live (hio_test_*). Live warehouse upstream forwarding is not wired yet.

Requires warehouse fulfillment. Scope: warehouse:read.

After inbound create, use returned package_id (pkg_*). Each package also has human-readable package_no (e.g. PKG202608160001).

Vòng đời {#lifecycle}

Luồng chính (nét liền): báo trước → đã nhập kho → đã gộp → đã gửi → đã nhận.
Nhánh (nét đứt): không khớp → UNCLAIMED (claim về RECEIVED); từ RECEIVED có thể DISCARDED.

Thêm: TRANSFERRING (chuyển kho), ARCHIVED (sau khi hoàn tất).

List {#list}

List rows are intentionally smaller than detail — no items[], full sender, services[], exception files, fee breakdown, or full timestamps.

Query parameters

Cursor pagination may be added later for large catalogs; v1 MOCK uses page offset.

List item example

{
  "id": "pkg_01K2ABCDEF1234567890",
  "package_no": "PKG202608160001",
  "status": "RECEIVED",
  "archived": false,
  "external_order_id": "KR-20260816-001",
  "supplier_order_id": "1688-987654321",
  "tracking_number": "SF123456789012",
  "carrier": "SF Express",
  "warehouse": {
    "location_code": "WH-CN-WH-01",
    "weight": {
      "value": 2.35,
      "unit": "kg"
    },
    "dimensions": {
      "length": 42,
      "width": 30,
      "height": 18,
      "unit": "cm"
    }
  },
  "attributes": {
    "goods_type": "GENERAL",
    "tags": [
      "GENERAL_GOODS"
    ]
  },
  "condition": {
    "status": "NORMAL",
    "has_exception": false
  },
  "item_summary": {
    "item_count": 2,
    "total_quantity": 20
  },
  "service_summary": {
    "total": 2,
    "pending": 0,
    "processing": 0,
    "completed": 2
  },
  "shipment": {
    "shipment_id": null
  },
  "created_at": "2026-08-16T07:40:00Z",
  "received_at": "2026-08-16T08:05:00Z",
  "updated_at": "2026-08-16T09:30:00Z"
}

List response envelope

{
  "data": [],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 128,
    "total_pages": 7
  },
  "request_id": "req_…"
}

Detail {#detail}

GET /v1/fulfillment/packages/{package_id} — full package after inbound.

Response layout (12 blocks)

identity · status · order/tracking · items · sender · warehouse
attributes · condition · services · fees · claim/transfer/shipment · timestamps

Money: face value + currency (not fen / CNY_minor).
Items: quantity and unit_price are numbers.
Identity: id (programmatic) + package_no (ops-friendly).

Locked decisions

1. items.quantity / unit_price → numbers
2. attributes.goods_type (GENERAL | SENSITIVE) + tags[]
3. Lifecycle status vs condition
4. Paid photos → services[].result.files; optional warehouse_files
5. fees summary only
6. warehouse.location_code = HIOBuy Fulfillment Location

Exception codes (v1)

DAMAGED · MISSING_ITEM · QUANTITY_MISMATCH · WRONG_ITEM · WRONG_SKU · PACKAGING_DAMAGED · UNKNOWN_ITEM · OTHER

Package status

PENDING, RECEIVED, CONSOLIDATED, SHIPPED, DELIVERED, TRANSFERRING, DISCARDED, UNCLAIMED, ARCHIVED.

Detail example

See internal packages.md for the full detail JSON (includes package_no, services, fees, timestamps).

Related

• Inbound notice
• Fulfillment overview
• Errors