使用DocuSign PHP SDK的listStatusChanges无法获取作废信封的作废原因与时间

排查步骤及解决方案 #

• 确认include参数的精确指定
  即便你尝试过添加include参数，需确保明确指定voided_reason和voided_date_time字段，而非泛泛的“所有参数”。PHP SDK中正确的参数设置示例：

  $envelopesApi = new DocuSign\eSign\Api\EnvelopesApi($apiClient);
  $options = new DocuSign\eSign\Api\EnvelopesApi\ListStatusChangesOptions();
  $options->setInclude("voided_reason,voided_date_time");
  $options->setFromDate("2024-01-01T00:00:00Z"); // 按需设置时间范围
  $results = $envelopesApi->listStatusChanges($accountId, $options);
  

• 验证信封是否存在有效作废原因
  若信封是通过API自动作废、或作废操作时未填写原因，voided_reason确实会返回null。可登录DocuSign控制台，找到对应作废信封，确认是否存在手动填写的作废原因——若控制台无该内容，API返回null属于正常情况。

• 改用getEnvelope接口单独获取详情
  如果listStatusChanges始终无法返回目标字段，可尝试对单个作废信封调用getEnvelope接口，指定相同include参数：

  $envelopeApi = new DocuSign\eSign\Api\EnvelopesApi($apiClient);
  $options = new DocuSign\eSign\Api\EnvelopesApi\GetEnvelopeOptions();
  $options->setInclude("voided_reason,voided_date_time");
  $envelope = $envelopeApi->getEnvelope($accountId, $envelopeId, $options);
  // 查看返回字段
  var_dump($envelope->getVoidedReason());
  var_dump($envelope->getVoidedDateTime());
  

• 升级PHP SDK版本
  旧版SDK可能存在字段映射缺陷，导致无法正确解析voided_reason。执行以下命令升级到最新稳定版：

  composer require docusign/esign-client:^6.0
  

• 检查API权限范围
  确保你的OAuth令牌拥有envelopes_read权限，权限不足可能导致部分字段被过滤，返回null。

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