用于 ERP、电商与支付网关集成的 REST API

把 ERP、电商和支付网关连起来，不只是“做一个 endpoint”。需要清晰的契约、可靠的认证、可预期的错误处理，以及幂等的 webhook。否则每新增一次集成都会变成技术债。

本文介绍 ERP、在线商店与 Yappy、BAC、Paguelo Fácil 等网关之间服务器到服务器的 REST API集成设计。

设计原则

• 显式契约：每个 endpoint 文档化 request、response 和错误码。
• 幂等性：重试 POST 不会重复订单或扣款。
• 版本管理：破坏性变更走 /v2/，不静默打补丁。
• 最小权限认证：按资源划分 scope，绝不在 query string 里放凭据。
• 可观测性：每个请求带 correlation ID，便于跨系统追踪。

资源结构

电商 + ERP 推荐模式：

服务器到服务器认证

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

Webhook 与轮询

Webhook 用于业务事件：支付确认、库存更新、发货。发送方通知；接收方校验签名、持久化并返回 200。

轮询 仅作后备，或外部系统不支持回调时。始终使用指数退避和重试上限。

错误处理

一致的响应便于集成：

            {
  "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 便于跨系统支持。

ERP 宕机时的韧性

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

不破坏客户端的版本管理

• URL 中的 /v1/ 或 header Accept-Version: 1。
• 每次发布更新并公开的 OpenAPI/Swagger。
• 弃用策略：下线 endpoint 前 90 天通知。
• 消费者与提供者之间的契约测试（Pact 等）。

集成检查清单

1. 文档化契约（OpenAPI）及 request/response 示例。
2. 最小 scope 认证与 key 轮换。
3. 创建 POST 的幂等性（header Idempotency-Key）。
4. 带 HMAC 校验和发送方重试的 webhook。
5. 异步同步队列与 dead-letter。
6. 带 correlation ID 的日志，无 PII 和密钥。
7. 公开 endpoint 限流。
8. 独立环境（sandbox/prod）与不同凭据。

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