landrok / yousign-api
A PHP implementation of YouSign API.
Installs: 5 517
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 3
Forks: 5
Open Issues: 1
Requires
- php: ^7.4 || ^8.0
- guzzlehttp/guzzle: ^7.8
Requires (Dev)
- phpstan/phpstan: ^0.12.23
- phpunit/phpunit: *
README
Yousign API client is a wrapper for the Yousign API v2 in PHP.
Its purpose is to use this API without having to write the HTTP calls yourself and then to retrieve the returned data through an object model.
If you still want to make HTTP calls to check the API responses, this is possible thanks to the low-level calls.
It provides several an API wrapper and shortcut methods.
All the API calls are wrapped into an object model. All features are implemented, it aims to be a full-featured client.
All subsequent types (Member, Procedure, File, etc...) are implemented too.
See the full documentation or an overview below.
Table of contents
Requirements
- PHP 7.4+
- You have to create your account on Yousign platform to get an API token before using this library.
Install
composer require landrok/yousign-api
Quick start
In this example, we will get all users in staging mode.
use Yousign\YousignApi; /* * token */ $token = '123456789'; $yousign = new YousignApi($token); $users = $yousign->getUsers();
Good news, your token is available.
Responses and data
All API responses are converted into objects that are iterable when it's a collection (ie a list of users) or an item (an user itself).
Dump data
You can use toArray() method to dump all data as a PHP array.
print_r( $users->toArray() );
Iterate over a list
You can iterate over all items of a collection.
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()); }
Basic Mode
Let's create your first signature procedure in basic mode.
In this example, we will accomplish this mode with low-level features.
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);
When the procedure is created, you can retrieve all the data with the
getters or dump all data with toJson() and toArray() methods.
It would output something like:
{
"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": []
}
Advanced Mode
Here is how to create a procedure in 5 steps with the advanced mode.
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);
In step 3, you may add several members.
In step 4, you may add one or more signature images for each one.
Branding with signature UI
By default, Signature-UI has the Yousign theme (logo, colors, ...) but
you can customize the signature flow embedded in the iFrame from
Signature-UI view located in the Admin menu of the app or entirely
customize this iFrame by using a specific resource /signature_uis.
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 } " ]);
In the response below, you will get an id that will be useful to create your 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"
]
More
-
To discuss new features, make feedback or simply to share ideas, you can contact me on Mastodon at https://cybre.space/@landrok
-
Create an account and an API token on Yousign Sandbox sign-up