{"id":16707808,"url":"https://github.com/landrok/yousign-api","last_synced_at":"2025-03-21T20:32:38.445Z","repository":{"id":47166139,"uuid":"262797323","full_name":"landrok/yousign-api","owner":"landrok","description":"Yousign API client is a PHP wrapper for the Yousign API","archived":false,"fork":false,"pushed_at":"2024-07-31T10:47:11.000Z","size":100,"stargazers_count":6,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-01T09:34:03.175Z","etag":null,"topics":["api","client","procedure","yousign"],"latest_commit_sha":null,"homepage":"https://yousign-api.readthedocs.io/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/landrok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["landrok"],"ko_fi":"landrok"}},"created_at":"2020-05-10T13:50:08.000Z","updated_at":"2023-06-08T15:48:59.000Z","dependencies_parsed_at":"2023-11-22T12:29:08.193Z","dependency_job_id":"4ccfff56-69fe-4bc2-88f9-83c4745ee281","html_url":"https://github.com/landrok/yousign-api","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landrok%2Fyousign-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landrok%2Fyousign-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landrok%2Fyousign-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/landrok%2Fyousign-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/landrok","download_url":"https://codeload.github.com/landrok/yousign-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244866012,"owners_count":20523448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","procedure","yousign"],"created_at":"2024-10-12T19:41:04.118Z","updated_at":"2025-03-21T20:32:38.128Z","avatar_url":"https://github.com/landrok.png","language":"PHP","funding_links":["https://github.com/sponsors/landrok","https://ko-fi.com/landrok"],"categories":[],"sub_categories":[],"readme":"Yousign API client\n==================\n\n[![Build Status](https://api.travis-ci.com/landrok/yousign-api.svg?branch=master)](https://travis-ci.com/landrok/yousign-api)\n[![Maintainability](https://api.codeclimate.com/v1/badges/cad81750c32c5346ac6b/maintainability)](https://codeclimate.com/github/landrok/yousign-api/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/cad81750c32c5346ac6b/test_coverage)](https://codeclimate.com/github/landrok/yousign-api/test_coverage)\n\nYousign API client is a wrapper for the Yousign API v2 in PHP.\n\nIts purpose is to use this API without having to write the HTTP calls\nyourself and then to retrieve the returned data through an object model.\n\nIf you still want to make HTTP calls to check the API responses, this is\npossible thanks to the low-level calls.\n\nIt provides several an API wrapper and shortcut methods.\n\nAll the API calls are wrapped into an object model. All features are\nimplemented, it aims to be a full-featured client.\n\nAll subsequent types (Member, Procedure, File, etc...) are implemented\ntoo.\n\n[See the full documentation](https://yousign-api.readthedocs.io/) or\nan overview below.\n\nTable of contents\n=================\n\n- [Requirements](#requirements)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [Basic mode](#basic-mode)\n- [Advanced mode](#advanced-mode)\n- [Branding with signature UI](#branding-with-signature-ui)\n\n________________________________________________________________________\n\nRequirements\n------------\n\n- PHP 7.4+\n- You have to create your account on Yousign platform to get an API\ntoken before using this library.\n\n________________________________________________________________________\n\nInstall\n-------\n\n```sh\ncomposer require landrok/yousign-api\n```\n\n________________________________________________________________________\n\nQuick start\n-----------\n\nIn this example, we will get all users in staging mode.\n\n```php\nuse Yousign\\YousignApi;\n\n/*\n * token\n */\n$token = '123456789';\n\n$yousign = new YousignApi($token);\n\n$users = $yousign-\u003egetUsers();\n\n```\n\nGood news, your token is available.\n\n\n________________________________________________________________________\n\nResponses and data\n------------------\n\nAll API responses are converted into objects that are iterable when it's\na collection (ie a list of users) or an item (an user itself).\n\n### Dump data\n\nYou can use toArray() method to dump all data as a PHP array.\n\n```php\n\nprint_r(\n    $users-\u003etoArray()\n);\n\n```\n\n### Iterate over a list\n\nYou can iterate over all items of a collection.\n\n```php\n\nforeach ($users as $user) {\n    /*\n     * For each User model, some methods are available\n     */\n\n    // toArray(): to get all property values\n    print_r($user-\u003etoArray());\n\n    // get + property name\n    echo PHP_EOL . \"User.id=\" . $user-\u003egetId();\n\n    // property (read-only)\n    echo PHP_EOL . \"User.id=\" . $user-\u003eid;\n\n    // Some properties are models that you can use the same way\n    echo PHP_EOL . \"User.Group.id=\" . $user-\u003egetGroup()-\u003egetId();\n    echo PHP_EOL . \"User.Group.id=\" . $user-\u003egroup-\u003eid;\n\n    // Some properties are collections that you can iterate\n    foreach ($user-\u003egroup-\u003epermissions as $index =\u003e $permission) {\n        echo PHP_EOL . \"User.Group.Permission.name=\" . $permission-\u003egetName();\n    }\n\n    // At any level, you can call a toArray() to dump the current model\n    // and its children\n    echo PHP_EOL . \"User.Group=\\n\";\n    print_r($user-\u003egroup-\u003etoArray());\n    echo PHP_EOL . \"User.Group.Permissions=\\n\";\n    print_r($user-\u003egroup-\u003epermissions-\u003etoArray());\n}\n\n```\n________________________________________________________________________\n\nBasic Mode\n----------\n\nLet's create your first signature procedure in basic mode.\n\nIn this example, we will accomplish this mode with low-level\nfeatures.\n\n```php\nuse Yousign\\YousignApi;\n\n/*\n * Token\n */\n$token = '123456789';\n\n/*\n * Production mode\n */\n$production = false;\n\n/*\n * Instanciate API wrapper\n */\n$yousign = new YousignApi($token, $production);\n\n/*\n * 1st step : send a file\n */\n$file = $yousign-\u003epostFile([\n    'name'    =\u003e 'My filename.pdf',\n    'content' =\u003e base64_encode(\n        file_get_contents(\n            dirname(__DIR__, 2) . '/tests/samples/test-file-1.pdf'\n        )\n    )\n]);\n\n/*\n * 2nd step : create the procedure\n */\n$procedure = $yousign-\u003epostProcedure([\n    \"name\"        =\u003e \"My first procedure\",\n    \"description\" =\u003e \"Awesome! Here is the description of my first procedure\",\n    \"members\"     =\u003e [\n        [\n            \"firstname\" =\u003e \"John\",\n            \"lastname\" =\u003e \"Doe\",\n            \"email\" =\u003e \"john.doe@yousign.fr\",\n            \"phone\" =\u003e \"+33612345678\",\n            \"fileObjects\" =\u003e [\n                [\n                    \"file\" =\u003e $file-\u003egetId(),\n                    \"page\" =\u003e 2,\n                    \"position\" =\u003e \"230,499,464,589\",\n                    \"mention\" =\u003e \"Read and approved\",\n                    \"mention2\" =\u003e \"Signed by John Doe\"\n                ]\n            ]\n        ]\n    ]\n]);\n\n// toJson() supports all PHP json_encode flags\necho $procedure-\u003etoJson(JSON_PRETTY_PRINT);\n```\n\nWhen the procedure is created, you can retrieve all the data with the\ngetters or dump all data with `toJson()` and `toArray()` methods.\n\nIt would output something like:\n\n```json\n{\n    \"id\": \"\\/procedures\\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n    \"name\": \"My first procedure\",\n    \"description\": \"Awesome! Here is the description of my first procedure\",\n    \"createdAt\": \"2018-12-01T11:49:11+01:00\",\n    \"updatedAt\": \"2018-12-01T11:49:11+01:00\",\n    \"finishedAt\": null,\n    \"expiresAt\": null,\n    \"status\": \"active\",\n    \"creator\": null,\n    \"creatorFirstName\": null,\n    \"creatorLastName\": null,\n    \"workspace\": \"\\/workspaces\\/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n    \"template\": false,\n    \"ordered\": false,\n    \"parent\": null,\n    \"metadata\": [],\n    \"config\": [],\n    \"members\": [\n        {\n            \"id\": \"\\/members\\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n            \"user\": null,\n            \"type\": \"signer\",\n            \"firstname\": \"John\",\n            \"lastname\": \"Doe\",\n            \"email\": \"john.doe@yousign.fr\",\n            \"phone\": \"+33612345678\",\n            \"position\": 1,\n            \"createdAt\": \"2018-12-01T11:49:11+01:00\",\n            \"updatedAt\": \"2018-12-01T11:49:11+01:00\",\n            \"finishedAt\": null,\n            \"status\": \"pending\",\n            \"fileObjects\": [\n                {\n                    \"id\": \"\\/file_objects\\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n                    \"file\": {\n                        \"id\": \"\\/files\\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n                        \"name\": \"The best name for my file.pdf\",\n                        \"type\": \"signable\",\n                        \"contentType\": \"application\\/pdf\",\n                        \"description\": null,\n                        \"createdAt\": \"2018-12-01T11:36:20+01:00\",\n                        \"updatedAt\": \"2018-12-01T11:49:11+01:00\",\n                        \"sha256\": \"bb57ae2b2ca6ad0133a699350d1a6f6c8cdfde3cf872cf526585d306e4675cc2\",\n                        \"metadata\": [],\n                        \"workspace\": \"\\/workspaces\\/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n                        \"creator\": null,\n                        \"protected\": false,\n                        \"position\": 0,\n                        \"parent\": null\n                    },\n                    \"page\": 2,\n                    \"position\": \"230,499,464,589\",\n                    \"fieldName\": null,\n                    \"mention\": \"Read and approved\",\n                    \"mention2\": \"Signed by John Doe\",\n                    \"createdAt\": \"2018-12-01T11:49:11+01:00\",\n                    \"updatedAt\": \"2018-12-01T11:49:11+01:00\",\n                    \"parent\": null,\n                    \"reason\": \"Signed by Yousign\"\n                }\n            ],\n            \"comment\": null,\n            \"notificationsEmail\": [],\n            \"operationLevel\": \"custom\",\n            \"operationCustomModes\": [\n                \"sms\"\n            ],\n            \"operationModeSmsConfig\": null,\n            \"parent\": null\n        }\n    ],\n    \"subscribers\": [],\n    \"files\": [\n        {\n            \"id\": \"\\/files\\/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n            \"name\": \"My filename.pdf\",\n            \"type\": \"signable\",\n            \"contentType\": \"application\\/pdf\",\n            \"description\": null,\n            \"createdAt\": \"2018-12-01T11:36:20+01:00\",\n            \"updatedAt\": \"2018-12-01T11:49:11+01:00\",\n            \"sha256\": \"bb57ae2b2ca6ad0133a699350d1a6f6c8cdfde3cf872cf526585d306e4675cc2\",\n            \"metadata\": [],\n            \"workspace\": \"\\/workspaces\\/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n            \"creator\": null,\n            \"protected\": false,\n            \"position\": 0,\n            \"parent\": null\n        }\n    ],\n    \"relatedFilesEnable\": false,\n    \"archive\": false,\n    \"archiveMetadata\": [],\n    \"fields\": [],\n    \"permissions\": []\n}\n```\n________________________________________________________________________\n\nAdvanced Mode\n-------------\n\nHere is how to create a procedure in 5 steps with the advanced mode.\n\n```php\nuse Yousign\\YousignApi;\n\n/*\n * Token\n */\n$token = '123456789';\n\n/*\n * Production mode\n */\n$production = false;\n\n/*\n * Instanciate API wrapper\n */\n$yousign = new YousignApi($token, $production);\n\n/*\n * Step 1 - Create your procedure\n */\n$procedure = $yousign-\u003epostProcedure([\n    \"name\"        =\u003e \"My first procedure\",\n    \"description\" =\u003e \"Description of my procedure with advanced mode\",\n    \"start\"       =\u003e false,\n]);\n\n/*\n * Step 2 - Add the files\n */\n$file = $yousign-\u003epostFile([\n    'name'    =\u003e 'Name of my signable file.pdf',\n    'content' =\u003e base64_encode(\n        file_get_contents(\n            dirname(__DIR__, 2) . '/tests/samples/test-file-1.pdf'\n        )\n    ),\n    'procedure' =\u003e $procedure-\u003egetId(),\n]);\n\n/*\n * Step 3 - Add the members\n */\n$member = $yousign-\u003epostMember([\n    \"firstname\"     =\u003e \"John\",\n    \"lastname\"      =\u003e \"Doe\",\n    \"email\"         =\u003e \"john.doe@yousign.fr\",\n    \"phone\"         =\u003e \"+33612345678\",\n    \"procedure\"     =\u003e $procedure-\u003egetId(),\n]);\n\n/*\n * Step 4 - Add the signature images\n */\n$fileObject = $yousign-\u003epostFileObject([\n    \"file\"      =\u003e $file-\u003egetId(),\n    \"member\"    =\u003e $member-\u003egetId(),\n    \"position\"  =\u003e \"230,499,464,589\",\n    \"page\"      =\u003e 2,\n    \"mention\"   =\u003e \"Read and approved\",\n    \"mention2\"  =\u003e \"Signed By John Doe\"\n]);\n\n /*\n  * Step 5 - Start the procedure\n  */\n$procedure = $yousign-\u003eputProcedure(\n    $procedure-\u003egetId(), [\n        \"start\" =\u003e true,\n    ]\n);\n\n\necho $procedure-\u003etoJson(JSON_PRETTY_PRINT);\n```\n\nIn step 3, you may add several members.\n\nIn step 4, you may add one or more signature images for each one.\n\n________________________________________________________________________\n\nBranding with signature UI\n--------------------------\n\nBy default, Signature-UI has the Yousign theme (logo, colors, ...) but\nyou can customize the signature flow embedded in the iFrame from\nSignature-UI view located in the Admin menu of the app or entirely\ncustomize this iFrame by using a specific resource `/signature_uis`.\n\n\n```php\nuse Yousign\\YousignApi;\n\n/*\n * Token\n */\n$token = '123456789';\n\n/*\n * Production mode\n */\n$production = false;\n\n/*\n * Instanciate API wrapper\n */\n$yousign = new YousignApi($token, $production);\n\n/*\n * Create your customized UI\n */\n$ui = $yousign-\u003epostSignatureUi([\n    \"name\"                    =\u003e \"My first template for Signature-UI\",\n    \"description\"             =\u003e \"Here is the Signature-UI template for Yousign Developers.\",\n    \"defaultZoom\"             =\u003e 100,\n    \"logo\"                    =\u003e \"data:image/png;base64,iVBORw0K [...] XIwU3i6foIAAAAAElFTkSuQmCC\",\n    \"languages\"               =\u003e [\"fr\", \"en\"],\n    \"defaultLanguage\"         =\u003e \"en\",\n    \"labels\"                  =\u003e [\n        [\n            \"name\"      =\u003e \"NAME OF THE LABEL\",\n            \"languages\" =\u003e [\n                \"en\" =\u003e \"Label en\",\n                \"fr\" =\u003e \"Label fr\"\n            ],\n            \"creator\"   =\u003e null,\n        ]\n    ],\n    \"signImageTypesAvailable\" =\u003e [\n        \"name\",\n        \"draw\",\n    ],\n    \"enableHeaderBar\"         =\u003e true,\n    \"enableHeaderBarSignAs\"   =\u003e true,\n    \"enableSidebar\"           =\u003e true,\n    \"enableMemberList\"        =\u003e true,\n    \"enableDocumentList\"      =\u003e true,\n    \"enableDocumentDownload\"  =\u003e true,\n    \"enableActivities\"        =\u003e false,\n    \"authenticationPopup\"     =\u003e false,\n    \"enableRefuseComment\"     =\u003e true,\n    \"fonts\"                   =\u003e [\"Roboto\", \"Lato\"],\n    \"creator\"                 =\u003e null,\n    \"redirectCancel\"          =\u003e [\n        \"url\"    =\u003e \"https://example.com?cancel=1\",\n        \"target\" =\u003e \"_top\",\n        \"auto\"   =\u003e false\n    ],\n    \"redirectError\"           =\u003e [\n        \"url\"    =\u003e \"https://example.com?error=1\",\n        \"target\" =\u003e \"_blank\",\n        \"auto\"   =\u003e true\n    ],\n    \"redirectSuccess\"           =\u003e [\n        \"url\"    =\u003e \"https://example.com?success=1\",\n        \"target\" =\u003e \"_parent\",\n        \"auto\"   =\u003e true\n    ],\n    \"style\"                   =\u003e \"\n        .sign-ui-header-bar { background-color: #00f }\n        .sign-ui-headerbar-signas { background-color: #f00 }\n        .sign-ui-headerbar-signas--primary { background-color: #f00 }\n        .sign-ui-tab-item { color: #000 }\n        .sign-ui-tab-item--current { background-color: #0f0; color: #fff }\n    \"\n]);\n```\n\nIn the response below, you will get an id that will be useful to create\nyour iFrame.\n\n\n```php\n[\n    \"id\"                      =\u003e \"/signature_uis/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n    \"name\"                    =\u003e \"My first template for Signature-UI\",\n    \"description\"             =\u003e \"Here is the Signature-UI template for Yousign Developers.\",\n    \"enableHeaderBar\"         =\u003e true,\n    \"enableHeaderBarSignAs\"   =\u003e true,\n    \"enableSidebar\"           =\u003e true,\n    \"enableMemberList\"        =\u003e true,\n    \"enableDocumentList\"      =\u003e true,\n    \"enableDocumentDownload\"  =\u003e true,\n    \"enableActivities\"        =\u003e true,\n    \"authenticationPopup\"     =\u003e true,\n    \"enableRefuseComment\"     =\u003e true,\n    \"defaultZoom\"             =\u003e 100,\n    \"logo\"                    =\u003e \"data:image/png;base64,iVBORw0K [...] XIwU3i6foIAAAAAElFTkSuQmCC\",\n    \"defaultLanguage\"         =\u003e \"en\",\n    \"signImageTypesAvailable\" =\u003e [\n        \"name\",\n        \"draw\"\n    ],\n    \"languages\"               =\u003e [\n        \"fr\",\n        \"en\",\n        \"es\",\n        \"de\",\n        \"it\",\n        \"pt\",\n        \"nl\"\n    ],\n    \"labels\"                  =\u003e [\n        [\n            \"id\"        =\u003e \"/signature_ui_labels/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n            \"name\"      =\u003e \"NAME OF THE LABEL\",\n            \"languages\" =\u003e [\n                \"en\" =\u003e \"Label en\",\n                \"fr\" =\u003e \"Label fr\"\n            ],\n            \"creator\"   =\u003e null,\n            \"createdAt\" =\u003e \"2018-12-07T07:34:22+01:00\",\n            \"updatedAt\" =\u003e \"2018-12-07T07:34:22+01:00\"\n        ]\n    ],\n    \"fonts\"                   =\u003e [\n        \"Roboto\",\n        \"Lato\"\n    ],\n    \"style\"                   =\u003e \"Just a CSS string for customize all of our iFrame.\",\n    \"redirectCancel\"          =\u003e [\n        \"url\"    =\u003e \"https://example.com?cancel=1\",\n        \"target\" =\u003e \"_top\",\n        \"auto\"   =\u003e false\n    ],\n    \"redirectError\"           =\u003e [\n        \"url\"    =\u003e \"https://example.com?error=1\",\n        \"target\" =\u003e \"_blank\",\n        \"auto\"   =\u003e true\n    ],\n    \"redirectSuccess\"           =\u003e [\n        \"url\"    =\u003e \"https://example.com?success=1\",\n        \"target\" =\u003e \"_parent\",\n        \"auto\"   =\u003e true\n    ],\n    \"workspace\"               =\u003e \"/workspaces/XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n    \"creator\"                 =\u003e null,\n    \"createdAt\"               =\u003e \"2018-12-07T07:34:22+01:00\",\n    \"updatedAt\"               =\u003e \"2018-12-07T07:34:22+01:00\"\n]\n```\n\n________________________________________________________________________\n\nMore\n----\n\n- [See the full documentation](https://yousign-api.readthedocs.io/)\n\n- To discuss new features, make feedback or simply to share ideas, you\n  can contact me on Mastodon at\n  [https://cybre.space/@landrok](https://cybre.space/@landrok)\n\n- Create an account and an API token on\n  [Yousign Sandbox sign-up](https://staging-auth.yousign.com/pre-signup)\n\n- [Official API manual](https://dev.yousign.com/?version=latest)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandrok%2Fyousign-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flandrok%2Fyousign-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandrok%2Fyousign-api/lists"}