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

每个电子签名步骤都会为每位签署人生成一项结果。您可以在以下位置的 signatures[] 数组项中找到该结果：

用于用户验证（KYC）和企业验证（KYB）会话的 GET /v3/session/{sessionId}/decision/。
V3 会话 Webhook 的 decision，在会话状态为 Approved、Declined、In Review 或 Abandoned 时发送。
控制台中该会话的签名选项卡，以及 PDF 报告中的签名部分。

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

示例

{
  "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`。被拒绝或失败的签名将采用其规则的决策结果，自定义状态规则可以修改它。
`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 的路径。
`warnings`	array	触发的每个警告对应的 `{ "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，与您在 `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）的路径。请参阅下载签名图像。
`value_unavailable_reason`	由 Didit 填充的字段没有值的原因：`not_verified`（身份或联系方式未验证）、`not_applicable`（个人自身签名上的企业字段）、`not_provided`（来源没有值）或 `set_at_confirmation`（签署人在确认前的签署日期）。其他情况下为 `null`。

下载已签署文档

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

# 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/`	下载已签署文档
`GET .../evidence/`	下载签名证据
`GET .../fields/{field_id}/image/`	下载签名图像
`POST .../validate/`	验证签名

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

已签署 PDF

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

向签署人展示的文档页面，每个字段值都已印在您放置的位置。
证据页，除非您关闭了 signature_evidence_page。
仅限高级（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 报告会打印签名部分，包含签署人、确认信息、证书、时间戳以及带有哈希值的文件。当文件包含字段时，紧随其后的是电子签名 · 字段页面，每个文件对应一个表格：包含每个字段的值、签名和姓名首字母图像、时间以及来源。签名部分在 KYC 报告中位于银行验证之后，在 KYB 报告中位于文件之后。传递 pages=signature 可仅打印该部分。

身份认证

验证

监控

平台

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

示例

签名对象

签署人

文件

字段

下载已签署文档

已签署 PDF

证据 PDF

重新验证签名

在 PDF 报告中

相关内容

​示例

​签名对象

​签署人

​文件

​字段

​下载已签署文档

​已签署 PDF

​证据 PDF

​重新验证签名

​在 PDF 报告中

​相关内容

示例

签名对象

签署人

文件

字段

下载已签署文档

已签署 PDF

证据 PDF

重新验证签名

在 PDF 报告中

相关内容