配置集成 IP 白名单
另请参阅
QI Tech 允许您将对集成的调用限制为一组预先授权的公网 IP 地址（或 CIDR 范围）。该过滤在签名校验之前生效：来自不在您活跃名单中的 IP 的请求将以 403 Forbidden（GDF000029）拒绝。
如何配置
登录 QI Tech 平台，点击左侧菜单中的"我的个人资料"，进入"集成"选项卡。滚动到"Whitelist de IPs da API"区域，在"IP / CIDR"字段中逐个添加 IP，每次添加后点击"ADICIONAR IP"按钮。
支持的格式：
- 公网 IPv4 地址（例如：
189.10.20.30） - 前缀为
/24或更大的 IPv4 CIDR 范围（例如：200.100.50.0/24） - 公网 IPv6 地址
- 前缀为
/48或更大的 IPv6 CIDR 范围
私有/保留地址范围（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8、169.254.0.0/16）不被接受。
激活等待期（48 小时）
注意！
出于安全考虑，通过控制面板新增的 IP 都会先停留在 Pendente（待激活）状态 48 小时，之后才会自动激活。在此期间该 IP 已被记录但不会授权任何请求 —— 您当前活跃白名单中的 IP 继续有效。
IP 创建时您会收到一封确认邮件，IP 进入 Ativo（已激活）状态时会再收到一封通知邮件。
48 小时后，IP 会自动转为 Ativo，开始被授权调用 API。
紧急激活
立即放行
如果您需要在 48 小时之前就放行某个 IP（例如：未计划的服务器迁移、生产事件），请通过官方渠道联系我们的支持团队，请求手动激活并提供以下信息：
- 已注册的
IP / CIDR - 您集成的
client_integration_key - 紧急原因
我们的运营团队会进行手动激活，IP 将立即生效。
常见错误
| 错误码 | 原因 | 解决方法 |
|---|---|---|
403 / GDF000029 | 请求来自不在白名单 Ativo 状态的 IP | 在"集成"页面查看哪些 IP 是激活状态。如果刚注册的 IP 仍为 Pendente，请等待 48 小时或申请手动激活。 |
| IP 注册被拒绝 | IP/CIDR 无效、私有地址、或范围过大（IPv4 前缀小于 /24、IPv6 前缀小于 /48） | 仅使用公网地址，并遵守最小前缀大小要求。 |