# 核销记录凭证

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

## 请求示例



```python [Python + requests]
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]
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_number` | string | 记录编号 |
| `record_id` | integer | 记录 ID |
| `org_id` | integer | 企业 ID |
| `submit_at` | integer | 记录提交时间（Unix 秒时间戳） |
| `certificate_status` | string | 核销后的凭证状态文本 |

---

`error_code` integer

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

---

`message_detail` string

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

---

## 错误码

常见错误包括：

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

完整定义见：[错误码与调用额度](https://cli.im/open-api/openapi/v2/error-codes.md)。
