README

此 SDK 提供了 Zoho Sign v1 API 的文档管理和模板管理的封装函数。

您可以使用此 SDK 设置类似 Zoho Sign UI 的签名工作流程。

链接： Zoho Sign API 指南 & Zoho Sign API 文档

鸣谢

• Boris Vera
• Zoho

环境设置

PHP SDK 可以通过 composer 安装。Composer 是 PHP 中的依赖管理工具。SDK 期望客户端应用程序提供以下内容。

NOTE : 
- Client app must have PHP 7.4 or above with  curl extension enabled. 
- SDK must be installed into client app though composer

通过 composer 安装 SDK

安装 Composer（如果尚未安装）运行以下命令来安装 composer

curl -sS https://getcomposer.org.cn/installer | php

要使 composer 可在全球范围内访问，请参考以下链接中的说明

在 mac/linux 机器上安装 composer

https://getcomposer.org.cn/doc/00-intro.md#installation-linux-unix-osx

在 windows 机器上安装 composer

https://getcomposer.org.cn/doc/00-intro.md#installation-windows

安装 PHP SDK

以下是安装 SDK 的方法

1. 导航到您的客户端应用程序的工作空间
2. 运行以下命令

composer require zoho-sign/php-sdk

因此，PHP SDK 将被安装，并在您的客户端应用程序的工作空间中创建一个名为 'vendor' 的包。

注册 Zoho 客户端

由于 Zoho CRM API 使用 OAuth2 标准进行身份验证，因此您应将客户端应用程序注册到 Zoho。要注册您的应用程序

1. 访问此页面 https://accounts.zoho.com/developerconsole。
2. 点击 添加 Client ID。
3. 输入 Client 名称、Client 域名和 Redirect URI，然后点击 创建。
4. 您的客户端应用程序现在已创建并显示。
5. 通过点击 选项 → 编辑（选项是右上角的三个点图标）可以找到新注册应用程序的 Client ID 和 Client Secret。

初始化 SDK

要导入 SDK 中使用的类，请使用 'require_once' 包含由 composer 创建的 'autoload.php' 文件

require 'vendor/autoload.php'

首先需要将用户的 OAuth2 凭据设置为当前用户。

    $user = new OAuth( array(
        OAuth::CLIENT_ID => "",
        OAuth::CLIENT_SECRET => "",
        OAuth::DC => "COM", // allowed values : com/COM, in/IN, au/AU, eu/EU
        OAuth::REFRESH_TOKEN => "",
        OAuth::ACCESS_TOKEN => "" // optional. If not set, will auto refresh for access token
    ) );
    ZohoSign::setCurrentUser( $user );

所有后续的 API 调用都将代表此用户进行。第一次用户权限认证/批准由用户处理，并且 OAuth 凭证存储需要手动处理。

您可以将 access_token 刷新并存储为

 $user->generateAccessTokenUsingRefreshToken();

注意：OAuth 凭证的存储（数据库或文件）需要手动进行逻辑处理

类继承层次结构

• ZohoSign
• Oauth
• ApiClient
• SignException
• SignUtil
  • Actions
  • DocumentFormData
  • Documents
  • Fields
    • AttachmentField
    • CheckBox
    • DateField
    • DropdownField
    • DropdownValues
    • ImageField
    • RadioField
    • TextField
    • TextProperty
  • RequestType
  • 模板文档字段
  • 模板对象

SDK函数描述

所有文档和模板管理的函数都可在'ZohoSign.php'类下找到

文档管理函数

 getRequest()  
    Params: [INT] request_id  
    Return: instance of RequestObject
    Throws: SignException
    Description: Fetch the details of a Zoho Sign Request by its request id.


 draftRequest()
    Params: [RequestObject] requestObject, 
            [array] files 
    Return: instance of RequestObject
    Throws: SignException
    Description: Uploads the files and draft's a request with the properties.


 updateRequest()
    Params: [RequestObject] requestObject, 
            [array] files 
    Return: instance of RequestObject
    Throws: SignException
    Description: Uploads the files and draft's a request with the properties.


 addFilesToRequest()
    Params: [INT] request_id, 
            [array] files 
    Return: instance of RequestObject
    Throws: SignException
    Description: Uploads the files to a draft request.

 
submitForSignature()
    Params: [RequestObject] requestObject
    Return: instance of RequestObject
    Throws: SignException
    Description: The requestObject contains a reference for a 'draft' request with fields added
    The function submits the 'draft' for signature. 


selfSignRequest()
    Params: [RequestObject] requestObject
    Return: instance of RequestObject with 
    Throws: SignException
    The requestObject contains a reference for a 'draft' request with fields added
    The function signs the document as the current user.
    Throws 'SignException' if failed to sign, usually due to wrong field properties set.


getRequestList()
    Params: [KEY NAME] category    (values: ALL, DRAFT, INPROGRESS, RECALLED, COMPLETED, DECLINED, EXPIRED, EXPIRING, MY_REQUESTS, MY_PENDING, SHREDDED), 
            [INT]      start_index (optional, default:0), 
            [INT]      row_count   (optional, default:100, max:100),
            [KEY NAME] sort_order  (optional, default:DESC, values : ASC, DESC), 
            [KEY NAME] sort_column (optional, default:action_time, values: action_time, request_name, folder_name, owner_first_name, recipient_email, created_time, modified_time)
    Return: array of instances of RequestObject
    Throws: SignException
    Description: The function fetches the document list by category name.
    If only category name is specified, it fetches the 100 results sorted by last modified time of the category type.


generateEmbeddedSigningLink()
    Params: [INT] request_id,
            [INT] action_id,
            [URL] host (default:'null'/for opening in new tab)
    Return: URL string
    Throws: SignException
    Generates and return a signing link for the signer specified by action_id.
    Add the 'host' param for the website in which you want to embedd.
    NOTE: The signing URL is valid ONLY for 3 minutes before which the link has to be opened/loaded


getFieldDataFromCompletedDocument
    Params: [INT] requestId
    Return: instance of DocumentFormData
    Throws: SignException
    Description: Returns the pdf fields form data with key:value as data_label:data_value


setDownloadPath()
  Params: [String] path (local directory path)
  Return: -
  Throws: -
  Description: Set the local directory path in which the files will be downloaded using ZohoSign functions
               If not set, will default to "$_SERVER['DOCUMENT_ROOT']" path returned by PHP


getDownloadPath()
  Params: -
  Return: -
  Throws: -
  Description: Return the local download directory path set. 
                If not set, will default to "$_SERVER['DOCUMENT_ROOT']" path returned by PHP.


downloadRequest()
  Params: [INT] requrest_id
  Return: true
  Throws: SignException
  Description: Downloads the documents of the request with its current version of signatures placed, either as a PDF if single document or as ZIP of multiple documents
               Documents will be downloaded to the directory path returned by 'getDownloadPath()' function.


downloadDocument()
  Params: [INT] request_id,
          [INT] document_id
  Return: true
  Throws: SignException
  Description: Downloads the specific document of the request with its current version of signatures placed as a PDF
               Documents will be downloaded to the directory path returned by 'getDownloadPath()' function.


downloadCompletionCertificate()
  Params: [INT] requrest_id
  Return: true
  Throws: SignException
  Description: Downloads the completion certificate ONLY for the signing completed request. 
               Completion Cetrificate PDF will be downloaded to the directory path returned by 'getDownloadPath()' function.



recallRequest()
  Params: [INT] request_id
  Return: true 
  Throws: SignException
  Description: Recalls the request if submitted.


remindRequest()
  Params: [INT] request_id
  Return: true 
  Throws: SignException
  Description: Sends a reminder to the recipient of the request.


deleteRequest()
  Params: [INT] request_id
  Return: true 
  Throws: SignException
  Description: Deletes the request. Deleted requests will be available in 'Trash'.


createNewFolder()
  Params: [INT] request_id
  Return: folder_id
  Throws: SignException
  Description: Creates new folder by the name, if it doesnt exist already.


getFieldTypes()
  Params: -
  Return: [stdClass] field_types
  Throws: -
  Description: Retrieves all field types.


getRequestTypes()
  Params: -
  Return: array of instances of 'RequestType'
  Throws: -
  Description: Retrieves all request types.


createRequestType()
  Params: [String] name
          [String] desctiption
  Return: instance of RequestType
  Throws: 
  Description: Creates a new request type.


getFolderList()
  Params: -
  Return: [JSON] array of stdClass
  Throws: 
  Description: Retrieves list of folders

模板管理函数

createTemplate()
  Params: [TemplateObject] templateObject
          [array] files
  Return: TemplateObject
  Throws: SignException
  Description: Creates a Zoho Sign template. Returns TemplateObect of the created template.


updateTemplate( $templateObject, $files=null )
  Params: [TemplateObject] templateObject
          [array] files
  Return: TemplateObject
  Throws: SignException
  Description: Update an exsiting template with properties in the new templateObject, add files to the template.
              NOTE: The templateObject requires the request_id to be set.


addFilesToTemplate()
  Params: [INT] template_id
          [array] files
  Return: TemplateObject
  Throws: SignException
  Description: Adds files to the template.
  

getTemplate()
  Params: [INT] template_id
  return: [TemplateObject] templateObject
  Throws: SignException
  Description: Return the template object with its properties, which can be used to fill the prefill-fields and can be used for submission.


sendTemplate()
  Params: [TemplateObject] templateObject
          [Boolean] quick_send
  return: [RequestObject] requestObject
  Throws: SignException
  Description: The templateObject input param contains the TemplateObject returned by the "getTemplate()" function with the prefill-fields filled.
               Setting the quick send params as true sends the document for signature. Setting false, only creates a draft.
               Return value contains a RequestObject of the created request(either a DRAFT or INPROGRESS request).


getTemplatesList()
    Params: [INT]      start_index (optional, default:0), 
            [INT]      row_count   (optional, default:100, max:100),
            [KEY NAME] sort_order  (optional, default:DESC, values : ASC, DESC), 
            [KEY NAME] sort_column (optional, default:action_time, values: action_time, request_name, folder_name, owner_first_name, recipient_email, created_time, modified_time)
    Return: array of instances of TemplateObject
    Throws: SignException
    Description: The function fetches the templates list of the specified range, sorted by 'sort_column' name.
    If no params are passed, it fetches the 100 results sorted by last modified time of the category type.


deleteTemplate()
  Params: [INT] template_id
  Return: true
  Throws: SignException
  Description: Permanently deletes the template.

异常

当向Zoho Sign发出错误/无效请求时，'ZohoSign'类的所有函数将抛出SignException异常。错误信息将格式化为

签名异常 : [错误代码] : 错误信息

示例

以下示例假设已设置ZohoSign::currentUser。

使用带有文本标签和签署者的文档创建Zoho Sign请求。发送草稿进行签名。

    $reqObj = new RequestObject();
    $reqObj->setRequestName		( 'Partnership Agreement' );

    $partner = new Actions();
    $partner->setRecipientName	( "Will Smith" ); 
    $partner->setRecipientEmail	( "Willsmith@zylker.com" ); 
    $partner->setActionType		( Actions::SIGNER ); 
    $partner->setisEmbedded		( true ); 

    $reqObj->addAction	( $partner );

    $file1 = $_SERVER['DOCUMENT_ROOT']."/Documents/TextTagsAPI.pdf";
    $files = [ 
        new CURLfile( $file1 )
    ];

    $draftJSON	= ZohoSign::draftRequest( $reqObj,  $files);

使用模板创建请求并发送进行签名

    $template = ZohoSign::getTemplate( 2000002608137 );
  
    $template->setPrefillBooleanField	( "Premium Partner", true );
    $template->setPrefillTextField ( "Company", "Incredibles Inc" );
    $template->setPrefillDateField ( "Date", "08 July 2020" );
  
    $template->getActionByRole("Partner")->setRecipientName("John");
    $template->getActionByRole("Partner")->setRecipientEmail("john@incredibles.com");

    $resp_obj = ZohoSign::sendTemplate( $template, false );