格物开放 API员工额度

REST API · 接口参考

REST API 参考 · 员工福利购物 / 企业采购

员工额度

以员工身份调用：查余额、流水与每批额度的到期时间，结算前判断能否用企业额度支付。

#当前用户资料与所属企业

GETPUT/v1/buyer/me

当前用户资料与所属企业（org：企业 id、名称、状态、本人角色、余额；没有归属为 null）

鉴权用户态

GET

用户资料

首次访问自动建档。org 是当前用户所属的企业：id、名称、在本产品里的开通状态（active 才能交易）、本人角色（owner / admin / member）、额度余额；没有归属企业为 null。登录后调一次即可拿全身份，按 role 决定显不显示企业管理入口。

返回字段17 个，点击展开

字段	类型	说明
`account`	object
`account.id`	string
`account.platform`	string	可选值：`wx` / `alipay` / `pc` / `h5` / `other`
`account.externalId`	string	= x-open-user
`account.nickname`	string
`account.avatar`	string
`account.realName`	string	未填为空串
`account.birthday`	string	未填为空串
`account.gender`	string	未填为空串
`account.createdAt`	string
`account.lastSeenAt`	string
`org`	object	所属企业；没有为 null。可能为 null
`org.id`	string	企业 id（orgId）
`org.name`	string
`org.status`	string	企业在本产品里的状态：active 才能交易；pending 待激活 / 开通审核中，rejected、disabled、none
`org.role`	string	可选值：`owner` / `admin` / `member`
`org.balance`	integer	本人额度余额（100 = 1 元）

PUT

修改用户资料

不接受 phone。传空串清空对应字段。

请求体application/json

字段	类型	必填	说明
`nickname`	string	否
`avatar`	string	否
`realName`	string	否
`birthday`	string	否	YYYY-MM-DD 或 MM-DD，须为过去的日期
`gender`	string	否	可选值：`male` / `female` / ``

返回字段

字段	类型	说明
`ok`	boolean
`account`	object

错误

400 BAD_BIRTHDAY / BAD_GENDER

调用示例

1curl -X GET "https://api.gowu.net/v1/buyer/me" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "account": {3    "id": "string",4    "platform": "wx",5    "externalId": "string",6    "nickname": "string",7    "avatar": "string",8    "realName": "string",9    "birthday": "string",10    "gender": "string",11    "createdAt": "string",12    "lastSeenAt": "string"13  },14  "org": {15    "id": "string",16    "name": "string",17    "status": "string",18    "role": "owner",19    "balance": 020  }21}

#结算页判断：这单能否用企业额度支付、余额多少

GET/v1/enterprise/points

鉴权用户态

结算页用：这个员工能不能用企业额度、余额多少。未绑定企业时 bound: false。

返回字段

字段	类型	说明
`bound`	boolean
`canUsePoints`	boolean	企业为 active 时为 true
`balance`	number
`org`	object
`org.name`	string
`org.status`	string
`role`	string

调用示例

1curl -X GET "https://api.gowu.net/v1/enterprise/points" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "bound": true,3  "canUsePoints": true,4  "balance": 0,5  "org": {6    "name": "string",7    "status": "string"8  },9  "role": "string"10}

#额度总览：余额、即将到期、所属企业与角色

GET/v1/enterprise/points/summary

鉴权用户态

余额、30 天内即将到期的额度、所属企业与角色。

返回字段

字段	类型	说明
`bound`	boolean
`balance`	number
`expiringSoon`	object
`expiringSoon.amount`	number
`expiringSoon.nearestDate`	string
`org`	object
`org.name`	string
`org.status`	string
`org.role`	string
`canUsePoints`	boolean
`ratio`	integer	100 = 1 元。例：`100`

调用示例

1curl -X GET "https://api.gowu.net/v1/enterprise/points/summary" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "bound": true,3  "balance": 0,4  "expiringSoon": {5    "amount": 0,6    "nearestDate": "string"7  },8  "org": {9    "name": "string",10    "status": "string",11    "role": "string"12  },13  "canUsePoints": true,14  "ratio": 10015}

#额度流水

GET/v1/enterprise/points/ledger

额度流水（发放 / 下单 / 退回 / 过期）

鉴权用户态

最多取最近 200 条再分页，因此 total 最大 200。

查询参数

字段	类型	必填	说明
`type`	string	否	不传 = 全部；refund 包含各种退回。可选值：`grant` / `order` / `refund` / `expire`
`page`	integer	否	默认 `1`。≥ 1
`pageSize`	integer	否	默认 `20`。≥ 1，≤ 100

返回字段

字段	类型	说明
`bound`	boolean
`total`	integer
`page`	integer
`pageSize`	integer
`items`	object[]
`items[].kind`	string
`items[].label`	string	展示用文案，由服务端下发
`items[].amount`	number	带正负号
`items[].balanceAfter`	number
`items[].remark`	string	可能为 null
`items[].lots`	object[]
`items[].lots[].id`	string
`items[].lots[].name`	string
`items[].lots[].theme`	string
`items[].createdAt`	string

调用示例

1curl -X GET "https://api.gowu.net/v1/enterprise/points/ledger" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "bound": true,3  "total": 0,4  "page": 0,5  "pageSize": 0,6  "items": [7    {8      "kind": "string",9      "label": "string",10      "amount": 0,11      "balanceAfter": 0,12      "remark": "string",13      "lots": [14        {}15      ],16      "createdAt": "string"17    }18  ]19}

#按发放批次查看剩余额度与到期日

GET/v1/enterprise/points/welfares

鉴权用户态

只含还有余量的批次，按到期日升序。

查询参数

字段	类型	必填	说明
`theme`	string	否	福利类型 key
`expiringWithin`	integer	否	只看 N 天内到期的。≥ 1

返回字段

字段	类型	说明
`bound`	boolean
`items`	object[]
`items[].id`	string
`items[].name`	string
`items[].theme`	string
`items[].themeLabel`	string
`items[].amount`	number	发放额度
`items[].remaining`	number	剩余额度
`items[].grantedAt`	string
`items[].expiresAt`	string	可能为 null
`total`	number	所有批次剩余之和
`expiringAmount`	number	有到期日的批次剩余之和

调用示例

1curl -X GET "https://api.gowu.net/v1/enterprise/points/welfares" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "bound": true,3  "items": [4    {5      "id": "string",6      "name": "string",7      "theme": "string",8      "themeLabel": "string",9      "amount": 0,10      "remaining": 0,11      "grantedAt": "string",12      "expiresAt": "string"13    }14  ],15  "total": 0,16  "expiringAmount": 017}

#额度使用规则文案

GET/v1/enterprise/points/rules

额度使用规则文案（登录前可看）

鉴权appKey

登录前也能看；带 x-open-user 时有效期按该员工所属企业的设置显示。

返回字段

字段	类型	说明
`ratio`	integer	例：`100`
`expiryPolicy`	object
`expiryPolicy.defaultDays`	number
`expiryPolicy.onExpire`	string	例：`return_to_org`
`sections`	object[]
`sections[].title`	string
`sections[].body`	string

调用示例

1curl -X GET "https://api.gowu.net/v1/enterprise/points/rules" \2  -H "x-app-key: $GOWU_APP_KEY"

返回示例

1{2  "ratio": 100,3  "expiryPolicy": {4    "defaultDays": 0,5    "onExpire": "return_to_org"6  },7  "sections": [8    {9      "title": "string",10      "body": "string"11    }12  ]13}

#每日签到：GET 看今天能否领与连续天数，POST 领取

GETPOST/v1/enterprise/points/checkin

每日签到：GET 看今天能否领与连续天数，POST 领取（幂等）

鉴权用户态适用员工福利可选

出现在员工福利 · 福豆任务、签到与生日

GET

签到状态

可选。今天能不能领、连续几个工作日、每日金额与连签奖励（画签到卡用）。金额与阈值由服务端下发、企业可调，不要写死。未绑定企业时只返回 { bound: false }。

返回字段

字段	类型	说明
`bound`	boolean
`enabled`	boolean	企业是否开启签到
`canClaim`	boolean
`reason`	string	不能领的原因。可选值：`disabled` / `weekend` / `claimed`
`streak`	integer	连续工作日数（今天未签时为签了之后的天数）
`today`	string	例：`2026-10-20`
`isWeekend`	boolean
`dailyAmount`	number
`streakDays`	number	连签几天发奖励
`streakBonus`	number
`claimedDays`	string[]	最近已签的日期

POST

签到领额度

可选。幂等：同一天重复调只发一次。周末不签到。额度从员工所属企业的额度池划出。

返回字段

字段	类型	说明
`ok`	boolean
`amount`	number	本次发放（含奖励）
`bonus`	number	其中连签奖励
`streak`	integer
`balance`	number	领取后余额
`replay`	boolean

错误

400 NOT_BOUND 未绑定企业 / DISABLED 企业未开启签到 / WEEKEND 周末 / CLAIMED 今天已领 / GRANT_FAILED

调用示例

1curl -X GET "https://api.gowu.net/v1/enterprise/points/checkin" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "bound": true,3  "enabled": true,4  "canClaim": true,5  "reason": "disabled",6  "streak": 0,7  "today": "2026-10-20",8  "isWeekend": true,9  "dailyAmount": 0,10  "streakDays": 0,11  "streakBonus": 0,12  "claimedDays": [13    "string"14  ]15}

#站内信：GET 列表

GETPOST/v1/enterprise/notifications

站内信：GET 列表（?unread=1），POST 标已读

鉴权用户态可选

GET

站内信列表

可选。发给当前用户的站内信（如预算预警、任务变更），新的在前，最多 50 条。只存表，不推送。

查询参数

字段	类型	必填	说明
`unread`	string	否	传 1 只看未读。可选值：`1`

返回字段

字段	类型	说明
`ok`	boolean
`unread`	integer	未读总数
`items`	object[]
`items[].id`	string
`items[].kind`	string
`items[].title`	string
`items[].body`	string
`items[].refId`	string	关联对象 id（如任务 id）
`items[].readAt`	string	未读时不返回
`items[].createdAt`	string

POST

标记已读

可选。不传 ids = 全部标为已读。

请求体application/json

字段	类型	必填	说明
`ids`	string[]	否

返回字段

字段	类型	说明
`ok`	boolean
`marked`	integer	本次标记的条数

调用示例

1curl -X GET "https://api.gowu.net/v1/enterprise/notifications" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "ok": true,3  "unread": 0,4  "items": [5    {6      "id": "string",7      "kind": "string",8      "title": "string",9      "body": "string",10      "refId": "string",11      "readAt": "string",12      "createdAt": "string"13    }14  ]15}