/docs

砸壳对接文档

只保留对接砸壳与下载所需的核心接口:登录、查询应用与版本、下载 IPA、提交并查询砸壳任务。

快速开始

第三方对接可直接请求 https://www.dumpipa.com/api/*。 登录返回的 token 通过 Authorization: Bearer <token> 携带。

# 1. 登录拿 token curl -X POST 'https://www.dumpipa.com/api/auth/login' \ -H 'Content-Type: application/json' \ -d '{"username":"demo","password":"******"}' # 2. 查询应用全部版本 curl 'https://www.dumpipa.com/api/apps/ph.telegra.Telegraph?country=us&platform=iphone&limit=1000' # 3. 下载已砸壳版本(调用即扣费) curl 'https://www.dumpipa.com/api/apps/download-url?bundle_id=ph.telegra.Telegraph&version=12.1.0&country=us' \ -H 'Authorization: Bearer <token>' # 4. 提交砸壳任务 curl -X POST 'https://www.dumpipa.com/api/tasks' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{"bundle_id":"ph.telegra.Telegraph","version":"12.1.0","country":"us","platform":"iphone"}'

响应格式

// 成功:ok = 1,字段平铺在顶层 { "ok": 1, "msg": "操作成功", "tasks": [], "total": 0 } // 失败:ok = 0,HTTP 状态码同时为错误码 { "ok": 0, "msg": "缺少必要参数" }
版本列表冷启动会触发节点抓取,请把客户端超时设为 180 秒;download_url 是 302 跳转链接,需要允许跟随重定向。

获取 Token

第三方对接只需要登录一次拿到 token,之后所有下载与砸壳接口携带 Authorization: Bearer <token> 即可。

POST/api/auth/login公开

用户名密码登录,返回 token 与用户信息。

Body(JSON)

字段类型说明
usernamestring用户名或邮箱,必填
passwordstring密码,必填

响应示例

{
  "ok": 1,
  "msg": "登录成功",
  "token": "eyJhbGciOi...",
  "user": { "id": 1, "username": "demo", "coins": 12.5, "is_vip": false }
}
GET/api/auth/me需登录

校验 token 是否有效,并获取当前金币余额与会员状态,用于判断是否还能继续下载。

响应示例

{ "ok": 1, "user": { "id": 1, "username": "demo", "coins": 12.5, "is_vip": false } }

查询应用与版本

先搜索应用拿到 Bundle ID,再查询详情与全部历史版本。版本列表首次请求可能触发节点抓取,客户端超时建议 180 秒。

GET/api/apps/search公开

搜索 App Store 应用,keyword 支持名称、Bundle ID、Track ID 或 App Store 链接。

Query 参数

参数类型说明
keywordstring必填,搜索关键词
countrystring地区,默认 cn
platformstringiphone / ipad / macos,默认 iphone

响应示例

{
  "ok": 1,
  "success": true,
  "count": 1,
  "results": [
    {
      "trackName": "Telegram Messenger",
      "bundleId": "ph.telegra.Telegraph",
      "artistName": "Telegram FZ-LLC",
      "version": "12.1",
      "formattedPrice": "免费",
      "artworkUrl512": "https://.../512x512bb.jpg"
    }
  ]
}
GET/api/apps/{bundle_id}公开

应用详情与全部历史版本。默认只返回 10 个版本,对接建议传 limit=1000 拉全量;hasMore 表示是否还有更多。

Query 参数

参数类型说明
countrystring地区,默认 cn
platformstringiphone / ipad / macos,默认 iphone
include_versions0 | 1是否返回版本列表,默认 1
limitnumber版本数量上限,默认 10,建议 1000

响应示例

{
  "ok": 1,
  "app": {
    "trackName": "Telegram Messenger",
    "bundleId": "ph.telegra.Telegraph",
    "artworkUrl512": "https://.../512x512bb.jpg",
    "version": "12.1",
    "minimumOsVersion": "13.0"
  },
  "versions": [
    {
      "version": "12.1.0",
      "display_version": "12.1",
      "updated_at": "2026-10-21T00:00:00.000Z",
      "size_formatted": "179.2 MB",
      "isDumped": true,
      "taskStatus": ""
    }
  ],
  "total": 362,
  "limit": 1000,
  "hasMore": false
}
GET/api/apps/versions公开

只查版本列表,比详情接口更轻量,适合只需要发行号做批量下载的场景。

Query 参数

参数类型说明
bundle_idstring必填,应用 Bundle ID
countrystring地区,默认 cn
platformstringiphone / ipad / macos,默认 iphone

响应示例

{
  "ok": 1,
  "versions": [
    { "version": "12.1.0", "display_version": "12.1", "isDumped": true, "size_formatted": "179.2 MB" }
  ]
}
GET/api/apps/hot公开

热门应用,按砸壳次数排序,可用于首页榜单。

Query 参数

参数类型说明
pagenumber页码,默认 1
page_sizenumber每页数量,默认 20

响应示例

{
  "ok": 1,
  "apps": [
    { "app_name": "微信", "bundle_id": "com.tencent.xin", "version": "8.0.46", "size_formatted": "352.00 MB", "icon_url": "https://..." }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 100, "total_pages": 5 }
}
GET/api/apps/recommended公开

推荐应用,按最近砸壳时间排序,带地区与设备类型。

Query 参数

参数类型说明
pagenumber页码,默认 1
page_sizenumber每页数量,默认 20

响应示例

{
  "ok": 1,
  "apps": [
    { "app_name": "微信", "bundle_id": "com.tencent.xin", "version": "894392035", "country": "cn", "platform": "iphone" }
  ],
  "pagination": { "page": 1, "page_size": 20, "total": 1000, "total_pages": 50 }
}

下载 IPA

只有已砸壳版本可以下载。download-url 调用成功即扣费(会员或免费时段为 0),请务必在用户确认下载后再调用;同一账号 + 同应用 + 同版本 3 分钟内重复调用不会重复扣费。

GET/api/apps/download-url需登录

获取下载地址。返回的 download_url 是一次性跳转链接,直接打开或跟随 302 即可下载;链接有过期时间与次数限制,过期需重新调用(会再次扣费)。

Query 参数

参数类型说明
bundle_idstring必填,应用 Bundle ID
versionstring必填,App Store 发行号
countrystring地区,需与查询版本时一致
platformstringiphone / ipad / macos

响应示例

{
  "ok": 1,
  "download_url": "https://你的域名/api/apps/download-redirect?token=9f3c...",
  "size": "179.2 MB"
}
GET/api/apps/download-redirect公开

由 download-url 返回的跳转地址。携带 ?token= 校验通过后 302 跳转真实文件,请让客户端跟随重定向;失效时返回 410。

Query 参数

参数类型说明
tokenstring必填,下载令牌,有有效期与最大使用次数
GET/api/apps/ipa/check需登录

检查某版本是否已有可下载的 IPA 文件。

Query 参数

参数类型说明
bundle_idstring必填
version_idstring必填,App Store 发行号
platformstring设备类型,默认 iphone
POST/api/apps/ipa/download需登录

直接下载指定版本的 IPA,成功即按站点规则扣费。

Body(JSON)

字段类型说明
bundle_idstring必填
version_idstring必填,App Store 发行号
countrystring地区,默认 cn
platformstring设备类型,默认 iphone

响应示例

{ "ok": 1, "download_url": "https://你的域名/api/apps/download-redirect?token=9f3c..." }

提交砸壳

版本未砸壳时提交砸壳任务,按报价扣费。任务异步执行,轮询任务详情即可;任务类接口不返回任何下载直链,完成后统一调用 /api/apps/download-url 获取(会再次扣费)。

GET/api/tasks/quote登录可选

砸壳报价:基础砸壳费 + 付费应用的应用价值。提交前可先展示总价。

Query 参数

参数类型说明
bundle_idstring必填
countrystring地区,默认 cn

响应示例

{
  "ok": 1,
  "base_coins": 2,
  "app_value_coins": 0,
  "total_coins": 2,
  "app_price": { "amount": 0, "currency": "USD", "cny": 0 }
}
POST/api/tasks需登录

提交砸壳任务并扣费。维护期间返回 503;不要传 size_mb,后端会自动计算大小与费用。

Body(JSON)

字段类型说明
bundle_idstring必填,应用 Bundle ID
versionstringApp Store 发行号
real_versionstring真实版本号,可选
app_namestring应用名称,可选
countrystring地区,默认 cn
platformstringiphone / ipad / macos 等,默认 iphone
decrypt_modestringfull / binary / unfaird,默认 full
icon_urlstring图标地址,可选

任务状态

queued排队中

任务已创建,等待可用设备

running进行中

正在设备上执行脱壳

uploading上传存储中

砸壳已完成,结果正在写入存储

transferring转存中

上传完成后进行转存

done已完成

可通过 /api/apps/download-url 获取下载地址

error失败

可调用 retry 接口重新入队

cancelled已取消

已取消的任务不会继续执行

响应示例

{
  "ok": 1,
  "msg": "任务创建成功",
  "task_id": 1203,
  "bundle_id": "ph.telegra.Telegraph",
  "app_name": "Telegram Messenger",
  "real_version": "12.1",
  "task_token": "tk_8f3c..."
}
GET/api/tasks登录可选

全站任务列表。默认返回全站正在提取中的任务;传 status=done 返回全部砸壳成功的任务。同样不返回下载直链。

Query 参数

参数类型说明
statusstring可选。done=砸壳成功;queued,running,transferring,uploading=提取中;可逗号组合
include_doneboolean未传 status 时,传 true 可在默认列表带上已完成任务
pagenumber页码,默认 1
page_sizenumber每页数量,默认 50
only_mineboolean登录后传 true 只看自己的任务

任务状态

queued排队中

任务已创建,等待可用设备

running进行中

正在设备上执行脱壳

uploading上传存储中

砸壳已完成,结果正在写入存储

transferring转存中

上传完成后进行转存

done已完成

可通过 /api/apps/download-url 获取下载地址

error失败

可调用 retry 接口重新入队

cancelled已取消

已取消的任务不会继续执行

响应示例

{
  "ok": 1,
  "tasks": [
    { "id": 1203, "app_name": "Telegram", "bundle_id": "ph.telegra.Telegraph", "status": "done", "progress": 100 }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}
GET/api/tasks/my需登录

我的任务列表,只返回自己的任务。出于安全考虑,不返回 alist_url / download_url / result_path,下载请调用 download-url。

Query 参数

参数类型说明
pagenumber页码,默认 1
page_sizenumber每页数量,默认 20

响应示例

{
  "ok": 1,
  "tasks": [
    {
      "id": 1203,
      "bundle_id": "ph.telegra.Telegraph",
      "version": "12.1.0",
      "display_version": "12.1",
      "status": "done",
      "progress": 100
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}
GET/api/tasks/batch需登录

批量查询自己的任务,适合同时轮询多个任务进度;同样不返回任何下载直链。

Query 参数

参数类型说明
task_idsstring必填,逗号分隔,例如 1203,1204

响应示例

{ "ok": 1, "tasks": [ { "id": 1203, "status": "done", "progress": 100 } ], "total": 1 }
GET/api/tasks/{id}登录可选

任务详情,适合轮询进度,建议间隔 3-5 秒。未登录只返回公开字段。

响应示例

{ "ok": 1, "task": { "id": 1203, "status": "running", "progress": 42 } }
POST/api/tasks/{id}/retry需登录

失败任务重新入队。

响应示例

{ "ok": 1, "msg": "已重新加入队列" }
POST/api/tasks/{id}/cancel需登录

取消排队或执行中的任务。

响应示例

{ "ok": 1, "msg": "任务已取消" }

账户与金币

查询金币、会员状态、下载记录与 Token 管理。除配置类接口外都需要登录;下载记录只返回当前账号自己的数据。

GET/api/vip-coin/config登录可选

站点金币与会员配置,用于提前展示下载/砸壳费用、免费次数与限免状态。

响应示例

{
  "ok": 1,
  "config": {
    "coin_download_cost": 2,
    "site_free_mode": 0,
    "free_download_daily": 1,
    "free_dump_daily": 0,
    "vip_download_free": 1
  }
}
GET/api/vip-coin/my-download-records需登录

我的下载与砸壳记录。download_url 只存在于真实下载过的记录中,可用于下载记录页免费重新下载;未下载过的记录没有该字段。

Query 参数

参数类型说明
pagenumber页码,默认 1
page_sizenumber每页数量
action_typestringdownload 或 dump
resource_typestringapp_store 或 forum_post

响应示例

{
  "ok": 1,
  "list": [
    {
      "id": 501,
      "action_type": "download",
      "resource_name": "Telegram",
      "bundle_id": "ph.telegra.Telegraph",
      "version": "12.1.0",
      "coin_cost": 2,
      "download_url": "https://.../Telegram.ipa",
      "created_at": "2026-11-15T02:18:58.000Z"
    }
  ],
  "total": 1
}
GET/api/vip-coin/lifetime-usage需登录

累计下载/砸壳次数与终身免费次数使用情况。

响应示例

{ "ok": 1, "usage": { "download_count": 12, "dump_count": 3 } }
GET/api/users/wallet/balance需登录

金币余额(balance)。

响应示例

{ "ok": 1, "balance": 120 }
POST/api/api-tokens需登录

创建 API Token(api_ 开头)。必须绑定域名,后端会校验请求来源;完整 Token 可随时在 Token 管理页查看。

Body(JSON)

字段类型说明
namestring必填,Token 名称
domainstring必填,绑定域名,例如 example.com
expires_in_daysnumber可选,有效天数,不传为永不过期

响应示例

{ "ok": 1, "msg": "创建成功", "token": "api_xxxxxxxxxxxxxxxx", "name": "对接服务端" }
GET/api/api-tokens需登录

Token 列表,返回完整 Token 与预览、绑定域名、最后使用时间、使用次数、过期时间,以及套餐额度(plan_id、quota_total、quota_used、quota_remaining、privilege_expires_at)。

响应示例

{ "ok": 1, "tokens": [ { "id": 1, "name": "对接服务端", "token": "api_xxxx", "token_preview": "api_xxxx...", "domain": "example.com", "status": 1, "is_expired": false, "plan_id": 1, "quota_total": 300, "quota_used": 12, "quota_remaining": 288 } ] }
GET/api/api-tokens/{id}需登录

Token 详情,返回完整 Token(仅本人可查看)。

响应示例

{ "ok": 1, "token": { "id": 1, "name": "对接服务端", "token": "api_xxxxxxxx", "domain": "example.com", "status": 1 } }
POST/api/api-tokens/{id}需登录

更新 Token 的名称、状态、绑定域名或有效期(PUT 与 POST 均可)。

Body(JSON)

字段类型说明
namestring名称,可选
domainstring绑定域名,可选
statusnumber1 启用 / 0 禁用
expires_atstring过期时间,可选

响应示例

{ "ok": 1, "msg": "更新成功" }
DELETE/api/api-tokens/{id}需登录

删除 Token,删除后立即失效。

响应示例

{ "ok": 1, "msg": "删除成功" }
GET/api/token-plans

API Token 套餐列表。days=0 表示永久,quota_total=null 表示不限调用次数。

响应示例

{ "ok": 1, "plans": [ { "id": 1, "name": "月卡", "days": 30, "price": "19.00", "quota_total": 300 } ] }
POST/api/token-plans/orders需登录

创建套餐订单(绑定单个 Token),拿到 order_no 后调用 /api/orders/payment/create 发起支付。

Body(JSON)

字段类型说明
plan_idnumber必填,套餐 ID
token_idnumber必填,要绑定套餐的 Token ID

响应示例

{ "ok": 1, "order_no": "TOK1750000000ABCDEF", "amount": 19, "plan_name": "月卡" }
GET/api/token-plans/my-orders需登录

我的 Token 套餐订单列表。

响应示例

{ "ok": 1, "orders": [ { "order_no": "TOK1750000000ABCDEF", "plan_name": "月卡", "price": "19.00", "status": "paid", "token_name": "对接服务端" } ] }

状态与错误

业务错误会同时返回 ok: 0 与 msg, HTTP 状态码与下表对应。

400参数错误

缺少必填参数、金币不足或任务状态不允许操作

401未登录

缺少 token 或 token 已过期

403无权限

账号被拉黑,或无权访问该资源

404不存在

应用、版本或 IPA 文件不存在

503维护中

砸壳功能维护中,暂停提交新任务

504上游超时

App Store 或节点响应超时,建议客户端超时 180 秒