统一代理 API 对接文档

快速开始

1. 登录用户中心的“API 接入管理”提交申请；管理员审核通过后，由用户在该页领取只显示一次的专属 API Key。
2. 使用服务端程序通过 HTTPS 请求；不要在浏览器前端或公开代码中保存 Key。
3. 先读取对应目录，只对 orderable=true 的商品或服务下单。
4. 每笔新订单生成新的 Idempotency-Key；同一订单超时重试必须复用原 Key，并保存返回的订单号查询状态。

连通与余额测试

以下内容全部是占位符，不包含真实 Key。将 API_KEY 替换为您在“API 接入管理”一次性领取并安全保存的密钥。

API_BASE='https://msk888acc.com/api/v1'
API_KEY='sk_live_请替换为您的API_KEY'

curl --request GET "$API_BASE/" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_KEY"

curl --request GET "$API_BASE/balance" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_KEY"

复制示例

接口总览

认证、请求头与 Scope

所有 /api/v1 接口（包括 v1 根索引）都要求 Bearer 认证。Key 只能放在请求头，不能放入 URL、查询参数、日志或网页源码；旧版四个账号接口继续沿用原有用户名/密码参数。

Authorization: Bearer sk_live_请替换为您的API_KEY
Accept: application/json

创建订单还必须加入：

Content-Type: application/json
Idempotency-Key: reseller-order-20260723-000001

可用 Scope

balance:read orders:read account:read account:write social:read social:write proxy:read proxy:write checker:read checker:write

这里的权限必须填写上方列出的完整名称，不支持字面通配符。各业务的 :read 用于读取目录、交付或检测结果，:write 用于创建订单或检测；订单列表还需要 orders:read。

余额

GEThttps://msk888acc.com/api/v1/balance

{
  "success": true,
  "data": {
    "balance": 12800,
    "currency": "site_balance"
  },
  "meta": {
    "api_version": "v1",
    "request_id": "示例请求ID"
  }
}

商品与服务目录

{
  "id": 1001,
  "fulfillment": "connected",
  "stock": 12,
  "stock_known": true,
  "variants": [
    {
      "key": "美国",
      "price": 120,
      "stock": 12,
      "stock_known": true,
      "orderable": true,
      "availability_reason": null
    }
  ],
  "orderable": true,
  "availability_reason": null
}

目录请求示例

API_BASE='https://msk888acc.com/api/v1'
API_KEY='sk_live_请替换为您的API_KEY'

curl "$API_BASE/catalog/accounts?limit=20&cursor=0" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_KEY"

curl "$API_BASE/catalog/social?limit=20&cursor=0" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_KEY"

curl "$API_BASE/catalog/proxy" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_KEY"

复制示例

目录分页

账号和刷粉目录支持 limit（1–200）及 cursor。读取响应中的 meta.pagination.next_cursor；为 null 时表示已到末页。

"meta": {
  "api_version": "v1",
  "request_id": "示例请求ID",
  "pagination": {
    "limit": 100,
    "next_cursor": 2100
  }
}

统一下单

POSThttps://msk888acc.com/api/v1/orders

通过 JSON 字段 type 区分业务：account、social 或 proxy。下单需要对应的写权限。

Idempotency-Key 幂等规则

• 长度必须为 16–64 位，首字符为字母或数字，其余可使用字母、数字、点、下划线、冒号和短横线。
• 同一用户使用相同幂等键和完全相同的 JSON 重试，只返回原订单，不会重复购买。
• 相同幂等键配合不同 JSON 会返回 409 idempotency_conflict。
• 网络超时后先用原幂等键重试或按订单号查询；若状态为 upstream_pending，不要换新键重复下单。
• 账号商品存在完全相同且未结束的请求时，即使误换了新键，系统也会返回原待处理订单并标记 meta.duplicate_pending_guard=true，不会再次提交购买。

1. 账号商品

{
  "type": "account",
  "product_id": 1001,
  "quantity": 2
}

product_id、数量范围和可选 variant_key 来自账号目录。无规格商品不要发送 variant_key。账号订单完整交付后，delivery 包含 product_id、quantity、variant_key 和仅属于当前代理的 accounts；无规格商品的 variant_key 为空字符串。本文档不展示任何卡密示例。

2. 刷粉服务

{
  "type": "social",
  "service_id": 2104,
  "url": "https://example.com/post/1",
  "quantity": 100
}

• Default：使用 url 和 quantity。
• Package：仍传 quantity，计费数量固定为 1。
• Custom Comments：仍需传一个正整数 quantity，并额外传 comments（每行一条）；实际计费和范围校验以非空评论行数为准。
• Mentions / Comment Likes：额外传 usernames。

3. 代理 IP

下单前可使用 POST/catalog/proxy/quote 获取实时站内余额价。该接口只读，需要 proxy:read，不需要 Idempotency-Key，不扣款也不创建订单。

curl --request POST 'https://msk888acc.com/api/v1/catalog/proxy/quote' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer sk_live_请替换为您的API_KEY' \
  --data '{"kind":"dedicated_ipv4","country":"us","period":30,"quantity":2}'

复制报价示例

{
  "success": true,
  "data": {
    "kind": "dedicated_ipv4",
    "country": "us",
    "period": 30,
    "quantity": 2,
    "amount": 1200,
    "currency": "site_balance",
    "price_locked": false,
    "notice": "报价仅供购买前参考；创建订单时会重新计算并按当时金额扣款"
  }
}

报价请求与代理下单使用相同参数规则：quantity 和 ip_list 必须且只能提交一种。如使用 ip_list，类型必须支持自选 IP，列表必须是 1–1000 个不重复的正整数 ID。price_locked=false 表示下单时会再次询价，实际扣款以下单当时为准。

{
  "type": "proxy",
  "kind": "dedicated_ipv4",
  "country": "us",
  "period": 30,
  "quantity": 2
}

kind、国家、周期和数量必须使用目录实时返回值。对 supports_ip_selection=true 的类型，可先查询 IP；该查询单次最多返回 2000 项且当前不分页。下单时使用返回的正整数 ID 组成 ip_list 来替换 quantity，ID 不能重复且最多 1000 个。其他类型不要传 ip_list，仍需传 quantity：

{
  "type": "proxy",
  "kind": "dedicated_ipv4",
  "country": "us",
  "period": 30,
  "ip_list": [90101, 90102]
}

代理续费

代理订单完成后，每个 delivery.items[] 会包含仅属于当前 API 用户的 renewal_token。先调用 /catalog/proxy/renew/quote 获取报价，再向 /orders/proxy/renew 提交相同凭证和周期；实际续费请求必须使用新的 Idempotency-Key，超时重试必须复用原值。一次最多续费同一订单中的 100 个代理。

curl --request POST 'https://msk888acc.com/api/v1/orders/proxy/renew' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer sk_live_请替换为您的API_KEY' \
  --header 'Idempotency-Key: proxy-renew-20260804-000001' \
  --data '{"renewal_tokens":["pr1.请替换为交付中的续费凭证"],"period":30}'

复制续费示例

完整 curl 示例

curl --request POST 'https://msk888acc.com/api/v1/orders' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer sk_live_请替换为您的API_KEY' \
  --header 'Idempotency-Key: social-20260723-000001' \
  --data '{"type":"social","service_id":2104,"url":"https://example.com/post/1","quantity":100}'

复制示例

订单查询与交付

订单列表

GET/orders?limit=50&before_id=9999&type=account

limit 为 1–100，默认 50；下一页使用 meta.pagination.next_before_id 作为新的 before_id。type 可选 account、social 或 proxy。省略时只返回当前 Key 具有对应读取 Scope 的订单。

订单详情

GET/orders/DO2607230123456789ABCDEF

订单详情只允许当前 API Key 所属用户读取。完成后，不同业务会在 delivery 中返回账号交付、刷粉进度或代理连接信息。请将交付内容视为敏感数据并加密保存。

统一订单字段

{
  "success": true,
  "data": {
    "id": "DO2607230123456789ABCDEF",
    "type": "social",
    "status": "processing",
    "amount": 1200,
    "currency": "site_balance",
    "error": null,
    "created_at": "2026-07-23 12:00:00",
    "updated_at": "2026-07-23 12:00:01"
  },
  "meta": {
    "api_version": "v1",
    "request_id": "示例请求ID"
  }
}

订单状态

processing、upstream_pending、reconciliation_pending、refund_pending 和 seller_pending 返回 HTTP 202；其他已结束状态返回 HTTP 200。ACGV3 待处理订单由计划任务自动查询；没有可靠查询接口的其他连接在结果不确定时会等待管理员核对，期间禁止换 Key 重复下单。

账号查活 API

1. 读取平台与限额

GET/checker/capabilities

返回当前支持的平台、单批上限、每分钟检测数量、结果保留天数和结果枚举。 当前平台为 facebook，检测对象必须是纯数字 UID。

2. 创建检测

POST/checker/checks

必须发送 16–64 位 Idempotency-Key。同一个检测超时重试时复用原键， 不会重复执行；同一幂等键配合不同内容会返回 409 idempotency_conflict。checker:write 允许读取本次创建请求的同步结果； 后续按编号查询仍需 checker:read。

curl --request POST 'https://msk888acc.com/api/v1/checker/checks' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer sk_live_请替换为您的API_KEY' \
  --header 'Idempotency-Key: checker-20260727-000001' \
  --data '{"platform":"facebook","identifiers":["100000000000001","100000000000002"]}'

复制示例

3. 查询检测结果

GET/checker/checks/{check_id}

{
  "success": true,
  "data": {
    "check_id": "CK2607270123456789ABCDEF",
    "platform": "facebook",
    "status": "partial",
    "submitted_count": 2,
    "unique_count": 2,
    "summary": {"live": 1, "dead": 0, "unknown": 1},
    "results": [
      {"position": 0, "identifier": "100000000000001", "status": "live"},
      {"position": 1, "identifier": "100000000000002", "status": "unknown"}
    ]
  }
}

• live：本次取得了可信的存活证据。
• dead：为后续可靠失效检测预留；当前 Facebook 检测不会返回此值。
• unknown：远端限制、网络异常或页面结构无法可靠判断；应稍后重试，不能归入 live/dead。
• 重复检测对象会按规范化值去重；submitted_count 是原数量，unique_count 是实际检测数量。
• 普通 unknown 建议采用指数退避重试；只有 HTTP 429 才按响应头 Retry-After 等待。
• 任务异常中断并超过处理时限后会变为 failed；确认失败后如需重试，请生成新的幂等键。
• 检测任务和明细默认保留 14 天，实际天数以 capabilities 返回值为准。

统一响应、错误与限流

成功响应

{
  "success": true,
  "data": {},
  "meta": {
    "api_version": "v1",
    "request_id": "示例请求ID"
  }
}

请求层失败响应

认证、权限、JSON、路由或幂等键格式等问题会返回 HTTP 4xx/5xx，并使用 success=false：

{
  "success": false,
  "error": {
    "code": "invalid_json",
    "message": "JSON 请求内容无效"
  },
  "meta": {
    "api_version": "v1",
    "request_id": "示例请求ID"
  }
}

订单业务失败仍是订单响应

只要请求已通过基础校验并创建了订单记录，库存不足、余额不足、业务参数错误或上游明确拒绝等结果会返回 success=true；此时必须继续检查 data.status 和 data.error，不能只看 HTTP 200/202 或顶层 success。

{
  "success": true,
  "data": {
    "id": "DO2607230123456789ABCDEF",
    "type": "account",
    "status": "failed",
    "amount": 0,
    "currency": "site_balance",
    "error": {
      "code": "insufficient_stock",
      "message": "商品库存不足"
    }
  },
  "meta": {
    "api_version": "v1",
    "request_id": "示例请求ID"
  }
}

请同时记录 HTTP 状态码、订单 data.status、相应错误码和 meta.request_id。联系平台方排查时只提供订单号和 request_id，不要发送完整 API Key。

常见 HTTP 状态

限流响应头包括 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset；超限时另有 Retry-After。

旧版账号 API（继续兼容）

Bearer v1 的账号目录同时覆盖本地库存商品和已适配连接商品；这只是新增能力，不会改变旧接口的 URL、参数以及原有 success/error 状态枚举。

旧接口使用商城用户名和密码鉴权，必须通过 HTTPS 从服务端调用：

GET https://msk888acc.com/api/GetBalance.php?username=账号&password=密码
GET https://msk888acc.com/api/ListResource.php?username=账号&password=密码
GET https://msk888acc.com/api/InfoResource.php?username=账号&password=密码&id=商品ID
GET https://msk888acc.com/api/BResource.php?username=账号&password=密码&id=商品ID&amount=数量

规格商品购买时继续附加 category=规格键。每次购买都应附加稳定且唯一的 request_no（16–64 位字母、数字、下划线或短横线）；同一次请求因超时或断线重试时必须复用原值。兼容字段还包括 requestNo、order_no、out_trade_no 或请求头 Idempotency-Key，同时提供多个字段时值必须一致。若外部商品结果暂时无法确认，旧接口仍返回 status=error，但提示会明确“订单正在处理中”并附带 data.trans_id；此时不得自动重复购买，应保存交易号并查询购买记录。下载本页合并版 Postman 后，在 Collection Variables 中填写 legacy_username、legacy_password、legacy_product_id 和可选的 legacy_category 即可测试。

旧接口与 Bearer v1 对照

ACGV3 Shared API 兼容

基础地址是本站域名，例如 https://msk888acc.com。所有接口使用 application/x-www-form-urlencoded 的 POST 请求。

除 sign 外，每个请求都必须提交领取到的数字 app_id。统一响应为：

{
  "code": 200,
  "msg": "success",
  "data": {}
}

签名算法

1. 从请求参数移除 sign。
2. 按参数名升序排序，仅移除值严格等于空字符串 '' 的参数。
3. 用 PHP http_build_query 生成查询串，再执行 urldecode。
4. 末尾追加 &key={app_key}，计算小写 MD5。

function makeSign(array $data, string $appKey): string
{
    unset($data['sign']);
    ksort($data);
    foreach ($data as $key => $value) {
        if ($value === '') {
            unset($data[$key]);
        }
    }
    return md5(urldecode(http_build_query($data) . '&key=' . $appKey));
}

接口列表

业务参数

订单公开状态固定为 pending、completed 或 failed；当状态为 pending 时应使用原订单号继续查询，不能更换请求号重复下单。

Dujiao-Next 上游协议兼容

Dujiao-Next 会在“站点地址”后自动拼接兼容接口路径，因此连接管理中只填写本站根地址：

https://msk888acc.com

实际签名和请求使用的接口基地址为：

https://msk888acc.com/api/v1/upstream

成功响应统一包含 "ok": true；失败响应包含 "ok": false、error_code 和 error_message。

请求签名

每个请求必须携带以下三个 Header。时间戳为 Unix 秒，允许偏差 ±60 秒。

BODY_MD5 = md5(raw_request_body)
SIGN_STRING = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY_MD5
SIGNATURE = hex_lower(hmac_sha256(SIGN_STRING, API_SECRET))

接口列表

创建与查询订单

必须使用商品列表中 is_active=true 且库存可用的 skus[].id。创建订单必须提交全局唯一的 downstream_order_no；同一 API Key 下重复提交相同值会返回原订单， 网络超时重试时不能换值重复下单。

{
  "sku_id": 1,
  "quantity": 1,
  "downstream_order_no": "your-order-202607290001",
  "trace_id": "your-order-202607290001",
  "callback_url": "https://your-dujiao.example/api/v1/upstream/callback"
}

{
  "ok": true,
  "order_id": 101,
  "order_no": "API202607290001",
  "status": "paid",
  "amount": "9.90",
  "currency": "USD"
}

保存返回的 order_id，并继续通过 GET /orders/:id 轮询作为回调失败时的兜底。完成后响应中的 fulfillment.payload 和 fulfillment.delivery_data.items 才是交付内容。

安全与生产接入要求

• 仅通过 HTTPS 从服务端请求；此 API 不支持浏览器跨域预检，不要在 JavaScript、App 安装包或公开仓库中嵌入 Key。
• 为测试和生产使用不同 Key，并申请最小 Scope；能够固定出口 IP 时启用 IP/CIDR 白名单。
• Key 泄露时立即联系平台方撤销并换新。日志只记录 Key 前缀，绝不记录完整 Authorization 请求头。
• 每个业务订单使用唯一幂等键；网络异常时不要盲目换键重下，先查询原订单。
• 账号卡密及代理账号密码均属于敏感交付数据，应加密保存、限制访问并设置合理保留期限。
• 请遵守适用法律、第三方平台规则和本站条款，不得将 API 用于欺诈、骚扰、侵权或其他违法用途。