使用DocuSign PHP SDK从模板创建信封时遭遇RECIPIENTS_NOT_PROVIDED错误

嘿，这个错误我之前踩过坑！明明代码里加了收件人信息，却还是提示“没找到收件人”，大概率是几个容易忽略的小问题，咱们一步步来排查：

• 先核对模板角色名称的一致性
  你代码里写的roleName是'User'，一定要去DocuSign后台确认模板里定义的角色名称是不是完全一模一样——大小写、空格、甚至连特殊符号都不能差！比如模板里如果是'user'或者'End User'，那你写'User'就会匹配失败，DocuSign自然识别不到收件人。

• 换一种方式创建TemplateRole试试
  有时候用数组初始化TemplateRole时，可能会因为隐性的格式问题导致参数没被正确识别。你可以改成显式设置属性的方式，这样更稳妥：

  $templateRole = new TemplateRole();
  $templateRole->setEmail('john@example.com');
  $templateRole->setName('John Doe');
  $templateRole->setRoleName('User'); // 再次确认这个名称和模板一致
  

• 检查信封定义的结构是否正确
  你可以在发送请求前，把$envelopeDefinition转成JSON打印出来，看看收件人信息是不是真的被正确包含进去了：

  echo json_encode($envelopeDefinition);
  

  如果打印出来的内容里templateRoles是空数组或者格式不对，那就是这里的问题。

• 确认模板的必填角色都已填充
  如果你的模板里有多个收件人角色，而且都是必填的，那你必须把所有角色的信息都传进去，不能只填一个。比如模板里有User和Admin两个必填角色，只传User也会触发这个错误。

给你一个调整后的示例代码，把这些注意点都涵盖了：

$apiClient = new ApiClient($config);

// Create an Envelope from a template
$templateId = env('TEMPLATE_ID');
$accountId = env('API_ACCOUNT_ID');
$envelopeApi = new EnvelopesApi($apiClient);

// 显式创建TemplateRole，避免数组初始化的隐性问题
$templateRole = new TemplateRole();
$templateRole->setEmail('john@example.com');
$templateRole->setName('John Doe');
// 务必保证这里的roleName和DocuSign模板里的角色名称完全匹配
$templateRole->setRoleName('User');

$envelopeDefinition = new EnvelopeDefinition();
$envelopeDefinition->setStatus('sent');
$envelopeDefinition->setTemplateId($templateId);
$envelopeDefinition->setTemplateRoles([$templateRole]);

// 可选：打印信封定义结构，用于调试
// echo json_encode($envelopeDefinition);

try {
    $envelopeSummary = $envelopeApi->createEnvelope($accountId, $envelopeDefinition);
    echo "信封创建成功！信封ID：" . $envelopeSummary->getEnvelopeId();
} catch (Exception $e) {
    echo "错误信息：" . $e->getMessage();
}

备注：内容来源于stack exchange，提问作者Steve