版本兼容与支持范围

核对当前 API、SDK 示例与已发布安装包的差异。

API v1更新于 2026年10月16日

先选接入方式

首次接入推荐使用快速开始和下载示例：通过 HTTP 完成 Customer、会话与持有读取，无需安装 SDK。本开发文档对应协议 0.5。

选择适用的客户端
方式	适用范围
HTTP	快速开始与 API 参考使用协议 0.5，可直接接入。
npm 0.5.0 beta	已发布，支持本指南的协议 0.5。
SDK 协议 0.5	已发布。安装支持该协议的具体 SDK 版本。
Invoice SDK 方法	npm 0.5.0 已提供这些方法；服务端和数据库须支持协议 0.5。SDK 发布不代表服务已部署。
Swift / Kotlin	目前提供源码包，尚无公开 SPM／Maven 发行；安装方式与功能范围见原生端指南。

选择适用的客户端

固定安装具体版本。遇到 UNSUPPORTED_PROTOCOL_VERSION 时，使用服务端支持的协议；不要通过删除版本头重试。

按实际返回处理
能力	接入要求
Customer / holdings	同一 App / 环境、正确权限、真实 Customer 凭据；空持有是有效结果。
Offering / Paywall	使用已发布的固定 Version；Paywall 必须绑定 Offering，Product 不可用时禁用对应选择。
Stripe	当前购买路径是 Sandbox 固定 Price，按 autumn / record_only 的 executor 处理；最终结果来自验签通知。
原生与进阶计费	原生购买、已有订阅变更、Entity / append 和 usage-priced checkout 不属于首次接入链路；未开放操作返回明确错误。
Funnel / GrowthBook	按当前环境支持的能力接入；后台等待、外部任务与进阶分析的要求见对应指南。

按实际返回处理

Customer / holdings
接入要求
同一 App / 环境、正确权限、真实 Customer 凭据；空持有是有效结果。
Offering / Paywall
接入要求
使用已发布的固定 Version；Paywall 必须绑定 Offering，Product 不可用时禁用对应选择。
Stripe
接入要求
当前购买路径是 Sandbox 固定 Price，按 autumn / record_only 的 executor 处理；最终结果来自验签通知。
原生与进阶计费
接入要求
原生购买、已有订阅变更、Entity / append 和 usage-priced checkout 不属于首次接入链路；未开放操作返回明确错误。
Funnel / GrowthBook
接入要求
按当前环境支持的能力接入；后台等待、外部任务与进阶分析的要求见对应指南。

遇到 NOT_CONFIGURED 或 SERVICE_UNAVAILABLE 时保留 requestId，核对当前环境配置与能力范围；不要通过替换 Customer、环境或请求身份来绕过错误。

当前 0.x 仅支持当前协议，允许在新次版本中进行破坏性调整，不兼容旧协议。请固定安装版本，并核对服务端部署。1.0 起，同一主版本内的次版本和补丁版本保持兼容；破坏性变更使用新的主版本。

新稳定主版本正式发布后，旧稳定主版本至少继续支持 12 个日历月。停止支持至少提前 180 天公开通知；实际停止时间取这两个期限中较晚者。新版本尚未发布或尚未发出通知时，不会自动结束旧稳定主版本的支持。

兼容覆盖公开 SDK 方法和类型、请求含义、响应必需字段、错误语义、身份隔离、幂等与恢复行为。支持期内提供关键缺陷与安全修复。迁移通知会写明受影响版本、替代版本、迁移步骤和最终支持日期，并保留在本页；升级请先在 Sandbox 验证。

HTTP 请求发送 X-Indiana-Protocol: 0.5。SDK 自动附带协议头和 X-Indiana-SDK-Version；两者须一致。协议头与凭据分别提供，/api/v1 路径不决定协议版本。

已发布的 SDK 0.2.0 不发送版本头。无版本头的请求按 0.2 识别，在仅支持 0.5 的服务上会被拒绝。响应 X-Indiana-Protocol 表示采用的协议，X-Indiana-Supported-Protocols 列出可用协议。

协议错误
HTTP	code	处理
400	INVALID_PROTOCOL_VERSION	修正格式或 SDK／协议不一致的版本头。
400	UNSUPPORTED_PROTOCOL_VERSION	使用服务端支持的协议并核对部署。
410	PROTOCOL_RETIRED	按公开迁移通知升级；请求未执行。

协议错误

弃用通知生效后，相应协议的响应提供 Deprecation（通知的 Unix 时间）、Sunset（停止支持的 HTTP 日期）和 Link（迁移通知）。通知期内原有请求继续可用，到期后明确拒绝。

时间为 UTC；0.x 不承诺旧协议支持期。