最佳实践

采用以下模式，可使合作伙伴集成保持可预测、可观测，并确保设施的安全。

一致地标识设施

选择为您的合作伙伴账户配置的关联方式，并始终如一地使用：

• Direct Link：使用设施端点返回的 Performance Hub facility_id。
• Linking Identifier：使用您自己的位置标识符，例如分店 ID、位置代码或门店编号。

请勿在同一请求中同时发送两种标识符。Performance Hub 会使用为您的合作伙伴账户配置的关联方式解析请求。

有关设置指南，请参阅合作伙伴关联方式。

谨慎进行批量写入

Partner API 接受 JSON 请求正文，并在文档注明的情况下专为面向批量的同步流程而设计。请控制批次大小，并确保批次可重试。

默认建议：

• 为获得最佳性能，每个批量请求最多 1000 个项目。
• 负载大小保持在 10MB 以下。
• 不超过每个端点每秒 5 个请求。

速率限制可以调整，并可由您的 Performance Hub 合作伙伴客户经理根据具体情况进行配置。如果您预计会有大量导入、上线流量或报告回填，请在变更窗口之前商定所需的吞吐量。

如果需要同步大型数据集，请将其拆分为确定性的分块，并在您这一侧记录每个分块 ID。这样更容易分析失败的重试。

安全地重试

对于 429、500、502、503 和 504 等暂时性故障，请使用指数退避。

避免密集的重试循环。建议从以下方式开始：

1. 1 秒后重试。
2. 2 秒后重试。
3. 4 秒后重试。
4. 如果操作仍然失败，则停止并发出警报。

对于 400 或 422 等验证失败，请先修正请求再重试。

在支持的情况下使用幂等性

门/闸机控制器解锁端点支持可选的 idempotency_key。对同一合作伙伴、设施和门重复使用相同的密钥时，如有现有结果，将返回该结果。

为所执行的操作使用稳定的密钥，例如您系统中的签到 ID 或访问事件 ID。

除非文档注明某个写入端点支持幂等性，否则请勿假定所有写入端点都支持。

保持源数据整洁

尽可能发送稳定、规范化的值：

• 使用源系统中一致的会员、计划、设施和签到 ID。
• 日期和时间使用 ISO 8601 时间戳。
• 尽可能以国际格式发送电话号码。
• 使用各端点文档中注明的字段发送货币。
• 避免在自由文本字段中塞入本应放在结构化字段中的数据。

同时设计增量同步和完整同步

大多数合作伙伴集成都需要两者：

• 增量同步：用于日常变更。
• 完整对账同步：用于纠正遗漏的事件、历史导入或数据偏差。

您的集成应能够重新发送会员、会员计划或报告快照的当前状态，而不依赖于之前的请求是否成功。

安全地发布 Access Time Windows

将每个会员的 access_time_windows 值视为一个完整的、独立修订的快照：

• 在增量工作进程和对账工作进程之间协调一个单调递增的 access_time_windows_revision 序列。
• 对于不确定或暂时失败的投递，使用相同的修订号和规范化负载进行重试。
• 不更新 access_time_windows 时，请省略该字段。
• 仅在从权威源成功获取数据并证明不再有任何时间窗口后，才发送 []。切勿将上游超时、部分结果或解析失败转化为撤销。
• 保持 external_id 和 scope_key 稳定，并在投入生产前认证每个范围映射。
• 根据为该集成商定的新鲜度策略监控源数据的时效。

有关完整快照、时区、夏令时、取消和测试向量，请参阅权威的 Access Time Windows 生产方指南。

将门禁控制视为安全关键功能

对于门/闸机控制器解锁：

• 在调用 Performance Hub 之前，您的系统必须确定是否允许该人员进入。
• 仅当现场控制器确认继电器已实际解锁后，Performance Hub 才会返回 200。
• 大多数确认在 3-5 秒内完成。
• 超时表示明确的解锁失败，而不是在后台成功。
• 仅按照您自己的访问和安全规则进行重试。

始终记录解锁端点返回的 event_id 和 command_id。

监控您的集成

在开发和上线期间，请使用 Partner Console 请求日志。在生产环境中，还请维护您自己的日志，包含以下内容：

• 请求时间戳。
• 端点。
• 源记录 ID。
• 设施标识符。
• HTTP 状态码。
• Performance Hub 响应正文或错误消息。

当客户询问发生了什么情况时，这些字段可以大大加快支持和对账的速度。