如何向HMRC的数字化税务API提交季度更新
内容提要
本文介绍英国数字化税务季度申报的开发流程：通过Business Details API获取businessId，用Obligations API查询待报期间，构建累计收支摘要并PUT提交，最后触发并读取税务计算。同时提醒常见陷阱，如沙盒数据过期、重复提交覆盖旧数据、零值也须上报。
延伸解读
累计申报机制：修正与覆盖
MTD季度更新采用累计模式，每次提交覆盖从税年开始到当前期末的所有数据。这意味着如果发现之前季度的错误，无需单独修正，下次更新时直接包含正确数据即可。但这也带来风险：若提交时未包含之前季度的数据，会覆盖并丢失已报信息。因此，每次提交前应从HMRC或自有记录中获取完整的年初至今数据，确保累计值准确。
合并支出申报的£90,000门槛
年营业额低于£90,000的纳税人可使用合并支出总额申报，简化流程。但由于更新是累计的，每次提交时需检查年初至今的营业额是否达到£90,000。一旦达到，必须改用逐项支出申报，否则HMRC会拒绝。开发者应在服务端实施此检查，避免无效提交。
沙盒环境常见陷阱
沙盒默认返回过时数据，导致累计端点报错。需发送Gov-Test-Scenario: DYNAMIC获取当前年度义务。此外，累计端点默认无状态，GET请求返回固定数据，要测试完整流程需使用STATEFUL场景。这些细节容易忽略，但会阻碍开发测试。
生产环境准入限制
HMRC目前不再接受针对2026-27季度更新产品的新生产凭证请求，但沙盒仍开放。开发者可以立即构建和测试，但在计划上线前务必查看Self Employment Business API页面的通知，确认生产环境可用性，避免影响发布计划。
Q&A
如何通过HMRC API找到企业的businessId？
使用Business Details API，调用GET /individuals/business/details/{nino}/list，从返回的listOfBusinesses数组中筛选typeOfBusiness为'self-employment'的条目，获取其businessId。
如何查询当前需要提交的季度更新义务？
使用Obligations API，调用GET /obligations/details/{nino}/income-and-expenditure?status=open，返回按业务分组的义务列表，每个义务包含periodStartDate、periodEndDate和dueDate。
构建累计摘要时，合并费用和分项费用有什么区别？
合并费用使用consolidatedExpenses字段，适用于年营业额低于90,000英镑的客户；分项费用则需列出具体类别如costOfGoods、carVanTravelExpenses等，并可包含periodDisallowableExpenses。两者不能混用，否则会返回RULE_BOTH_EXPENSES_SUPPLIED错误。
提交季度更新时，PUT请求的URL格式是什么？
PUT /individuals/business/self-employment/{nino}/{businessId}/cumulative/{taxYear}，其中taxYear格式为YYYY-YY，期间日期在请求体中传递。成功返回204 No Content。
如何触发并读取税务计算？
使用Individual Calculations API，先POST /individuals/calculations/{nino}/self-assessment/{taxYear}/trigger/in-year触发计算，返回202和calculationId；等待至少5秒后，GET /individuals/calculations/{nino}/self-assessment/{taxYear}/{calculationId}获取结果，若返回404则重试。
提交季度更新时有哪些常见陷阱？
常见陷阱包括：沙盒默认数据过期，需使用Gov-Test-Scenario: DYNAMIC；新提交会覆盖旧数据，需预填累计值；零值也必须上报；不能提前超过10天提交；义务状态更新可能延迟一小时；触发计算时需发送空对象{}而非null。
