帕依提提 PayItiti 数据集开放API接入说明
版权所有：©2026 帕依提提 保留所有权利
文档用途：本文档用于指导开发者快速、安全接入帕依提提数据集开放API，规范密钥配置、调用方式及参数使用，规避风控、扣费及网络安全风险。
一、安全核心规范（强制遵守）
所有开发者接入前必须严格遵守以下安全规则，违规将可能导致密钥封禁、账号风控、扣费异常等问题：
1. 密钥保密原则：AK/SK为个人账户付费凭证，一旦泄露将造成Token被盗刷、恶意扣费风险。严禁将AK/SK转发他人、上传公网平台、代码托管平台（GitHub/Gitee等）。
2. 密钥编码规范：禁止将AK/SK明文硬编码写入业务代码并上传网络，统一使用本地.env配置文件或服务器系统环境变量注入密钥参数。
3. 接口频率限制：单组AK/SK密钥每分钟最大请求次数为60次，超出频率阈值将触发临时封禁，封禁时长为5分钟，期间所有请求失效。
4. 单次条数限制：接口单次读取数据条数范围为1~5000条，请求参数中条数超出该区间，接口将直接返回参数错误。
5. 传输协议规范：线上公网生产环境强制使用HTTPS协议；HTTP协议仅允许本地127.0.0.1内网调试使用，公网明文传输会导致密钥劫持、数据泄露风险。
6. 密钥安全机制：SK仅在本地设备参与请求签名计算，全程不会通过网络传输，外部抓包无法单独盗用密钥，无需担心网络抓包导致SK泄露。
7. 审计日志说明：平台对所有API请求永久留存审计日志，用于后期账单核对、风险风控、问题溯源，开发者请勿发起恶意、高频无效请求。
二、环境配置方式（两种可选）
API接入所需核心参数：PAYITITI_AK（访问密钥）、PAYITITI_SK（签名密钥）、API_BASE_URL（接口基础地址），支持本地开发、服务器部署两种配置方式，优先级可根据项目场景自定义。
方式一：本地开发环境（推荐）
在项目根目录新建 .env 环境配置文件，将密钥及接口地址写入文件，本地程序自动读取，避免密钥泄露。
示例.env配置内容：
# 帕依提提API密钥配置
PAYITITI_AK=你的个人AK密钥
PAYITITI_SK=你的个人SK密钥
# 接口基础地址
API_BASE_URL=平台官方接口地址
⚠️ 注意：将.env文件加入.gitignore忽略列表，禁止提交至代码仓库。
方式二：服务器生产环境
服务器部署时，无需配置本地文件，直接配置系统全局环境变量，业务程序读取系统变量完成鉴权调用，安全性更高。
核心环境变量名：
PAYITITI_AK：账户访问密钥
PAYITITI_SK：账户签名密钥
API_BASE_URL：API接口基础请求地址
三、API调用模式说明
平台提供两种标准化调用模式，适配不同业务查询场景，开发者可根据数据查询量级、是否需要分页自主选择。
模式一：统一limit分页模式（推荐批量查询）
适用场景：需要批量拉取数据、分页遍历数据集、大批量数据同步场景，支持分页查询，规避单次条数超限问题。
核心特性：
1. 通过 WANT_MAX_ROWS 参数控制单次最大获取条数，严格遵循1~5000条限制；
2. 支持循环分页请求，可分段获取大批量数据；
3. 不会一次性拉取全量数据，有效保护接口频次、避免超时报错。
模式二：limit_list自定义条数模式（适合少量查询）
适用场景：多数据集同时查询、单次少量数据获取、无需分页的临时查询、精准小批量数据提取场景。
核心特性：
1. 支持为不同数据集单独自定义查询条数，灵活性更高；
2. 不支持分页，仅适用于少量数据查询；
3. 所有数据集单次查询条数仍需遵守1~5000条参数限制。
四、接入常见限制与报错说明
1. 参数错误：单次请求数据条数＜1或＞5000，调整limit参数至合规区间即可解决；
2. 请求封禁：1分钟内请求次数超过60次，需等待5分钟自动解封，建议添加请求节流、休眠机制；
3. 请求失败：公网环境使用HTTP协议，切换为HTTPS协议即可恢复正常；
4. 鉴权失败：AK/SK配置错误、环境变量未生效，核对密钥及配置文件加载逻辑。
五、接入最佳实践
1. 开发、测试、生产环境严格分离，仅本地调试使用HTTP，线上全程使用HTTPS；
2. 批量数据获取优先使用分页模式，添加请求间隔，避免触发频率限制；
3. 所有密钥仅通过环境变量/.env文件注入，全程无明文硬编码；
4. 业务侧增加请求日志，方便结合平台审计日志排查异常请求、对账溯源。