谈到通过API连接农场、饲料公司和核查机构时，人们很容易先讨论“要创建哪些端点”。但技术上的连通，与各方以相同含义理解同一事实，并不是一回事。如果农场的feed_amount究竟是实际饲喂量还是采购量，饲料公司的batch_id究竟是生产批次还是交付单位，核查机构的approved究竟表示收到数据还是已完成减排量核查，各方理解不一，API就会成为快速传播错误的通道。

碳数据API并非简单的系统对接。它是一份交换以下信息的数字契约：谁提交了何种依据，哪项计算使用了该依据，以及谁依据什么标准作出了判断。应先定义业务含义与责任，再设计URL和JSON。

误解：把所有原始数据集中到一个数据库，就更容易核查

集中化可以使检索更方便，却不能一并解决权利和责任问题。农场持有工作日志和传感器原始数据，饲料公司管理产品规格与批次信息，核查机构则保存独立判断及其证据。如果不加区分地把各主体负责的原件复制到一个地方，最新版本、纠正权限、商业秘密和保存期限都会变得模糊。

赋予核查机构对所有系统的写入权限，也可能损害其独立性。核查人员应核对提交材料，并留下问询、判断和补充要求，但不得修改农场的原始数据或饲料批次。API设计的重点不应只是汇集数据，而应明确原件的权责主体，以及读取、提交和判断的权限。

此外，并非有了API就具备互操作性。字段名、单位、时区、标识符、状态转换、错误处理和版本政策都必须一致。OpenAPI规范提供一种与语言无关的接口描述，使人和计算机无需查看源代码即可理解HTTP API的功能。但碳领域的业务含义仍需由各组织另行达成共识。

第一步是按利益相关方区分原始记录和事件

农场的原始记录包括畜舍、传感器、个体或群体标识，饲养数量，饲喂、通风、清洁、转移事件，测量值，校准和设备状态。饲料公司的原始记录包括产品代码、生产批次、成分与有效期、出库和交付数量、使用说明及变更历史。核查机构的原始记录包括核查范围、准则、重要性判断、样本、问询、发现事项、结论和签署时间。

三方需要共享的不是全部内部资料，而是建立关联所必需的最少事件。例如可以定义FeedDelivered、FeedApplied、SensorObserved、CalibrationPerformed、DataExcluded、CalculationExecuted、EvidenceSubmitted、FindingRaised、StatementVerified等业务事件。名称可因实现方式而异，但不能把“饲料已经交付”与“已经实际饲喂给牲畜”合并为一个事件。

GS1 EPCIS是一项以共同语言共享供应链事件的可视化事件标准。它不是必须采用的标准，但可作为区分产品、地点、时间和业务环节的参考模型。

共同数据契约必须包含的内容

第一是稳定的标识符。应为组织、农场、畜舍、设备、传感器、饲料产品、批次、交付、应用项目和核查任务分别分配不同的ID。显示名称可能改变，因此不应作为键使用。不要混淆外部标识符与内部ID，并应记录签发机构和命名空间。

第二是数值与单位。不要只发送12.3，还应同时发送数值、单位、测量原理、检出限和质量状态。ppm浓度与kg CH₄排放量是不同概念，因此应使用不同的字段和模式。单位换算不得覆盖原始值，并应保留所用换算公式及其版本。

第三是时间与有效期。应区分观测时间、事件发生时间、系统接收时间和纠正时间。使用RFC 3339等包含UTC偏移量的格式，并明确期间的开始、结束及边界是否包含在内。饲料应用期与核查对象期间可能不同，因此不能缩减为一个日期字段。

第四是状态与状态转换。应确定draft、submitted、accepted、questioned、superseded、verified、rejected分别表示什么，以及谁有权改变状态。accepted可能仅表示通过格式检查，并不代表内容核查已经完成。应记录各状态的责任主体和下一步允许执行的操作。

第五是数据谱系。W3C PROV-O为表达数据实体Entity、使用或生成该实体的活动Activity、责任主体Agent及其关系提供了基础。实现形式不一定非得采用RDF，但可以一致地保留derived_from、generated_by、attributed_to、method_version、source_hash等关系。对于哈希，还必须说明所用算法，以及哈希对象是原始字节还是规范化后的记录，才能复现结果。应能够从最终减排量反向追溯到原始数据和计算执行记录。

第六是纠正方式。如果直接修改已提交的原始数据，核查人员所查看的版本就会消失。发现错误时，应创建新版本，将旧版本关联为superseded，并记录纠正原因和批准人。删除请求可能与法定保存要求冲突，因此应按数据类型分别制定保存、去标识化和阻断访问政策。

现场场景：交付2吨饲料不等于开展2吨减排活动

假设饲料公司发送了一项交付2吨低甲烷饲料的事件。农场系统确认已收货，但实际饲喂记录为1.7吨，另有0.2吨库存和0.1吨废弃。如果API把交付量视为应用量，就会高估减排活动。核查机构应询问交货单、库存、饲喂日志和目标牲畜数量之间的关系。

在正确的模型中，FeedDelivered和FeedApplied是独立事件，并通过同一个批次ID关联。应用事件应包含期间、畜舍或目标群体、数量、单位、记录方法、记录人和证据链接。核查机构不修改原件，而是创建FindingRaised，要求说明0.3吨差异。农场随后补充库存和废弃事件，并创建提交材料包的新版本。

之后，计算服务使用已获批准的应用量、测量期间和方法版本生成结果。核查结论不仅引用结果值，也引用所用证据包和计算执行ID。这样，日后饲料批次信息得到纠正或计算公式发生变化时，才能找出受影响的结果和报告。

认证与权限应按操作而非合作方类型设计

2025年发布的RFC 9700是OAuth 2.0最新安全最佳实践，涵盖针对令牌重放攻击的相关缓解措施，以及权限和受众范围限制的设计。在服务器间对接中，应区分组织身份与工作负载身份，并根据风险程度和服务架构制定令牌生命周期及密钥轮换政策。

权限不能止于“饲料公司用户”这类宽泛角色。可以像farm:A/read:aggregates、farm:A/write:delivery、verification:case-123/read:evidence这样限制对象和操作。批量下载、访问原始数据、纠正和作出核查结论应要求更高权限，并列为审计对象。农场撤回同意或合同终止时，除了中止令牌，还必须处理既有副本的使用权和保存权。

重试、错误和版本决定运行可靠性

农场网络可能频繁中断，因此重试应是默认操作。为避免同一项交付或观测被多次登记，应使用事件ID和幂等键。服务器必须明确返回处理结果；即使成功响应丢失后重新发送请求，也应得到相同结果。批量上传应提供批次ID、逐项成功或失败信息以及续传位置。

错误应区分格式、权限、重复、引用ID不存在、模式过期和待审核，并提供是否可重试的信息以及用于追踪的关联ID。completed、rejected等状态值只是示例；实际API规范应以表格固定允许使用的状态和转换条件。

版本并不只是URL中的数字问题。应制定字段、枚举值和单位变更的兼容政策，并将OpenAPI文档与代码一同管理。还应将弃用日程及替代方法通知合作方。

面向核查机构的API必须提供“可审计性”

核查并不是确认API响应为200。ISO 14064-3涵盖组织、项目和产品的温室气体声明核查与审定原则和要求；如有具体项目机制，还需满足其附加要求。因此，API不应自动宣称符合某项标准，而应提供材料，使核查人员能够评估边界、准则、依据、变更历史和重大错误。

面向核查的只读界面或导出内容应包括提交时的快照、模式和方法版本、原始数据哈希、排除清单、问询与答复，以及结论历史。如果只能查询当前值，就无法复现过去审核的内容。大规模原始数据可以通过签名URL、限时访问URL或单独的数据包提供，但必须记录访问和下载。

实施检查清单

  • 是否定义了农场、饲料公司和核查机构各自负责的原始记录与共享事件？

  • 是否将交付、收货、实际饲喂、库存和废弃区分为不同事件？

  • 组织、农场、畜舍、设备、饲料批次和核查任务是否拥有稳定ID？

  • 是否为每个值提供单位、时间、质量状态以及测量或计算方法版本？

  • 是否区分提交、格式接收、内容审核和核查完成状态？

  • 纠正是否以新版本和原因保留，而非覆盖原件？

  • 能否从最终声明反向追溯到原始数据、活动和责任主体？

  • 是否将令牌权限按农场、期间、数据类型和操作限制在最小范围？

  • 重试和批量上传是否不会造成重复汇总？

  • 错误代码、关联ID和是否可重试是否明确？

  • 是否具备OpenAPI规范、示例、变更通知和消费者契约测试？

  • 核查人员能否以只读方式查看提交时的快照和变更历史？

结论：优秀的API保存责任与含义，而不仅是建立连接

API是否成功，不能用调用次数来判断。必须区分交付与应用、浓度与排放量、接收与核查，并保存每项数据原件的责任主体。如果标识符、单位、时间、状态、谱系、纠正和权限没有达成共识，快速连接只会带来快速混乱。

因此，合理的顺序是：定义事件和证据责任、制定数据契约、落实最小权限、制定重试和版本政策、设计核查快照。OpenAPI、OAuth、EPCIS、PROV等标准是表达和交换这份契约的工具。某项标准的名称并不会自动保证碳声明具备资格。只有API依照各项目机制的方法学和核查标准，不间断地呈现Evidence Chain，系统间的连接才能转化为信任。

来源