查询用户签约列表

更新时间：2024.11.18

商户使用签约签约模板号和OpenID来查询用户签约信息，返回用户在该签约模版下的合约列表（包括处于已解约状态下的合约，被用户主动删除的合约无法被查询到），结果中已签约合约排列于已解约合约之前。需要注意的是调用该接口传入的OpenID应当与签约AppID对应，如果传入的OpenID不合法，或与签约AppID不对应，则可能出现：1）查询结果为空或者报错；2）查询返回的OpenID与请求传入的OpenID不一致。

接口说明

支持商户：【普通服务商】

请求方式：【GET】/v3/eduschoolpay/users/{openid}/contracts

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

path 路径参数

openid 　必填 string(128)

【商户AppID下的用户标识】OpenID是由微信生成的，代表某个微信用户在AppID下的唯一标识。相同微信用户，AppID不同，则生成的OpenID不同。
请注意：调用该接口传入的OpenID应当与签约appid对应，如果传入的OpenID不合法，或与签约AppID不对应，则可能出现：1、查询结果为空或者报错；2、查询返回的OpenID与请求传入的OpenID不一致。

query 查询参数

plan_id 　必填 string(32)

【签约模板号】签约模板的唯一标识。商户接入校园轻松付并申请签约模板后由微信支付生成。

contract_status 　必填 string(32)

【签约状态】希望查询的签约协议的状态。枚举值：ADD-已签约; DELETE-已解约; ALL-同时查询已签约和已解约

offset 　选填 integer

【分页页码】该次请求资源的起始位置，从0开始计数，请保持为分页大小limit的整数倍。调用方选填，默认为0。

limit 　选填 integer

【分页大小】该次请求可返回的最大资源条数。调用方选填，默认值为20，最小为1，最大为40。

请求示例

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/eduschoolpay/users/oUpF8uMuAJOM2pxb1Q/contracts?plan_id=101164396123311331&contract_status=ADD&offset=0&limit=20 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数

200 OK

data 　选填 array[object]

【查询结果列表】符合查询条件的用户签约协议列表

属性

contract_id 　必填 string(32)

【签约协议号】微信用户在校园轻松付下的合约的唯一标识，用户在校园轻松付小程序完成签约后，由微信支付生成。

mchid 　必填 string(32)

【商户号】微信支付分配的商户号。
如果是服务商模式接入则为服务商商户号；如果是直连商户模式接入则为直连商户号。

appid 　必填 string(32)

【商户AppID】微信公众平台（mp.weixin.qq.com）为商户分配的公众账号ID，与商户号存在绑定关系。
如果是服务商模式接入则为服务商商户号绑定的AppID；如果是直连商户模式接入则为直连商户号绑定的AppID。

openid 　必填 string(128)

【商户AppID下的用户标识】用户在商户AppID下的唯一标识。如果是服务商模式接入则为服务商商户AppID下的唯一标识；如果是直连商户模式接入则为直连商户AppID下的唯一标识。

plan_id 　必填 string(32)

【签约模板号】签约模板的唯一标识。商户在商户平台（pay.weixin.qq.com）接入校园轻松付，并为学校申请了签约模板后，由微信支付生成。

contract_status 　必填 string(32)

【签约状态】ADD-已签约; DELETE-已解约

create_time 　必填 string(32)

【签约时间】签约完成时间，使用rfc3339所定义的格式，即为YYYY-MM-DDThh:mm:ss+TIMEZONE

out_contract_code 　必填 string(64)

【外部签约号】由商户自行生成的签约号，要求64个字符内，只能是数字、大小写字母和_-，且在同一签约模板下唯一。

offset 　选填 integer

【请求资源起始位置】该次请求资源的起始位置，请求参数原样返回

limit 　选填 integer

【最大资源条数】该次请求可返回的最大资源条数，请求参数原样返回

total_count 　选填 integer

【资源总条数】符合查询条件的资源总条数。

links 　选填 object

【相关链接】请求翻页相关链接

属性

应答示例

200 OK

1{
2  "data" : [
3    {
4      "contract_id" : "2045011120563805041758214605",
5      "mchid" : "1230000109",
6      "appid" : "wx8888888888888888",
7      "openid" : "oUpF8uMuAJOM2pxb1Q",
8      "plan_id" : "101164396123311331",
9      "contract_status" : "ADD",
10      "create_time" : "2017-08-26T09:43:39+08:00",
11      "out_contract_code" : "20190806125346"
12    }
13  ],
14  "offset" : 10,
15  "limit" : 20,
16  "total_count" : 1234,
17  "links" : {
18    "next" : "/v3/eduschoolpay/users/{openid}/contracts?offset=15&limit=5",
19    "prev" : "/v3/eduschoolpay/users/{openid}/contracts?offset=5&limit=5",
20    "self" : "/v3/eduschoolpay/users/{openid}/contracts?offset=10&limit=5"
21  }
22}
23

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	INVALID_REQUEST	用户信息有误，请检查OpenID	使用正确的微信OpenID重试
429	RATELIMIT_EXCEEDED	达到调用速率限制	接口调用频率过快，请降低请求频率
500	SYSTEM_ERROR	出现内部服务器错误	5开头的错误码均为系统错误，请使用相同的参数稍后重试

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服