Partner API 接入基础

可靠接入应从公开 API 契约、一个受控凭据和小范围验证请求开始。应按 MangoOTP 文档中的字段与状态码开发，不要复制其他系统的假设。

创建唯一有效 API Key

每个用户最多保留一个有效 API Key。原始值只在创建时展示一次，应立即保存到受保护的秘密管理位置，不要期待列表再次返回。

处理“Partner API 接入基础”时，应把“创建唯一有效 API Key”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

配置必填 IP 白名单

每个 Key 都必须配置非空的 IPv4 或 CIDR 白名单。请求来源地址必须符合平台解析后的允许范围。

处理“Partner API 接入基础”时，应把“配置必填 IP 白名单”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

使用 X-API-Key 鉴权

Partner 接口只接受 X-API-Key，USER JWT 不能替代。凭据必须通过 HTTPS 发送，不能放在查询参数、浏览器页面、公开源码或日志中。

处理“Partner API 接入基础”时，应把“使用 X-API-Key 鉴权”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

下单前查询目录与价格

按照文档调用接码或租赁目录和价格接口。价格结果表示平台当前售价与库存估算，不代表已经为请求保留库存。

处理“Partner API 接入基础”时，应把“下单前查询目录与价格”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

使用 partnerOrderNo 保证幂等

每次业务尝试生成稳定 partnerOrderNo。相同编号与相同参数重试应得到同一逻辑结果；相同编号但参数不同会被拒绝。

处理“Partner API 接入基础”时，应把“使用 partnerOrderNo 保证幂等”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

正确使用 maxPrice

接码 createOrder 必须提供 maxPrice；当前售价高于该值时，在冻结资金前拒绝。租赁 V1 不接受 maxPrice。

处理“Partner API 接入基础”时，应把“正确使用 maxPrice”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

超时后查询原订单

遇到结果不明的超时时，应使用同一订单引用查询，不要创建新的 partnerOrderNo。列表分页必须有界，状态必须来自已知集合。

处理“Partner API 接入基础”时，应把“超时后查询原订单”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

按 code 与 traceId 处理错误

程序只能依赖稳定错误 code，并保留 traceId 供排查。面向人的 message 可能随语言变化，不能作为自动化判断依据。

处理“Partner API 接入基础”时，应把“按 code 与 traceId 处理错误”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

实际操作检查清单

1. 核对“创建唯一有效 API Key”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
2. 核对“配置必填 IP 白名单”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
3. 核对“使用 X-API-Key 鉴权”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
4. 核对“下单前查询目录与价格”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
5. 核对“使用 partnerOrderNo 保证幂等”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
6. 核对“正确使用 maxPrice”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
7. 核对“超时后查询原订单”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
8. 核对“按 code 与 traceId 处理错误”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。

最终业务状态和账户流水是判断结果的依据。截图或客服沟通中不要发送密码、完整验证码、认证密钥、Access Token、API Key 或未遮挡的身份材料。更多说明可查看 MangoOTP 帮助中心。