README

esign-api-php 是一个 PHP 库，提供了一种方便的方式来与 Mekari eSign API 进行交互。它简化了将 eSign 功能集成到您的 PHP 应用程序中的过程。使用此 SDK，您可以轻松创建、管理和使用 eSign API 签署文档。

安装 SDK

运行以下命令来安装 SDK

composer require mekari/esign-api-php

初始化 EsignApiClient SDK

EsignApiClient 类是交互 eSign API 的主要入口点。以下是初始化它的方法

先决条件

在您初始化 EsignApiClient 之前，您需要以下内容

• 客户端 ID：这是您的 eSign API 客户端的 ID。
• 客户端密钥：这是您的 eSign API 客户端的密钥。
• 生产标志：这是一个布尔标志，表示您是否在使用生产环境。它是可选的，默认为 false。

初始化

要初始化 EsignApiClient，您需要创建一个 EsignApiClient 类的新实例，并将您的客户端 ID 和客户端密钥传递给构造函数。如果您正在使用生产环境，还应将 true 作为第三个参数传递。

以下是一个示例

<?php
$clientId = 'your-client-id';
$clientSecret = 'your-client-secret';
$production = true; // or false if you're not using the production environment

$client = new EsignApiPhp\EsignApiClient($clientId, $clientSecret, $production);
?>

下一步

在初始化 EsignApiClient 之后，您可以使用其方法与 eSign API 进行交互。例如，您可以使用 auth 方法获取 Auth 类的实例，该类提供了获取用户身份验证令牌和刷新令牌的方法

<?php
$auth = $client->auth();
?>

授权

获取身份验证令牌

getUserAuthToken 方法是 Auth 类的一部分。它用于从 eSign API 获取用户身份验证令牌。

参数

该方法接受一个参数

$code: The authorization code.

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 getUserAuthToken 方法的示例

<?php
$auth = $client->auth();
$code = 'your-authorization-code';

try {
    $data = $auth->getUserAuthToken($code);
    echo 'Access Token: ' . $data['access_token'];
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}
?>

获取刷新令牌

getRefreshToken 方法是 Auth 类的一部分。它用于使用刷新令牌从 eSign API 获取新的访问令牌。

参数

该方法接受一个参数

$refreshToken: The refresh token.

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 getRefreshToken 方法的示例

<?php
$auth = $client->auth();
$refreshToken = 'your-refresh-token';

try {
    $data = $auth->getRefreshToken($refreshToken);
    echo 'New Access Token: ' . $data['access_token'];
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}
?>

全局签名

请求全局签名

requestGlobalSign 方法是 GlobalSign 类的一部分。它用于请求 eSign API 的文档全局签名。

参数

该方法接受以下参数

• $doc：要签名的文档 (base64)。
• $filename：文件名。
• $signers：文档的签署者。
• $signing_order：是否有顺序签署。
• $callback_url：API 应将响应发送到的回调 URL。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 requestGlobalSign 方法的示例

<?php
$globalSign = $client->globalSign();
$doc = 'your-document';
$filename = 'your-filename';
$signers = ['signer1', 'signer2'];
$signing_order = true //optional, default false;
$callback_url = 'your-callback-url';
$token = 'your-token';

try {
    $data = $globalSign->requestGlobalSign($doc, $filename, $signers, $signing_order, $callback_url, $token);
    echo 'Document ID: ' . $data['id'];
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}
?>

PSRE 签名

请求 PSRE 签名

requestPsreSign 方法是 PsreSign 类的一部分。它用于请求 eSign API 的文档 PSRE 签名。

参数

该方法接受以下参数

• $doc：要签名的文档 (base64)。
• $filename：文件名。
• $signers：文档的签署者。
• $signing_order：是否有顺序签署。
• $callback_url：API 应将响应发送到的回调 URL。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 requestPsreSign 方法的示例

<?php
$globalSign = $client->psreSign();
$doc = 'your-document';
$filename = 'your-filename';
$signers = ['signer1', 'signer2'];
$signing_order = true //optional, default false;
$callback_url = 'your-callback-url';
$token = 'your-token';

try {
    $data = $globalSign->requestGlobalSign($doc, $filename, $signers, $signing_order, $callback_url, $token);
    echo 'Document ID: ' . $data['id'];
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}
?>

生成签名URL

generateSigningUrl 方法是 PsreSign 类的一部分。它用于从电子签名API生成文档的签名URL。

参数

该方法接受以下参数

• $documentId：文档的ID。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 generateSigningUrl 方法的示例

<?php
$psreSign = $client->psreSign();
$documentId = 'your-document-id';
$token = 'your-token';

try {
    $data = $psreSign->generateSigningUrl($documentId, $token);
    echo 'Document ID: ' . $data['id'];
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

盖章

盖章

stamp 方法是 Stamping 类的一部分。它用于使用电子签名API的注释在文档上盖章。

参数

该方法接受以下参数

• $doc：要盖章的文档。
• $filename：文件名。
• $annotation：要盖章在文档上的注释。
• $callback_url：API 应将响应发送到的回调 URL。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 stamp 方法的示例

$stamping = $client->stamping();
$doc = 'your-document';
$filename = 'your-filename';
$annotation = 'your-annotation';
$callback_url = 'your-callback-url';
$token = 'your-token';

try {
    $data = $stamping->stamp($doc, $filename, $annotation, $callback_url, $token);
    echo 'Document ID: ' . $data['id'];
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

文档

获取文档列表

getDocumentList 方法是 Document 类的一部分。它用于从电子签名API获取文档列表。

### 参数 该方法接受以下参数

• $page：页码。
• $limit：每页文档数量。
• $token：身份验证令牌。
• $category（可选）：文档的分类（global，psre）。
• $signing_status（可选）：文档的签名状态（in_progress，completed，voided，declined）。
• $stamping_status（可选）：文档的盖章状态（none，in_progress，pending，failed，success）。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 getDocumentList 方法的示例

$document = $client->document();
$page = 1;
$limit = 10;
$token = 'your-token';
$category = 'your-category';
$signing_status = 'your-signing-status';
$stamping_status = 'your-stamping-status';

try {
    $data = $document->getDocumentList($page, $limit, $token, $category, $signing_status, $stamping_status);
    echo 'Documents: ' . print_r($data, true);
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

获取文档详情

getDocumentDetail 方法是 Document 类的一部分。它用于从电子签名API获取特定文档的详细信息。

参数

该方法接受以下参数

• $documentId：文档的ID。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是使用 getDocumentDetail 方法的示例

$document = $client->document();
$documentId = 'your-document-id';
$token = 'your-token';

try {
    $data = $document->getDocumentDetail($documentId, $token);
    echo 'Document Details: ' . print_r($data, true);
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

下载文档

downloadDocument 方法是 Document 类的一部分。它用于从电子签名API下载特定文档。

参数

该方法接受以下参数

• $documentId：文档的ID。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回下载的文档。如果请求失败，它将抛出一个包含错误信息的异常。

用法

以下是使用 downloadDocument 方法的示例

$document = $client->document();
$documentId = 'your-document-id';
$token = 'your-token';

try {
    $data = $document->downloadDocument($documentId, $token);
    file_put_contents($documentId . '.pdf', $data);
    echo 'Document downloaded successfully.';
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

重发文档

resendDocument 方法是 Document 类的一部分。它用于从电子签名API重发特定文档。

参数

该方法接受以下参数

• $documentId：文档的ID。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回API的响应数据。如果请求失败，它将抛出一个包含错误信息的异常。

用法

以下是使用 resendDocument 方法的示例

$document = $client->document();
$documentId = 'your-document-id';
$token = 'your-token';

try {
    $data = $document->resendDocument($documentId, $token);
    echo 'Document resent successfully.';
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

作废文档

voidDocument 方法是 Document 类的一部分。它用于在电子签名API中作废特定文档。

参数

该方法接受以下参数

• $documentId：文档的ID。
• $token：身份验证令牌。
• $reason：作废文档的原因。

返回值

如果请求成功，该方法返回API的响应数据。如果请求失败，它将抛出一个包含错误信息的异常。

用法

以下是使用 voidDocument 方法的示例

$document = $client->document();
$documentId = 'your-document-id';
$token = 'your-token';
$reason = 'your-reason';

try {
    $data = $document->voidDocument($documentId, $token, $reason);
    echo 'Document voided successfully.';
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

删除文档

deleteDocument 方法是 Document 类的一部分。它用于从电子签名API删除特定文档。

参数

该方法接受以下参数

• $documentId：文档的ID。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回API的响应数据。如果请求失败，它将抛出一个包含错误信息的异常。

用法

以下是使用 deleteDocument 方法的示例

$document = $client->document();
$documentId = 'your-document-id';
$token = 'your-token';

try {
    $data = $document->deleteDocument($documentId, $token);
    echo 'Document deleted successfully.';
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

自动签名

创建自动签名

createAutoSign 方法是 AutoSign 类的一部分。它用于在电子签名API中创建自动签名请求。

参数

该方法接受以下参数

• $docMakerEmails：文档创建者邮箱数组。
• $signerEmails：签名者邮箱数组。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回API的响应数据。如果请求失败，它将抛出一个包含错误信息的异常。

用法

以下是使用 createAutoSign 方法的示例

$autoSign = $client->autoSign();
$docMakerEmails = ['docmaker1@example.com', 'docmaker2@example.com'];
$signerEmails = ['signer1@example.com', 'signer2@example.com'];
$token = 'your-token';

try {
    $data = $autoSign->createAutoSign($docMakerEmails, $signerEmails, $token);
    echo 'AutoSign created successfully.';
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

更新自动签名

updateAutoSign 方法是 AutoSign 类的一部分。它用于在电子签名API中更新自动签名请求。

参数

该方法接受以下参数

• $id：自动签名请求的ID。
• $docMakerEmail：文档创建者的邮箱。
• $signerEmail：签名者的邮箱。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回API的响应数据。如果请求失败，它将抛出一个包含错误信息的异常。

用法

以下是使用 updateAutoSign 方法的示例

$autoSign = $client->autoSign();
$id = 'your-autosign-id';
$docMakerEmail = 'docmaker@example.com';
$signerEmail = 'signer@example.com';
$token = 'your-token';

try {
    $data = $autoSign->updateAutoSign($id, $docMakerEmail, $signerEmail, $token);
    echo 'AutoSign updated successfully.';
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

删除自动签名

deleteAutoSign 方法是 AutoSign 类的一部分。它用于在电子签名API中删除自动签名请求。

参数

该方法接受以下参数

• $id：自动签名请求的ID。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回 true。如果请求失败，它将抛出一个包含错误信息的异常。

用法

以下是使用 deleteAutoSign 方法的示例

$autoSign = $client->autoSign();
$id = 'your-autosign-id';
$token = 'your-token';

try {
    $result = $autoSign->deleteAutoSign($id, $token);
    if ($result) {
        echo 'AutoSign deleted successfully.';
    }
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

自动签名详情

detailAutoSign 方法是 AutoSign 类的一部分。它用于从电子签名 API 获取自动签名请求的详细信息。

参数

该方法接受以下参数

• $id：自动签名请求的ID。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是如何使用 detailAutoSign 方法的示例

$autoSign = $client->autoSign();
$id = 'your-autosign-id';
$token = 'your-token';

try {
    $data = $autoSign->detailAutoSign($id, $token);
    echo 'AutoSign Details: ' . print_r($data, true);
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

自动签名列表

listAutoSign 方法是 AutoSign 类的一部分。它用于从电子签名 API 获取自动签名请求的列表。

参数

该方法接受以下参数

• $docMakerEmail：文档创建者的邮箱。
• $signerEmail：签名者的邮箱。
• $page：页码。
• $limit：每页的项目数量。
• $token：身份验证令牌。

返回值

如果请求成功，该方法返回包含 API 响应数据的关联数组。如果请求失败，则抛出一个包含错误消息的异常。

用法

以下是如何使用 listAutoSign 方法的示例

$autoSign = $client->autoSign();
$docMakerEmail = 'docmaker@example.com';
$signerEmail = 'signer@example.com';
$page = 1;
$limit = 10;
$token = 'your-token';

try {
    $data = $autoSign->listAutoSign($docMakerEmail, $signerEmail, $page, $limit, $token);
    echo 'AutoSign List: ' . print_r($data, true);
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}