README

使用 PHP 编写的官方库，用于使用 Stiply API。

目录

• 需求
• 安装
• 使用
  • 配置
  • 身份验证
  • 可用方法
• 示例
• 测试

需求

• PHP >= 7.2.0

安装

此库可通过 Composer 获取

composer require stiply/stiply-php-sdk

使用

此库的主要目的是简化与 Stiply API 的交互。设置 HTTP 客户端和执行请求的任务由 SDK 处理。相反，您只需调用 \Stiply\Api 实例上的专用方法即可获取所需响应。快速示例

<?php

$tokens = new \My\Custom\TokenRepository();

$api = \Stiply\Api::create($tokens);

// Returns an instance of \Stiply\Ping
$result = $api->ping(['ping_value' => 'pong']);

echo $result['ping_value'];  // Or "$result->ping_value"
echo $result['status_code'];

如你所见，在成功的情况下，将返回一个数据对象，其中包含来自 Stiply API 的响应体作为其属性。

配置

默认情况下，\Stiply\Api 实例配置为使用 Stiply API 的 v1.1 版本，该版本需要 OAuth2 进行身份验证/授权。但是，如果您想针对另一个 API 版本和身份验证/授权方式，可以通过 \Stiply\Config\Config 的单例实例来更改此设置。

<?php

// We want to target the "v1" version of the Stiply API instead
$config = \Stiply\Config\Config::getInstance();

$config->set('version', 'v1');
$config->set('auth', 'basic');

$tokens = new \My\Custom\TokenRepository();

$api = \Stiply\Api::create($tokens);

// Use "$api" to interact with the Stiply API

这里有一些需要注意的事项

1. $config 变量指向 \Stiply\Config\Config 的单例实例。在任何时候都应只存在一个配置对象，因为它由 SDK 本身以及可能由 SDK 的用户使用来自定义一些可配置选项（例如 API 版本和身份验证方法）。
2. 建议在创建新的 \Stiply\Api 实例之前自定义任何配置选项，因为一些配置选项（例如 "guzzle"、"base_url"）仅在创建新的 \Stiply\Api 实例时才会被认可。
3. SDK 在内部使用 Guzzle 来执行所有 HTTP 请求。因此，可以在创建客户端时自定义一些特定的 Guzzle 请求选项。但这很少是必要的，并且应小心覆盖 SDK 本身设置的任何选项（例如 "base_uri"）。

> 重要：如果您使用 SDK 并且遇到消息为 "cURL 错误 60：SSL 证书问题：无法获取本地颁发者证书..." 的 \Stiply\Exceptions\StiplyException，则可能是您的服务器 SSL 证书有问题或完全缺失。如果您在本地测试 SDK 并且不想被此错误打扰，可以像这样更新 "guzzle" 配置选项：$config->set('guzzle', ['verify' => false])。这将禁用 SSL 证书验证。然而，这是不安全的，我们不推荐这样做。

身份验证

SDK 故意不关心与 Stiply API 连接的身份验证/授权部分。因此，实现合适的身份验证/授权策略是 SDK 用户的唯一责任。这里采取的方法是向 \Stiply\Api 实例提供一个实现 \Stiply\Contracts\Auth\TokenRepository 的实例。此实现应通过 \My\Custom\TokenRepository#token 方法返回有效的身份验证令牌。

<?php

namespace My\Custom;

use Stiply\Contracts\Auth\TokenRepository as TokenRepositoryContract;

class TokenRepository implements TokenRepositoryContract
{
    /**
     * Return a Stiply compatible auth token.
     *
     * @return string
     */
    public function token() : string
    {
        // Your custom logic for generating a suitable auth token for use with
        // the Stiply API. In case of API version "v1.1" this would mean
        // providing a valid (personal) access token using OAuth, in case of API
        // version "v1" this would mean the base64 encoded combination of
        // "username:password"

        return $token;
    }
}

然后应在创建新的 \Stiply\Api 实例时提供您自定义的令牌存储库实例。

<?php

$tokens = new \My\Custom\TokenRepository();

$api = \Stiply\Api::create($tokens);

// Use "$api" to interact with the Stiply API

然后，每次SDK向Stiply API发出请求时，都会负责构造适当的授权头。

重要：如果您想自定义默认的授权配置，请确保指定的“版本”和“授权”选项兼容。例如，Stiply API的“v1”版本只能与“basic”授权（或某些合作伙伴的“jwt”）配合使用，而“v1.1”版本只能与“oauth”授权配合使用。如果SDK检测到版本/授权选项不匹配，将抛出一个\Stiply\Exceptions\AuthException实例。

可用方法

当前所有API端点都在SDK的以下相应方法中表示：

$result = $api->ping($parameters);

ping Stiply API。如果成功，$result将是一个包含Stiply API响应体的\Stiply\Ping实例的属性。$parameters是一个包含以下键/值对的数组

$result = $api->createSignRequest($parameters);

创建一个新的签名请求。如果成功，$result将是一个包含Stiply API响应体的\Stiply\CreateSignRequest实例的属性。$parameters是一个包含以下键/值对的数组

$result = $api->createSigner($signRequest, $parameters);

为给定的签名请求创建一个新的签署者。

先决条件

• 签名请求必须存在
• 签名请求尚未发送

如果成功，$result将是一个包含Stiply API响应体的\Stiply\CreateSigner实例的属性。$signRequest是一个表示签名请求键的字符串。$parameters是一个包含以下键/值对的数组

$result = $api->sendSignRequest($signRequest);

发送指定的签署请求。

先决条件

• 签名请求必须存在
• 签名请求尚未发送
• 签署请求至少有 1 个签名人且至少有 1 个签名字段

成功时，$result 将是 \Stiply\SendSignRequest 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签署请求的键。

$result = $api->getSignedDocument($signRequest);

获取与给定签署请求关联的签署文档。

先决条件

• 签名请求必须存在
• 签署请求已被所有签名人签署

成功时，$result 将是 \Stiply\GetSignedDocument 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签署请求的键。

$result = $api->getProofDocument($signRequest);

获取与给定签署请求关联的证明文档。

先决条件

• 签名请求必须存在
• 签署请求已被所有签名人签署

成功时，$result 将是 \Stiply\GetProofDocument 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签署请求的键。

$result = $api->sendReminder($signRequest);

向给定签署请求的当前签名人发送提醒邮件。

先决条件

• 签名请求必须存在
• 签署请求已发送

成功时，$result 将是 \Stiply\SendReminder 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签署请求的键。

$result = $api->extendTerm($signRequest, $parameters);

延长给定签署请求的期限。

先决条件

• 签名请求必须存在
• 签署请求已发送
• 签署请求的当前期限已过期

成功时，$result 将是 \Stiply\ExtendTerm 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签署请求的键。 $parameters 是一个包含以下键/值对的数组

$result = $api->getSignRequestKey($key);

使用给定的外部键（您本地的键）获取签署请求键。

先决条件

• 签名请求必须存在

成功时，$result 将是 \Stiply\GetSignRequestKey 的一个实例，它将 Stiply API 的响应体作为其属性。 $key 是一个字符串，表示签署请求的外部键（您本地的键）。

$result = $api->getSignRequest($signRequest);

获取给定的签名请求。

先决条件

• 签名请求必须存在

成功时，$result 将是 \Stiply\GetSignRequest 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签名请求的键。

$result = $api->deleteSignRequest($signRequest);

删除给定的签名请求。

先决条件

• 签名请求必须存在

成功时，$result 将是 \Stiply\DeleteSignRequest 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签名请求的键。

$result = $api->getSigner($signRequest, $signer);

获取给定签名请求的给定签名人。

先决条件

• 签名请求必须存在
• 签名人必须存在

成功时，$result 将是 \Stiply\GetSigner 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签名请求的键。 $signer 是一个字符串，表示签名人键。

$result = $api->updateSigner($signRequest, $signer, $parameters);

更新尚未签名的签名人电子邮件地址和/或电话号码。在更新时需要同时提交这两个值。如果您只想更新其中一个，只需提交另一个的原始值。

请注意，如果签名人已经收到签名请求邮件，并且在之后更新了签名人电子邮件地址，签名人邮件中的链接将不再有效。签名人不会在新电子邮件地址上收到新的签名请求邮件。请使用 \Stiply\Api#sendReminder 在电子邮件地址更新后进行此操作。如果您只更新电话号码，原始签名链接仍然有效，因此不需要提醒。

先决条件

• 签名请求必须存在
• 签名人必须存在
• 签名人未签署

成功时，$result 将是 \Stiply\UpdateSigner 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签名请求的键。 $signer 是一个字符串，表示签名人键。 $parameters 是一个数组，包含以下键/值对

$result = $api->deleteSigner($signRequest, $signer);

删除给定的签名人。

先决条件

• 签名请求必须存在
• 签名请求尚未发送
• 签名人必须存在

成功时，$result 将是 \Stiply\DeleteSigner 的一个实例，它将 Stiply API 的响应体作为其属性。 $signRequest 是一个字符串，表示签名请求的键。 $signer 是一个字符串，表示签名人键。

示例

以下示例演示了如何使用 SDK 创建新的签名请求、添加签名人，并最终发送签名请求。

首先，我们将创建 \Stiply\Api 类的新实例，然后我们可以使用它来与 Stiply API 通信

<?php

$tokens = new \My\Custom\TokenRepository();

$api = \Stiply\Api::create($tokens);

接下来，我们将创建一个新的签名请求

<?php

// Previously discussed code is here

$result = $api->createSignRequest([
    'file' => \file_get_contents('/some/path/to/a/valid/document/foo.pdf'),
    'filename' => 'foo.pdf', // Without this uploading the doc will fail!
    'term' => '1w',
    'doc_name' => 'SDK Test',
    'comment' => 'Testing the SDK',
]);

$key = $result['data']['signRequest']['key'];

现在我们可以将一个签名人添加到新创建的签名请求中

<?php

// Previously discussed code is here

$result = $api->createSigner($key, [
    'signer_email' => 'signer@stiply.nl',
    'signer_signature_fields' => [['name' => 'signature_0']],
    'auth_method' => 'sms',
    'cell_phone_number' => 31612345678,
]);

重要 假设我们之前上传的文档 foo.pdf 包含一个或多个格式为 {{signature_0}} 的标签。

最后，我们可以将签名请求发送给第一个（在这种情况下是唯一的）签名人

<?php

// Previously discussed code is here

$result = $api->sendSignRequest($key);

这位签名人现在应该会收到一封包含链接的邮件，该链接指向我们的查看器应用程序，可以在其中数字签名上传的文档。

总结来说，创建新的签名请求、添加单个签署者和发送签名请求的完整代码可能看起来像这样

<?php

$tokens = new \My\Custom\TokenRepository();

$api = \Stiply\Api::create($tokens);

// Create a new sign request and upload the document to be signed
$result = $api->createSignRequest([
    'file' => \file_get_contents('/some/path/to/a/valid/document/foo.pdf'),
    'filename' => 'foo.pdf', // Without this uploading the doc will fail!
    'term' => '1w',
    'doc_name' => 'SDK Test',
    'comment' => 'Testing the SDK',
]);

// We will need the sign request key for the next steps
$key = $result['data']['signRequest']['key'];

// Create a new signer for the sign request referred to by "$key"
$result = $api->createSigner($key, [
    'signer_email' => 'signer@stiply.nl',
    'signer_signature_fields' => [['name' => 'signature_0']],
    'auth_method' => 'sms',
    'cell_phone_number' => 31612345678,
]);

// Send the sign request referred to by "$key"
$result = $api->sendSignRequest($key);

测试

可以模拟\Stiply\Api的一个实例。这可能在您自己的测试目的中很有用

<?php

$tokens = new \My\Custom\TokenRepository();

$handler = new \GuzzleHttp\Handler\MockHandler([
    new Response(200, [], \json_encode([...])),
]);

$api = \Stiply\Api::mock($tokens, $handler);

// Perform your own testing

还可以查看相关的Guzzle 文档。