> ## 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.

# 签名验证 API：重新校验已签署 PDF

> Didit 可重新检查电子签名步骤中已签署文件的完整性、PAdES 签名、证书、吊销数据和时间戳。

按步骤重新检查已签署文件，并将结果保存到每位签署人的 `validation` 中。Didit 会重新读取每份已签署的 PDF，并检查其 SHA-256。对于高级（AES）签名，还会验证 PAdES 签名、证书、吊销数据和时间戳。简单签名没有数字签名，因此仅检查文件的完整性。不会重新签名。在控制台中，这对应会话的**签名**标签页中的**重新验证**按钮。

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/session/{session_id}/signatures/{node_id}/validate/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"signature_id": "{signature_id}"}'
```

传入 `signature_id` 可检查单个签署人。若不传，Didit 会检查该步骤的所有签署人；如果其中任何一人尚未签署，则返回 `409` 和 `signature_not_signed`。已存储的已签署 PDF 如果与其 `sha256_signed` 不再匹配，则返回 `400` 和 `signature_document_changed`。

响应为 `{ "signatures": [...] }`，其中包含已检查的签署人。请读取 `validation.valid` 获取整体结果，读取 `validation.documents[]` 获取每份文档的结果。所有字段请参阅[重新验证签名](https://docs.didit.me/zh/core-technology/electronic-signature/report-electronic-signature.md#重新验证签名)。

## 相关内容

* [电子签名报告](https://docs.didit.me/zh/core-technology/electronic-signature/report-electronic-signature.md)
* [下载已签署文档](https://docs.didit.me/zh/sessions-api/electronic-signature/download-signed-document.md)


## OpenAPI

````yaml zh/openapi-25.json POST /v3/session/{sessionId}/signatures/{nodeId}/validate/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/{sessionId}/signatures/{nodeId}/validate/:
    post:
      tags:
        - Sessions
      summary: 再次验证签名
      description: >-
        重新检查电子签名步骤的已签名证件。Didit 会重新读取每份已签名的 PDF，检查其 SHA-256，对于高级（AES）签名，还会验证
        PAdES 签名、证书、吊销数据和时间戳（简单签名没有数字签名，因此仅检查文件完整性），然后将结果保存在每个签署人的 `validation`
        中并返回更新后的项目。不会重新签名任何内容。发送 `signature_id`
        以检查单个签署人；若不提供，则检查该步骤的所有签署人，如果其中有任何人未签名，则调用失败。


        需要 `write:sessions` 权限；您的 API 密钥有效。在控制台中，对应 **Validate again** 按钮。
      operationId: post_v3_session_signature_validate
      parameters:
        - name: sessionId
          in: path
          required: true
          description: 用户验证（KYC）或企业验证（KYB）会话。
          schema:
            type: string
            format: uuid
            example: 11111111-2222-3333-4444-555555555555
        - name: nodeId
          in: path
          required: true
          description: 电子签名步骤：`signatures[]` 中项目的 `node_id`。
          schema:
            type: string
            example: feature_signature
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                signature_id:
                  type: string
                  format: uuid
                  description: '`signatures[]` 中某个签署人条目的 `id`。'
            example:
              signature_id: 0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10
      responses:
        '200':
          description: 已核验的签署人，包含其更新后的 `validation`。
          content:
            application/json:
              schema:
                type: object
                properties:
                  signatures:
                    type: array
                    items:
                      $ref: '#/components/schemas/SignatureResult'
        '400':
          description: 存储的已签名 PDF 与其签名时记录的 SHA-256 不再匹配。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
              examples:
                Document changed:
                  summary: 已签名的文件与其哈希值不再匹配
                  value:
                    code: signature_document_changed
                    detail: signature_document_changed
        '403':
          description: 缺少凭据，或凭据无法读取此会话。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: You do not have permission to perform this action.
        '404':
          description: 没有匹配的签名：会话、步骤或签名者不存在或已被删除。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
              examples:
                Unknown signer:
                  summary: 该步骤中不存在此签名
                  value:
                    code: signature_not_found
                    detail: signature_not_found
        '409':
          description: 该步骤的签名人尚未签名，因此无需验证任何内容。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
              examples:
                Not signed:
                  summary: 签名人尚未签名
                  value:
                    code: signature_not_signed
                    detail: signature_not_signed
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.sessions.signatures.validate(
                "11111111-2222-3333-4444-555555555555",
                "feature_signature",
                signature_id="0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.sessions.signatures.validate(
              "11111111-2222-3333-4444-555555555555",
              "feature_signature",
              {
                signature_id: "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
              },
            );
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Signatures.Validate(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", didit.SessionsSignaturesValidateParams{\n\tSignatureID: didit.String(\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.SessionsSignaturesValidateParams;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.sessions().signatures().validate("11111111-2222-3333-4444-555555555555",
            "feature_signature", SessionsSignaturesValidateParams.builder()
                    .signatureId("0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->sessions->signatures->validate('11111111-2222-3333-4444-555555555555',
            'feature_signature', [
                'signature_id' => '0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10',
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.sessions.signatures.validate(
              "11111111-2222-3333-4444-555555555555",
              "feature_signature",
              signature_id: "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Sessions.Signatures.ValidateAsync("11111111-2222-3333-4444-555555555555",
            "feature_signature", new SessionsSignaturesValidateParams

            {
                SignatureId = "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    SignatureResult:
      type: object
      description: >-
        单个电子签名步骤中一位签名人的结果。请参阅[电子签名报告](/zh/core-technology/electronic-signature/report-electronic-signature)。
      properties:
        id:
          type: string
          format: uuid
          description: 将其作为 `signature_id` 传入以下载该签署人的证据或核验其签名。
        node_id:
          type: string
          description: 生成它的工作流步骤。
        status:
          type: string
          enum:
            - intro
            - review
            - code
            - signing
            - signed
            - declined
          description: 签署人在该步骤中所处的进度。仅 `signed` 表示文件已签署。
        verdict:
          type: string
          enum:
            - Not Finished
            - Approved
            - In Review
            - Declined
          description: 步骤的结果。警告会通过其规则对其进行设置；自定义状态规则在此之后应用。
        level:
          type: string
          enum:
            - simple
            - aes
            - qes
          description: '`simple`（默认）或 `aes`。`qes`（合格电子签名，QES）是尚未开放的附加功能。'
        format:
          type: string
          enum:
            - pdf
            - pades
          description: Simple 签名对应 `pdf`，Advanced (AES) 对应 `pades`。
        profile:
          type: string
          nullable: true
          description: 高级（AES）签名完成签署后为 `PAdES-B-LT`，否则为 null。
        signer:
          type: object
          properties:
            name:
              type: string
              nullable: true
              description: >-
                签署人的姓名。已验证（来自已通过的身份证件验证或会话），但 Simple
                等级且没有已验证会话姓名的情况除外，此时为签署人输入的姓名且未经核验。
            capacity:
              type: string
              enum:
                - self
                - company
            company:
              type: string
              nullable: true
            role:
              type: string
              nullable: true
              description: 关键人员的职务（按申报）。
            roles:
              type: array
              items:
                type: string
              description: 关键人员的结构化角色（针对企业申报）。
            identity_session_id:
              type: string
              format: uuid
              description: 验证了签署人的 KYC 会话。
        identity_used:
          type: object
          description: 签名所依赖的已验证身份。对于未关联已验证身份的 Simple 签名，该项为空。
          properties:
            session_id:
              type: string
              format: uuid
            kyc_id:
              type: string
              format: uuid
              nullable: true
            verified:
              type: boolean
            expected_name:
              type: string
              nullable: true
              description: 签署人必须匹配的姓名。
        certificate:
          type: object
          nullable: true
          description: 签署文件所用的证书。签署前为 `null`，对于简单签名则始终为 `null`。
          properties:
            issuer:
              type: string
            issued_to:
              type: string
            serial:
              type: string
              description: 序列号，十六进制。
            valid_from:
              type: string
              format: date-time
            valid_until:
              type: string
              format: date-time
        confirmation:
          type: object
          properties:
            channel:
              type: string
              nullable: true
              enum:
                - email
                - sms
              description: 对于没有代码的 Simple 签名，该值为 `null`。
            destination:
              type: string
              nullable: true
              description: 验证码发送至的已脱敏联系方式。
            confirmed_at:
              type: string
              format: date-time
              nullable: true
            attempts:
              type: integer
              description: 已输入的验证码，其中包括正确的验证码。
        timestamp:
          type: object
          nullable: true
          description: >-
            签名中的 RFC 3161 时间戳，由 Didit 签发。完成签名之前为 `null`，对于简单签名（Simple
            signature）始终为 `null`。
          properties:
            time:
              type: string
              format: date-time
            qualified:
              type: boolean
              description: 对于 AES 始终为 `false`。
            valid:
              type: boolean
        documents:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: 此签署人副本上的证件。用于下载已签署的文件。
              uuid:
                type: string
                format: uuid
                description: 与 `id` 相同。
              title:
                type: string
              file_name:
                type: string
              pages:
                type: integer
                description: 已签署的证件页码。对于 Word 证件，指转换后的 PDF 页码。
              size_bytes:
                type: integer
              sha256_original:
                type: string
                description: 向签署人展示的文档的 SHA-256。
              sha256_signed:
                type: string
                nullable: true
                description: 签署后的 PDF 的 SHA-256。
              status:
                type: string
                enum:
                  - signed
                  - declined
                  - not_signed
                  - not_reached
                description: '`not_signed`：已打开但未签署。`not_reached`：从未打开。'
              opened_at:
                type: string
                format: date-time
                nullable: true
              read_at:
                type: string
                format: date-time
                nullable: true
                description: 当步骤有要求时，签署人到达无字段证件末尾的时间。
              read_to_end:
                type: boolean
              consented_at:
                type: string
                format: date-time
                nullable: true
                description: 签署人同意无字段证件的时间，或完成有字段证件中各个字段的时间。
              consent:
                type: boolean
              signed_file:
                type: string
                nullable: true
                description: >-
                  签署后的 PDF
                  路径（签署完成后）。参见[下载已签署证件](/zh/sessions-api/electronic-signature/download-signed-document)。
              mode:
                type: string
                enum:
                  - fields
                  - read_and_agree
                description: 带有字段的证件为 `fields`，没有字段的证件为 `read_and_agree`。
              source_format:
                type: string
                enum:
                  - pdf
                  - docx
                description: '`pdf`，或者对于 Didit 转换为 PDF 的 Word 文档为 `docx`。'
              conversion:
                type: object
                nullable: true
                description: PDF 文件为 `null`。对于 Word 文档，则包含原始文件和转换后的文件。
                properties:
                  from:
                    type: string
                    enum:
                      - docx
                  file_name:
                    type: string
                    description: 您的原始 Word 文件名。
                  sha256:
                    type: string
                    description: 您原始 Word 文件的 SHA-256。
                  size_bytes:
                    type: integer
                    description: 您的原始 Word 文件的大小。
                  converter:
                    type: string
                    description: 生成该 PDF 的转换器版本。
              fields:
                type: array
                description: 证件上的字段及其对应值。对于没有字段的证件，该项为空。
                items:
                  $ref: '#/components/schemas/SignatureFieldResult'
        adopted_signature:
          type: object
          nullable: true
          description: 签署人为签名和首字母字段采用的签名及首字母。在签署人采用之前为 `null`。
          properties:
            method:
              type: string
              enum:
                - typed
                - drawn
              description: '`typed`：手写体风格的已验证姓名。`drawn`：使用手指或鼠标绘制。'
            font:
              type: string
              nullable: true
              description: 键入签名的手写样式。手绘签名时为 `null`。
            adopted_at:
              type: string
              format: date-time
        electronic_signature_consent_at:
          type: string
          format: date-time
          nullable: true
          description: 签署人在审核屏幕上同意对证件进行电子签名的时间。当任何证件包含字段时设置。
        evidence_file:
          type: string
          nullable: true
          description: >-
            签名完成后证据 PDF
            的路径。参见[下载签名证据](/zh/sessions-api/electronic-signature/download-evidence)。
        warnings:
          type: array
          description: >-
            针对该签名人的警告。请参阅[电子签名警告](/zh/core-technology/electronic-signature/warnings-electronic-signature)。
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - SIGNATURE_DECLINED
                  - SIGNATURE_OTP_FAILED
                  - SIGNATURE_NAME_MISMATCH
                  - SIGNATURE_IDENTITY_NOT_VERIFIED
                  - SIGNATURE_DOCUMENT_CHANGED
                  - SIGNATURE_FIELD_DATA_MISSING
              node_id:
                type: string
        validation:
          type: object
          nullable: true
          description: >-
            已签名证件的最新加密核验结果。在证件签名之前为 `null`。如果 Didit 无法确认签名结果，则为 `{"valid": null,
            "reason": "signature_provider_outcome_unknown", "checked_at":
            ...}`，且 `status` 保持为 `signing`：请将其视为未签名。
          properties:
            valid:
              type: boolean
              nullable: true
              description: 当所有证件均有效时为 `true`。当无法确认签名结果时为 `null`。
            reason:
              type: string
              description: 当 `valid` 为 `null` 时设置：`signature_provider_outcome_unknown`。
            checked_at:
              type: string
              format: date-time
            documents:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  checked_at:
                    type: string
                    format: date-time
                  valid:
                    type: boolean
                    description: 当签名和时间戳均有效且可信时为 `true`。
                  integrity:
                    type: boolean
                    description: 当证件自签名后未发生更改时为 `true`。
                  trusted:
                    type: boolean
                    description: 当签名证书链接到受信任的根证书时为 `true`。
                  revoked:
                    type: boolean
                  trusted_list:
                    type: object
                    description: >-
                      欧盟信任列表（EU Trusted List）检查。对于 AES：`{"status":
                      "not_applicable", "reason": "aes_not_qualified"}`。
                    properties:
                      status:
                        type: string
                      reason:
                        type: string
                  certificate:
                    type: object
                    nullable: true
                    description: 签署文件所用的证书。签署前为 `null`，对于简单签名则始终为 `null`。
                    properties:
                      issuer:
                        type: string
                      issued_to:
                        type: string
                      serial:
                        type: string
                        description: 序列号，十六进制。
                      valid_from:
                        type: string
                        format: date-time
                      valid_until:
                        type: string
                        format: date-time
                  timestamp:
                    type: object
                    nullable: true
                    description: >-
                      签名中的 RFC 3161 时间戳，由 Didit 签发。完成签名之前为 `null`，对于简单签名（Simple
                      signature）始终为 `null`。
                    properties:
                      time:
                        type: string
                        format: date-time
                      qualified:
                        type: boolean
                        description: 对于 AES 始终为 `false`。
                      valid:
                        type: boolean
        declined_at:
          type: string
          format: date-time
          nullable: true
        declined_action:
          type: string
          enum:
            - DECLINE
            - REVIEW
            - NO_ACTION
        signed_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          description: 签名链接失效的时间。
        email_sent_at:
          type: string
          format: date-time
          nullable: true
        email_unavailable_reason:
          type: string
          nullable: true
        ip_address:
          type: string
          nullable: true
          description: 签署人请求验证码时的地址。
        place:
          type: string
          nullable: true
          description: 未采集：始终为 `null`。
        place_unavailable_reason:
          type: string
          nullable: true
          enum:
            - not_collected
    SignatureFieldResult:
      type: object
      description: >-
        已签署证件的一个字段，包含其在此签署人副本上的值。请参阅
        [Fields](/zh/core-technology/electronic-signature/report-electronic-signature#字段)。
      properties:
        key:
          type: string
          description: 字段的键，与 `sign.field_values` 中使用的相同。
        type:
          type: string
          enum:
            - signature
            - initials
            - full_name
            - date_signed
            - text
            - checkbox
            - email
            - data
        role:
          type: string
          enum:
            - verified_person
            - legal_representative
            - key_people
        label:
          type: string
        page:
          type: integer
          description: 页码，从 1 开始。对于 Word 证件，指转换后 PDF 的页码。
        x:
          type: number
          description: 左边缘，占页面宽度的比例。
        'y':
          type: number
          description: 顶部边缘，以页面高度的比例表示。
        width:
          type: number
          description: 宽度，占页面宽度的比例。
        height:
          type: number
          description: 高度，表示为页面高度的比例。
        required:
          type: boolean
        value:
          nullable: true
          description: >-
            `text`、`email`、`full_name`、`date_signed` 和 `data` 为字符串，`checkbox`
            为布尔值，应用的签名或缩写签名为 `true`。为空时为 `null`。
        display_value:
          type: string
          nullable: true
          description: 页面上印刻的值：日期采用字段的 `date_format`，复选框为 `Yes` 或 `No`，签名或姓名缩写为 `Signed`。
        value_source:
          type: string
          nullable: true
          enum:
            - signer
            - identity
            - contact
            - company
            - session
            - metadata
            - api
            - signing_time
            - null
          description: >-
            该值的来源：`signer`（由签署人输入、勾选或应用）、`identity`（核验的证件）、`contact`（核验的邮箱或电话）、`company`（核验的公司）、`session`（`vendor_data`）、`metadata`、`api`（`sign.field_values`）或
            `signing_time`（签署日期）。
        filled_at:
          type: string
          format: date-time
          nullable: true
        image_url:
          type: string
          nullable: true
          description: >-
            仅限签名和姓名首字母：所应用图像的路径。请参阅[下载签名图像](/zh/sessions-api/electronic-signature/download-field-image)。
        value_unavailable_reason:
          type: string
          nullable: true
          enum:
            - source_empty
            - null
          description: >-
            当预填字段在会话中没有值且 `signature_field_data_missing_action` 允许签署人仍然签名时，为
            `source_empty`。
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        您的应用 API 密钥，可在 Business Console 的“开发者 -> API
        密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
        IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
        列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
        URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
        https://docs.didit.me/console/api-keys。

````

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