Docusign系列 - Docusign的嵌入式签名

Posted 2021-02-28 luqinghua

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Docusign系列 - Docusign的嵌入式签名相关的知识，希望对你有一定的参考价值。

之前谈到的Dicusign，都是发送一封邮件给到收件人，然后收件人完成签名的一个过程，那么有的时候，当我们需要直接在页面上打开用户签名的界面，而不是通过邮件的形式，那么就需要开启Docusign的嵌入式签名过程

整体步骤参考 Docusign系列（三）- SOAP方式调用Docusign，本质上来讲，嵌入式签名的形式，即将发送到用户的那封信件的链接，在页面上完成跳转，所以我们首先写一个页面按钮：打开Docusign签名链接（图左），当你点击按钮，会直接跳转到Docusign的签名页面（图右）

技术图片

页面代码很简单，通过按钮调用Docusign的SOAP接口

<apex:page controller="ShowButtonCtrl" showHeader="false" sidebar="false">
    <apex:form >
        <apex:pagemessages />
        <apex:pageBlock >
            <apex:commandButton value="打开Docusign签名链接" action="{!testFunction}"/>
        </apex:pageBlock>
    </apex:form>
</apex:page>

public class ShowButtonCtrl {
    
    public String testFunction(){
        String docusignurl = DocusignDemo2.sendWithDocusign(‘8002w000000HXkJ‘);
        return docusignurl;
    }
}

那么关于Docusign部分的代码该怎么做呢？

首先是关于收件人，需要添加新的参数

// 设定一个 Client User Id
String signer_user_id = ‘1‘;

// 第一个签字
DocusignApi.Recipient firstSigner = new DocusignApi.Recipient();
firstSigner.ID = 1;
firstSigner.Type_x = ‘Signer‘;// 收件人类型 - Signer表示需要签字
firstSigner.RoutingOrder = 1;// 签字顺序
firstSigner.Email = ‘XXXXXXX‘;
firstSigner.UserName = ‘第一个签字‘;
firstSigner.RequireIDLookup = false;

// 嵌入式签名的参数
firstSigner.CaptiveInfo = new DocuSignAPI.RecipientCaptiveInfo();
firstSigner.CaptiveInfo.ClientUserID = signer_user_id;
firstSigner.CaptiveInfo.EmbeddedRecipientStartURL = ‘SIGN_AT_DOCUSIGN‘;

然后在通过Docusign生成EnvelopeID之后，获取需要跳转的链接：

// 第一步：创建assertion
DocuSignAPI.RequestRecipientTokenAuthenticationAssertion assertion  = new DocuSignAPI.RequestRecipientTokenAuthenticationAssertion();
assertion.AssertionID = ‘1‘;
assertion.AuthenticationInstant = Datetime.now();
assertion.AuthenticationMethod = ‘Password‘;
assertion.SecurityDomain = ‘DS_Recipe_Signer_View_Controller‘;

// Salesforce 环境域名
String baseUrl = URL.getSalesforceBaseUrl().toExternalForm();
String signer_return_url = baseURL + ‘?cId=‘ + recordId;

String return_url_base = signer_return_url;

if(return_url_base.contains(‘?‘)) {
    return_url_base += ‘&event=‘;
}else {
    return_url_base = return_url_base += ‘?event=‘;
}

System.debug(LoggingLevel.INFO , ‘**** return_url_base:‘ + return_url_base);

// 第二步：为电子签名的不同结果创建重定向URL
DocuSignAPI.RequestRecipientTokenClientURLs urls = new DocuSignAPI.RequestRecipientTokenClientURLs();        
urls.OnSigningComplete  = baseURL + ‘/apex/welcome?conId=‘ + recordId;
urls.OnViewingComplete  = return_url_base + ‘viewing_complete‘;
urls.OnCancel           = return_url_base + ‘cancel‘;
urls.OnDecline          = return_url_base + ‘decline‘;
urls.OnSessionTimeout   = return_url_base + ‘session_timeout‘;
urls.OnTTLExpired       = return_url_base + ‘ttl_expired‘;
urls.OnException        = baseURL + ‘/apex/welcome?conId=‘ + recordId;
urls.OnAccessCodeFailed = return_url_base + ‘failed_access_code‘;
urls.OnIdCheckFailed    = return_url_base + ‘failed_id_check‘;
urls.OnFaxPending       = return_url_base + ‘fax_pending‘;

System.debug(LoggingLevel.INFO , ‘**** return_url_base:‘ + return_url_base);

String signer_view_url;
Boolean no_error = true;

try {
    // 第三步：调用Docusign请求
    signer_view_url = dsApi.RequestRecipientToken(envelopeId, signer_user_id, firstSigner.UserName, firstSigner.Email, assertion, urls);
    System.debug(LoggingLevel.INFO , ‘**** Received signer_view_url:‘ + signer_view_url);
} catch ( CalloutException e) {
    System.debug(LoggingLevel.INFO , ‘**** Exception - ‘ + e );
    String error_code = ‘Problem: ‘ + e;
    String error_message = error_code;
    no_error = false;
}

在搞定上面的内容之后，当Docusign签订完成会跳转到 ‘welcome‘ 这个自定义页面，

技术图片

整体来看，在SOAP的接触上使用嵌入式签名还是很简单的，这样就可以让Docusign能在更多的地方被使用，比如在我们发送出去的Email中，或者其他自定义页面上，赋予了这种电子签名更广泛的应用空间

需要注意的是，这种嵌入式签名的有效期仅仅五分钟，同时在默认情况下，Docusign不会发送之前我们看到的Docusign请求签名的邮件给收件人，这一点从需求上不难理解，毕竟在页面上把合同啥的都签了，也不需要额外的邮件提醒了，不过Docusign也不是完全关闭了这样的通道，在Docusign的管理员界面中，选择Signing Setting页签

技术图片

在这里，你可以关闭或者启用是否要在嵌入式场景下发送邮件给签名者

最后，附上DocusignDemo2 类的完整代码

public class DocusignDemo2 {
    public static String USERID = ‘XXXXX‘;
    public static String ACCOUNTID = ‘XXXXX‘;
    public static String PASSWORD = ‘XXXXXX‘;
    public static String INTEGRATORKEY = ‘XXXXXX‘;
    public static String ENDPOINT = ‘https://demo.docusign.net/api/3.0/dsapi.asmx‘;
    
    public static String sendWithDocusign(String recordId){
        Contract con = [SELECT id FROM Contract WHERE Id=:recordId];
        
        DocusignApi.DSAPIServiceSoap dsApi = new DocusignApi.DSAPIServiceSoap();
        dsApi.endpoint_x = ENDPOINT;
        
        //Set Authentication
        String auth = ‘<DocuSignCredentials>‘
                        + ‘<Username>‘+ USERID + ‘</Username>‘ 
                        + ‘<Password>‘ + PASSWORD + ‘</Password>‘ 
                        + ‘<IntegratorKey>‘ + INTEGRATORKEY + ‘</IntegratorKey>‘ 
                    + ‘</DocuSignCredentials>‘;
        System.debug(‘Setting authentication to: ‘ + auth);
            
        dsApi.inputHttpHeaders_x = new Map<String, String>();
        dsApi.inputHttpHeaders_x.put(‘X-DocuSign-Authentication‘, auth);
        
        // 发送Docusign中的模板
        DocuSignAPI.TemplateReference templateReference = new DocuSignAPI.TemplateReference();
        templateReference.Template = ‘XXXXXXXXX‘;
        templateReference.TemplateLocation = ‘Server‘;
        
        DocusignApi.ArrayOfTemplateReference templateReferences = new DocusignApi.ArrayOfTemplateReference();
        templateReferences.TemplateReference = new DocusignApi.TemplateReference[]{templateReference};
        
        // 设定一个 Client User Id
        String signer_user_id = ‘1‘;
        
           // 第一个签字
        DocusignApi.Recipient firstSigner = new DocusignApi.Recipient();
        firstSigner.ID = 1;
        firstSigner.Type_x = ‘Signer‘;// 收件人类型 - Signer表示需要签字
        firstSigner.RoutingOrder = 1;// 签字顺序
        firstSigner.Email = ‘XXXXXX‘;
        firstSigner.UserName = ‘第一个签字‘;
        firstSigner.RequireIDLookup = false;

        // 嵌入式签名的参数
        firstSigner.CaptiveInfo = new DocuSignAPI.RecipientCaptiveInfo();
        firstSigner.CaptiveInfo.ClientUserID = signer_user_id;
        firstSigner.CaptiveInfo.EmbeddedRecipientStartURL = ‘SIGN_AT_DOCUSIGN‘;
        
        DocusignApi.ArrayOfRecipient1 recipients = new DocusignApi.ArrayOfRecipient1();
        recipients.Recipient = new DocusignApi.Recipient[]{firstSigner};
        
        DocusignApi.EnvelopeInformation envelopeInfo = new DocusignApi.EnvelopeInformation();
        envelopeInfo.AccountId = ACCOUNTID;
        envelopeInfo.Subject = ‘email subject‘;// Max 100 characters
        envelopeInfo.EmailBlurb =  ‘email message.‘;// Max 10000 characters
            
        DocusignApi.CustomField platformName = new DocusignApi.CustomField (); 
        platformName.Name = ‘PlatformName‘;
        platformName.Value = ‘Salesforce‘;
        platformName.Show = ‘False‘;
        
        DocusignApi.CustomField appName = new DocusignApi.CustomField (); 
        appName.Name = ‘AppName‘;
        appName.Value = ‘DocuSignForSalesforce‘;
        appName.Show = ‘False‘;
        
        DocusignApi.CustomField SFContract = new DocusignApi.CustomField (); 
        SFContract.Name = ‘##SFContract‘;
        SFContract.Value = recordId;
        SFContract.Show = ‘False‘;
        
        DocusignApi.CustomField DSFSSourceObjectId = new DocusignApi.CustomField (); 
        DSFSSourceObjectId.Name = ‘DSFSSourceObjectId‘;
        DSFSSourceObjectId.Value = recordId + ‘~Contract‘;
        DSFSSourceObjectId.Show = ‘False‘;
        
        DocusignApi.ArrayOfCustomField arrayOfCustomFields = new DocusignApi.ArrayOfCustomField();
        arrayOfCustomFields.CustomField  = new list<DocusignApi.CustomField>();
        arrayOfCustomFields.CustomField.add(platformName);
        arrayOfCustomFields.CustomField.add(appName);
        arrayOfCustomFields.CustomField.add(SFContract);
        arrayOfCustomFields.CustomField.add(DSFSSourceObjectId);        
            
        System.debug(‘*** arrayOfCustomFields:‘ + arrayOfCustomFields);        
        envelopeInfo.CustomFields = arrayOfCustomFields;
        
        // 保留信封ID
        String envelopeId;
        
        try {
            DocusignApi.EnvelopeStatus es = dsApi.CreateEnvelopeFromTemplates(templateReferences,recipients,envelopeInfo,true);
            envelopeId = es.EnvelopeID;
            System.debug(LoggingLevel.INFO, ‘*** EnvelopeID:‘ + es.EnvelopeID);
            System.debug(LoggingLevel.INFO, ‘*** Status:‘ + es.Status);
        } catch ( CalloutException e) {
            System.debug(‘Exception - ‘ + e );
        }
        // 第一步：创建assertion
        DocuSignAPI.RequestRecipientTokenAuthenticationAssertion assertion = new DocuSignAPI.RequestRecipientTokenAuthenticationAssertion();
        assertion.AssertionID = ‘1‘;
        assertion.AuthenticationInstant = Datetime.now();
        assertion.AuthenticationMethod = ‘Password‘;
        assertion.SecurityDomain = ‘DS_Recipe_Signer_View_Controller‘;
        
        // Salesforce 环境域名
        String baseUrl = URL.getSalesforceBaseUrl().toExternalForm();
        String signer_return_url = baseURL + ‘?cId=‘ + recordId;

        String return_url_base = signer_return_url;

        if(return_url_base.contains(‘?‘)) {
            return_url_base += ‘&event=‘;
        }else {
            return_url_base = return_url_base += ‘?event=‘;
        }

        System.debug(LoggingLevel.INFO , ‘**** return_url_base:‘ + return_url_base);
        
        // 第二步：为电子签名的不同结果创建重定向URL
        DocuSignAPI.RequestRecipientTokenClientURLs urls = new DocuSignAPI.RequestRecipientTokenClientURLs();        
        urls.OnSigningComplete  = baseURL + ‘/apex/welcome?conId=‘ + recordId;
        urls.OnViewingComplete  = return_url_base + ‘viewing_complete‘;
        urls.OnCancel           = return_url_base + ‘cancel‘;
        urls.OnDecline          = return_url_base + ‘decline‘;
        urls.OnSessionTimeout   = return_url_base + ‘session_timeout‘;
        urls.OnTTLExpired       = return_url_base + ‘ttl_expired‘;

        // urls.OnException        = return_url_base + ‘exception‘;
        urls.OnException        = baseURL + ‘/apex/welcome?conId=‘ + recordId;
        urls.OnAccessCodeFailed = return_url_base + ‘failed_access_code‘;
        urls.OnIdCheckFailed    = return_url_base + ‘failed_id_check‘;
        urls.OnFaxPending       = return_url_base + ‘fax_pending‘;
        
        System.debug(LoggingLevel.INFO , ‘**** return_url_base:‘ + return_url_base);
        
        String signer_view_url;
        Boolean no_error = true;
        try {
            // 第三步：调用Docusign请求
            signer_view_url = dsApi.RequestRecipientToken(envelopeId, signer_user_id, firstSigner.UserName, firstSigner.Email, assertion, urls);
            System.debug(LoggingLevel.INFO , ‘**** Received signer_view_url:‘ + signer_view_url);
        } catch ( CalloutException e) {
            System.debug(LoggingLevel.INFO , ‘**** Exception - ‘ + e );
            String error_code = ‘Problem: ‘ + e;
            String error_message = error_code;
            no_error = false;
        }

        String signingUrl;
        if (no_error) {
            signingUrl = signer_view_url;
            System.debug(LoggingLevel.INFO , ‘**** signingUrl:‘ + signingUrl);
        }
        return signingUrl;
    }
}

以上是关于Docusign系列 - Docusign的嵌入式签名的主要内容，如果未能解决你的问题，请参考以下文章

使用 Jwt Oauth2 授权的 Docusign 嵌入式签名，无需客户登录/同意

DocuSign：在 JWT 令牌中设置过期 - 始终获取一小时过期的访问令牌

通过 DocuSign Rest API 创建 DocuSign 信封时出错（包含多个文档和多个收件人）

当我们进行API调用时，Docusign会保留发送文档的副本吗 - eSignRestAPI？

无法使用 DocuSign Python 代码生成 jwt 令牌

DocuSign 集成。是不是可以在未经用户同意的情况下获得身份验证令牌。我想使用我的凭据在内部发送 docusign 信封电子邮件 [关闭]