# 静态 API 概览

查看静态住宅公开接口的认证、业务编号、异步结果、资金语义及逐接口文档。

静态 API 通过账户 API 令牌使用同一账户的钱包、订单、实例和客户价格。正式采购前需完成当前有效的个人或企业实名认证。**本文是接口合同，不代表功能已在目标环境开放或完成真实供应商验收。**是否开放以控制台实际状态为准。

## 接入约定

生产请求基址为 `https://api.zzhttp.com/openapi/v1/static`，接口前缀为 `/openapi/v1/static`，使用 HTTPS 和 [统一 API 令牌认证](/developers/authentication/static-hmac)。成功响应包含数字 `code: 200`、`message`、`requestId` 和 `data`；异步写入的 HTTP 202 仅表示受理。金额均为 `CNY` 整数分。分页默认第 1 页、每页 20 条，最多 100 条。

采购使用 `clientOrderNo`，续费与改密使用 `clientOperationNo`。业务编号允许 1–64 位字母、数字、`_`、`.`、`-`，幂等范围是账户、操作类型与编号。同编号不同参数返回 409 / `10705`。网络超时先按原编号查询，不要更换编号重新发起。`requestId` 仅用于排障，不是幂等编号。API 开关关闭后不再接受新命令，已受理任务继续处理。

## 按功能查阅

- 地区：[查询国家](/developers/api/static-countries)、[查询城市](/developers/api/static-cities)
- 账户余额：[查询余额](/developers/api/static-balance)。接口路径仍位于静态 API 命名空间，余额用于静态采购。
- 商品与报价：[查询商品](/developers/api/static-offers)、[获取报价](/developers/api/static-quotes)
- 订单：[创建采购订单](/developers/api/static-create-order)、[查询订单列表](/developers/api/static-orders)、[查询订单详情](/developers/api/static-order-detail)
- 实例：[查询实例列表](/developers/api/static-instances)、[查询实例详情](/developers/api/static-instance-detail)、[读取实例凭据](/developers/api/static-credentials)
- 售后与结果：[续费](/developers/api/static-renew)、[修改凭据](/developers/api/static-update-credentials)、[查询操作列表](/developers/api/static-operations)、[查询操作详情](/developers/api/static-operation-detail)、[结果通知](/developers/api/static-webhooks)

[下载静态 API OpenAPI 定义](/static-supply-openapi.json)；[下载 Python / Node.js 示例](/static-supply-examples.zip)。

## 结果与资金

订单和收费操作返回 `accepted`、`processing`、`succeeded`、`partial`、`failed` 或 `manual_review`。以查询的逐项结果为准；通知可能重复、乱序，改密不发送结果通知。`settlement` 中原冻结金额等于当前冻结、已扣和已释放之和。钱包订单使用 `fundingSource: wallet`；查询历史直付订单时可能为 `external`，未付款或免费操作为 `none`。`refundDueAmountCents` 表示应退，不能当作已到账。`manual_review` 时应查看具体订单和资金状态，不要盲目重新购买。

常见业务错误：`10700` 参数错误、`10001` 令牌无效、`10601` 未实名、`10711/10207` API 或交易资格不可用、`10703/10704` 资源不存在或不归属当前账户、`10710/10702` 价格变动、`10204` 余额不足、`10705` 编号冲突、`10701` 商品或实例能力不满足、`10713` 限流。HTTPS 要求错误为 403 / `10712`，服务不可用为 503 / `10707`。收到 429 按 `Retry-After` 等待；500/503 或请求中断先用原业务编号查询。完整错误与字段以 [OpenAPI 定义](/static-supply-openapi.json) 为准。