ThingAPI - infoplus/docs GitHub Wiki

Glossary

  • 物品／Thing：一个物品（包裹）
  • 物品编码／ThingCode：每个物品的唯一标识（简称code），可作为条形码扫描。
  • 取件码／PickupCode：每个物品可绑定零到多个取件码（简称pickup）

Data Structure

  • 物品／Thing
// Type: {thing} 
{
    "id":{guid},
    "name":{string},          // 物品名称
    "code":{string},          // 物品编码，默认13位，可作为条形码扫描
    "attributes":{map<string, string>},       // 物品其他属性
    "pickups": [ {pickup} ]   // 取件码列表
}
  • 取件码／Pickup
// Type: {pickup} 
{
    "id":{guid},
    "description":{string}, // 收件码描述
    "code":{string},        // 取件码，默认8位数字
    "user": {profile},      // 用户，可选  
    "thing": {thing},       // 要取的物品信息  
    "timestamp": {long},    // 创建时间
    "expire": {long},       // 有效期，可选
    "used": {long},         // 被使用时间
    "quantity": {int},      // 可使用次数
    "counter": {int},       // 已使用次数
    "state": {string},      // 取件码限制使用的状态（流程步骤代码），支持正则表达式 
    "action": {string},     // 取件时执行的动作（流程按钮代码） 
    "meta": {string},       // 自定义属性集  
}

APIs

Id Method EndPoint Scope Token Description
11.1s PUT /thing/{code}/pickup sys_thing_edit sys 创建一个收件码
11.2s GET /thing/{code} sys_thing sys 查询物品详情
11.3s GET /pickup/{pickup}/things sys_thing sys 查询指定收件码的可收物品
11.4s GET /pickup/{pickup} sys_thing sys 查询指定收件码详情
11.5s POST /pickup/{pickup} sys_thing_edit sys 修改收件码次数、描述、meta
11.6s GET /me/pickups thing u/s 查询当前用户（或指定用户）有效的取件码，2020/10/20 
[1] PUT "/thing/{code}/pickup" @returns Response<Pickup>

  • 功能：创建一个取件码

  • 权限：要求系统token

  • 同一个用户（含null）对于特定物品的取件码唯一，多次请求此接口会覆盖老的取件码

  • 参数表（所有参数均为可选）：

Parameter Type Description
userId string 可指定某用户专用；不指定用户的取件码为默认取件码
format string [Numeric8|AlplabetNumeric8] 取件码格式，默认8位纯数字
description string 描述信息
expire long 有效期的Unix时间戳，默认30天后
quantity int 有效数量，比如打印份数。默认NULL
state string 可选。适用的流程节点，可支持正则表达式匹配。默认 "box(.+)"
action string 可选。物品收取时执行的流程动作，默认适用一键办理的动作 
[2] GET "/thing/{code}" @returns Response<Thing>
  • 功能：根据物品代码，获取该物品的详情（含取件码）
  • 权限：系统token可获取全部取件码；用户token仅能获取到该用户自己的
  • 尚不支持（2017年11月24日）
[3] GET "/pickup/{pickup}/things" @returns Response<Thing>
  • 功能：按取件码查询物品（由于收件码会小概率重复，可能会有多个）
  • 权限：系统token可获取全部取件码；用户token仅能获取到该用户自己的
[4] GET "/pickup/{pickup}" @returns Response<Pickup>
  • 功能：按取件码查询取件码详情，包括其对应的物品（Thing）信息
  • 注意，仅返回未过期且未使用的取件码。
[5] POST "/pickup/{pickup}" @returns Response<Pickup>

  • 功能：更新pickup使用次数、描述、meta。

  • 参数表（所有参数均为可选）：

Parameter Type Description
consumed int 本次使用掉的次数，详见后面补充说明
expire int 有效期。参考PUT操作定义
description string 描述。参考PUT操作定义
state string 状态。参考PUT操作定义
action string 动作。参考PUT操作定义
meta string 自定义元数据。参考PUT操作定义 
[6u] GET "/me/pickups" @returns Response<Pickup>
[6s] GET "/user/{code}/pickups" @returns Response<Pickup>

  • 功能：获取当前用户（指定用户）的取件码列表。客户端授权的token可以指定用户id或用户帐号。

  • 参数表：

Parameter Type Description
includeConsumed boolean 可选，默认false，是否包括已使用的
includeExpired boolean 可选，默认false，是否包括已过期的

补充说明：

  • {pickup}参数，请尽量使用pickup.id而不是code，有效code如果产生重复报错：THING_PICKUP_NOT_UNIQUE
  • consumed 参数，是本次使用掉的次数，比如满足 pickup.counter + consumed < pickup.quantity，否则会到报 THING_PICKUP_INSUFFICIENT ；如果 pickup.quantity 未设置，会报 THING_PICKUP_NOT_UNIQUE 。调用成功后，其结果是 pickup.counter += consumed，不会影响 pickup.quantity
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️