3. API 基础：RESTful API 设计原则、HTTP 方法、状态码在财务接口中的应用

在财务系统集成中，RESTful API 是连接企业 ERP、费控平台与发票池的标准通信协议。理解其设计原则、HTTP 方法与状态码，是排查变更索赔与发票匹配异常的前提。本章从财务视角拆解 REST 核心要素，帮助你在接口调用中快速定位问题。

3.1 RESTful 设计原则在财务场景中的映射

REST（Representational State Transfer）强调资源导向、无状态与统一接口。在财务接口中，资源通常是“发票”、“索赔单”、“付款单”等业务实体。

3.2 HTTP 方法在财务接口中的标准用法

财务接口严格遵循 CRUD 语义。错误的方法选择会导致幂等性问题或数据不一致。以下是财务场景中五种核心 HTTP 方法的详细说明：

• GET：查询资源，幂等且安全。例如 GET /api/v2/invoices?status=unmatched 获取所有未匹配发票。
• POST：创建资源，非幂等。例如 POST /api/v2/claims 提交新的变更索赔单。
• PUT：全量替换资源，幂等。例如 PUT /api/v2/invoices/INV2024001 覆盖整张发票信息。
• PATCH：部分更新资源，幂等。例如 PATCH /api/v2/claims/CLM003 仅更新索赔金额字段。
• DELETE：删除资源，幂等。例如 DELETE /api/v2/credit-notes/CN001 作废红字通知单。

3.3 HTTP 状态码：财务异常排查的“第一信号”

状态码是服务端对请求处理结果的标准化反馈。在发票匹配与索赔变更场景中，准确识别状态码能大幅缩短排障时间。

3.4 财务接口调用实战：发票匹配异常排查示例

假设你调用 POST /api/v2/invoice-matching 接口尝试将索赔单与发票进行匹配，收到以下响应：

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "code": "MATCH_TAX_MISMATCH",
  "message": "索赔单与发票的税率不一致",
  "errors": [
    {
      "field": "claim.taxRate",
      "value": "13%",
      "issue": "发票税率为 6%，无法匹配"
    },
    {
      "field": "invoice.taxCode",
      "value": "VAT06",
      "issue": "索赔单税码为 VAT13"
    }
  ]
}

3.5 财务接口设计最佳实践清单

• 版本管理：在 URI 中嵌入版本号，如 /api/v2/，避免破坏性变更影响现有集成。
• 分页与过滤：查询接口支持 ?page=1&size=20&status=unmatched，防止一次返回过多数据。
• 错误响应标准化：统一使用 { "code": "", "message": "", "errors": [] } 结构，便于客户端解析。
• 幂等性支持：对 POST 创建类接口，允许客户端传入 Idempotency-Key 头，防止重复创建索赔单。
• 审计日志：所有修改操作（PUT/PATCH/DELETE）应在响应中返回操作时间戳与操作人信息。