如何连接HMRC的税务数字化API：新手指南
内容提要
本文介绍为英国税务数字化（MTD）开发HMRC集成的方法。MTD要求自雇者和房东每季度数字化申报收入支出。开发者需在HMRC开发者中心注册沙盒应用、订阅API、实现OAuth 2.0授权码流程获取令牌，并发送防欺诈请求头。同时需注意API版本、state单次使用、GET请求勿带JSON Content-Type等常见陷阱。
延伸解读
MTD覆盖范围将快速扩大
文章指出，自2026年4月起，年收入超过5万英镑的自雇者和房东必须使用MTD。2027年4月门槛降至3万英镑，2028年4月进一步降至2万英镑。这意味着未来两年内，需要MTD软件的用户数量将大约增加两倍。开发者应提前准备，以应对即将到来的需求增长。
沙盒环境与生产环境的关键区别
HMRC提供完整的沙盒环境（test-api.service.hmrc.gov.uk），与生产环境（api.service.hmrc.gov.uk）镜像。开发者应在沙盒中创建虚假纳税人进行测试。文章强调，沙盒和生产环境的主要区别在于基础URL，建议将其放在配置中而非硬编码。此外，选择环境时应使用显式设置（如HMRC_BASE_URL），而非依赖NODE_ENV，以避免生产部署仍指向沙盒时出现凭证错误。
防欺诈请求头：不可忽视的法律要求
HMRC依法要求所有MTD调用必须发送防欺诈请求头，包括描述设备、网络路径和软件的Gov-Client-*和Gov-Vendor-*头。连接方法（如WEB_APP_VIA_SERVER）决定了哪些头是必需的或禁止的。初学者应使用HMRC的测试防欺诈请求头API来验证请求，确保头信息完整正确。忽略这些头可能导致请求被拒绝，且错误信息不明显。
常见陷阱及避免方法
文章列举了五个常见错误：1. 未在Accept头中指定正确的API版本会导致406错误；2. state令牌必须单次使用，验证后立即删除；3. 无请求体的GET请求不应设置Content-Type: application/json，否则可能返回403；4. 必须为每个API订阅应用，否则返回403；5. 重定向URI必须完全匹配，包括斜杠和协议。注意这些细节可以节省大量调试时间。
Q&A
HMRC的MTD for Income Tax是什么？它要求纳税人做什么？
MTD for Income Tax是HMRC推动税务记录和申报数字化的计划。它要求自雇者和房东保留数字记录，每季度向HMRC发送收入和支出的累计更新，并在年底提交最终申报。
如何为HMRC MTD创建沙盒应用？
在HMRC开发者中心注册免费账户，创建应用获取client ID和client secret，设置重定向URI，并订阅所需的API。沙盒基础URL是https://test-api.service.hmrc.gov.uk。
HMRC OAuth 2.0授权码流程中state参数的作用是什么？
state参数用于防御CSRF攻击。生成随机不可猜测的字符串，存储在服务器端，在授权请求中发送，并在回调时验证。验证后必须立即删除，确保单次使用。
为什么HMRC API要求发送防欺诈请求头？
HMRC依法要求软件在每次MTD调用时发送防欺诈请求头，包括Gov-Client-*和Gov-Vendor-*头，描述设备、网络路径和软件信息，以帮助检测凭证滥用。
调用HMRC API时常见的错误有哪些？
常见错误包括：未固定API版本导致406错误；state令牌未单次使用；在无请求体的GET请求中发送Content-Type: application/json导致403；未订阅API导致403；重定向URI不完全匹配。
如何刷新HMRC的访问令牌？
当访问令牌过期时，使用刷新令牌向令牌端点发送POST请求，grant_type=refresh_token，包含refresh_token、client_id和client_secret，以获取新的访问令牌和刷新令牌。
