住宅代理 API 何时用、对接第一步清单与鉴权安全边界；与控制台/客户端分工，细节深链 Docs quickstart 与认证页，不以营销页替代 OpenAPI。
API 对接解决什么
住宅代理 API 回答的是：怎样用程序完成鉴权、查余额与产品、创建动态或静态订单、查询状态、提取或读取实例凭据。它适合脚本、后端服务和自动化流水线，而不是只在图形界面里点几下。
若你只是要把已有代理填进 curl、爬虫库或浏览器——那是客户端怎么连上的问题，请先读 HTTP / SOCKS5 住宅代理怎么配。若还没选定动态还是静态，请先读 动态与静态住宅代理如何选。
下文给你一张「何时用 API / 控制台 / 客户端」对照、可勾选的第一步清单，以及鉴权安全边界；逐步命令、请求体与接口字段以文档为准，请打开 快速开始、认证 与 接口参考。本站服务仅限合法、经授权的商业与技术用途。
何时用 API、何时用控制台 / 客户端
| 你要做的事 | 优先入口 | 说明 |
|---|---|---|
| 少量开通、看余额、改备注 | 控制台 | 最快上手；适合试探与核对 |
| 把代理填进脚本 / 浏览器 / 工具连上网 | 客户端配置（zt-07） | 填协议 / 主机 / 端口 / 认证；值来自控制台 |
| 批量下单、自动续费或释放、对账、嵌进自有后台 | API | 鉴权后按 Docs 调用下单 / 查询 / 提取等接口 |
| 既要自动开通又要业务请求走代理 | API + 客户端 | API 管资源生命周期；客户端用返回凭据发业务流量 |
| 还没定动态还是静态 | 先选型（zt-01） | API 不替代产品选型 |
三者经常配合使用：用 API（或控制台）开通资源，再用控制台返回的协议与凭据在客户端发业务请求。套餐入口见 动态住宅、静态住宅 与 价格方案。
第一步清单：账号 → 鉴权 → 只读 → 再写
按顺序推进（全部以 Docs 与控制台为准；本文不提供可滥用的示例 token，也不复制整本 curl 家族）：
- 账号可用： 完成注册与邮箱激活，确认能登录控制台。
- 读懂鉴权： 打开 认证，理解「登录拿到 token → 后续请求带 Bearer」。
- 只读探测： 按 快速开始 先查余额、查产品 / 地区代码，确认环境、权限与计价口径可读通。
- 再写下单： 动态按流量（GB）、静态按 IP × 周期——细节与字段在 Docs；静态标准创建可能是异步受理，需用订单列表确认最终状态与实例信息。
- 提取或连上： 动态提取说明见 Docs；拿到主机 / 端口 / 认证后，客户端怎么填回 zt-07。
- 排错与嵌套： 业务错误与 HTTP 语义见 错误处理；习惯与限流意识见 最佳实践；服务端持有凭据见 后端集成。
- 价格与档位： 公示口径（如动态约 $0.40/GB）以控制台为准；静态按 IP/月。账单单位解释见 按 GB 还是按 IP。
对接步骤对照
| 步骤 | 你在确认什么 | 深读哪里 |
|---|---|---|
| 账号可用 | 已激活、能登控制台 | 控制台；认证页常见错误 |
| 鉴权 | 登录拿 token，请求带 Bearer | /docs/authentication |
| 只读探测 | 余额、产品与地区代码 | /docs/quickstart、接口参考 |
| 下单 | 动态流量或静态 IP 订单 | quickstart、openapi；价格以控制台为准 |
| 查状态 / 实例 | 异步受理、列表与搜索 | quickstart、openapi |
| 提取 / 连上 | 动态提取或静态实例凭据 → 客户端 | Docs 提取说明 + zt-07 |
| 排错 | 401 / 业务错误、重试意识 | /docs/errors、最佳实践 |
| 后端嵌套 | 凭据留在服务端，不进前端 | /docs/backend-integration |
表中不粘贴具体 path 大段或示例密钥；需要字段字典时打开 接口参考。
鉴权与安全边界
ZTProxy 对外 API 使用 JWT Bearer Token：先用账号密码调用登录接口取得 token，再在需要认证的请求头中携带。完整示例、响应字段与 401 / 403 说明以 认证 为准。
安全边界（营销页也必须遵守）：
- 不要把 token、密码写进前端代码、公开仓库、截图教程或群聊。
- 不要在日志里打印完整 Authorization 头。
- Token 过期或无效时，按 Docs 重新登录（或按其说明刷新），而不是把失败请求打满重试。
- 账号未激活时，先完成邮箱激活再调接口。
本文不会提供可复制的假 token，也不会把 OpenAPI 路径表搬进营销正文。
和 zt-07、Docs 的边界
| 文档 | 回答什么 | 不回答什么 |
|---|---|---|
| 本文（zt-11） | 何时用 API、第一步顺序、鉴权安全原则、该点哪份 Docs | 完整请求体、path 字典、可复制密钥 |
| zt-07 客户端清单 | HTTP / SOCKS5 怎么选、客户端字段怎么填 | 下单 / 提取 API |
| Docs quickstart | 典型调用流程与命令级示例 | 产品选型话术 |
| 认证 | 登录、Bearer、常见认证错误 | 场景营销 |
| 接口参考 | 字段与接口说明 | 「第一次该不该用 API」的决策表 |
请把完整请求示例留在 Docs；集成方把本页当地图，把 Docs 当手册。
常见坑与下一步
常见踩坑（定性，不编造错误码大全）：
- 账号未激活就连续调接口 → 先看认证页 403 说明。
- 只读（余额 / 产品）未通就批量下单 → 先跑通 quickstart 前半段。
- 把本页或 FAQ 当成 OpenAPI → 字段以接口参考为准。
- 把「API 下单」和「客户端协议配置」混成一步 → 资源用 API / 控制台；连上用 zt-07。
- 凭据进前端或日志 → 改回服务端持有，参考后端集成与最佳实践。
下一步
- 用上面两张表确认：你的任务该走 API、控制台还是客户端。
- 打开 认证 与 快速开始，先只读再写。
- 字段与错误 → 接口参考、错误处理。
- 未选型 → zt-01；估账单 → zt-03 + 定价；产品 → 动态 / 静态。
- 更多指南见 使用指南。
还不确定？可通过站内支持入口或 [email protected] 联系我们（不承诺固定响应时效）。记住：API 管资源生命周期；客户端管怎么连上；深步骤去 Docs。
常见问题
API 和对控制台有什么区别？
控制台适合少量手工开通与核对；API 适合程序化下单、查询、提取和对账，并可嵌进自有后台。两者常配合：API 或控制台开通资源后，仍用控制台返回的凭据在客户端发业务流量。
什么时候该用 API，而不是只配客户端？
需要批量、定时、自动续费 / 释放，或把开通流程写进自己的系统时，优先 API。若目标只是「让脚本或浏览器走代理上网」，先按 HTTP / SOCKS5 配置清单 填客户端即可。
对接第一步做什么？
账号激活 → 读 认证 → 按 快速开始 做只读（余额、产品）→ 再创建订单或提取。完整勾选见上文「第一步清单」。
鉴权怎么做？Token 能写进前端吗？
使用 JWT Bearer：登录取得 token 后，在请求头携带。不要把 token 或密码写进前端、公开仓库或日志；放在服务端或密钥管理系统。细节与常见 401 / 403 见 认证。
本文和 OpenAPI / quickstart 有什么区别？
本文是营销站可索引的对接地图（何时用、第一步、安全边界）。逐步命令、路径与字段在 快速开始 与 接口参考。请勿在本页查找完整接口表。
和 HTTP / SOCKS5 配置文什么关系？
zt-07 讲客户端协议与字段；本文讲 API 侧资源与鉴权。API 下单拿到实例或提取结果后，连上代理仍按 zt-07 与控制台返回值配置。
动态和静态都能用 API 下单吗？
可以。动态与静态的字段、计价与（静态）异步受理细节以 Docs 与控制台为准。尚未选型时先读 动态与静态如何选；账单单位见 按 GB 还是按 IP。产品入口：动态住宅、静态住宅。
价格以哪里为准？中国大陆能用吗？
套餐与标价见 价格方案，以控制台为准（动态约 $0.40/GB 等为公示口径，可能调整；静态按 IP/月）。本站所有代理服务产品均不支持在中国大陆地区使用。