格物开放 API企业与员工

REST API · 接口参考

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

企业与员工

企业在开发者控制台申请正式接入时录入，平台审批通过后建好并归属你的 appKey。你的服务端查到自己的企业后，把你的用户绑成员工、设管理员；员工的 userId 就是他之后请求时放进 x-open-user 的值。

#你的企业

GET/v1/partner/orgs

你的企业（审批通过后由平台建好）：orgId、审核状态

鉴权服务端签名

出现在福利 / 采购 · 企业与员工

你的企业——审批通过后由平台建好，归属当前 appKey，这里查到 orgId 后再绑定员工。按创建时间倒序，最多 200 条，不分页。

返回字段20 个，点击展开

字段	类型	说明
`items`	object[]
`items[].orgId`	string
`items[].name`	string
`items[].status`	string	pending = 待平台审核；active 后才能充值与下单。可选值：`pending` / `active` / `disabled`
`items[].unifiedCreditCode`	string
`items[].shortName`	string
`items[].contactName`	string
`items[].adminEmail`	string
`items[].region`	string
`items[].invoice`	object
`items[].invoice.title`	string	发票抬头，缺省 = 企业名称
`items[].invoice.taxNo`	string	税号，固定等于统一社会信用代码
`items[].invoice.bankName`	string
`items[].invoice.bankAccount`	string
`items[].invoice.address`	string
`items[].invoice.phone`	string
`items[].invoiceReady`	boolean	抬头与税号都已具备
`items[].poolBalance`	number	企业额度池余额（100 = 1 元）
`items[].memberCount`	integer
`items[].createdAt`	string

调用示例

1curl -X GET "https://api.gowu.net/v1/partner/orgs" \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"

返回示例

1{2  "items": [3    {4      "orgId": "string",5      "name": "string",6      "status": "pending",7      "unifiedCreditCode": "string",8      "shortName": "string",9      "contactName": "string",10      "adminEmail": "string",11      "region": "string",12      "invoice": {13        "title": "string",14        "taxNo": "string",15        "bankName": "string",16        "bankAccount": "string",17        "address": "string",18        "phone": "string"19      },20      "invoiceReady": true,21      "poolBalance": 0,22      "memberCount": 0,23      "createdAt": "string"24    }25  ]26}

#企业详情：审核状态、开票信息、额度池余额

GET/v1/partner/orgs/{orgId}

鉴权服务端签名

轮询它看审核状态（status 从 pending 变为 active）。

路径参数

字段	类型	必填	说明
`orgId`	string	是

返回字段20 个，点击展开

字段	类型	说明
`org`	object
`org.orgId`	string
`org.name`	string
`org.status`	string	pending = 待平台审核；active 后才能充值与下单。可选值：`pending` / `active` / `disabled`
`org.unifiedCreditCode`	string
`org.shortName`	string
`org.contactName`	string
`org.adminEmail`	string
`org.region`	string
`org.invoice`	object
`org.invoice.title`	string	发票抬头，缺省 = 企业名称
`org.invoice.taxNo`	string	税号，固定等于统一社会信用代码
`org.invoice.bankName`	string
`org.invoice.bankAccount`	string
`org.invoice.address`	string
`org.invoice.phone`	string
`org.invoiceReady`	boolean	抬头与税号都已具备
`org.poolBalance`	number	企业额度池余额（100 = 1 元）
`org.memberCount`	integer
`org.createdAt`	string

错误

404 ORG_NOT_FOUND：不存在或不归属当前 appKey

调用示例

1curl -X GET "https://api.gowu.net/v1/partner/orgs/{orgId}" \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"

返回示例

1{2  "org": {3    "orgId": "string",4    "name": "string",5    "status": "pending",6    "unifiedCreditCode": "string",7    "shortName": "string",8    "contactName": "string",9    "adminEmail": "string",10    "region": "string",11    "invoice": {12      "title": "string",13      "taxNo": "string",14      "bankName": "string",15      "bankAccount": "string",16      "address": "string",17      "phone": "string"18    },19    "invoiceReady": true,20    "poolBalance": 0,21    "memberCount": 0,22    "createdAt": "string"23  }24}

#已绑定员工：角色、在职状态、额度余额

GET/v1/partner/orgs/{orgId}/members

鉴权服务端签名

只列经本接入方绑定的员工，含已离职的，不分页。

路径参数

字段	类型	必填	说明
`orgId`	string	是

返回字段

字段	类型	说明
`items`	object[]
`items[].userId`	string	你自己的用户 ID（即该员工请求时的 x-open-user）
`items[].name`	string
`items[].phone`	string	接入方声明的手机号，平台不验证
`items[].role`	string	可选值：`owner` / `admin` / `member`
`items[].status`	string	可选值：`active` / `suspended` / `offboarded`
`items[].balance`	number	员工额度余额（100 = 1 元）
`items[].boundAt`	string

错误

404 ORG_NOT_FOUND

调用示例

1curl -X GET "https://api.gowu.net/v1/partner/orgs/{orgId}/members" \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"

返回示例

1{2  "items": [3    {4      "userId": "string",5      "name": "string",6      "phone": "string",7      "role": "owner",8      "status": "active",9      "balance": 0,10      "boundAt": "string"11    }12  ]13}

#把你的用户绑成员工

PUT/v1/partner/orgs/{orgId}/members/{userId}

把你的用户绑成员工（owner / admin / member），同时开通采购权限

鉴权服务端签名

出现在福利 / 采购 · 企业与员工

把你的用户绑成员工，同时开通采购权限。userId 用你自己的用户 ID，之后该员工请求时放进 x-open-user。已是本企业在职员工时只更新角色（HTTP 200）；一个用户同时只能属于一家企业。

路径参数

字段	类型	必填	说明
`orgId`	string	是
`userId`	string	是	你的用户 ID，匹配 ^[\w.:@-]{1,128}$

请求体application/json

字段	类型	必填	说明
`name`	string	否	最长 40
`phone`	string	否	仅存档，平台不验证、不用于识别身份。最长 20
`role`	string	否	可选值：`owner` / `admin` / `member`。默认 `"member"`
`platform`	string	否	可选值：`wx` / `alipay` / `pc` / `h5` / `other`。默认 `"other"`

返回字段已是员工，角色已更新

字段	类型	说明
`ok`	boolean
`created`	boolean	例：`false`
`member`	object
`member.userId`	string	你自己的用户 ID（即该员工请求时的 x-open-user）
`member.name`	string
`member.phone`	string	接入方声明的手机号，平台不验证
`member.role`	string	可选值：`owner` / `admin` / `member`
`member.status`	string	可选值：`active` / `suspended` / `offboarded`
`member.balance`	number	员工额度余额（100 = 1 元）
`member.boundAt`	string

错误

400 BAD_USER / BAD_ROLE
404 ORG_NOT_FOUND
409 ALREADY_BOUND：该用户已是其他企业的在职员工

调用示例

1curl -X PUT "https://api.gowu.net/v1/partner/orgs/{orgId}/members/{userId}" \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 "content-type: application/json" \8  -d '{"name":"张三","role":"member"}'

返回示例

1{2  "ok": true,3  "created": false,4  "member": {5    "userId": "string",6    "name": "string",7    "phone": "string",8    "role": "owner",9    "status": "active",10    "balance": 0,11    "boundAt": "string"12  }13}

#员工离职：未用额度退回企业额度池，收回采购权限

DELETE/v1/partner/orgs/{orgId}/members/{userId}

鉴权服务端签名

出现在福利 / 采购 · 企业与员工

未用额度全部退回企业额度池，收回采购权限。超级管理员（owner）不能直接离职，需先把 owner 交接给别人。

路径参数

字段	类型	必填	说明
`orgId`	string	是
`userId`	string	是

请求体application/json

字段	类型	必填	说明
`reason`	string	否	最长 60

返回字段

字段	类型	说明
`ok`	boolean
`reclaimed`	number	退回企业的额度

错误

404 ORG_NOT_FOUND / NOT_MEMBER
409 OFFBOARD_FAILED：成员不在职，或 owner 需先交接

调用示例

1curl -X DELETE "https://api.gowu.net/v1/partner/orgs/{orgId}/members/{userId}" \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"

返回示例

1{2  "ok": true,3  "reclaimed": 04}