Nordlet

← 博客

什么是会计 API？面向平台构建者的通俗指南

对会计 API 的通俗定义，它与税务 API 或支付 API 的区别，以及在对接前需要检查的要点。

Nordlet Team · · 2 分钟阅读

会计 API 是一种让一个程序去维护另一个程序账目的接口。你的软件通过 HTTP 发送一条财务事件，该 API 会将该事件转换为针对科目表（Chart of Accounts）的平衡复式记账分录（double-entry journal entries），将其持久化存储以防被静默篡改，应用相应的税务处理，并从同一接口返回报表、单据和导出文件。

这个定义已经完成了大部分核心工作。本文其余的内容都是这一定义的自然延伸。

一句话总结

会计 API 接收来自你的应用程序的财务事件，将每一个事件转换为平衡的分录，连同税务处理及支撑凭证一起进行不可变存储，并将生成的分类账、单据和报表作为可编程的端点暴露出来。

如果一个产品自称为会计 API，却无法生成记账分录，那么它只是借用了好听名字的其他产品。这并不一定不好，但这意味着它无法胜任你接下来要委派给它的任务。

会计 API 不是什么

有四个相邻的产品类别经常与会计 API 混淆，通常是在项目推进到后期时。

类别 它的功能 它不做的事
税务计算 API 为交易返回正确的税率或税额 记账，或在法定保存期内存储决策背后的凭证
支付 API 在各方之间划转资金并报告这些变动情况 记录在付款与结算之间产生的佣金收入、应交增值税或对卖家的应付账款
聚合或聚合器 API 读取和写入客户现有会计软件中的数据 充当记录系统（System of Record）；你的账目依然保存在每个客户原有的工具中
报表或 BI API 从现有分类账中读取数据并将其可视化 创建这些数据所派生的分录

这些产品各有其切实的用途。一个需要成为记录系统的平台，其底层需要的是会计 API，而不是替代它。

会计 API 必须做到的五件事

1. 记录平衡的分录。 每一个事件都会转化为借方和贷方，两者的总额必须相等。当买家在某家平台支付 100 欧元，而平台收取 15 欧元佣金时，该分录会借记（debit）一个清算账户 100 欧元，贷记（credit）应付卖家款项 85 欧元，并贷记佣金收入 15 欧元。这不是繁文缛节的记账仪式，而是一种结构化检查，能够在集成错误影响到报表之前将其拦截。

2. 保留历史记录。 已过账的分录不会被修改。纠错的方式是通过红字冲销加上一张更正分录，两者都与原始分录相关联。已关闭的月份会被锁定，确保没有任何新分录能落入其中。

3. 处理税务。 对于欧盟贸易，这意味着确定供应地、反向征收（reverse charge）、根据官方注册库验证增值税号（VAT identification numbers），以及存储用于合规决策的凭证，所有这些都随交易一起存储，而不是在计算完成后被丢弃。

4. 与外部资金进行对账。 从不对账的账目只是一种猜测。API 必须能够摄入银行对账单或服务商结算单，并将其与已记录的内容进行匹配。

5. 导出。 以人类会计师和税务机关可接受的格式输出报表、单据和审计文件。

一个能够完成前三项但无法完成最后两项的产品，仍然会让财务人员每月疲于处理电子表格。

实际调用长什么样

其底层机制比会计本身更简单。在 Nordlet 的 API 中，每个操作都是一个具有可预测结构的 RPC 风格的 POST 请求：

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

你创建销售发票，然后对其进行开具（issue）。开具的瞬间就是会计分录发生的时候：单据获得连续的编号，平衡的记账分录过账，增值税行也随之记录。你的平台永远不需要手动拼凑借方和贷方。

这段代码片段中有三个细节比端点名称更重要：

  • 密钥的权限范围（Scope）。 一个密钥带有诸如 sales:write 之类的权限，因此集成只能获取它所需的访问权限。
  • 幂等键（Idempotency key）。 使用相同的有效负载（payload）重试相同的请求，你将获得已存储的响应，而不是生成第二张发票。如果使用相同的密钥发送不同的有效负载，请求将被 idempotency_key_reuse 拒绝，而不是被默默接受。
  • 以字符串表示金额。 金额是十进制字符串，而不是浮点数，因为浮点数会以在年末显现的方式丢失美分精度。

它在架构中的位置

你的应用程序仍然是前端和业务事件的来源。会计 API 则成为其背后的财务记录系统。整个流程通常如下：

  1. 你的产品中发生了某项业务：订单、退款、结算或订阅续费。
  2. 你的后端携带着事件和幂等键调用会计 API。
  3. API 发布记账分录、应用增值税，并返回用于关联你自身记录的标识符。
  4. 诸如 sale_invoice.paid 的 Webhook 会在状态发生变化时通知你的系统，从而让你能够对事件作出反应，而无需轮询。
  5. 银行交易通过银行直联（bank feed）或对账单导入到达，并与已记录的单据进行匹配。
  6. 期末时，根据相同的数据生成报表和税册，并锁定已关闭的月份。

上述清单中的任何环节都不需要人工打开会计应用程序。这就是该产品类别的意义所在。

它与替代方案的对比

方法 启动成本 审计立场 随交易量扩展的能力
电子表格与手工录入 最低 薄弱；历史记录可修改 否
会计软件加上 CSV 导出 低 完全取决于规范程度 差；需要人工导入文件
针对每个客户自有账目的聚合器 API 中等 继承客户所用工具的特性 是，但你永远不拥有记录
嵌入式会计 API 中等 如果分类账是不可变的且期间可锁定，则较强 是
自建分类账 最高 只有在你同时构建了控制机制时才较强 是，且需要永久维护

对于某些团队而言，自建分类账是一个合理的选择。我们在面向市场的自建与购买指南中对此进行了更详细的探讨。

在对接前需要检查的要点

  • 余额是派生出来的还是存储的？ 询问卖家余额是通过查询日记账明细计算出来的，还是由某个字段更新得来的。只有前者才能经受住审计。
  • 重试时会发生什么？ 发送两次相同的请求并计算分录数量。
  • 能否编辑已过账的分录？ 答案应当是不行，且应提供有据可查的更正路径。
  • 锁定的期间是否确实会拒绝过账？ 在沙箱中进行测试。对于日期在锁定期间内的过账，Nordlet 会返回 409。
  • 如何表示金额？ 使用十进制字符串或整数的最小货币单位。切勿使用浮点数。
  • 审计记录中包含什么？ 操作人、操作、实体以及变更本身，且应当是可查询的，而不是埋藏在日志文件中。
  • 速率限制（Rate limits）是怎样的？ Nordlet 允许每个 API 密钥每分钟进行 300 次请求，并在响应标头中报告你的剩余额度。无论具体数字是多少，在设计同步机制之前务必弄清楚。
  • 如何导出数据？ 以可提供给会计师的格式导出报表、单据和日记账。

在沙箱公司环境中，上述每一项都可以在一个下午内完成测试。供应商的功能列表不能作为证据，可复现的测试才可以。

FAQ

会计 API 等同于会计软件吗？

它本质上就是会计软件，只是界面发生了转移。传统的会计软件将操作人员置于分类账前，而会计 API 则将你的代码置于其中。底层的法律义务、复式记账结构和报表都是相同的。

使用会计 API 后，我还需要会计师吗？

是的。API 实现了记录、计算和报告的自动化。它不会对科目分类、准备金或特定合同的处理方式做出主观判断，并且在大多数国家/地区，它不能签署或提交你的法定财务报表。

在不理解复式记账的情况下，我能使用会计 API 吗？

部分可以。一个优秀的 API 会根据发票等业务单据为你构建记账分录。但在阅读报表或向审计师解释余额时，你仍然需要理解这些科目的含义。

会计 API 和分类账（Ledger）API 有什么区别？

分类账 API 记录账户之间平衡的资金变动。而会计 API 在此基础上增加了法定层面：具有合法编号的单据、增值税处理、税册、固定资产、期末结账以及监管机构期望看到的报表。每个会计 API 都包含一个分类账，但并非每个分类账都是会计系统。

集成一个会计 API 需要多长时间？

对于首个可行的流程（创建客户、开具发票、接收付款、查看记账分录），如果使用带类型的 SDK 和沙箱环境，计划几天时间即可，而无需数周。涵盖退款、更正、多币种、对账和期末结账的生产环境集成则是一项更大的工作，具体工期取决于你的产品实际会产生多少此类业务场景。

延伸阅读