草料开放平台文档

简体中文

English

简体中文

English

主题

核销记录凭证 ​

对凭证类记录执行核销操作：设置为指定状态（action_type=set_certificate_status）或推进到下一状态（action_type=set_next_certificate_status）。当 action_type 为 set_certificate_status 时，参数 to_certificate_status 必填。该接口属于写操作，要求 API Key 具备写权限。

请求示例 ​

python
import requests

url = 'https://open.cli.im/api/v2/rpc/certificates/verify'
data = {
    'certificate_code': 'https://example.com/certificates/verify_demo_001',
    'action_type': 'set_certificate_status',
    'to_certificate_status': '已核销',
    'from_certificate_status': '待核销',
    'tpl_id': 122507,
    'code_id': 6763267
}
headers = {
    'Authorization': 'Bearer <你的API Key>',
    'Content-Type': 'application/json'
}
response = requests.post(url, json=data, headers=headers)
print(response.text)
bash
curl -X POST 'https://open.cli.im/api/v2/rpc/certificates/verify' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"certificate_code":"https://example.com/certificates/verify_demo_001","action_type":"set_certificate_status","to_certificate_status":"已核销","from_certificate_status":"待核销","tpl_id":122507,"code_id":6763267}'

响应示例 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "record_number": "R202603240001",
    "record_id": 123456789,
    "org_id": 94910252,
    "submit_at": 1773302553,
    "certificate_status": "已核销"
  }
}

错误响应示例 ​

json
{
  "code": 400,
  "message": "Invalid target certificate status: 重复核销",
  "data": {},
  "error_code": 100326,
  "message_detail": "重复核销"
}

请求详情 ​

certificate_code string 必填

核销码 coding 或完整访问 URL，指定要核销的凭证记录。

action_type string 必填

操作类型：

  • set_certificate_status：设置为指定状态（此时 to_certificate_status 必填）
  • set_next_certificate_status：推进到下一状态

to_certificate_status string 条件必填

目标状态名或 ID；当 action_type 为 set_certificate_status 时必填。若目标状态不存在、不可达，或当前凭证无需变更到该状态，请求会失败。

from_certificate_status string 可选

当前状态选项名或 ID。传入后，仅允许从该状态执行核销；适合在多状态流程中限制状态跃迁来源。

tpl_id integer 可选

限制只核销指定表单下的凭证记录。传入后，只有凭证所属表单与该值匹配时才允许核销。

code_id integer 可选

限制只核销指定二维码下的凭证记录。传入后，只有凭证所属二维码与该值匹配时才允许核销。

响应详情 ​

code integer

状态码。0 表示成功；业务错误通常返回 400，鉴权或权限问题可能返回 401 / 403。

message string

状态消息。成功时通常返回 ok；失败时返回对应错误说明。

data object

核销成功后的结果对象。

data 对象 ​

json
{
  "record_number": "R202603240001",
  "record_id": 123456789,
  "org_id": 94910252,
  "submit_at": 1773302553,
  "certificate_status": "已核销"
}
字段类型说明
record_numberstring记录编号
record_idinteger记录 ID
org_idinteger企业 ID
submit_atinteger记录提交时间（Unix 秒时间戳）
certificate_statusstring核销后的凭证状态文本

error_code integer

业务错误码。发生业务错误时返回，可结合错误码总表排查具体原因。

message_detail string

可选的补充错误信息，便于定位失败原因；不同错误场景下可能为空或省略。

错误码 ​

常见错误包括：

error_codemessage说明
100301Invalid request parameters请求参数缺失、类型错误，或 action_type=set_certificate_status 时未传 to_certificate_status
100319Certificate verification failed通用核销失败，未命中更细错误场景
100320Invalid certificate code凭证码无效，或对应凭证记录不存在
100321Certificate verification is not enabled表单或凭证未开启核销
100322Certificate record is not approved for verification凭证记录尚未审核通过
100323Certificate does not match the requested scope凭证与 tpl_id / code_id 限制范围不匹配
100324Certificate cannot be verified in current status当前凭证状态不允许核销，或核销流程已结束
100325Invalid verification action核销动作不支持，或该表单未开启对应核销方式
100326Invalid target certificate status指定目标状态不存在、没有下一状态，或无需状态变更
100327Invalid verification authorization code核销授权码无效或已过期
100328No permission to verify this certificate当前操作方没有核销该凭证的权限
100329Identity information required before verification核销前需先补全身份信息

完整定义见：错误码说明。