如何向英国税务海关总署的“数字化纳税”API提交季度更新报告

import axios from 'axios';

const HMRC_BASE_URL = 'https://test-api.service.hmrc.gov.uk'; // 沙盒环境

async function request(method, path, accessToken, req, data = null, apiVersion = '2.0') {
  const headers = {
    Authorization: 'Bearer ' + accessToken,
    Accept: 'application/vnd.hmrc.' + apiVersion + '+json',
    ...getFraudHeaders(req),
  };
  // 只有在请求体存在的情况下，才需要设置JSON Content-Type。否则HMRC的边缘服务器会拒绝接收没有请求体的GET请求，并返回403错误。
  if (data !== null && data !== undefined) {
    headers['Content-Type'] = 'application/json';
  }
  const res = await axios({ baseURL: HMRC_BASE_URL, method, url: path, headers, data });
  return res.data;
}

req参数代表用户的请求信息（在我的代码中，这是Express框架中的Request对象），欺诈预防头部信息中的客户端详细数据就是从这里获取的。只要有了承载令牌以及这个辅助函数，你就可以开始提交相关文件了。

MTD模式中季度更新的具体运作方式

季度更新并不等同于纳税申报表。它实际上是一组累计数据，反映了企业在当前纳税年度内迄今为止所赚取的收入和支出的金额，这些分类与自我评估系统已经使用的分类是一致的。

关键在于“迄今为止”这个时间点。每次更新都是累积性的，它涵盖的是从纳税年度开始到当前更新周期结束期间的所有数据，而不仅仅是最近三个月的信息。英国政府关于提交季度更新的指南中明确规定了各更新周期的标准时间范围及其截止日期：

这种设计还有一个不错的副作用：如果用户在之前的某个季度发现了错误，那么在后续的更新中就可以直接进行修正。HMRC提供的端到端服务指南中也明确指出：每次更新都会使之前的数据失效，因为每个更新周期都是从4月6日开始的。

对于那些会计年度从4月1日开始的客户，他们也可以选择按日历周期来申报（例如4月1日至6月30日等），且截止日期同样不变。您无需将这两种方式硬编码在程序中，因为Obligations API会返回准确的日期信息。

英国税务海关总署将每一项需要更新的资料称为“义务事项”：对于每个从事自雇或房地产经营的业务来说，每个纳税年度会有四项这样的义务事项，再加上每年一次的纳税申报。

以下是您即将完成的整个处理流程：

步骤1：如何获取业务ID

每个与自雇相关的接口请求都需要一个businessId，这是英国税务海关总署用于识别某项收入来源的标识符。如果一个人既从事自雇活动，又拥有房产进行出租，那么他就会有两个这样的ID。您可以通过Business Details API，使用客户的国民保险号码来获取这些ID：

// 使用Business Details API v2.0获取信息
const result = await request(
  'GET',
  '/individuals/business/details/' + nino + '/list',
  accessToken,
  req,
  null,
  '2.0',
);

const businesses = result.listOfBusinesses ?? [];
const soleTrade = businesses.find((b) => b.typeOfBusiness === 'self-employment');
const businessId = soleTrade?.businessId;

这些信息存储在listOfBusinesses数组中，每个条目都包含typeOfBusiness（如“self-employment”、“uk-property”等）、businessId，有时还会包含tradingName。在沙箱测试环境中，自雇业务的ID通常形如XBIS12345678901。

英国税务海关总署的建议是直接存储这些ID，而无需在每次调用接口之前都去查询它们。由于这个列表很少会发生变化，通常只有当客户新增或停止某项业务时才会更新，因此您可以在客户连接系统时或者他们主动询问时才去刷新这个列表。

步骤2：如何了解应缴纳的税款金额

接下来，您可以使用Obligations API来查询哪些期限内的义务事项尚未结清。这个接口目前处于3.0版本：

// 使用Obligations API v3.0获取信息
const raw = await request(
  'GET',
  '/obligations/details/' + nino + '/income-and-expenditure?status=open',
  accessToken,
  req,
  null,
  '3.0',
);

这些义务按照业务类型进行分类，相关日期信息则嵌套在下一层级中：

{
  "obligations": [
    {
      "typeOfBusiness": "self-employment",
      "businessId": "XBIS12345678901",
      "obligationDetails": [
        {
          "periodStartDate": "2026-04-06",
          "periodEndDate": "2026-10-05",
          "dueDate": "2026-11-07",
          "status": "open"
        }
      ]
    }
  ]
}

在用户界面中，这种嵌套结构会很快导致显示效果变得混乱，因此我将其优化为每项义务只显示在一行中，并将相关业务信息也放在同一行中；同时，我会筛选出那些状态为“open”且到期日期最早的义务：

function flattenObligations(raw, businessId) {
  return (raw.obligations ?? [])
    .filter((group) => group.businessId === businessId)
    .flatMap((group) =>
      (group(obligationDetails ?? []).map((d) => ({
        businessId: group.businessId,
        periodStartDate: d.periodStartDate,
        periodEndDate: d-periodEndDate,
        dueDate: d.dueDate,
        status: (d.status ?? '').toLowerCase() === 'fulfilled' ? 'fulfilled' : 'open',
      }),
    );
}

const next = flattenObligations(raw, businessId)
  .filter((o) => o.status === 'open')
  .sort((a, b) => a.dueDate.localeCompare(b.dueDate))[0];

在根据这些数据构建用户界面之前，有 three 点需要注意：

首先，这些义务并没有专门的“周期标识键”；它们的开始日期和结束日期实际上就代表了相应的统计周期，而你在第三步中需要返回的也正是这些信息。如果你需要一个固定的键值对，可以从这两个日期中推导出一个。

其次，应该直接从响应数据中获取 dueDate ，而不是自行计算它。因为这些日期是由 HMRC 设定的，而且他们之前也曾经更改过这些规定，所以应该以 API 提供的数据为准，而不要在你的代码中编写自定义的日期计算逻辑。

第三，过滤条件也有相应的规则：fromDate 和 toDate 必须一起发送，并且两者之间的时间间隔不得超过 366 天；此外，使用 businessId 进行过滤时，也需要提供 typeOfBusiness 参数。像上面那样，在你的代码中先获取所有状态为“open”的义务信息，然后再进行过滤处理，就可以避开这两个问题。

步骤 3：如何构建累计汇总报表

现在来看数据内容。自我雇佣业务 API 将这种报表称为“累计周期汇总报表”，它由四个部分组成：

• periodDates：必填项。指的是你正在报告的统计周期的开始日期和结束日期，这些数据直接来源于各项义务信息。

• periodIncome：包括 turnover（收入、费用和销售额）、other 类别的业务收入，以及 taxTakenOffTradingIncome。

• periodExpenses：可以选择提供 consolidatedExpenses 的合计数值，也可以进行详细分类列出。

• periodDisallowableExpenses：指各项明细费用中那些不能用于抵扣税款的部分。

以下是2026-27年度第二季度的完整、有效的申报表格，其中所有费用均以合并后的数值进行呈现：

{
  "periodDates": {
    "periodStartDate": "2026-04-06",
    "periodEndDate": "2026-10-05"
  },
  "periodIncome": {
    "turnover": 28450,
    "other": 0
  },
  "periodExpenses": {
    "consolidatedExpenses": 4310.45
  }
}

在详细列出的费用表格中，这些合并后的数值会被分解为与自我评估表格中的分类相对应的各项，例如costOfGoods、carVanTravelExpenses、adminCosts以及professionalFees。如果某项费用中包含个人开支，那么不允许计入申报的部分应被记录在相应的字段中：

"periodExpenses": {
  "costOfGoods": 2100,
  "carVanTravelExpenses": 1640.2,
  "adminCosts": 185.99
},
"periodDisallowableExpenses": {
  "carVanTravelExpensesDisallowable": 410.05
}

这两种申报方式不能同时使用。如果既提交了consolidatedExpenses，又提供了详细列出的费用信息，系统会返回错误提示RULE_both_EXPENSES_supPLIED。由于每项不允许计入申报的费用都对应着详细的分类项目，因此这些不允许扣除的费用应通过详细列出的表格进行申报。

const CONSOLIDATED_EXPENSES_TURNOVER_LIMIT = 90_000;

function checkConsolidatedExpensesLimit({ turnover, usesConsolidatedExpenses }) {
  if (!usesConsolidatedExpenses) return null;
  if ((turnover ?? 0) >= CONSOLIDATED_EXPENSES_TURNOVER_LIMIT) {
    return (
      '当营业额达到90,000英镑时，不得再使用合并后的费用申报方式。'
      '请详细列明各项费用。'
    );
  }
  return null;
}

// PUT /individuals/business/self-employment/{nino}/{businessId}/cumulative/{taxYear}
// 自雇业务API v5.0
await request(
  'PUT',
  '/individuals/business/self-employment/' + nino + '/' + businessId + '/cumulative/' + taxYear,
  accessToken,
  req,
  summary,
  '5.0',
);

// 使用“POST”请求
const { calculationId } = await request(
  'POST',
  '/individuals/calculations/' + nino + '/self-assessment/' + taxYear + '/trigger/in-year',
  accessToken,
  req,
  {}, // 必须是一个空对象，不能为null（请参阅相关注意事项）
  '8.0',
);

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForCalculation(nino, taxYear, calculationId, accessToken, req) {
  const path =
    '/individuals/calculations/' + nino + '/self-assessment/' + taxYear + '/' + calculationId;
  await sleep(5000); // 英国税务海关总署建议在触发计算后至少等待五秒钟

  for (let attempt = 0; attempt < 5; attempt += 1) {
    try {
      return await request('GET', path, accessToken, req, null, '8.0');
    } catch (err) {
      // 只有当返回码为404时，才表示计算结果尚未准备好；其他错误都需要被重新抛出。
      if (err.response?.status !== 404 || attempt === 4) throw err;
    }
    await sleep(1000 * (attempt + 1));
  }
}

{
  "metadata": {
    "calculationId": "f2fb30e5-4ab6-4a29-b3c1-c7264259ff1c",
    "taxYear": "2026-27",
    "calculationType": "in-year",
    "periodFrom": "2026-04-06",
    "periodTo": "2026-10-05"
  },
  "calculation": {
    "taxCalculation": {
      "totalIncomeTaxAndNicsDue": 3902.6
    }
  }
}