狗狗接码控制 API 文档
使用统一的 /api/control 接口即可自动化调用号码库存、取号、收码、取消、复用、租号等功能。支持 OAuth2 Client Credentials 或 API Key 签名，所有写操作需要传递 Idempotency-Key。
接入流程总览
一个典型接入通常只包含四个环节：拿凭证、查库存、下订单、跟踪送达。
准备凭证
先在控制台创建 OAuth2 Client 或 API Key，再开始调用控制接口。
建议按环境拆分凭证，便于做限流审计、权限收敛和后续密钥轮换。
查询库存
下单前先查询可用服务与国家，再选择有效的服务-国家组合。
库存和起价会随着供应状态变化，不建议把国家列表或价格硬编码在客户端。
创建订单
调用取号或租号接口时附带 Idempotency-Key，避免重试时产生重复扣费。
拿到 requestId 或 rentalId 后应立即落库，方便后续轮询、对账和人工支持。
跟踪送达
持续轮询状态、收集短信内容，并在超时场景下执行取消或退款策略。
推荐把轮询、重试、取消和退款视为同一条运营链路，而不是孤立接口调用。
鉴权
• 推荐使用 OAuth2 Client Credentials，获取 access_token 后 2 小时过期。
• 也支持静态 API Key，需在 HTTP Header 中传递 X-API-Key。
• 访问控制台可随时刷新密钥，支持 IP 白名单。
限流 & 幂等
• 默认限流：每秒 10 次写操作、每秒 30 次读操作。
• 使用 Idempotency-Key header 可避免重复扣费，建议每笔交易生成唯一 UUID。
• 返回 HTTP 429 时请指数退避后重试。
运行规则
建议把 API 接入视为订单工作流，而不是一次性的 request-response 调用。
先保证写操作安全
所有会创建订单或改变状态的请求都应携带独立的 Idempotency-Key，确保重试不会重复扣费。
明确建模订单状态
建议在客户端显式处理 pending、received、cancelled、expired 等状态，减少排障时对人工日志的依赖。
按可重试系统设计
把 HTTP 429、库存波动和短信延迟当作常规运行状态处理，而不是异常兜底。
核心接口
以下为常用接口示例，完整列表请查阅 OpenAPI 文件。
| Method | Path | 说明 | 常见响应 |
|---|---|---|---|
| GET | /api/control/balance | 查询账户余额 | 200 成功返回余额数据。 / 401 鉴权失败，请检查 token、API Key 或签名上下文。 |
| GET | /api/control/services | 查询可用服务目录 | 200 成功返回服务目录。 / 401 鉴权失败，或当前凭证无权访问该资源。 |
| GET | /api/control/inventory | 查询库存与起价 | 200 成功返回库存与报价信息。 / 404 请求的服务编码不存在，或当前环境未开放该服务。 |
| POST | /api/control/activations | 创建一次性取号请求 | 200 订单创建成功，并返回号码分配结果。 / 402 当前余额不足以支付该国家-服务组合。 / 460 当前供应侧没有可用库存。 |
| GET | /api/control/activations/{requestId} | 查询取号状态与短信内容 | 200 成功返回当前状态与短信内容。 / 404 requestId 不存在，或当前凭证无权查看该订单。 |
| PATCH | /api/control/activations/{requestId}/cancel | 取消等待中的取号请求 | 200 取消成功。 / 404 请求不存在，或订单已结束。 / 409 当前状态已不允许取消。 |
| POST | /api/control/rentals | 创建长期租号订单 | 200 租号订单创建成功，并返回分配结果。 / 402 余额不足，无法支付当前租期。 / 460 当前国家没有可用的租号库存。 |
/api/control/balance查询账户余额
返回可用余额、冻结资金及结算相关元数据，适合在创建新订单前做预检查。
请求参数
该接口无需额外请求参数。
响应语义
成功返回余额数据。
鉴权失败，请检查 token、API Key 或签名上下文。
/api/control/services查询可用服务目录
返回当前开放的服务编码、分类和复用能力，适合用于渲染服务选择器。
请求参数
该接口无需额外请求参数。
响应语义
成功返回服务目录。
鉴权失败，或当前凭证无权访问该资源。
/api/control/inventory查询库存与起价
返回目标服务下的可用国家、起价、库存量及是否支持可复用号码。
请求参数
serviceCodestring必填用于限定库存范围的服务编码。
countryCodestring可选可选国家过滤条件，用于只查看某一个目标市场。
响应语义
成功返回库存与报价信息。
请求的服务编码不存在，或当前环境未开放该服务。
/api/control/activations创建一次性取号请求
创建一次性订单，分配号码，并返回用于轮询、取消和退款的 requestId。
请求参数
serviceCodestring必填需要接码的目标服务编码，例如 whatsapp 或 telegram。
countryCodestring必填分配号码的目标国家。
reuseboolean可选当目标服务支持复用时，是否优先使用可复用库存。
响应语义
订单创建成功，并返回号码分配结果。
当前余额不足以支付该国家-服务组合。
当前供应侧没有可用库存。
/api/control/activations/{requestId}查询取号状态与短信内容
根据 requestId 查询当前状态、时间戳、复用窗口以及最新短信内容。
请求参数
requestIdstring必填创建订单时返回的激活请求 ID。
响应语义
成功返回当前状态与短信内容。
requestId 不存在，或当前凭证无权查看该订单。
/api/control/activations/{requestId}/cancel取消等待中的取号请求
在订单仍可取消时主动终止流程，释放供应预占并停止后续轮询。
请求参数
requestIdstring必填需要取消的激活请求 ID。
响应语义
取消成功。
请求不存在，或订单已结束。
当前状态已不允许取消。
/api/control/rentals创建长期租号订单
分配月租号码，并返回租期、自动续费状态和绑定服务元数据。
请求参数
countryCodestring必填用于分配租号库存的国家编码。
monthsinteger必填租期月份，通常位于支持的 1-12 个月范围内。
notestring可选可选业务备注，用于区分项目、渠道或下游归属。
响应语义
租号订单创建成功，并返回分配结果。
余额不足，无法支付当前租期。
当前国家没有可用的租号库存。
号码请求示例
发送 POST /api/control/activations 时的请求体与响应 JSON。
POST /api/control/activations
Headers:
Authorization: Bearer <token>
Idempotency-Key: 73b7-...-ff2
Body:
{
"serviceCode": "whatsapp",
"countryCode": "US",
"reuse": true
}Response 200:
{
"requestId": "act-123",
"number": "+1 650 555 0101",
"expiresAt": "<ISO8601 timestamp>",
"canReuseUntil": "<ISO8601 timestamp>"
}支持的服务与国家
当前开放 6 种服务、10 个国家/地区。
建议始终通过库存接口读取实时结果，而不是依赖静态国家或价格配置，这样运营、控制台和报价才能保持一致。
常见错误语义
以下状态在真实业务接入中最常见，建议显式处理，而不是统一走泛化重试。
鉴权或权限范围错误
当前 token、API Key 或凭证 scope 缺失、过期，或无权访问目标资源。
先刷新凭证，确认环境无误，再检查请求是否使用了正确的租户与签名上下文。
余额不足
当前账户可用余额不足，无法创建所请求的取号或租号订单。
重试前先查询余额接口，并在补足余额后再重新提交订单。
状态冲突
订单已完成、已取消，或已经进入不可变更状态，当前操作不再允许。
先重新拉取订单状态，再更新客户端流程，而不是继续重复提交同一写请求。
触发限流
当前客户端超过了读或写操作的配额窗口。
请采用指数退避，并保留幂等键后排队重试，不要持续直接冲击同一接口。
供应库存不可用
当前目标国家与服务组合无法由实时供应侧完成分配。
重新查询库存，切换国家或服务，或把缺货情况抛给运营人员做人工选择。
技术支持
Telegram 支持
@dogesms_support
服务时间：每日 09:00-21:00（UTC+8）可实时跟进
邮件支持
support@dogesms.com
服务时间：7x24 小时接单，工作时段处理
如需企业级接入或高并发配额，请直接与商务团队联系。