en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

使用eSigner CSC API进行远程文档签名

本指南将向您展示如何使用SSL.com的文档注册文档签名证书订单 电子签名者 服务并使用Cloud Signature Consortium(CSC)API对文档哈希和PDF文件进行数字签名。 您可以将本指南与 卷曲 or 邮差。 我们建议Postman用户安装 桌面应用 通过示例工作。

本指南中的示例使用 SSL.com 的生产 eSigner 和 eSealing 环境。 如果您想在使用真实的证书订单之前在SSL.com的沙盒测试环境中尝试使用CSC API,请阅读 使用eSigner CSC API测试远程签名的集成指南. 如果您想使用演示帐户和证书尝试 eSigner Sandbox,请阅读 eSigner 演示凭据和证书 获取凭据和配置信息。

要遵循这些说明,您将需要:

  • 经过验证的文档签名证书订单。 请阅读 这个方法 有关订购和验证的完整说明。
  • A 客户ID (也称为 应用程序ID。 Please refer to请参阅 这个方法 有关生成此证书的说明)。

注册eSigner并设置两因素身份验证

  1. 在开始使用CSC API之前,您需要注册eSigner。 导航到 我的订单 标签进入您的SSL.com帐户,然后找到您的订单。
    找到订单
  2. 点击订单的 详情 链接。
    详情
  3. 创建一个并确认4位PIN码,然后点击 创建PIN码 按钮。
    如果您需要重设eSigner PIN,请阅读 这个方法.
    创建PIN码
  4. 将会出现QR码。
    下次重新加载页面时,QR码将不可见。 如果您需要查看或重置您的eSigner QR码,请阅读 这个方法.
    二维码
  5. 将代码扫描到移动设备上的2因子身份验证应用程序中,例如 谷歌身份验证 or Authy。 该应用程序将为您提供一次性密码(OTP),供您在签名时使用。 每个OTP有效期为30秒。
    Authy中的OTP
提示: 您可以使用eSigner在队友之间共享经过组织验证(OV)的签名证书。 请阅读 eSigner文档和EV代码签名证书的团队共享 作为指示。

安装Postman和导入API集合

本节中的说明仅适用于Postman用户。 如果将cURL与CSC API结合使用,则可以进入下一部分。

  1. 下载并解压缩 CSC API邮递员收藏文档签名API邮递员集合 (见 https://www.postman.com/sslcom 用于在线 SSL.com API 集合)。
    邮差收藏
  2. 下载并安装 邮递员REST客户端.
    邮递员REST客户端下载
  3. 启动Postman,然后创建一个新的Postman帐户或登录到现有的帐户。
    邮递员登录
  4. 点击 进口 按钮。
    导入按钮
  5. 点击 上传文件 按钮,导航到未压缩的API集合文件(csc-api-prod.postman_collection.jsondocument-signing-api-prod.postman_collection.json),然后打开它们。
    上传文件
  6. 点击 进口 按钮。
    点击导入按钮
  7. 您将使用的API请求现在可以在 精品系列 邮递员窗口左侧的标签。
    API请求

检索访问令牌

下一步是从SSL.com检索访问令牌。 你需要你的 客户ID 可用,以及SSL.com帐户的用户名和密码。 访问令牌在发出后一小时内有效。

使用下面的可点击标签来选择Postman或cURL的说明:

邮递员说明cURL说明
  1. 从CSC API集合中选择一个API请求。
    选择API请求
  2. 点击 授权 选项​​卡,并选择 身份验证 2.0 来自 类型 菜单。
    授权标签
  3. 在表单中输入以下信息:
    • 标头前缀: Bearer
    • 令牌名称: SSLCOM CSC (或您喜欢的其他易于记忆的名称)
    • 赠款类型: Authorization Code
    • 回调网址: https://upload.esigner.com
    • 使用浏览器授权: 选中
    • 验证网址: https://login.ssl.com/oauth2/authorize
    • 访问令牌URL: https://login.ssl.com/oauth2/token
    • 客户编号: [您的客户编号]
    • 客户机密: [您的客户秘密]
    • 范围: service
    • 省(自治区,直辖市,州): [留着空白]
    • 客户端身份验证: Send as Basic Auth header

    完成后,单击 获取新的访问令牌 按钮。
    获取新的访问令牌

  4. 将出现一个登录表格。 输入您的SSL.com用户名和密码,然后单击 会员登录 按钮。
    帐号登录
  5. 您的新访问令牌应出现在Postman中。 选择访问令牌文本并将其复制到剪贴板,然后关闭 管理访问令牌 对话框。 将您的访问令牌粘贴到文本编辑器中,您可以在其中轻松访问它。 每个访问令牌将在一个小时后过期。
    您还可以保存令牌以在Postman请求中重复使用,但是我们发现将令牌直接复制并粘贴到每个请求中最可靠。
    访问令牌
  1. 使用以下命令来请求访问令牌。 用您的实际值替换ALL-CAPS中显示的值:
    curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{
     "client_id" : "你的客户 ID",
    "client_secret" : "你的客户秘密",
    “grant_type”:“密码”,
     “用户名”:“您的用户名”,
     “密码”:“您的密码”
    }'
  2. 您应该收到一个包含访问令牌和刷新令牌的JSON对象。 复制访问令牌值以粘贴到您的API请求中。 这些示例不需要刷新令牌。
    检索访问令牌

签署哈希

有了访问令牌后,就可以开始发出API请求和创建签名了。 本节将引导您完成Postman CSC集合中的五个可用请求,从而从文档哈希中创建数字签名。

获取CSC信息(可选)

邮递员说明cURL说明
  1. 您可以使用 CSC资讯 请求获取有关SSL.com的云签名服务的信息。 请注意,与集合中的其他集合不同,此请求不需要您的访问令牌。 要发送请求,请选择 CSC资讯 来自 CSC API 集合,然后单击 发送 按钮。
    发送CSC信息请求
  2. 有关云签名服务的信息将显示在Postman的JSON对象中 响应 领域。
    CSC资讯
  1. 使用以下命令获取有关SSL.com的CSC API服务的信息:
    curl --location --request POST“ https://cs.ssl.com/csc/v0/info” \ --header“内容类型:application / json” \ --data-raw“ {}”
  2. 您将收到一个JSON对象,其中包含有关服务的详细信息:
    获取CSC信息

CSC凭证列表

CSZ  CSC凭证列表 请求将检索您将在以后的API请求中使用的凭据。

邮递员说明cURL说明
  1. 选择 CSC凭证列表 并单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 类型 菜单,将您的访问令牌粘贴到 代币 字段,然后单击 发送 按钮。
    发送凭据列表请求
  3. 带有与用户相关联的凭据ID列表的JSON对象将出现在 响应 领域。 您的列表可能包含一个值。 将您的凭据ID复制并粘贴到文本编辑器中,以用于以后的请求。
    凭证ID
  1. 输入以下命令。 (将MY-ACCESS-TOKEN替换为您的实际访问令牌):
    curl --location --request POST“ https://cs.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.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-访问令牌" \ --data-raw '{"clientData": "DS_ESEAL"}'
  2. 您应该收到一个JSON对象,其中包含与用户相关联的凭据ID列表。 您的列表可能包含一个值。 将您的凭据ID复制并粘贴到文本编辑器中,以用于以后的请求。
    凭证ID

CSC凭证信息(可选)

CSZ CSC凭证信息 请求将返回证书和与凭据ID相关的其他信息,并且不需要签名。

邮递员说明cURL说明
  1. 要使用此请求,请选择 CSC凭证信息 从集合中,然后单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 类型 菜单,然后将您的访问令牌粘贴到 代币 领域。
    粘贴令牌
  3. 点击 琴体 标签,然后将您的凭据ID粘贴为 credentialID.
    粘贴凭证ID
  4. 点击 发送 按钮。
    发送
  5. 带有您的签名证书链和其他信息的JSON对象将显示在 响应 领域。
    凭证信息
  1. 输入以下命令。 代替 MY-ACCESS-TOKENMY-CREDENTIAL-ID 使用您的实际信息:
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }'
  2. 您应该收到带有签名证书链和其他信息的JSON对象:
    CSC凭证信息

凭证授权

CSZ 凭证授权 请求将检索用于签名哈希的授权。

邮递员说明cURL说明
  1. 首先选择 凭证授权 从集合中,然后单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 类型 菜单,然后将您的访问令牌粘贴到 代币 领域。
    粘贴令牌
  3. 点击 琴体 标签。 将您的凭据ID粘贴为 credentialID 值和您希望作为文档签名的文档的哈希值 hash 值。 从身份验证应用程序检索并输入OTP,然后将其输入为 OTP,然后点击 发送 按钮。 注意:密封证书不需要 OTP。
    身体标签
  4. 带有您的签名激活数据(SAD)的JSON对象将出现在 响应 领域。 复制此值并将其粘贴到文本编辑器中,以用于哈希签名请求。
    悲伤
  1. 使用以下命令。 代替 MY-ACCESS-TOKEN, MY-CREDENTIAL-IDMY-HASH 与您的实际信息。 从您的2FA应用程序中获得一次性密码,并使用作为该密码的值 MY-OTP. 注意:密封证书不需要 OTP。
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP " }'
  2. 您应该收到带有签名激活数据(SAD)的JSON对象。 复制此值并将其粘贴到文本编辑器中,以用于哈希签名请求。
    凭证授权

签名哈希

现在您准备对文档哈希签名。

邮递员说明cURL说明
  1. 选择 签名哈希 从集合中,然后选择 授权 标签。
    授权标签
  2. 不记名令牌 来自 类型 菜单,然后将您的访问令牌粘贴到 代币 领域。
    粘贴令牌
  3. 点击 琴体 标签。 将您的凭据ID粘贴为 credentialID 值,您的签名激活数据作为 SAD 值,以及您希望作为文档签名的文档的哈希值 hash 值,然后单击 发送 按钮。
    身体标签
  4. 带有您签名的JSON对象将出现在 响应 领域。
    签名
  1. 输入以下命令。 代替 MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-SADMY-HASH 使用您的实际信息:
    curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": ["MY-HASH"], "signAlgo": “1.2.840.113549.1.1.11”}'
  2. 您应该收到一个包含签名的JSON对象。
    签名哈希

签署PDF

除了签署文档哈希之外,您还可以上传和签署PDF文件。

在签署PDF时,您将处理两个POST请求:

  • 上载PDF文件
  • 签署PDF文件

文档签名API集合

您可以将上面使用的凭证重新使用 CSC凭证列表 请求。 您可能还需要检索一个新的 访问令牌.

上载PDF文件

邮递员说明cURL说明
  1. 点击 上载PDF文件 请求并单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 类型 菜单,然后将您的访问令牌粘贴到 代币 领域。
    粘贴令牌
  3. 点击 标签,然后将您的凭据ID粘贴到 列。
    标题标签
  4. 点击 琴体 选项卡并单击 × 旁边 hello.pdf 删除此占位符文件名。
    删除示例文件名
  5. 点击 选择文件 按钮,然后导航到您要上传的文件。
    选择文件
  6. 点击 发送 按钮。
    发送
  7. 选择并复制 id 要在下一个请求中使用的响应中的值。
    ID
  1. 使用以下命令。 代替 MY-CREDENTIAL-ID, MY-ACCESS-TOKEN/PATH/TO/FILE.pdf 使用您的实际信息:
    curl --location --request POST“ https://ds.ssl.com/v1/pdf/upload” \ --header“凭据ID:MY-CREDENTIAL-ID” \ --header“授权:Bearer MY- ACCESS-TOKEN“ \ --header”内容类型:application / pdf“ \ --data-binary” @ / PATH / TO / FILE.pdf“
  2. 您将收到一个JSON对象,其值为 id。 复制此值以在下一个请求中使用。
    上传PDF

注意:对于可见的签名,请参考以下 HTTP 请求标头(/v1/pdf/upload):

请求头

描述

凭据 ID

分配给密钥的唯一凭据 ID – 必需

签约理由

添加签名原因以添加签名外观和签名字典 - 可选,例如我批准此文档

签约地点

在签名字典中添加签名位置 - 可选,例如德克萨斯州休斯顿

联系方式

在签名字典中添加联系信息 - 可选,例如电话号码

签名字段位置

显示视觉签名的签名字段位置。 格式是 “x,y,宽度,高度“ - 可选的

页码

页码在哪里绘制签名 - 可选

手签

手签名的 Base64 编码 PNG 图像 - 可选


签署PDF文件

现在您可以签署PDF。

使用密封文件签名证书进行签名时不需要 OTP 授权。 如果使用密封文件签名证书,请忽略以下指南中的所有 OTP 参数。
邮递员说明cURL说明
  1. 点击 上载PDF文件 请求并单击 授权 标签。
       授权
  2. 不记名令牌 来自 类型 菜单,然后将您的访问令牌粘贴到 代币 领域。
    粘贴令牌
  3. 选择“身体”标签,然后粘贴到 id 上一步中的值和身份验证应用中的OTP,然后单击 发送 按钮。
    发送请求
  4. PDF数据将显示在下方 响应 领域。 选择 保存到文件 来自 保存回复 菜单,然后为文件命名。
    将PDF保存到文件
  5. 在Acrobat中打开文件以确认文件已签名。
    有效签名
  1. 输入以下命令。 代替 MY-CREDENTIAL-ID, MY-FILE-IDOUTPUT-FILENAME 与您的实际信息。 从您的2FA应用中获取一次性密码(OTP)并输入为 MY-OTP. 注意:密封证书不需要 OTP:
    curl --location --request POST'https://ds.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”}'\- -输出OUTPUT-FILENAME
  2. cURL将下载已签名的文件并将其保存到您指定的文件名中:
    签名PDF
  3. 在Acrobat或Acrobat Reader中打开PDF以检查签名是否有效。
    有效签名

分享到Twitter
Twitter
在Facebook上分享
Facebook
分享到LinkedIn
LinkedIn
分享Reddit上
Reddit
分享电子邮件
电子邮箱