使用DocuSign PHP API为模板信封添加电话验证遇500错误

我正在通过DocuSign PHP API实现网站集成签名流程，已完成从模板生成信封、用会话数据填充标签的功能，但添加电话验证后出现问题：点击生成信封按钮跳转至DocuSign验证页面（https://verify-d.docusign.net/ChooseMethod）时触发500错误并无限加载。模板中已为第一个签署人设置电话验证，问题应该出在新增的电话验证代码中。

相关代码文件 #

EmbedSigningService.php #

<?php

namespace DocuSignSrc\Services;

use DocuSign\eSign\Client\ApiException;
use DocuSign\eSign\Model\Document;
use DocuSign\eSign\Model\EnvelopeDefinition;
use DocuSign\eSign\Model\Recipients;
use DocuSign\eSign\Model\Signer;
use DocuSign\eSign\Model\SignHere;
use DocuSign\eSign\Model\TemplateRole;
use DocuSign\eSign\Model\Tabs;
use DocuSignSrc\Services\SignatureClientService;


use DocuSign\eSign\Model\RecipientIdentityVerification;
use DocuSign\eSign\Model\RecipientPhoneNumber;
use DocuSign\eSign\Model\RecipientIdentityPhoneNumber;
use DocuSign\eSign\Model\RecipientIdentityInputOption;


class EmbeddedSigningService
{
    /**
     * Do the work of the example
     * 1. Create the envelope request object
     * 2. Send the envelope
     * 3. Create the Recipient View request object
     * 4. Obtain the recipient_view_url for the embedded signing
     *
     * @param  $args array
     * @param SignatureClientService $clientService
     * @return array ['redirect_url']
     */
    # ***DS.snippet.0.start
    public static function worker(array $args, SignatureClientService $clientService): array
    {
        # 1. Create the envelope request object
        $envelope_definition = EmbeddedSigningService::make_envelope($args["envelope_args"], $args["template_id"], $clientService);
        $envelope_api = $clientService->getEnvelopeApi();

        # 2. call Envelopes::create API method
        # Exceptions will be caught by the calling function
        try {
            $envelopeSummary = $envelope_api->createEnvelope($args['account_id'], $envelope_definition);
        } catch (ApiException $e) {
            $clientService->showErrorTemplate($e);
            exit;
        }
        $envelope_id = $envelopeSummary->getEnvelopeId();

        # 3. Create the Recipient View request object
        $authentication_method = 'None'; # How is this application authenticating
        # the signer? See the `authentication_method' definition
        # https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient/
        $recipient_view_request = $clientService->getRecipientViewRequest(
            $authentication_method,
            $args["envelope_args"]
        );

        # 4. Obtain the recipient_view_url for the embedded signing
        # Exceptions will be caught by the calling function
        $viewUrl = $clientService->getRecipientView($args['account_id'], $envelope_id, $recipient_view_request);

        return ['envelope_id' => $envelope_id, 'redirect_url' => $viewUrl['url']];
    }

    /**
 *  Creates envelope definition
 *  Parameters for the envelope: signer_email, signer_name, signer_client_id
 *
 * @param  $args array
 * @param  $template_id string
 * @return EnvelopeDefinition -- returns an envelope definition
 */
public static function make_envelope(array $args, string $template_id, SignatureClientService $clientService): EnvelopeDefinition
{

    $accounts_api = $clientService->getAccountsApi();
        $accounts_response = $accounts_api->getAccountIdentityVerification($_SESSION['ds_account_id']);
        
        // *************** Elements added below
        $workflows_data = $accounts_response->getIdentityVerification();
        $workflow_id = '';
        foreach ($workflows_data as $workflow) {
            if ($workflow['default_name'] == 'Phone Authentication')
                $workflow_id = $workflow['workflow_id'];
        }
        
        $phoneNumber = new RecipientIdentityPhoneNumber;
        $phoneNumber->setCountryCode($args['phone_country_code']);
        $phoneNumber->setNumber($args['phone_number']);

        $inputOption = new RecipientIdentityInputOption;
        $inputOption->setName('phone_number_list');
        $inputOption->setValueType('PhoneNumberList');
        $inputOption->setPhoneNumberList(array($phoneNumber));

        $identityVerification = new RecipientIdentityVerification;
        $identityVerification->setWorkflowId($workflow_id);
        $identityVerification->setInputOptions(array($inputOption));
        // ***************** End elements added


    $envelope_definition = new EnvelopeDefinition([
        'status' => 'sent',
        'template_id' => $template_id,
        'template_roles' => [
            new TemplateRole([
                'email' => $args['signer_email'],
                'name' => $args['signer_name'],
                'role_name' => 'Client',
                'client_user_id' => $args['signer_client_id'],
                'tabs' => $args['tabs'],
                // ***************  Element added below
                'identity_verification' => $identityVerification
             
            ])
        ]
    ]);

    return $envelope_definition;
}

    # ***DS.snippet.0.end
}

调用函数代码 #

<?php 
function embedSigning()
{


    $signer_name = 'John Doe';
    $signer_email = 'my@email.com'; // Anonymized here
    $myphonenumber= '0000000'; //Anonymized for sharing here but format is correct
    $signer_client_id = 1000; # Used to indicate that the signer will use embedded
    $envelope_args = [
        'signer_email' => $signer_email,
        'signer_name' => $signer_name,
        'phone_number' => $myphonenumber,
        'phone_country_code' => '33',
        'signer_client_id' => $signer_client_id,
        'tabs' => [
            'textTabs' => [
                [
                    'tabLabel' => 'TAB_text_to_prefill', // Label de l'onglet dans le modèle
                    'value' => $_SESSION['My-prefill-session-content'], // Valeur à insérer dans l'onglet
                ]
            ],
        ],
        'ds_return_url' => $GLOBALS['DS_CONFIG']['app_url'] . '/process-signature.php?page=embed-signing-return',
        'template_id' => 'xxxxx-xxxxx-xxxxx-xxxxxx-xxxxxxx', // Anonymized here for sharing
    ];

    $args = [
        'account_id' => $_SESSION['ds_account_id'],
        'base_path' => $_SESSION['ds_base_path'],
        'ds_access_token' => $_SESSION['ds_access_token'],
        'template_id' => 'xxxxx-xxxxx-xxxxx-xxxxxx-xxxxxxx', // Spécifiez l'ID du modèle à utiliser
        'envelope_args' => $envelope_args
    ];

    $clientService = new SignatureClientService($args);


    $envelopeIdAndReturnUrl = EmbeddedSigningService::worker(
        $args,
        $clientService
    );
    if ($envelopeIdAndReturnUrl) {
        $_SESSION['envelope_id'] = $envelopeIdAndReturnUrl['envelope_id'];
        # Redirect the user to the embedded signing
        # Don't use an iFrame!
        # State can be stored/recovered using the framework's session or a
        # query parameter on the returnUrl (see the make recipient_view_request method)
        header('Location:' . $envelopeIdAndReturnUrl["redirect_url"]);
        exit();
    } else {
        die('$envelopeIdAndReturnUrl === false, censé ne jamais arriver');
    }
}

排查建议 #

• 检查Workflow ID获取逻辑：遍历$workflows_data时，确认$workflow['default_name']的匹配值是否准确，部分环境中该名称可能是本地化版本（比如法语环境可能显示为“Authentification par téléphone”），或者存在名称缩写差异。可以先打印$workflows_data的完整内容，确认正确的工作流名称和对应ID，避免$workflow_id为空导致验证流程初始化失败。
• 验证电话号码格式：确认$args['phone_number']符合DocuSign要求，比如法国号码应去掉前置0，使用123456789配合国家代码33，而非0123456789。同时检查RecipientIdentityPhoneNumber的参数设置是否无误。
• 排查模板与代码配置冲突：模板中已为签署人设置电话验证，代码中重复添加identity_verification配置可能引发冲突。可以尝试移除模板中的验证设置，仅保留代码配置，或反过来仅使用模板配置。
• 检查API请求结构：开启DocuSign API请求日志，查看创建信封时的请求体，对比官方规范确认identity_verification部分的参数结构是否正确。
• 调整认证方式参数：创建Recipient View时，$authentication_method设置为'None'可能不符合验证场景，可尝试调整为'PhoneVerification'，确保DocuSign能正确识别签署人的认证方式。

内容的提问来源于stack exchange，提问作者MaxTab