> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 电子签名报告：signatures[] 参考

> 通过 Didit 读取会话决策和 Webhook 中的 signatures[]，下载已签署的 PDF 与存证 PDF，并重新验证签名。

每个[电子签名](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md)步骤都会为每位签署人生成一项结果。您可以在以下位置的 `signatures[]` 数组项中找到该结果：

* 用于用户验证（KYC）和企业验证（KYB）会话的 [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/zh/sessions-api/retrieve-session)。
* V3 [会话 Webhook](https://docs.didit.me/zh/integration/webhooks.md) 的 `decision`，在会话状态为 `Approved`、`Declined`、`In Review` 或 `Abandoned` 时发送。
* 控制台中该会话的**签名**选项卡，以及 [PDF 报告](https://docs.didit.me/zh/sessions-api/generate-pdf.md)中的签名部分。

仅当工作流包含电子签名步骤时，`signatures` 才会包含在决策中。在签署人进入该步骤之前，它是一个空数组。KYC 步骤包含一个项；KYB 步骤中每位签署人对应一个项。

## 示例

```json theme={null}
{
  "signatures": [
    {
      "id": "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
      "node_id": "feature_signature",
      "status": "signed",
      "verdict": "Approved",
      "level": "aes",
      "format": "pades",
      "profile": "PAdES-B-LT",
      "signer": {
        "name": "Jane Doe",
        "capacity": "self",
        "company": null,
        "role": null,
        "roles": [],
        "identity_session_id": "11111111-2222-3333-4444-555555555555"
      },
      "identity_used": {
        "session_id": "11111111-2222-3333-4444-555555555555",
        "kyc_id": "6f1e8f6c-1d2b-4c3a-9e8f-7a6b5c4d3e2f",
        "verified": true,
        "expected_name": "Jane Doe"
      },
      "certificate": {
        "issuer": "<certificate issuer>",
        "issued_to": "<certificate subject>",
        "serial": "5A3F9C21",
        "valid_from": "2026-01-01T00:00:00+00:00",
        "valid_until": "2028-01-01T00:00:00+00:00"
      },
      "confirmation": {
        "channel": "email",
        "destination": "j***@example.com",
        "confirmed_at": "2026-11-03T10:42:18.512Z",
        "attempts": 1
      },
      "timestamp": {
        "time": "2026-11-03T10:42:21+00:00",
        "qualified": false,
        "valid": true
      },
      "documents": [
        {
          "id": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
          "uuid": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
          "title": "Account agreement",
          "file_name": "agreement.pdf",
          "pages": 4,
          "size_bytes": 182344,
          "sha256_original": "3b8e5f0c2a9d4e7f1b6c0a5d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f",
          "sha256_signed": "a1f2e3d4c5b6a7980f1e2d3c4b5a69788f7e6d5c4b3a29180f1e2d3c4b5a6978",
          "status": "signed",
          "opened_at": "2026-11-03T10:40:02.118Z",
          "read_at": "2026-11-03T10:41:10.044Z",
          "read_to_end": true,
          "consented_at": "2026-11-03T10:41:12.730Z",
          "consent": true,
          "signed_file": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/documents/9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b/file/",
          "mode": "fields",
          "source_format": "pdf",
          "conversion": null,
          "fields": [
            {
              "key": "full_name",
              "type": "full_name",
              "role": "verified_person",
              "label": "Full name",
              "page": 1,
              "x": 0.34,
              "y": 0.2326,
              "width": 0.57,
              "height": 0.0325,
              "required": true,
              "value": "Jane Doe",
              "display_value": "Jane Doe",
              "value_source": "identity",
              "filled_at": "2026-11-03T10:40:02.118Z",
              "value_unavailable_reason": null
            },
            {
              "key": "occupation",
              "type": "text",
              "role": "verified_person",
              "label": "Occupation",
              "page": 1,
              "x": 0.34,
              "y": 0.4618,
              "width": 0.57,
              "height": 0.0325,
              "required": true,
              "value": "Architect",
              "display_value": "Architect",
              "value_source": "signer",
              "filled_at": "2026-11-03T10:40:41.502Z",
              "value_unavailable_reason": null
            },
            {
              "key": "signature",
              "type": "signature",
              "role": "verified_person",
              "label": "Signature",
              "page": 4,
              "x": 0.09,
              "y": 0.5303,
              "width": 0.36,
              "height": 0.0849,
              "required": true,
              "value": true,
              "display_value": "Signed",
              "value_source": "signer",
              "filled_at": "2026-11-03T10:41:05.200Z",
              "image_url": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/fields/c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f/image/",
              "value_unavailable_reason": null
            }
          ]
        }
      ],
      "adopted_signature": {
        "method": "drawn",
        "font": null,
        "adopted_at": "2026-11-03T10:41:02.871Z"
      },
      "electronic_signature_consent_at": "2026-11-03T10:41:40.016Z",
      "evidence_file": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/evidence/?signature_id=0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
      "warnings": [],
      "validation": {
        "valid": true,
        "checked_at": "2026-11-03T10:42:24.903Z",
        "documents": [
          {
            "id": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
            "checked_at": "2026-11-03T10:42:24.903Z",
            "valid": true,
            "integrity": true,
            "trusted": true,
            "revoked": false,
            "trusted_list": { "status": "not_applicable", "reason": "aes_not_qualified" },
            "certificate": {
              "issuer": "<certificate issuer>",
              "issued_to": "<certificate subject>",
              "serial": "5A3F9C21",
              "valid_from": "2026-01-01T00:00:00+00:00",
              "valid_until": "2028-01-01T00:00:00+00:00"
            },
            "timestamp": { "time": "2026-11-03T10:42:21+00:00", "qualified": false, "valid": true }
          }
        ]
      },
      "declined_at": null,
      "declined_action": "REVIEW",
      "signed_at": "2026-11-03T10:42:24.903Z",
      "expires_at": "2026-11-10T10:30:00.000Z",
      "email_sent_at": "2026-11-03T10:42:30.011Z",
      "email_unavailable_reason": null,
      "ip_address": "203.0.113.10",
      "place": null,
      "place_unavailable_reason": "not_collected"
    }
  ]
}
```

## 签名对象

| 字段 | 类型 | 描述 |
| - | - | - |
| `id` | string (UUID) | 签署人的签名。将其作为 `signature_id` 传递以供下载其证据或验证其签名。 |
| `node_id` | string | 生成该签名的工作流步骤。 |
| `status` | string | 签署人当前所处的步骤阶段：`intro`、`review`、`code`、`signing`、`signed` 或 `declined`。仅 `signed` 表示文件已完成签署。 |
| `verdict` | string | 步骤的结果：`Not Finished`、`Approved`、`In Review` 或 `Declined`。被拒绝或失败的签名将采用其[规则](https://docs.didit.me/zh/core-technology/electronic-signature/warnings-electronic-signature.md)的决策结果，自定义状态规则可以修改它。 |
| `level` | string | `simple`（默认）或 `aes`。`qes` 为附加组件，目前尚未推出。 |
| `format` | string | 简单签名（Simple）为 `pdf`，高级电子签名（AES）为 `pades`。 |
| `profile` | string \| null | 高级电子签名（AES）完成签署后为 `PAdES-B-LT`，否则为 `null`。 |
| `signer` | object | 签署人信息。参见[签署人](#签署人)。 |
| `identity_used` | object | 签名所依赖的已验证身份。参见[签署人](#签署人)。对于没有已验证身份的简单签名，该对象为空。 |
| `certificate` | object \| null | 签署文件所使用的证书：`issuer`、`issued_to`、`serial`、`valid_from` 和 `valid_until`。在签署完成前为 `null`，且对于简单签名始终为 `null`。 |
| `confirmation` | object | 一次性验证码：`channel`（`email` 或 `sms`）、`destination`（发送到的脱敏联系方式）、`confirmed_at` 和 `attempts`（输入的验证码次数，包含正确的那次）。简单签名没有验证码，因此 `channel` 和 `destination` 为 `null`。 |
| `timestamp` | object \| null | 签名中由 Didit 签发的 RFC 3161 时间戳：`time`、`qualified`（对于 AES 始终为 `false`）和 `valid`。在签署完成前为 `null`，且对于简单签名始终为 `null`。 |
| `documents` | array | 每个文件对应一个项目。参见[文件](#文件)。 |
| `adopted_signature` | object \| null | 签署人为签名字段和姓名缩写字段所采用的签名和姓名缩写：`method`（`typed` 或 `drawn`）、`font`（键入签名的手写字体样式，手绘签名时为 `null`）以及 `adopted_at`。在签署人采用之前为 `null`。 |
| `electronic_signature_consent_at` | string \| null | 签署人在审查页面同意以电子方式签署文件的时间。当任何文件包含填写字段时设置。 |
| `evidence_file` | string \| null | 签署完成后，该签署人的[证据 PDF](#证据-pdf) 的路径。 |
| `warnings` | array | 触发的每个[警告](https://docs.didit.me/zh/core-technology/electronic-signature/warnings-electronic-signature.md)对应的 `{ "code", "node_id" }` 项目。 |
| `validation` | object \| null | 已签署文件的最新密码学检查。参见[重新验证签名](#重新验证签名)。 |
| `declined_at` | string \| null | 签署人拒绝的时间。 |
| `declined_action` | string | 步骤的 `signature_declined_action`：拒绝签署对决策产生的影响。 |
| `signed_at` | string \| null | 文件完成签署的时间。 |
| `expires_at` | string | 签署链接停止工作的时间。 |
| `email_sent_at` | string \| null | Didit 通过电子邮件向签署人发送已签署副本的时间。 |
| `email_unavailable_reason` | string \| null | 当您请求发送副本时未发送副本的原因。 |
| `ip_address` | string \| null | 签署人请求验证码时的 IP 地址。 |
| `place` | string \| null | 未收集。始终为 `null`，且伴随 `place_unavailable_reason: "not_collected"`。 |

在 `status` 变为 `signed` 之前，切勿将签署人视为已签署。在高级电子签名（AES）中，若证书、时间戳或 `signed_file` 为 `null`，则表示尚未完成签名。已签署的简单签名包含 `signed_file`，但证书和时间戳始终为 `null`。

### 签署人

| 字段 | 描述 |
| - | - |
| `signer.name` | 签署人已核验的姓名，来自其已通过的身份证件验证。在简单签名级别，若存在已验证的会话姓名则为该姓名；否则为签署人键入的姓名（未经核验）。 |
| `signer.capacity` | 个人为自己签署（KYC）时为 `self`，关键人员代表企业签署（KYB）时为 `company`。 |
| `signer.company` | 企业名称，适用于 KYB。 |
| `signer.role` | 申报的关键人员职务，适用于 KYB。 |
| `signer.roles` | 使其具备签署人资格的关键人员结构化角色，例如 `representative` 或 `authorized_signatory`。这些是为企业申报的角色，而非公司登记确认的记录。 |
| `signer.identity_session_id` | 验证签署人的 KYC 会话。对于 KYB，则为关键人员自己的 KYC 会话。对于没有已核验身份的简单签名，该字段不存在。 |
| `identity_used.session_id` | 同 `signer.identity_session_id`。对于没有已核验身份的简单签名，`identity_used` 为空，因此其字段均不存在。 |
| `identity_used.kyc_id` | 姓名所来源的身份证件验证。 |
| `identity_used.verified` | 当该身份证件验证已通过时为 `true`。 |
| `identity_used.expected_name` | 签署人必须匹配的姓名。对于 KYB，为申报的关键人员姓名。 |

### 文件

| 字段 | 描述 |
| - | - |
| `id`, `uuid` | 文件标识符。用于下载已签署的文件。 |
| `title`, `file_name` | 按上传或发送时的原样。 |
| `pages`, `size_bytes` | 签署人所签署文件的页数和字节大小。对于 Word，则为转换后的 PDF 的对应值。 |
| `sha256_original` | 展示给签署人时的文件 SHA-256 哈希值。 |
| `sha256_signed` | 签署完成后，已签署 PDF 的 SHA-256 哈希值。 |
| `status` | `signed`；`declined`；`not_signed`（已打开但未签署）；或 `not_reached`（从未打开）。 |
| `opened_at` | 签署人首次打开文件的时间。 |
| `read_at`, `read_to_end` | 当您要求通读至结尾时，签署人阅读完不含字段文件的时间。包含字段的文件无需此项。 |
| `consented_at`, `consent` | 当您要求逐份文件确认时，签署人同意不含字段文件的时间；或完成包含字段的文件各字段填写的时刻。 |
| `signed_file` | 签署完成后，已签署 PDF 的路径。 |
| `mode` | 包含字段的文件为 `fields`，不含字段的文件为 `read_and_agree`。 |
| `source_format` | `pdf`，或者对于 Didit 转换的 Word 文档为 `docx`。 |
| `conversion` | 对于 PDF 为 `null`。对于 Word 文档，为 `{ "from": "docx", "file_name", "sha256", "size_bytes", "converter" }`：您的原始文件、其 SHA-256 和大小，以及转换器的版本。 |
| `fields` | 文档上的[字段](#字段)及其值。对于没有字段的文档为空。 |

### 字段

`documents[].fields[]` 的每一项代表文档的一个字段，包含其在此签署人副本上的值：

| 字段 | 描述 |
| - | - |
| `key` | 字段的 [key](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md#文档上的字段)，与您在 `sign.field_values` 中使用的相同。 |
| `type`、`role`、`label`、`required` | 按照其在文档上的设置。 |
| `page`、`x`、`y`、`width`、`height` | 字段所在的位置，以显示页面的比例表示。 |
| `value` | 对于 `text`、`email`、`full_name`、`date_signed` 和 `data` 字段为字符串，对于复选框为布尔值，对于已应用的签名或首字母签名则为 `true`。字段为空时为 `null`。 |
| `display_value` | 印在页面上的值：字段 `date_format` 格式的日期，复选框的 `Yes` 或 `No`，以及签名或首字母签名的 `Signed`。 |
| `value_source` | 值的来源：`signer`（由签署人键入、勾选或应用）、`identity`（已验证的身份证件）、`contact`（已验证的邮箱或电话）、`company`（已验证的企业）、`session`（会话的 `vendor_data`）、`metadata`（会话的 `metadata`）、`api`（您的 `sign.field_values`）或 `signing_time`（签署日期）。 |
| `filled_at` | 设置该值的时间。 |
| `image_url` | 对于签名或首字母签名，为所应用图像（PNG）的路径。请参阅[下载签名图像](https://docs.didit.me/zh/sessions-api/electronic-signature/download-field-image.md)。 |
| `value_unavailable_reason` | 由 Didit 填充的字段没有值的原因：`not_verified`（身份或联系方式未验证）、`not_applicable`（个人自身签名上的企业字段）、`not_provided`（来源没有值）或 `set_at_confirmation`（签署人在确认前的签署日期）。其他情况下为 `null`。 |

## 下载已签署文档

将 `signed_file` 和 `evidence_file` 中的路径与您的 API 密钥结合使用。每个路由都会直接返回 PDF 本身。

```bash theme={null}
# Signed PDF of one document
curl -L 'https://verification.didit.me/v3/session/{session_id}/signatures/{node_id}/documents/{document_id}/file/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -o agreement-signed.pdf

# Evidence PDF of one signer
curl -L 'https://verification.didit.me/v3/session/{session_id}/signatures/{node_id}/evidence/?signature_id={signature_id}' \
  -H 'x-api-key: YOUR_API_KEY' \
  -o signature-evidence.pdf
```

| 路由 | 参考 |
| - | - |
| `GET .../documents/{document_id}/file/` | [下载已签署文档](https://docs.didit.me/zh/sessions-api/electronic-signature/download-signed-document.md) |
| `GET .../evidence/` | [下载签名证据](https://docs.didit.me/zh/sessions-api/electronic-signature/download-evidence.md) |
| `GET .../fields/{field_id}/image/` | [下载签名图像](https://docs.didit.me/zh/sessions-api/electronic-signature/download-field-image.md) |
| `POST .../validate/` | [验证签名](https://docs.didit.me/zh/sessions-api/electronic-signature/validate-signatures.md) |

在返回响应之前，Didit 会根据记录的 SHA-256 检查存储的文件。如果不一致，已签署 PDF 和证据路由将返回 `409`，图像路由将返回 `400`，且均包含 `signature_document_changed`。当 KYB 步骤有多个签署人时，调用证据路由请务必传入 `signature_id`。

## 已签署 PDF

已签署 PDF 按顺序包含以下内容：

1. 向签署人展示的文档页面，每个字段值都已印在您放置的位置。
2. 证据页，除非您关闭了 `signature_evidence_page`。
3. 仅限高级（AES）：PAdES 签名，附带 Didit 签发的 RFC 3161 时间戳以及未来验证该签名所需的吊销数据。简单 PDF 在证据页后结束，不包含数字签名、印章或时间戳。

在高级（AES）PDF 上，签名覆盖其前面的每一个字节，包括字段值和证据页。之后对文件的任何更改都会使其失效，任何支持 PAdES 的验证工具都会显示这一点。签名的详细信息注明了签署人姓名，并引用了其已验证的用户验证会话和验证码确认。

字段值会成为页面内容的一部分，而不是表单字段，因此之后无法被编辑，并且每个 PDF 查看器都可以显示它们。勾选的复选框会显示对勾，未勾选的则保留文档原本绘制的样式。高于 24 磅的签名框还会在签名下方显示一行小说明：`Signed with Didit ·`，后接签名 `id` 的前 8 个字符。

Didit 会在向签署人展示的文档字节之后追加字段值、证据页和签名。该展示文档是已签署文件的精确前缀，因此仍然可以针对已签署 PDF 校验 `sha256_original`。

## 证据 PDF

证据 PDF 会记录单个签署人的以下信息：

* 等级和格式。
* 签署人姓名、其签署身份，对于 KYB 还包括企业名称。
* 已验证的身份证件会话（仅限高级 (AES)）。
* 确认信息：渠道、脱敏后的目的地和时间（仅限高级 (AES)）。
* 签署人的地址。
* 每个文档：标题、页数和原始文件的 SHA-256。对于 Word 文档，还包含 Word 文件的名称和 SHA-256、转换器版本以及 PDF 的 SHA-256。
* 采用的签名：键入（附带其手写风格）或绘制、采用的时间，以及签名和首字母签名的图像。
* 每个字段（按文档划分）：其标签、页面和类型、其值（签名或首字母签名则为图像）、值的来源（例如 **由签署人键入**、**已验证的身份证件** 或 **您的 API**）、填充时间 (UTC)，以及对于签署人键入的值，记录其当时的地址。
* 最终同意：签署人在审核屏幕上同意的文本，以及同意的时间。
* 每个已签署文件的 SHA-256，对于高级（AES），还包括证书（颁发给、颁发者、序列号和有效期）以及时间戳。

附加到每个已签署 PDF 末尾的页面包含相同的内容（不含证书部分），因为该页面是在应用签名之前添加的。

## 重新验证签名

`POST /v3/session/{session_id}/signatures/{node_id}/validate/` 会重新读取该步骤的每个已签署 PDF 并检查其 SHA-256。对于高级（AES）签名，它还会验证 PAdES 签名、其证书、吊销数据和时间戳。简单签名没有数字签名，因此仅核验文件的完整性。它将结果保存在 `validation` 中并返回更新后的 `signatures[]`。发送 `signature_id` 可核验单个签署人。此接口需要 `write:sessions` 权限，在控制台中对应**重新验证**按钮。如果存储的已签署 PDF 与其 `sha256_signed` 不再匹配，则返回 `400` 及 `signature_document_changed`。

在文件完成签署之前，`validation` 为 `null`。如果 Didit 无法确认签署结果，`validation` 为 `{ "valid": null, "reason": "signature_provider_outcome_unknown", "checked_at" }`，并且 `status` 会保持为 `signing` 直至问题解决：请将其视为未签署。

| `validation.documents[]` 的字段 | 描述 |
| - | - |
| `valid` | 当签名和时间戳均有效且受信任时为 `true`。对于简单签名，文件未发生变更时为 `true`。 |
| `integrity` | 自签署以来文件未发生变更时为 `true`。 |
| `trusted` | 当签名证书链指向受信任的根证书时为 `true`。对于简单签名则为 `null`。 |
| `revoked` | 当签名证书已被吊销时为 `true`。对于简单签名则为 `null`。 |
| `trusted_list` | AES 为 `{ "status": "not_applicable", "reason": "aes_not_qualified" }`。欧盟信任列表核验适用于合格签名。简单签名返回 `{ "status": "not_applicable", "reason": "simple_not_sealed" }`。 |
| `certificate`、`timestamp` | 文件中的信息。 |

## 在 PDF 报告中

[PDF 报告](https://docs.didit.me/zh/sessions-api/generate-pdf.md)会打印签名部分，包含签署人、确认信息、证书、时间戳以及带有哈希值的文件。当文件包含字段时，紧随其后的是**电子签名 · 字段**页面，每个文件对应一个表格：包含每个字段的值、签名和姓名首字母图像、时间以及来源。签名部分在 KYC 报告中位于银行验证之后，在 KYB 报告中位于文件之后。传递 `pages=signature` 可仅打印该部分。

## 相关内容

* [电子签名概览](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md)
* [电子签名警告](https://docs.didit.me/zh/core-technology/electronic-signature/warnings-electronic-signature.md)
* [数据模型：电子签名](https://docs.didit.me/zh/reference/data-models.md#电子签名)
* [Webhooks](https://docs.didit.me/zh/integration/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.