幂等性
幂等性可以避免同一个操作在请求需要重发时被处理多次。
实际效果是：您可以带着同一个 idempotencyKey 重复发起创建调用，而不会生成一笔新的重复操作。
适用场景
只要存在同一请求因技术原因被再次发送的可能，就应使用幂等性，例如：
- 响应超时
- 网络瞬时故障
- HTTP 客户端的自动重试
- 手动重发同一个调用
这一点在资金类操作中尤为重要，因为它能避免集成方误创建两笔交易、两笔充值或两笔提现。
如何使用
推荐的流程很简单：
- 为该操作生成唯一的
idempotencyKey - 在创建请求中带上这个键
- 若同一操作需要重发，沿用同一个键
- 若是新的操作，生成新的键
实用规则
业务意图相同，就沿用同一个 idempotencyKey。
意图发生变化，就创建新的键。
平台的处理方式
从集成方的角度看，平台会将同一个幂等键识别为同一集成上下文中的同一笔操作。
这样，重试就不会被误当成一笔新的操作。
如果第一次尝试仍在处理中，第二次调用可能会等待原操作的结果后再返回。
幂等键的有效期
平台会从首次发送起，将与该 idempotencyKey 关联的操作结果保留 1 小时。
ℹ️ 幂等窗口
在该窗口内重发同一个 idempotencyKey，会返回原操作的结果，不会创建新的操作。
超过 1 小时后幂等键即过期：此时再用同一个 idempotencyKey 重发将不再被识别为重试，并可能生成一笔新的操作。
如果您的重试流程可能超过这个时长，请确保重发发生在该窗口之内。
idempotencyKey 与 externalCode 的区别
这两个字段的职责不同：
idempotencyKey：标识一次唯一的操作尝试，防止技术层面的重复externalCode：您的业务参考编号，用于在自己的系统中定位该操作
两者可以同时使用，但彼此不能互相替代。
何时需要生成新的幂等键
出现以下情况时请生成新的 idempotencyKey：
- 订单发生变化
- 金额发生变化
- 收款方发生变化
- 这是另一笔操作，即便看起来相似
不要把同一个幂等键用于不同的意图。
实际示例
第一次尝试
{
"amount": 500,
"paymentMethod": "PIX",
"externalCode": "PEDIDO-123",
"idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}
同一操作的重试
如果上一次调用没有得到明确的响应，带着同一个 idempotencyKey 重发相同的报文，平台应将其视为同一笔操作。
{
"amount": 500,
"paymentMethod": "PIX",
"externalCode": "PEDIDO-123",
"idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}
最佳实践
- 在创建类的
POST请求中使用idempotencyKey - 在仍尝试完成同一笔操作期间，保持使用同一个键
- 每一个新的业务意图都生成新的键
- 不要用该键替代
externalCode - 把客户端的超时与重试视为预期内的情况
适用范围
在我们的 API 中，这一概念主要出现在创建类端点上：
小结
幂等性让您可以重复执行同一个意图而不产生重复。
对集成方来说，主要规则是：
- 同一笔操作，同一个
idempotencyKey - 新的操作，新的
idempotencyKey