签署会话 API

为合同问题创建、管理和跟踪电子签署会话。

签署会话 API 让您以编程方式为合同问题创建和管理签署会话。您可以创建会话、跟踪签署进度、重发请求、作废会话，以及下载已签署的文档。

所有请求和响应体均使用 snake_case 字段命名。

Endpoints

POST/api/v1/forms/:id/signing-sessionsGET/api/v1/forms/:id/signing-sessionsGET/api/v1/signing-sessions/:sessionIdPOST/api/v1/signing-sessions/:sessionId/voidPOST/api/v1/signing-sessions/:sessionId/resend/:slotNumberGET/api/v1/signing-sessions/:sessionId/documentsGET/api/v1/signing-sessions/:sessionId/documents/:docIdGET/api/v1/signing-sessions/:sessionId/auditGET/api/v1/s/:shortCodePOST/api/v1/s/:shortCode/verify-password

创建会话

POST/api/v1/forms/:id/signing-sessions

为包含一个或多个合同问题的表单创建新的签署会话。返回该会话，其中包含每个签署者插槽的唯一签署链接。

路径参数

idstring

表单 ID

请求体

signersarray

签署者配置数组，每个插槽一项。每个对象可包含 slot_number（整数）、first_name（字符串）、last_name（字符串）和 email（字符串）。除 slot_number 外的所有字段均为可选。

signing_orderstring

"sequential" 或 "any"。默认为该问题的默认签署顺序。

expiry_daysinteger

会话过期前的天数。默认：30。

passwordstring

用于保护签署链接的密码。

hide_other_signersboolean

隐藏其他签署者已填写的字段。默认：false。

require_email_verificationboolean

签署前要求邮箱验证。默认：false。

copy_modestring

"ask"、"always" 或 "disabled"。默认："ask"。

notify_emailsarray

接收状态通知的邮箱地址数组。

notify_eventsarray

事件类型数组："each_signature"、"all_complete"、"decline"、"expiry"。

send_signing_emailsboolean

向已配置邮箱地址的签署者发送签署请求邮件。默认：false。

custom_email_bodystring

自定义邮件模板。支持变量：{slot_firstName}、{slot_lastName}、{slot_link}、{expiryDate}。

响应

json

{
  "id": "ses_abc123def456",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "status": "active",
  "signing_order": "sequential",
  "total_slots": 2,
  "total_signed": 0,
  "expires_at": "2026-04-25T00:00:00.000Z",
  "hide_other_signers": false,
  "copy_mode": "ask",
  "signer_links": [
    {
      "slot_number": 1,
      "slot_label": "Buyer",
      "short_code": "xK9f2",
      "signing_url": "https://nue.fm/s/xK9f2",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "status": "pending"
    },
    {
      "slot_number": 2,
      "slot_label": "Seller",
      "short_code": "mP3a7",
      "signing_url": "https://nue.fm/s/mP3a7",
      "first_name": null,
      "last_name": null,
      "email": null,
      "status": "pending"
    }
  ],
  "created_at": "2026-03-26T10:00:00.000Z"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signers": [
      {"slot_number": 1, "first_name": "John", "last_name": "Smith", "email": "john@example.com"},
      {"slot_number": 2, "first_name": "Jane", "last_name": "Doe"}
    ],
    "signing_order": "sequential",
    "expiry_days": 30,
    "send_signing_emails": true
  }'

列出会话

GET/api/v1/forms/:id/signing-sessions

返回某个表单的所有签署会话。

查询参数

statusstring

按状态筛选："active"、"fully_signed"、"declined"、"voided"、"expired"。

pageinteger

页码（默认：1）

per_pageinteger

每页结果数（默认：20）

响应

json

{
  "sessions": [
    {
      "id": "ses_abc123def456",
      "status": "active",
      "total_slots": 2,
      "total_signed": 1,
      "signing_order": "sequential",
      "expires_at": "2026-04-25T00:00:00.000Z",
      "created_at": "2026-03-26T10:00:00.000Z"
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

获取会话

GET/api/v1/signing-sessions/:sessionId

返回单个签署会话的完整详情，包括签署者链接及其状态。

响应

返回与创建端点相同的会话对象，其中每个签署者链接的状态和时间戳均已更新。

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

作废会话

POST/api/v1/signing-sessions/:sessionId/void

作废一个活跃的签署会话。所有待处理的签署链接都会失效。已签署的各方会收到通知，PDF 会加上 "VOIDED" 水印。

请求体

reasonstring

作废该会话的原因。

响应

json

{
  "id": "ses_abc123def456",
  "status": "voided",
  "voided_at": "2026-03-27T15:30:00.000Z",
  "void_reason": "Terms changed, new agreement required"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/void" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Terms changed, new agreement required"}'

重发签署请求

POST/api/v1/signing-sessions/:sessionId/resend/:slotNumber

向指定签署者重发签署请求邮件。该签署者必须已配置邮箱地址。

响应

json

{
  "success": true,
  "sent_to": "john@example.com",
  "slot_number": 1
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/resend/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

列出已签署文档

GET/api/v1/signing-sessions/:sessionId/documents

返回已完成会话的已签署文档列表。每份文档对应表单中的一个合同问题。

响应

json

{
  "documents": [
    {
      "id": "doc_xyz789",
      "question_id": "q_abc123",
      "question_title": "Service Agreement",
      "document_url": "https://storage.nueform.io/signed/doc_xyz789.pdf",
      "document_hash": "sha256:a1b2c3d4e5f6...",
      "generated_at": "2026-03-28T12:00:00.000Z"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

获取已签署文档

GET/api/v1/signing-sessions/:sessionId/documents/:docId

以 PDF 文件形式下载指定的已签署文档。

响应

返回 PDF 文件，Content-Type: application/pdf。

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123/documents/doc_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o signed-document.pdf

获取审计跟踪

GET/api/v1/signing-sessions/:sessionId/audit

返回签署会话的完整审计跟踪，包括查看事件、签署、拒签和系统事件。

响应

json

{
  "entries": [
    {
      "id": "aud_001",
      "action": "session_created",
      "timestamp": "2026-03-26T10:00:00.000Z",
      "actor_email": "owner@company.com",
      "ip_address": "192.168.1.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_002",
      "action": "document_viewed",
      "slot_number": 1,
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:44:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_003",
      "action": "signed",
      "slot_number": 1,
      "actor_name": "John Smith",
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:45:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/audit" \
  -H "Authorization: Bearer YOUR_API_KEY"

解析短代码

GET/api/v1/s/:shortCode

公开端点（无需认证）。将签署短代码解析为渲染签署体验所需的表单和会话上下文。

响应

json

{
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "session_id": "ses_abc123def456",
  "slot_number": 1,
  "slot_label": "Buyer",
  "status": "pending",
  "requires_password": true,
  "requires_email_verification": false,
  "signing_order": "sequential",
  "is_turn": true
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/s/xK9f2"

验证密码

POST/api/v1/s/:shortCode/verify-password

公开端点。验证受密码保护的签署会话的密码。验证成功时返回临时访问令牌。

请求体

passwordstring

会话密码。

响应

json

{
  "success": true,
  "access_token": "tmp_abc123..."
}

错误响应（401）

json

{
  "error": "Invalid password"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/s/xK9f2/verify-password" \
  -H "Content-Type: application/json" \
  -d '{"password": "mySecretPass123"}'

最后更新：2026年8月24日