跳转到主要内容

​
环境

Flex Forward API 提供两个环境，分别用于生产运营和开发测试。

​
可用环境

环境基础 URL物流商连接
生产https://api.flexforward.com生产物流商服务
开发https://sandbox.flexforward.com物流商沙盒服务
所有请求必须使用 HTTPS。通过 HTTP 发送的请求将被拒绝。

​
开发环境

开发环境连接至物流商的沙盒服务（如 YunExpress 沙盒）。适用于：
  • 在不创建实际配送的情况下测试您的集成
  • 验证请求格式和响应处理
  • 开发错误处理和重试逻辑
沙盒物流商服务可能返回模拟的追踪数据和标签文件。响应时间和可用的追踪状态可能与生产环境不同。

​
沙盒测试数据

开发环境支持生成可预测追踪响应的测试值。使用这些来验证您的集成能正确处理不同的配送结果：
收件人邮编模拟追踪结果
90001Delivered — 配送正常完成
90002Exception — 发生派送例外
90003InTransit — 货件持续运送中
90004Cancelled — 配送已取消
测试值和模拟响应可能会变更。如需最新的沙盒测试数据，请联系 Flex Forward 团队。

​
认证信息分离

每个环境请使用单独的 API 令牌。请勿在开发环境中使用生产认证信息，反之亦然。
生产令牌可访问生产的物流商服务。发送请求前请务必确认您的目标环境。

​
令牌最佳实践

  • 将令牌存放在环境变量或密钥管理器中
  • 切勿在源代码中硬编码令牌或将其提交至版本控制
  • 每个环境使用单独令牌，以防止开发期间意外发送生产请求
  • 定期轮换令牌
令牌使用方式和错误响应的详细信息请参阅身份验证。

​
速率限制

目前未强制实施速率限制。建议每个账户将请求量控制在 每秒 10 个请求 以下。速率限制头部（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset）目前不包含在响应中。 如果未来引入速率限制，将通过变更记录提前通知。如需针对高吞吐量集成讨论容量规划，请联系 Flex Forward 团队 [email protected]。

​
上线检查清单

从开发环境切换至生产环境前：
  • 开发令牌已发放并测试完成
  • 生产令牌已获 Flex Forward 团队批准
  • 配送账户已配置生产物流商
  • 在开发环境中标签创建测试成功
  • 标签文件获取已测试
  • 追踪获取已测试
  • 幂等性行为已验证（重复密钥返回相同结果）
  • 已实现所有状态码的错误处理
  • 所需物流商和物流路线配置已确认

​
HTTPS 要求

所有 API 端点需要 TLS 1.2 或更高版本的 HTTPS。通过 HTTP 发送的请求将收到连接错误。