PHP调用HMRC VAT API提交申报时全量必填字段报缺失的排查

全字段同时触发MANDATORY_FIELD_MISSING报错的核心原因是HMRC端未解析到合法的JSON请求体，结合你提供的代码，常见触发场景与修复方案如下：

• json_encode执行失败导致请求体为空

  • 触发逻辑：如果传入json_encode的数组包含非UTF-8编码内容（比如从Excel导出的GBK格式字符串、不可见控制字符），json_encode会返回false，最终$postData为空字符串，curl发送的POST请求无有效内容，所有字段都会被判定为缺失。
  • 验证方式：在json_encode执行后新增调试代码 var_dump(json_last_error_msg());，若输出Malformed UTF-8 characters类错误即可确认该问题。
  • 修复方案：对数组内所有字符串字段先做编码转换，确保为UTF-8格式后再传入json_encode。

• 所有字段值为null被HMRC判定为缺失

  • 触发逻辑：代码中引用的$strPeriodKey、$rngBox1~$rngBox9、$chkFinaliseConfirm变量未正确赋值（比如变量名拼写错误、取值逻辑为空、前端传参字段不匹配），json_encode生成的JSON会包含大量null值，HMRC的必填字段校验不接受null值，会直接判定为字段缺失。
  • 验证方式：在curl发起请求前新增调试代码 echo $postData;exit;，打印生成的JSON内容，确认每个字段是否有非null的合法值。
  • 修复方案：逐一检查所有变量的赋值逻辑，确保：
    • periodKey为字符串类型
    • 所有数值字段为数字类型（不要传字符串型数字）
    • finalised为严格布尔型（true/false，不要传字符串的"true"）

• JSON顶层结构不符合HMRC要求

  • 触发逻辑：如果json_encode生成的是数组结构而非顶层对象（比如关联数组被错误改写为索引数组），HMRC无法匹配字段路径，会触发全字段缺失。
  • 验证方式：查看打印的JSON内容，确认顶层结构为{...}而非[...]。

• 新增json_encode结果校验：若返回false直接抛出异常，不要继续发起curl请求。
• 对所有字段做强类型转换：比如数值字段写为'vatDueSales' => (float)$rngBox1，finalised写为'finalised' => (bool)$chkFinaliseConfirm，避免类型不匹配的问题。
• 可在curl执行前打印最终的$postData和header内容，和HMRC官方示例对比排查异常。

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