通过 
搜索
搜索landrok / yousign-api
PHP 实现的 YouSign API。
1.4.0
2023-12-20 18:57 UTC
Requires
- php: ^7.4 || ^8.0
- guzzlehttp/guzzle: ^7.8
Requires (Dev)
- phpstan/phpstan: ^0.12.23
- phpunit/phpunit: *
README
Yousign API 客户端是 PHP 中 Yousign API v2 的包装器。
它的目的是使用此 API 而无需自己编写 HTTP 调用，并通过对象模型检索返回的数据。
如果您仍然想通过 HTTP 调用来检查 API 响应，这可以通过低级调用实现。
它提供了几个 API 包装器和快捷方法。
所有 API 调用都包装在对象模型中。所有功能都已实现，它旨在成为一个功能齐全的客户端。
所有后续类型（成员、流程、文件等）也已实现。
查看完整文档 或以下概述。
目录
要求
- PHP 7.4+
- 在使用此库之前，您必须创建 Yousign 平台上的账户并获取 API 令牌。
安装
composer require landrok/yousign-api
快速入门
在此示例中，我们将以预览模式获取所有用户。
use Yousign\YousignApi; /* * token */ $token = '123456789'; $yousign = new YousignApi($token); $users = $yousign->getUsers();
好消息，您的令牌可用。
响应和数据
所有 API 响应都转换为对象，当它是集合（即用户列表）或项（用户本身）时，它是可迭代的。
转储数据
您可以使用 toArray() 方法将所有数据转储为 PHP 数组。
print_r( $users->toArray() );
遍历列表
您可以遍历集合中的所有项。
foreach ($users as $user) { /* * For each User model, some methods are available */ // toArray(): to get all property values print_r($user->toArray()); // get + property name echo PHP_EOL . "User.id=" . $user->getId(); // property (read-only) echo PHP_EOL . "User.id=" . $user->id; // Some properties are models that you can use the same way echo PHP_EOL . "User.Group.id=" . $user->getGroup()->getId(); echo PHP_EOL . "User.Group.id=" . $user->group->id; // Some properties are collections that you can iterate foreach ($user->group->permissions as $index => $permission) { echo PHP_EOL . "User.Group.Permission.name=" . $permission->getName(); } // At any level, you can call a toArray() to dump the current model // and its children echo PHP_EOL . "User.Group=\n"; print_r($user->group->toArray()); echo PHP_EOL . "User.Group.Permissions=\n"; print_r($user->group->permissions->toArray()); }
基本模式
让我们以基本模式创建您的第一个签名流程。
在此示例中，我们将使用低级功能完成此模式。
use Yousign\YousignApi; /* * Token */ $token = '123456789'; /* * Production mode */ $production = false; /* * Instanciate API wrapper */ $yousign = new YousignApi($token, $production); /* * 1st step : send a file */ $file = $yousign->postFile([ 'name' => 'My filename.pdf', 'content' => base64_encode( file_get_contents( dirname(__DIR__, 2) . '/tests/samples/test-file-1.pdf' ) ) ]); /* * 2nd step : create the procedure */ $procedure = $yousign->postProcedure([ "name" => "My first procedure", "description" => "Awesome! Here is the description of my first procedure", "members" => [ [ "firstname" => "John", "lastname" => "Doe", "email" => "john.doe@yousign.fr", "phone" => "+33612345678", "fileObjects" => [ [ "file" => $file->getId(), "page" => 2, "position" => "230,499,464,589", "mention" => "Read and approved", "mention2" => "Signed by John Doe" ] ] ] ] ]); // toJson() supports all PHP json_encode flags echo $procedure->toJson(JSON_PRETTY_PRINT);
当流程创建时，您可以使用获取器检索所有数据，或使用 toJson() 和 toArray() 方法转储所有数据。
它将输出类似以下内容
{
"id": "\/procedures\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name": "My first procedure",
"description": "Awesome! Here is the description of my first procedure",
"createdAt": "2018-12-01T11:49:11+01:00",
"updatedAt": "2018-12-01T11:49:11+01:00",
"finishedAt": null,
"expiresAt": null,
"status": "active",
"creator": null,
"creatorFirstName": null,
"creatorLastName": null,
"workspace": "\/workspaces\/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"template": false,
"ordered": false,
"parent": null,
"metadata": [],
"config": [],
"members": [
{
"id": "\/members\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"user": null,
"type": "signer",
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@yousign.fr",
"phone": "+33612345678",
"position": 1,
"createdAt": "2018-12-01T11:49:11+01:00",
"updatedAt": "2018-12-01T11:49:11+01:00",
"finishedAt": null,
"status": "pending",
"fileObjects": [
{
"id": "\/file_objects\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"file": {
"id": "\/files\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name": "The best name for my file.pdf",
"type": "signable",
"contentType": "application\/pdf",
"description": null,
"createdAt": "2018-12-01T11:36:20+01:00",
"updatedAt": "2018-12-01T11:49:11+01:00",
"sha256": "bb57ae2b2ca6ad0133a699350d1a6f6c8cdfde3cf872cf526585d306e4675cc2",
"metadata": [],
"workspace": "\/workspaces\/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"creator": null,
"protected": false,
"position": 0,
"parent": null
},
"page": 2,
"position": "230,499,464,589",
"fieldName": null,
"mention": "Read and approved",
"mention2": "Signed by John Doe",
"createdAt": "2018-12-01T11:49:11+01:00",
"updatedAt": "2018-12-01T11:49:11+01:00",
"parent": null,
"reason": "Signed by Yousign"
}
],
"comment": null,
"notificationsEmail": [],
"operationLevel": "custom",
"operationCustomModes": [
"sms"
],
"operationModeSmsConfig": null,
"parent": null
}
],
"subscribers": [],
"files": [
{
"id": "\/files\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name": "My filename.pdf",
"type": "signable",
"contentType": "application\/pdf",
"description": null,
"createdAt": "2018-12-01T11:36:20+01:00",
"updatedAt": "2018-12-01T11:49:11+01:00",
"sha256": "bb57ae2b2ca6ad0133a699350d1a6f6c8cdfde3cf872cf526585d306e4675cc2",
"metadata": [],
"workspace": "\/workspaces\/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"creator": null,
"protected": false,
"position": 0,
"parent": null
}
],
"relatedFilesEnable": false,
"archive": false,
"archiveMetadata": [],
"fields": [],
"permissions": []
}
高级模式
以下是使用高级模式创建流程的 5 个步骤。
use Yousign\YousignApi; /* * Token */ $token = '123456789'; /* * Production mode */ $production = false; /* * Instanciate API wrapper */ $yousign = new YousignApi($token, $production); /* * Step 1 - Create your procedure */ $procedure = $yousign->postProcedure([ "name" => "My first procedure", "description" => "Description of my procedure with advanced mode", "start" => false, ]); /* * Step 2 - Add the files */ $file = $yousign->postFile([ 'name' => 'Name of my signable file.pdf', 'content' => base64_encode( file_get_contents( dirname(__DIR__, 2) . '/tests/samples/test-file-1.pdf' ) ), 'procedure' => $procedure->getId(), ]); /* * Step 3 - Add the members */ $member = $yousign->postMember([ "firstname" => "John", "lastname" => "Doe", "email" => "john.doe@yousign.fr", "phone" => "+33612345678", "procedure" => $procedure->getId(), ]); /* * Step 4 - Add the signature images */ $fileObject = $yousign->postFileObject([ "file" => $file->getId(), "member" => $member->getId(), "position" => "230,499,464,589", "page" => 2, "mention" => "Read and approved", "mention2" => "Signed By John Doe" ]); /* * Step 5 - Start the procedure */ $procedure = $yousign->putProcedure( $procedure->getId(), [ "start" => true, ] ); echo $procedure->toJson(JSON_PRETTY_PRINT);
在步骤 3 中，您可能需要添加多个成员。
在步骤 4 中，您可能需要为每个成员添加一个或多个签名图像。
使用签名 UI 品牌化
默认情况下，Signature-UI 具有Yousign主题（徽标、颜色等），但您可以从应用管理菜单中的Signature-UI视图自定义嵌入在iFrame中的签名流程，或者使用特定资源 /signature_uis 完全自定义此iFrame。
use Yousign\YousignApi; /* * Token */ $token = '123456789'; /* * Production mode */ $production = false; /* * Instanciate API wrapper */ $yousign = new YousignApi($token, $production); /* * Create your customized UI */ $ui = $yousign->postSignatureUi([ "name" => "My first template for Signature-UI", "description" => "Here is the Signature-UI template for Yousign Developers.", "defaultZoom" => 100, "logo" => "data:image/png;base64,iVBORw0K [...] XIwU3i6foIAAAAAElFTkSuQmCC", "languages" => ["fr", "en"], "defaultLanguage" => "en", "labels" => [ [ "name" => "NAME OF THE LABEL", "languages" => [ "en" => "Label en", "fr" => "Label fr" ], "creator" => null, ] ], "signImageTypesAvailable" => [ "name", "draw", ], "enableHeaderBar" => true, "enableHeaderBarSignAs" => true, "enableSidebar" => true, "enableMemberList" => true, "enableDocumentList" => true, "enableDocumentDownload" => true, "enableActivities" => false, "authenticationPopup" => false, "enableRefuseComment" => true, "fonts" => ["Roboto", "Lato"], "creator" => null, "redirectCancel" => [ "url" => "https://example.com?cancel=1", "target" => "_top", "auto" => false ], "redirectError" => [ "url" => "https://example.com?error=1", "target" => "_blank", "auto" => true ], "redirectSuccess" => [ "url" => "https://example.com?success=1", "target" => "_parent", "auto" => true ], "style" => " .sign-ui-header-bar { background-color: #00f } .sign-ui-headerbar-signas { background-color: #f00 } .sign-ui-headerbar-signas--primary { background-color: #f00 } .sign-ui-tab-item { color: #000 } .sign-ui-tab-item--current { background-color: #0f0; color: #fff } " ]);
在以下响应中，您将获取一个id，这对于创建您的iFrame非常有用。
[
"id" => "/signature_uis/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name" => "My first template for Signature-UI",
"description" => "Here is the Signature-UI template for Yousign Developers.",
"enableHeaderBar" => true,
"enableHeaderBarSignAs" => true,
"enableSidebar" => true,
"enableMemberList" => true,
"enableDocumentList" => true,
"enableDocumentDownload" => true,
"enableActivities" => true,
"authenticationPopup" => true,
"enableRefuseComment" => true,
"defaultZoom" => 100,
"logo" => "data:image/png;base64,iVBORw0K [...] XIwU3i6foIAAAAAElFTkSuQmCC",
"defaultLanguage" => "en",
"signImageTypesAvailable" => [
"name",
"draw"
],
"languages" => [
"fr",
"en",
"es",
"de",
"it",
"pt",
"nl"
],
"labels" => [
[
"id" => "/signature_ui_labels/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"name" => "NAME OF THE LABEL",
"languages" => [
"en" => "Label en",
"fr" => "Label fr"
],
"creator" => null,
"createdAt" => "2018-12-07T07:34:22+01:00",
"updatedAt" => "2018-12-07T07:34:22+01:00"
]
],
"fonts" => [
"Roboto",
"Lato"
],
"style" => "Just a CSS string for customize all of our iFrame.",
"redirectCancel" => [
"url" => "https://example.com?cancel=1",
"target" => "_top",
"auto" => false
],
"redirectError" => [
"url" => "https://example.com?error=1",
"target" => "_blank",
"auto" => true
],
"redirectSuccess" => [
"url" => "https://example.com?success=1",
"target" => "_parent",
"auto" => true
],
"workspace" => "/workspaces/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"creator" => null,
"createdAt" => "2018-12-07T07:34:22+01:00",
"updatedAt" => "2018-12-07T07:34:22+01:00"
]
更多
-
要讨论新功能、提出反馈或简单地分享想法，您可以在 Mastodon 上联系我：https://cybre.space/@landrok
-
在 Yousign Sandbox 注册 上创建账户和 API 令牌