本指南将引导您使用SSL.com的文档对文档哈希和PDF文件进行签名 电子签名者 云签名服务和云签名联盟（CSC）API。 所有API请求示例都将显示为 邮差，我们建议您安装 邮递员桌面应用 如果您想通过示例操作，请在计算机上使用。 API请求的cURL命令示例也包括在内。
如果您准备在SSLcom的生产eSigner环境中使用CSC API，请阅读 使用eSigner CSC API进行远程文档签名.
创建测试订单
- 首先，您需要在沙盒中创建文档签名顺序。 首先登录您的沙盒帐户，然后转到 數據表 标签。
- 点击 开发者工具.
- 选择 eSigner文档签名，然后点击 创建测试订单 按钮。
- 将出现一个对话框。 点击 OK 按钮。
- 找到您的测试订单，然后单击 详情 链接。
- 点击 编辑注册人 开始输入您的测试订单的申请人和收件人信息。 请注意，由于此信息将不会用于签发有效的文档签名证书，因此，如果需要，您可以输入虚拟信息。
- 添加测试证书的申请人信息，然后单击 下一个>> 按钮。
- 输入收件人信息，然后单击 下一个>> 按钮。
- 点击 跳至 按钮以跳过上传测试证书的验证文档。
- 您的测试订单现在应具有以下状态： 待验证。 联系SSL.com支持团队，网址为 Support@SSL.com 验证您的测试证书。
注册eSigner并设置两因素身份验证
- 一旦测试订单通过SSL.com支持人员的验证，就可以将其注册到eSigner中。 导航到 订单管理 标签，然后找到您的测试订单。
- 点击订单的 详情 链接。
- 创建并确认4位PIN码，然后点击 创建PIN码 按钮。
如果您需要重设eSigner PIN，请阅读 这个方法.
- 将会出现QR码。
下次重新加载页面时，QR码将不可见。 如果您需要查看或重置您的eSigner QR码，请阅读 这个方法.
- 将代码扫描到移动设备（例如Google Authenticator或Authy）上的2因子身份验证应用程序中。 该应用程序将为您提供一次性密码（OTP），供您在签名时使用。 每个OTP有效期为30秒。
Install 安装 邮差 并导入 CSC API 集合
- 下载并解压缩 CSC API邮递员收藏 （见 https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation 用于最新的 api 端点或集合下载）。
- 下载并安装 邮递员REST客户端.
- 启动Postman，然后创建一个新的Postman帐户或登录到现有的帐户。
- 点击 导入模板 按钮。
- 点击 上传文件 按钮，导航到未压缩的API收集文件（
CSC-API.postman_collection.json），然后将其打开。
- 点击 导入模板 按钮。
- 点击 系列 标签，然后展开CSC API集合以查看将要使用的五个POST请求：
- CSC资讯
- CSC凭证列表
- CSC凭证信息
- 凭证授权
- 签名哈希
检索访问令牌
- 下一步是从SSL.com检索访问令牌。 在您请求访问令牌之前，您需要一个 客户ID （也称为 应用程序ID。 Please refer to请参阅 这个方法 有关生成此证书的说明）。
- 点击 授权 标签，选择 身份验证 2.0 来自 类型 菜单，然后点击 获取新的访问令牌 按钮。
- 在表单中输入以下信息：
- 令牌名称： SandBox CSC（或您喜欢的任何其他易于记忆的名称）
- 赠款类型： 授权码
- 回调网址： [留着空白]
- 使用浏览器授权： 检查
- 验证网址：
https://oauth-sandbox.ssl.com/oauth2/authorize - 访问令牌URL：
https://oauth-sandbox.ssl.com/oauth2/token - 客户编号： [您的客户编号]
- 客户机密： [您的客户秘密]
- 范围： 服务
- 省（自治区，直辖市，州）： [留着空白]
- 客户端身份验证： 作为基本身份验证标头发送
完成后，单击 请求令牌 按钮。
- 登录表单将出现在您的Web浏览器中。 输入您的SSL.com用户名和密码，然后单击 会员登录 按钮。
- 您的新访问令牌应出现在Postman中。 选择访问令牌文本并将其复制到剪贴板，然后关闭 管理访问令牌 对话框。 将您的访问令牌粘贴到文本编辑器中，您可以在其中轻松访问它。 每个访问令牌将在一个小时后过期。
您还可以保存您的令牌以供重复使用 邮差 请求，但我们发现将令牌直接复制并粘贴到每个请求中是最可靠的。
签署哈希
现在您有了访问令牌，您可以开始发出 API 请求并创建签名。 本节将引导您完成五个可用的请求 邮递员 CSC 集合，导致从文档哈希创建数字签名。
获取CSC信息（可选）
- 您可以使用 CSC资讯 请求获取有关SSL.com的云签名服务的信息。 请注意，与集合中的其他集合不同，此请求不需要您的访问令牌。 要发送请求，请选择 CSC资讯 来自 CSC 应用程序接口 集合，然后单击 提交 按钮。
- 有关云签名服务的信息将显示在Postman的JSON对象中 响应 领域。
cURL命令
curl --location --request POST“ https://cs-try.ssl.com/csc/v0/info” \ --header“内容类型：application / json” \ --data-raw“ {}”
CSC凭证列表
- 特 CSC凭证列表 请求将检索您将在以后的API请求中使用的凭据。 选择 CSC凭证列表 并单击 授权 标签。
- 不记名令牌 来自 类型 菜单，将您的访问令牌粘贴到 Token 字段，然后单击 提交 按钮。
- 带有与用户相关联的凭据ID列表的JSON对象将出现在 响应 领域。 您的列表可能包含一个值。 将您的凭据ID复制并粘贴到文本编辑器中，以用于以后的请求。
cURL命令
更换 MY-ACCESS-TOKEN 使用您的实际访问令牌：
curl --location --request POST“ https://cs-try.ssl.com/csc/v0/credentials/list” \ --header“内容类型：application / json” \ --header“授权：Bearer MY-ACCESS-TOKEN“ \ --data-raw” {}“
如果使用 eseal 证书（仅包含组织信息的文档签名证书；包含在您的免费 esigner.com 帐户中），则包括“clientData”：“DS_ESEAL”（注意：eseal 不需要 OTP 身份验证）。 “clientData”的其他选项是用于 EV 代码签名的“EVCS”和用于 IV 或 IV+OV 文档签名的“DS”（默认）：
curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN" \ --data-raw "{\"clientData\": \"DS_ESEAL\"}"
CSC凭证信息（可选）
- 特 CSC凭证信息 请求将返回证书和与凭据ID相关的其他信息，并且不需要签名。 要使用此请求，请选择 CSC凭证信息 从集合中，然后单击 授权 标签。
- 不记名令牌 来自 类型 菜单，然后将您的访问令牌粘贴到 Token 领域。
- 点击 Body 标签，然后将您的凭据ID粘贴为
credentialID.
- 点击 提交 按钮。
- 带有您的签名证书链和其他信息的JSON对象将显示在 响应 领域。
cURL命令
更换 MY-ACCESS-TOKEN 和 MY-CREDENTIAL-ID 使用您的实际信息：
curl --location --request POST“ https://cs-try.ssl.com/csc/v0/credentials/info” \ --header“内容类型：application / json” \ --header“授权：Bearer MY-ACCESS-TOKEN“ \ --data-raw” {\“ credentialID \”：\“ MY-CREDENTIAL-ID \”，\“ certificates \”：\“ chain \”，\“ certInfo \”：true， \“ authInfo \”：true}“
凭证授权
- 特 凭证授权 请求将检索签名哈希的授权。 首先选择 凭证授权 从集合中，然后单击 授权 标签。
- 不记名令牌 来自 类型 菜单，然后将您的访问令牌粘贴到 Token 领域。
- 点击 Body 标签。 将您的凭据ID粘贴为
credentialID值和您希望作为文档签名的文档的哈希值hash值。 从身份验证应用程序检索并输入OTP，然后将其输入为OTP，然后点击 提交 按钮。
- 带有您的签名激活数据（SAD）的JSON对象将出现在 响应 领域。 复制此值并将其粘贴到文本编辑器中，以用于哈希签名请求。
cURL命令
更换 MY-ACCESS-TOKEN, MY-CREDENTIAL-ID, MY-HASH及 MY-OTP 使用您的实际信息：
curl --location --request POST“ https://cs-try.ssl.com/csc/v0/credentials/authorize” \ --header“内容类型：application / json” \ --header“授权：Bearer MY-ACCESS-TOKEN“ \ --data-raw” {\“ credentialID \”：\“ MY-CREDENTIAL-ID \”，\“ numSignatures \”：1，\“ hash \”：[\“ MY-HASH \“]，\” OTP \“：\” MY-OTP \“}”
签名哈希
- 现在我们准备对文档哈希签名。 选择 签名哈希 从集合中，然后选择 授权 标签。
- 不记名令牌 来自 类型 菜单，然后将您的访问令牌粘贴到 Token 领域。
- 点击 Body 标签。 将您的凭据ID粘贴为
credentialID值，您的签名激活数据作为SAD值，以及您希望作为文档签名的文档的哈希值hash值，然后单击 提交 按钮。
- 带有您签名的JSON对象将出现在 响应 领域。
cURL命令
更换 MY-ACCESS-TOKEN, MY-CREDENTIAL-ID, MY-SAD及 MY-HASH 使用您的实际信息：
curl --location --request POST“ https://cs-try.ssl.com/csc/v0/signatures/signHash” \ --header“内容类型：application / json” \ --header“授权：Bearer MY-ACCESS-TOKEN“ \ --data-raw” {\“ credentialID \”：\“ MY-CREDENTIAL-ID \”，\“ SAD \”：\“ MY-SAD \”，\“哈希\”： [\“ MY-HASH \”]，\“ signAlgo \”：\“ 1.2.840.113549.1.1.11 \”}“
签署PDF
除了签署文档哈希之外，您还可以上传和签署PDF文件。 首先下载并导入 文档签名API邮递员集合 （见 https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation 对于最新的 api 端点和集合下载），遵循相同的 安装步骤 您在上面遵循了 CSC API 集合。
- 上载PDF文件
- 签署PDF文件
您可以将上面使用的凭证重新使用 CSC凭证列表 请求。 您可能还需要检索一个新的 访问令牌.
上载PDF文件
- 点击 上载PDF文件 请求并单击 授权 标签。
- 不记名令牌 来自 类型 菜单，然后将您的访问令牌粘贴到 Token 领域。
- 点击 头 标签，然后将您的凭据ID粘贴到 值 列。
- 点击 Body 选项卡并单击 × 旁边
hello.pdf删除此占位符文件名。
- 点击 选择文件 按钮，然后导航到您要上传的文件。
- 点击 提交 按钮。
- 选择并复制
id要在下一个请求中使用的响应中的值。
cURL命令
更换 MY-CREDENTIAL-ID, MY-ACCESS-TOKEN及 /PATH/TO/FILE.pdf 使用您的实际信息：
curl --location --request POST“ https://ds-try.ssl.com/v1/pdf/upload” \ --header“凭据ID：MY-CREDENTIAL-ID” \ --header“授权：承载MY-ACCESS-TOKEN“ \ --header”内容类型：application / pdf“ \ --data-binary” @ / PATH / TO / FILE.pdf“
注意：对于可见的签名，请参考以下 HTTP 请求标头（/v1/pdf/upload）：
|
凭据 ID |
分配给密钥的唯一凭据 ID – 必需 |
|
签约理由 |
添加签名原因以添加签名外观和签名字典 - 可选，例如我批准此文档 |
|
签约地点 |
在签名字典中添加签名位置 - 可选，例如德克萨斯州休斯顿 |
|
联系方式 |
在签名字典中添加联系信息 - 可选，例如电话号码 |
|
签名字段位置 |
显示视觉签名的签名字段位置。 格式是 “x，y，宽度，高度“ - 可选的 |
|
页码 |
页码在哪里绘制签名 - 可选 |
|
手签 |
手签名的 Base64 编码 PNG 图像 - 可选 |
签署PDF文件
- 现在您可以签署PDF。 选择 上载PDF文件 请求并单击 授权 标签。
- 不记名令牌 来自 类型 菜单，然后将您的访问令牌粘贴到 Token 领域。
- 选择“正文”标签，然后粘贴到
id上一步中的值。
- 在验证应用中输入OTP，然后点击 提交 按钮。
- PDF数据将显示在下方 响应 领域。 选择 保存到文件 来自 保存回复 菜单，然后为文件命名。
- 在Acrobat中打开文件以确认文件已签名。 （请注意，在下面的屏幕快照中，Acrobat已手动信任SSL.com的RSA Development根目录。）
cURL命令
更换 MY-CREDENTIAL-ID, MY-FILE-ID及 MY-OTP 使用您的实际信息：
curl --location --request POST“ https://ds-try.ssl.com/v1/pdf/sign” \ --header“ Content-Transfer-Encoding：application / json” \ --header“ Content-Type ：application / json“ \ --header”授权：Bearer MY-ACCESS-TOKEN“ \ --data-raw” {\“ id \”：\“ MY-FILE-ID \”，\“ otp \”：\ “ MY-OTP \”}“
投入生产
要上线，您需要从子域中删除“-try”。 例如，要使用 ds-try.ssl.com，请删除“-try”，这样子域将变为 ds.ssl.com。
