上传与发布

通过 API 上传 App 到蒲公英的接口说明，包含快速上传三步流程、HarmonyOS 证书与 Hsp 文件上传，以及旧版上传接口。

本页介绍通过蒲公英 API 上传应用的所有接口。推荐使用快速上传流程，速度更快、稳定性更高。

API 发布同样适用账户容量与历史版本清理规则。容量超额时，自动策略会先尝试清理已有超额；无法释放足够空间，或选择手动清理时，API 会返回失败结果。请检查 code、message 和最终发布状态，不要将文件传输完成视为发布成功。长期需要的安装包请另行归档。

如需选择 API、CLI、CI/CD 插件、MCP 或 Agent Skill，请先查看自动上传 App 与 CI/CD 集成指南。

快速上传 App（新版）

代码调用示例：https://github.com/PGYER/upload-app-api-example

获取预上传 URL：调用 getCOSToken 拿到上传地址和签名参数。

上传应用文件：将应用文件以 multipart/form-data 方式 POST 到上一步返回的 URL。

轮询发布结果：调用 buildInfo 查询应用是否发布完成，直到返回成功或失败。

获取上传的 token

获取预上传 URL 和相关的签名参数。

POSThttps://www.pgyer.com/apiv2/app/getCOSToken

请求参数

参数名	类型	必填	说明
_api_key	String	是	API Key，请见鉴权说明
buildType	String	是	应用类型。iOS 传 `ios` 或 `ipa`，Android 传 `android` 或 `apk`，HarmonyOS 传 `harmonyos` 或 `hap`
oversea	Integer	否	是否使用海外加速上传：1 使用海外加速，2 使用国内加速；留空根据 IP 自动判断
buildInstallType	Integer	否	应用安装方式，默认 1。1：公开安装，2：密码安装，3：邀请安装
buildPassword	String	否	App 安装密码，为空时默认公开安装
buildDescription	String	否	应用介绍，如没有请传空字符串或不传
buildUpdateDescription	String	否	版本更新描述，如没有请传空字符串或不传
buildInstallDate	Integer	否	是否设置安装有效期：1 设置有效时间，2 不限制下载起止时间；不填写则不修改上一次的设置。此设置不改变历史版本保留规则
buildInstallStartDate	String	否	安装有效期开始时间，如 `2018-01-01`
buildInstallEndDate	String	否	安装有效期结束时间，如 `2018-12-31`
buildChannelShortcut	String	否	指定更新的渠道短链接。渠道必须已创建成功，且只能指定一个，如 `abcd`

返回数据

参数	类型	说明
key	String	上传文件存储标识唯一 key
endpoint	String	上传文件的 URL
params	Object	上传文件需要的参数，包含 `signature`、`x-cos-security-token`、`key`

{
  "code": 0,
  "message": "",
  "data": {
    "endpoint": "https://upload-v7.upload.cos.ap-shanghai.myqcloud.com",
    "key": "apps/xxx/yyyy/zzzz.apk",
    "params": {
      "signature": "q-sign-algorithm=sha1&q-ak=...&q-signature=...",
      "x-cos-security-token": "...",
      "key": "apps/xxx/yyyy/zzzz.apk"
    }
  }
}

上传文件到上一步获取的 URL

将应用文件上传到 getCOSToken 返回的 endpoint 地址。

上传成功后，应用会自动进入服务器后台队列继续发布流程。这一步返回成功并不代表发布完成，通常 1 分钟内完成。发布状态请调用下一步的 buildInfo 接口检测。

POST<上一步响应中 endpoint 的值>

请求需设置 Content-Type: multipart/form-data。

请求参数

参数名	类型	必填	说明
key	String	是	从上一步响应中获取
signature	String	是	从上一步响应中获取
x-cos-security-token	String	是	从上一步响应中获取
x-cos-meta-file-name	String	否	上传的原始文件名，如 `app-release.apk`
file	File	是	App 文件的本地路径

返回数据

上传成功：返回 HTTP 状态码 204 No Content。
上传失败：返回相应错误信息说明。

检测应用是否发布完成

检测应用是否发布完成，并获取发布应用的信息。

GEThttps://www.pgyer.com/apiv2/app/buildInfo

请求参数

参数名	类型	必填	说明
_api_key	String	是	API Key，请见鉴权说明
buildKey	String	是	第一步中返回的 key

返回数据

返回值分为以下三种情况。

参数	类型	说明
buildKey	String	Build Key，唯一标识应用的索引 ID
buildType	Integer	应用类型（1:iOS; 2:Android）
buildIsFirst	Integer	是否是第一个 App（1:是; 2:否）
buildIsLastest	Integer	是否是最新版（1:是; 2:否）
buildFileSize	Integer	App 文件大小
buildName	String	应用名称
buildVersion	String	版本号，默认为 1.0（向用户宣传时用到的标识，例如 1.1、8.2.1）
buildVersionNo	String	上传包的版本编号，默认为 1（即编译版本号，Android 上叫 Version Code。iOS 为字符串，Android 为整数，例如 1001、28）
buildBuildVersion	Integer	蒲公英生成的用于区分历史版本的 build 号
buildIdentifier	String	应用程序包名，iOS 为 BundleId，Android 为包名
buildIcon	String	应用 Icon 图标 key，访问地址为 `https://cdn-app-icon2.pgyer.com/<buildIconPath>/<buildIcon>?x-oss-process=image/resize,m_lfit,h_120,w_120/format,jpg`，buildIconPath 为 buildIcon 前 5 个字符用 `/` 连接。例如 buildIcon = `123abcdefaaa`，buildIconPath = `1/2/3/a/b`
buildDescription	String	应用介绍
buildUpdateDescription	String	应用更新说明
buildScreenShots	String	应用截图 key，访问地址为 `https://www.pgyer.com/image/view/app_screenshots/<screenshot_key>`
buildShortcutUrl	String	应用短链接
buildQRCodeURL	String	应用二维码地址
buildCreated	String	应用上传时间
buildUpdated	String	应用更新时间

{
  "code": 0,
  "message": "",
  "data": {
    "buildKey": "a1b2c3d4e5f6",
    "buildType": 2,
    "buildIsFirst": 2,
    "buildIsLastest": 1,
    "buildFileSize": 12345678,
    "buildName": "示例应用",
    "buildVersion": "1.1",
    "buildVersionNo": "28",
    "buildBuildVersion": 5,
    "buildIdentifier": "com.example.app",
    "buildIcon": "123abcdefaaa",
    "buildDescription": "示例介绍",
    "buildUpdateDescription": "修复若干问题",
    "buildScreenShots": "",
    "buildShortcutUrl": "abcd",
    "buildQRCodeURL": "https://www.pgyer.com/app/qrcode/abcd",
    "buildCreated": "2025-01-01 10:00:00",
    "buildUpdated": "2025-01-01 10:05:00"
  }
}

参数	类型	说明
code	Integer	错误码，1247 应用正在发布中
message	String	信息提示

{
  "code": 1247,
  "message": "应用正在发布中"
}

参数	类型	说明
code	Integer	错误码，1216 应用发布失败
message	String	信息提示

{
  "code": 1216,
  "message": "应用发布失败"
}

当返回 code = 1247（正在发布中）时，可间隔 3 ～ 5 秒重新调用接口进行检测，直到返回成功或失败。

上传 HarmonyOS App p12 证书

发布 HarmonyOS 的 hap 包时，需要上传 p12 签名证书。

POSThttps://upload.pgyer.com/apiv2/app/uploadHarmonyCert

请求需设置 Content-Type: multipart/form-data。

请求参数

参数名	类型	必填	说明
_api_key	String	是	API Key，请见鉴权说明
file	File	是	需要上传的 p12 文件
password	String	是	p12 文件密码
buildKey	String	是	见 buildKey

buildKey 对应的版本必须带有签名信息，请先上传用内部测试或企业 Profile 签名的安装包。

返回数据

参数	类型	说明
code	Integer	返回结果 code，`0` 表示证书已保存，大于 0 见下方错误码
message	String	出错时说明原因；`code` 为 `0` 且不为空时，表示证书已保存，但与该版本安装包的签名证书不一致
data	String	保存成功时为 `success`

P12 与该版本安装包的签名证书不一致时，证书仍会保存并返回 code: 0，但 message 会说明不匹配，测试者可能无法安装。此时请上传签名该安装包时使用的 P12。

错误码

错误码	说明
3001	`buildKey` 为空或找不到对应版本
3002	没有该 App 的权限
3003	不是 HarmonyOS App
3004	没有上传证书文件
3005	文件扩展名不是 `.p12`
3006	P12 证书尚未生效或已过期，`message` 附有生效或到期时间
3008	P12 密码错误，或文件不是有效的 P12 证书
3009	P12 中没有私钥，或无法读取私钥条目，请重新导出 P12
3010	证书保存失败，请稍后重试
3011	证书文件超过 10 MB
3012	证书文件为空
3013	证书文件格式无效
3014	该版本没有签名信息（未签名或无法识别），请先上传用内部测试或企业 Profile 签名的安装包

上传 HarmonyOS Hsp 文件

HarmonyOS 的 hap 如有 hsp 依赖时，需要上传相应的 hsp 文件。

POSThttps://upload.pgyer.com/apiv2/app/uploadHarmonyHsp

请求需设置 Content-Type: multipart/form-data。

请求参数

参数名	类型	必填	说明
_api_key	String	是	API Key，请见鉴权说明
file	File	是	需要上传的 Hsp 文件
buildKey	String	是	见 buildKey

返回数据

参数	类型	说明
code	Integer	返回结果 code，`0` 表示上传成功，大于 0 见错误码含义

上传 App（旧版）

本接口上传速度较慢，建议使用快速上传 App 替代。

POSThttps://upload.pgyer.com/apiv2/app/upload

请求参数

参数名	类型	必填	说明
_api_key	String	是	API Key，请见鉴权说明
file	File	是	需要上传的 ipa 或 apk 文件
buildInstallType	Integer	否	应用安装方式，默认 1。1：公开安装，2：密码安装，3：邀请安装
buildPassword	String	否	App 安装密码，为空时默认公开安装
buildUpdateDescription	String	否	版本更新描述，如没有请传空字符串或不传
buildInstallDate	Integer	否	是否设置安装有效期：1 设置有效时间，2 长期有效；不填写则不修改上一次的设置
buildInstallStartDate	String	否	安装有效期开始时间，如 `2018-01-01`
buildInstallEndDate	String	否	安装有效期结束时间，如 `2018-12-31`
buildChannelShortcut	String	否	所需更新的指定渠道短链接，只能指定一个，如 `abcd`

返回数据

参数	类型	说明
buildKey	String	Build Key，唯一标识应用的索引 ID
buildType	Integer	应用类型（1:iOS; 2:Android）
buildIsFirst	Integer	是否是第一个 App（1:是; 2:否）
buildIsLastest	Integer	是否是最新版（1:是; 2:否）
buildFileSize	Integer	App 文件大小
buildName	String	应用名称
buildVersion	String	版本号，默认为 1.0
buildVersionNo	String	上传包的版本编号，默认为 1
buildBuildVersion	Integer	蒲公英生成的用于区分历史版本的 build 号
buildIdentifier	String	应用程序包名，iOS 为 BundleId，Android 为包名
buildIcon	String	应用 Icon 图标 key，访问地址为 `https://cdn-app-icon2.pgyer.com/<buildIconPath>/<buildIcon>?x-oss-process=image/resize,m_lfit,h_120,w_120/format,jpg`，buildIconPath 为 buildIcon 前 5 个字符用 `/` 连接
buildDescription	String	应用介绍
buildUpdateDescription	String	应用更新说明
buildScreenShots	String	应用截图 key，访问地址为 `https://www.pgyer.com/image/view/app_screenshots/<screenshot_key>`
buildShortcutUrl	String	应用短链接
buildQRCodeURL	String	应用二维码地址
buildCreated	String	应用上传时间
buildUpdated	String	应用更新时间

上传与发布

本页目录