第6章：数据格式说明

本文档统一说明 WMS API 中涉及的数据格式规范，包括日期时间、数值、字符串、枚举值等。

6.1 日期时间格式

6.1.1 日期格式

格式：MM/dd/yyyy

说明：

• MM：月份，两位数（01-12）
• dd：日期，两位数（01-31）
• yyyy：年份，四位数

示例：

• 10/10/2025 - 2025年10月10日
• 01/01/2025 - 2025年1月1日
• 12/31/2025 - 2025年12月31日

使用场景：

• 入库日期（inboundDate）
• 出库日期
• 其他日期字段

6.1.2 时间格式

格式：HH:mm:ss

说明：

• HH：小时，24小时制，两位数（00-23）
• mm：分钟，两位数（00-59）
• ss：秒，两位数（00-59）

示例：

• 17:00:00 - 下午5点
• 09:30:00 - 上午9点30分
• 23:59:59 - 晚上11点59分59秒

使用场景：

• 截单时间（cutoffTime）
• 其他时间字段

6.1.3 日期时间格式

格式：MM/dd/yyyy HH:mm:ss

说明：

• 日期和时间之间用空格分隔
• 日期部分：MM/dd/yyyy
• 时间部分：HH:mm:ss

示例：

• 10/10/2025 17:00:00 - 2025年10月10日下午5点
• 01/01/2025 09:30:00 - 2025年1月1日上午9点30分

使用场景：

• 创建时间
• 更新时间
• 其他日期时间字段

6.1.4 时区说明

重要说明：

1. 所有时间均为仓库所在地时区

2. 不同仓库可能位于不同时区

3. 时区信息可通过仓库信息接口获取（timeZone 字段）

4. 时区格式遵循 IANA 时区数据库标准

示例：

• America/Los_Angeles - 美国洛杉矶（UTC-8）
• America/New_York - 美国纽约（UTC-5）

建议：

• 在调用接口前，先获取仓库的时区信息
• 根据仓库时区进行时间转换
• 避免使用系统默认时区

6.2 数值格式

6.2.1 金额格式

单位：USD（美元）

精度：保留两位小数

格式：数字.两位小数

示例：

• 29.99 - 29.99美元
• 100.00 - 100.00美元
• 0.01 - 0.01美元（最小值）

使用场景：

• 申报价值（declaredValue）
• 其他金额字段

约束：

• 必须大于等于 0.01
• 最多保留两位小数

6.2.2 重量格式

单位：Lbs（磅）

精度：支持小数

格式：数字 或 数字.小数

示例：

• 0.5 - 0.5磅
• 1.5 - 1.5磅
• 10 - 10磅

使用场景：

• 商品重量（weight）

约束：

• 必须大于 0
• 支持小数

6.2.3 尺寸格式

单位：Inch（英寸）

精度：整数

格式：整数

示例：

• 6 - 6英寸
• 10 - 10英寸
• 1 - 1英寸

使用场景：

• 商品长度（dimensionsLength）
• 商品宽度（dimensionsWidth）
• 商品高度（dimensionsHeight）

约束：

• 必须大于 0
• 必须为整数

6.2.4 数量格式

单位：无（个数）

精度：整数

格式：整数

示例：

• 1 - 1个
• 100 - 100个
• 1000 - 1000个

使用场景：

• 入库数量（forecastQty）
• 出库数量（outboundQty）
• 库存数量（availableQty、frozenQty、totalQty）

约束：

• 必须大于等于 1
• 必须为整数

6.3 字符串格式

6.3.1 SKU 格式

格式要求：

1. 仅支持：大写字母（A-Z）、数字（0-9）、下划线（_）、横线（-）

2. 长度限制：1-20 个字符

3. 首字符：可以是字母、数字、下划线、横线

4. 必须唯一

正确示例：

• SKU123456
• PROD-2024-001
• ITEM_001
• A（单个字符）

错误示例：

• sku123456（包含小写字母）
• SKU 123456（包含空格）
• SKU@123（包含特殊字符）
• SKU12345678901234567890（长度超过20个字符）

使用场景：

• 商品 SKU
• 库存查询中的 SKU

6.3.2 序列号格式

格式要求：

1. 首字符：必须是大写字母（A-Z）

2. 后续字符：可以是大写字母（A-Z）、数字（0-9）、下划线（_）、横线（-）

3. 长度限制：最大 32 个字符

4. 不能包含空格

正确示例：

• SN001234567890
• AUSD124254253223
• PROD-2024-001

错误示例：

• sn001234567890（首字母必须大写）
• 1234567890（首字符必须是字母）
• SN 001234567890（不能包含空格）

使用场景：

• 序列号预报（serialNo）
• 序列号库存查询

6.3.3 仓库编码格式

格式要求：

1. 由系统分配，不可自定义

2. 通常为简短字符串（如：W1、W2）

3. 可通过仓库信息接口获取

示例：

• W1 - LA Warehouse
• W2 - NJ Warehouse

使用场景：

• 仓库编码（warehouseCode）
• 查询条件中的仓库编码

6.3.4 订单号格式

格式要求：

1. 由系统自动生成

2. 格式：OUT + 日期 + 序号（如：OUT202411010001）

3. 唯一标识

示例：

• OUT202411010001 - 2024年11月1日的第1个订单
• POT13424424 - 客户自定义订单号

使用场景：

• 出库订单号（orderNo）
• 客户自定义订单号（referenceNo）

6.4 枚举值说明

6.4.1 入库预报类型

6.4.2 库存类型

SKU库存类型

退货库存类型

6.4.3 出库订单类型

6.4.4 出库订单发货渠道

6.4.5 出库订单状态

6.4.6 控制字段

使用场景：

• enableExpiryControl - 是否效期控制
• enableLocationControl - 是否需要库位管理
• enableSerialControl - 是否需要序列号管理

6.5 枚举值字典

本文档汇总了 WMS API 中所有枚举值的完整列表，便于快速查找。

6.5.1 入库预报类型

6.5.2 库存类型

SKU库存类型

退货库存类型

6.5.3 出库订单类型

6.5.4 出库订单发货渠道

6.5.5 出库订单状态

6.5.6 控制字段

字段说明：

• enableExpiryControl - 是否效期控制
• enableLocationControl - 是否需要库位管理
• enableSerialControl - 是否需要序列号管理

6.6 地址格式

6.6.1 国家代码

格式：ISO 3166-1 alpha-2 标准

示例：

• US - 美国
• CA - 加拿大

6.6.2 州/省代码

格式：二字码

美国州代码示例：

• CA - 加利福尼亚州
• NJ - 新泽西州
• NY - 纽约州
• TX - 德克萨斯州
• FL - 佛罗里达州

加拿大省代码示例：

• ON - 安大略省（Ontario）
• BC - 不列颠哥伦比亚省（British Columbia）
• QC - 魁北克省（Quebec）
• AB - 艾伯塔省（Alberta）
• MB - 马尼托巴省（Manitoba）

6.6.3 邮编

格式：字符串，长度和格式根据国家不同

美国邮编格式：

• 5位数字格式：90001
• 9位数字格式（ZIP+4）：90001-1234
• 示例：90001、10001、90210-1234

加拿大邮编格式：

• 6位字符格式：A1A 1A1（字母-数字-字母 空格 数字-字母-数字）
• 示例：M5B 2H4、K1A 0B1、V6B 1A1
• 注意：必须包含空格，格式为：字母数字字母 空格 数字字母数字

6.6.4 电话号码格式

美国电话号码格式：

• 10位数字，不含空格、横线等分隔符
• 示例：1234567890、3105551234
• 格式：区号（3位）+ 交换码（3位）+ 号码（4位）

加拿大电话号码格式：

• 10位数字，不含空格、横线等分隔符
• 示例：4161234567、6045551234
• 格式：区号（3位）+ 交换码（3位）+ 号码（4位）
• 注意：加拿大电话号码格式与美国相同，但区号不同

6.7 批量操作限制

6.7.1 批量数量限制

建议：

• 如果数据量较大，建议分批处理
• 每批建议不超过 100 条，以提高成功率

6.8 分页格式

6.8.1 分页参数

6.8.2 分页响应

{
  "pagination": {
    "current": 1,
    "pageSize": 10,
    "total": 100
  }
}

说明：

• current：当前页码
• pageSize：每页条数
• total：数据总条数

6.9 注意事项

1. 日期格式：严格使用 MM/dd/yyyy 格式，不要使用其他格式

2. 时区处理：注意仓库时区，避免时间错误

3. 数值精度：金额保留两位小数，重量支持小数，尺寸和数量为整数

4. 字符串格式：SKU 和序列号有严格的格式要求，请仔细检查

5. 枚举值：使用数字值，不要使用字符串描述

6. 批量限制：注意批量操作的数量限制，避免超限

6.10 格式验证

建议在调用接口前进行格式验证：

1. 日期格式验证：使用正则表达式验证日期格式

2. 数值范围验证：检查数值是否在有效范围内

3. 字符串格式验证：使用正则表达式验证 SKU、序列号等格式

4. 枚举值验证：检查枚举值是否在允许的范围内

反馈与建议

如有任何格式相关问题，请联系技术支持团队。