README

一个用于与 BlueInk REST API 交互的 PHP 客户端。有关 API 的概述，请参阅 API v2 文档。

此客户端库在内部依赖于 guzzle 和 snorlax。

入门指南

use BlueInk\ApiClient\Client;

$client = new Client('<API_KEY_HERE>');

// Get a list of Bundles
$bundle_list = $client->bundles->list();

// $bundle_list is the parsed data from the response. To 
// get the actual response object, do:
$response = $client->bundles->getLastResponse();

// Retrieve a single Bundle
$bundle_id = $bundle_list[0]->id;
$bundle = $client->bundles->retrieve($bundle_id);

// Get a list of Templates
$template_list = $client->templates->list();

// Assume there was at least one Document Template setup in the account
$template_01 = $template_list[0];
// Save the $role for later, so we can map our signer to
// this role in the template.
$role = $template_01->roles[0];

// Setup data for a request to create a new Bundle,
// using an existing template.
$request_data = [
    'label' => 'A Test Bundle',
    'is_test' => true,
    'packets' => [
         {
             'name' => 'Peter Gibbons',
             'email' => 'peter.gibbons@example.com',
             'key' => 'signer-1',
         }
    ],
    'documents' => [
        'key' => 'doc-01',
        'template_id' => $template_01->id,
        'assignments' => [
            'role' => $role,
            'signer' => 'signer-01'
        ]
    ],
];
// Create and send a new Bundle. 
// Note that we pass the request data as 'json', which results in
// in the request body being sent as application/json data
$new_bundle = $client->bundles->create([ 'json' => $request_data ]);

错误处理和异常

如果在请求过程中遇到错误，则会抛出异常。这包括网络错误（连接超时、DNS 错误等）、服务器错误（5XX 状态码）和应用级别错误（4XX 状态码）。

请参阅 Guzzle 异常文档

所有异常都继承自 GuzzleHttp\Exception\TransferException。

您可以根据以下方式处理特定类别的错误

所有异常都在 GuzzleHttp\Exception 命名空间中。

• 4XX 错误：ClientException
• 5XX 错误：ServerException
• 网络错误：ConnectException
• 重定向过多：TooManyRedirectsException

或者捕获多个类别的异常

• BadResponseException：4XX 和 5XX
• RequestException：4XX、5XX 和网络错误
• TransferException：请求/响应过程中可能抛出的所有错误

通过捕获 RequestException 处理多个错误

try {
    $client->bundles->create($new_bundle_data);
} catch (RequestException $e) {
    // A 4XX, 5XX or networking error occured
    echo 'Got an exception';
    $response = $e->getResponse();
    echo "Status Code: " . $response->getStatusCode() . "\n";
    echo "Reason: " . $response->getReasonPhrase() . "\n";
    
    // Dump the error details, which are formatted
    // as described in the APIv2 documentation.
    var_export($response->getBody()->getContents());
}

单独处理不同类型的错误

try {
    $client->bundles->create($new_bundle_data);
} catch (ClientException $e) {
    // handle 4XX error
} catch (ServerException $e) {
    // handle 5xx error
} catch (RequestException $e) {
    // handle any other error
}

分页

返回数据列表的 API 操作（例如 /bundles/、/persons/）是分页的。

$bundles = $client->bundles->list();
$response = $client->bundles->getLastResponse();

代码约定

我们在此代码库中使用以下命名约定

• ClassName
• methodName
• propertyName
• function_name（用于全局函数）
• $variable_name
• CONSTANT_NAME（使用 define(...)) 创建）