适用场景
在 iOS 应用开发和发布流程中，证书与描述文件的管理是频繁且容易出错的环节。开发者经常需要：
- 在 CI/CD 流水线中验证打包证书是否有效、是否被吊销。
- 监控描述文件中准备的设备 UDID 是否满足分发要求。
- 区分证书类型（Development / Distribution / Enterprise）并确认与描述文件的匹配关系。
- 审计应用的推送（aps）、调试（debug）、Keychain 等 25 项 entitlements 权限是否开启。
- 提前感知证书即将过期，避免因证书失效导致构建失败或应用无法安装。
上述场景如果人工逐一检查，效率低下且容易遗漏。通过调用统一的检测接口，可以将这些校验步骤工具化、自动化，集成到团队的 CI 脚本或内部管理平台中。
接口能力边界
本接口专注于解析 .p12 格式的证书文件与 .mobileprovision 格式的描述文件，并提供结构化数据输出。核心能力包括：
- 解析证书基本信息（名称、颁发者、序列号等）。
- 验证证书吊销状态（调用 Apple OCSP 或 CRL 实时检测）。
- 计算证书剩余有效天数。
- 识别证书类型（Development / Distribution / Enterprise）及 Team ID。
- 提取描述文件的权限列表（25 项 entitlements）和准备设备列表。
- 自动对比证书与描述文件是否匹配（同一 Team、证书是否在描述文件的 Certificates 数组中）。
- 接口 QPS 为 5，适合定时轮询或单次触发，不建议在大量并发场景下直接使用。
该接口不主动修改证书或描述文件，仅提供只读检测结果，因此可以安全地集成到生产环境中。
请求参数与鉴权
请求地址
POSThttps://v1.apizero.cn/api/ios-cert
HTTP 头
| 参数名 | 必须 | 类型 | 说明 |
|---|---|---|---|
| X-API-Key | 是 | string | 用于身份认证的 API Key，需向平台申请。 |
| Content-Type | 是 | string | 固定为application/json。 |
注意：实际使用时请以官方文档为准，Header 名称可能调整为
Authorization或其他格式。下文的 curl 示例采用X-API-Key，与官方提供的示例保持一致。
请求体
请求体为一个 JSON 对象，包含以下字段：
| 字段名 | 必须 | 类型 | 说明 |
|---|---|---|---|
| cert | 是 | string | Base64 编码的 .p12 文件内容。 |
| provision | 是 | string | Base64 编码的 .mobileprovision 文件内容。 |
| password | 否 | string | 证书密码，默认为空字符串。 |
获取 Base64 编码的方法（以 Linux/macOS 为例）：
base64 -w 0 path/to/certificate.p12 # 输出 cert 字符串 base64 -w 0 path/to/profile.mobileprovision # 输出 provision 字符串Windows 用户可以使用 PowerShell：[Convert]::ToBase64String([IO.File]::ReadAllBytes("path\to\certificate.p12"))。
接入示例
curl 请求
将你的 API Key 设为环境变量APIZERO_API_KEY，然后执行：
curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cert": "<your base64 encoded .p12>", "provision": "<your base64 encoded .mobileprovision>", "password": "<cert password if any>" }' \ "https://v1.apizero.cn/api/ios-cert"替换<...>中的占位符为实际值。如果证书无密码，可省略password字段或设为空字符串""。
Python 接入（示意）
import requests import base64 API_ENDPOINT = "https://v1.apizero.cn/api/ios-cert" API_KEY = "your_api_key_here" def check_ios_cert(p12_path, provision_path, password=""): with open(p12_path, "rb") as f: cert_b64 = base64.b64encode(f.read()).decode() with open(provision_path, "rb") as f: provision_b64 = base64.b64encode(f.read()).decode() headers = { "X-API-Key": API_KEY, "Content-Type": "application/json" } payload = { "cert": cert_b64, "provision": provision_b64, "password": password } resp = requests.post(API_ENDPOINT, json=payload, headers=headers) return resp.json() # 示例使用 result = check_ios_cert("distribution.p12", "app.mobileprovision", "mypassword") print(result)返回字段解读
成功时 HTTP 状态码为 200，响应体为 JSON 格式，结构如下：
{ "code": 0, "msg": "成功", "data": { "certificate": { "name": "iPhone Developer: John Doe (ABCD1234)", "is_revoked": false, "status": "正常" }, "mobileprovision": { "cert_end_days": 350, "cert_type": "Development" }, "is_matching": true, "permissions": { "aps": true, "debug": true, "keychain": true, "in_app_purchase": false } } }字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功，其他值表示错误，详见错误处理。 |
| msg | string | 状态描述。 |
| data | object | 检测结果主体。 |
| data.certificate.name | string | 证书通用名称，通常包含开发者名称和 Team ID。 |
| data.certificate.is_revoked | boolean | 证书是否已被 Apple 吊销。 |
| data.certificate.status | string | 可读状态，如“正常”、“已吊销”。 |
| data.mobileprovision.cert_end_days | int | 证书剩余有效天数。 |
| data.mobileprovision.cert_type | string | 证书类型：Development、Distribution、Enterprise等。 |
| data.is_matching | boolean | 描述文件是否包含当前证书，true表示匹配。 |
| data.permissions | object | 包含 25 项 entitlements 的布尔值键值对，如aps表示推送权限。 |
cert_type可帮助开发者确认证书用途：开发阶段应使用Development，App Store 或 Ad Hoc 分发使用Distribution，企业内部分发使用Enterprise。若实际类型与预期不符，需及时更换证书。
is_matching是最关键的校验结果之一。当将描述文件与证书配合使用时，必须保证描述文件的 Certificates 数组中包含该证书，否则签名或安装会失败。
错误处理
调用接口可能遇到以下错误情况：
| HTTP 状态码 | 业务 code | 可能原因 | 处理建议 |
|---|---|---|---|
| 401 | -1 | API Key 无效或未提供 | 检查 Header 中 X-API-Key 是否正确 |
| 400 | 1001 | 请求参数缺失（cert 或 provision 为空） | 确保 body 包含必要的字段 |
| 400 | 1002 | Base64 格式错误 | 确认文件已正确编码，没有多余换行 |
| 400 | 1003 | 证书密码错误 | 核实密码，或尝试空密码 |
| 400 | 1004 | 描述文件格式无效 | 上传的 .mobileprovision 是否为 Apple 官方格式 |
| 403 | 1005 | QPS 超限（超过 5/s） | 降低请求频率，加入重试退避 |
注意：错误码和描述以实际返回为准，上方表格仅为常见场景归纳。程序应始终检查code字段，并根据msg输出日志或提示。
工程化注意事项
Base64 编码的完整性：使用
base64 -w 0或编程语言的base64库时，务必不产生换行符。部分工具默认每 76 个字符插入换行，会导致解析错误。API Key 安全：不要将 API Key 硬编码在代码仓库中。建议通过环境变量、CI Secret 或配置中心注入。
重试与限流：QPS 限制为 5，如果需要在短时间内检测大量证书，请实现节流队列。遇到 403 状态码时，指数退避重试。
定时检测：通过 cron 或调度工具每日运行检测脚本，发现证书即将过期（如剩余天数 < 30）时发送告警通知（邮件、钉钉、企业微信等）。
日志与监控：记录每次检测的原始响应和使用的证书指纹，便于事后追溯。可存储到数据库中形成证书生命周期管理视图。
离线降级：如果因网络问题无法调用接口，建议保留上一次的检测结果，避免阻塞发布流程。当网络恢复后重新校验。
参考文档
- API 官方文档：https://apizero.cn/aidocs/ios-cert
- 原始 Markdown 说明：https://apizero.cn/aidocs/ios-cert/raw.md
（注意：本文档可能更新，请以官网为准。）
