如何用不易崩溃的 REST API 连接 ERP、电商与支付

当在线商店、ERP 和支付网关“说不同的语言”时，业务立刻有感：重复订单、库存不准，或谁也说不清的扣款。问题往往不是“少做一个 endpoint”，而是系统之间缺少清晰契约。

本文说明如何为服务器到服务器集成设计REST API——用通俗类比、具体步骤，以及团队落地所需的技术细节，避免越积越多的技术债。适用于 ERP、电商以及 Yappy、BAC、Paguelo Fácil 等网关。

为什么对业务重要

脆弱的集成像信号差的电话：消息有时到达、有时重复、有时丢失。每次失败都消耗客服时间、手工对账和客户信任。

• 订单：客户已付款，ERP 看不到 → 发货延误。
• 库存：卖了已售罄的商品 → 取消订单与口碑受损。
• 支付：一次尝试扣了两次 → 投诉与拒付。
• 支持：系统间没有共享 ID，没人知道哪里坏了。

关键概念（通俗 + 技术）

把 API 想成银行柜台：有一张表单（request）、一份签过字的回复（response），以及防止同一张单据被扣两次的规则（幂等性）。

• 契约：发什么、收什么、有哪些错误。技术上：带示例的 OpenAPI。
• 幂等性：重试不会重复。技术上：创建 POST 使用 Idempotency-Key header。
• 版本管理：大变更不破坏旧客户端。技术上：/v1/ 与 /v2/。
• 最小权限认证：每个系统只做必要操作。技术上：带 scope 的 API keys。
• Correlation ID：跨系统传递的追踪号，便于支持与日志。

推荐资源结构

电商 + ERP + 支付的常见模式：

实践指南：从零到稳定集成

1. 服务器到服务器认证

• API keys 使用最小 scope（只读库存、只写订单）。
• HMAC webhook：接收方用共享 secret 校验签名。
• 供应商要求时使用 OAuth2 client credentials（SAP、部分云 ERP）。
• 文档化轮换；绝不把 key 放进仓库、query string 或 Docker 镜像。

2. Webhook 与轮询

Webhook 是通知：“支付已确认”。发送方调用；接收方校验签名、保存事件并返回 200。业务事件优先用它。

轮询 是按计划询问：“有新消息吗？”仅作后备，或外部系统不支持回调时使用。始终配合指数退避和重试上限。

3. 可预期的错误

一致的响应让对方系统能决定：重试、告警还是中止？

            {
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order 12345 does not exist",
    "correlation_id": "abc-123"
  }
}
          

• 清晰的 HTTP 码：400（无效输入）、401（认证）、404（不存在）、409（冲突/幂等）、429（限流）、500（内部错误）。
• 生产环境绝不暴露 stack trace 或 SQL。
• 在 header 和 body 中包含 correlation_id，便于跨系统支持。

4. ERP 宕机时

1. 电商在本地创建订单，状态为 pending_sync。
2. 队列 job 带重试和退避尝试同步。
3. N 次失败后进入 dead-letter queue 并告警团队。
4. 客户已看到确认；同步事后对账。

常见错误

• 按“每个页面一个 endpoint”设计，缺少稳定的资源模型。
• 仅因用户访问成功 URL 就标记订单已付款。
• 无幂等地重试 POST，导致重复扣款或订单。
• 在无通知的情况下更改 /v1/ 契约（静默破坏性变更）。
• 日志没有 correlation ID：跨系统支持如同盲人摸象。
• 使用“全能”共享凭据，而不是最小 scope。

集成检查清单

1. 带 request/response 与错误示例的 OpenAPI 契约。
2. 最小 scope 认证与 key 轮换。
3. 创建 POST 的幂等性（Idempotency-Key）。
4. 带 HMAC 校验和发送方重试的 webhook。
5. 异步同步队列与 dead-letter。
6. 带 correlation ID 的日志，无 PII 和密钥。
7. 公开 endpoint 限流。
8. 沙箱与生产分离，凭据不同。
9. 下线 endpoint 前的弃用策略（例如 90 天）。
10. 多团队时做消费者与提供者之间的契约测试。

相关内容 系统集成、巴拿马支付和API 防护 .