FreeSign-p12 简易代销参数对接文档

一、整体流程

1. 证书站创建简易代销 / 贴牌配置，生成唯一 short_site。
2. 证书站签名工具时修改 App 名称、图标、Bundle ID，并写入启动图资源。
3. 签名工具启动后调用 /api/signtool/index，使用当前 App 的 app_bundle_id 拉取远程配置。
4. 签名工具按设置启用默认软件源、安装域名、菜单、黑白名单、导入导出权限等。
5. 签名工具需要云端证书时调用 /api/signtool/udid 和 /api/signtool/getcertificate 两步拉取。

二、签名工具配置接口

签名工具启动时调用 Signtool.php 的配置接口，用于读取扩展菜单、默认软件源、安装域名、权限开关、公告等远程配置。

POST /api/signtool/index HTTP/1.1
Host: cert.invalid
Content-Type: application/x-www-form-urlencoded; charset=utf-8

app_bundle_id=com.vendor.signer

返回示例

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "domain": "cert.invalid",
    "app_bundle_id": "com.vendor.signer",
    "config": {
      "app_icon_url": "https://assets.invalid/icon.png",
      "app_name": "演示签名",
      "buy_url": "https://site.invalid/buy",
      "contact_url": "https://site.invalid/contact",
      "default_app_source_urls": "https://source.invalid/source.json",
      "exchange": true,
      "group": "https://site.invalid/group",
      "import_permissions": true,
      "export_permissions": true,
      "notice": "公告内容",
      "whitelist": true,
      "tutorial_url": "https://site.invalid/help",
      "plist_url": "https://cert.invalid/plist.php",
      "app_source_urls_qx": true
    }
  }
}

签名工具内部展开后的字段

{
  "app_bundle_id": "com.vendor.signer",
  "app_name": "演示签名",
  "plist_url": "https://cert.invalid/plist.php",
  "default_app_source_urls": "https://source.invalid/source.json",
  "app_icon_url": "https://assets.invalid/icon.png",
  "group": "https://qm.qq.com/xxx",
  "contact_url": "https://site.invalid/contact",
  "buy_url": "https://site.invalid/buy",
  "tutorial_url": "https://site.invalid/help",
  "notice": "公告内容",
  "exchange": 1,
  "import_permissions": 1,
  "whitelist": 1,
  "allow_external_source": true
}

三、贴牌设置字段

注意：

云端证书下载走 Signtool.php；已签名 App 的设备资格校验走 /api/signconfig，不依赖下载云端 P12。兼容接收字段不等于当前后台会返回或保存该字段。

四、云端证书接口

签名工具需要自动拉取证书时，使用 Signtool.php 的接口。第一步按 UDID 查 profile，第二步按 profile_id 获取 p12 和 mobileprovision。

1. 查询设备可用 Profile

POST /api/signtool/udid HTTP/1.1
Host: cert.invalid
Content-Type: application/x-www-form-urlencoded; charset=utf-8

udids[]=00008030-0012345678901234

{
  "code": 0,
  "msg": "成功",
  "data": {
    "profiles": [
      {
        "profile_id": "123456",
        "uuid": "PROFILE-UUID",
        "name": "00008030-0012345678901234",
        "status": "正常",
        "using": true,
        "devices": ["00008030-0012345678901234"],
        "expiration_date": "2026-12-31T00:00:00Z",
        "certificate": [
          {
            "name": "iOS Distribution",
            "id": "CERT-ID",
            "country": "US"
          }
        ]
      }
    ]
  },
  "time": 1780000000
}

2. 下载证书内容

POST /api/signtool/getcertificate HTTP/1.1
Host: cert.invalid
Content-Type: application/x-www-form-urlencoded; charset=utf-8

profile_id=123456

{
  "code": 0,
  "msg": "成功",
  "data": {
    "mobileprovision": "BASE64_MOBILEPROVISION",
    "p12": "BASE64_P12",
    "p12_password": "1"
  }
}

签名工具内部会把第二步返回值转换成原本使用的 p12、mobileprovision、password 结构，然后继续走原来的导入和保存逻辑。

成功码不同：配置接口成功为 code=1，以上两个证书接口成功为 code=0。证书接口在无匹配、参数不满足或解析失败的部分路径可能返回空响应，不保证统一错误 JSON；不得把空响应当作明确封禁。

五、浏览器唤醒签名工具打开网页

用于从网页或证书站页面直接打开签名工具内置浏览器。

<a href="freesign://web?url=https%3A%2F%2Fcert.invalid%2Findex%2Findex%2Fsigntool">
  打开签名工具网页
</a>

六、浏览器唤醒添加软件源

用于网页按钮一键拉起签名工具并添加软件源。

<a href="freesign://apps?url=https%3A%2F%2Fsource.invalid%2Fsource.json">
  添加软件源
</a>

<button onclick="location.href='freesign://apps?url=' + encodeURIComponent('https://source.invalid/source.json')">
  添加软件源
</button>

七、软件源 JSON 建议格式

签名工具的软件源解析较宽松，但建议统一使用下面结构，方便缓存和展示。

{
  "name": "示例软件源",
  "identifier": "invalid.source",
  "sourceicon": "https://assets.invalid/source-icon.png",
  "message": "源公告",
  "apps": [
    {
      "name": "示例 App",
      "bundleIdentifier": "invalid.app",
      "version": "1.0.0",
      "iconURL": "https://assets.invalid/app-icon.png",
      "downloadURL": "https://download.invalid/app.ipa",
      "localizedDescription": "应用介绍"
    }
  ]
}

八、安装链接 / Plist 服务

签名工具安装 App 时会把 App 名、图标、Bundle ID、IPA 地址组合后交给 plist_url 生成安装描述文件。

签名工具内部会按现有编码规则拼接 Plist 地址，外部对接通常只需要在贴牌设置里正确填写 plist_url。

九、HTML 表单示例

以下为已有贴牌记录的编辑表单示例，需登录证书站且记录属于当前用户；不能用于新建记录。提交时应回填已有值，三个开关提交字符串 true/false（不要用 1/0 代替）。

<form method="post" action="/index/index/signtool">
  <label>站点标识</label>
  <input name="row[short_site]" value="demo" readonly>

  <label>Bundle ID</label>
  <input name="row[app_bundle_id]" value="com.vendor.signer" readonly>

  <label>App 名称</label>
  <input name="row[app_name]" value="演示签名">

  <label>安装域名</label>
  <input name="row[plist_url]" value="https://cert.invalid/plist.php">

  <label>默认软件源</label>
  <input name="row[default_app_source_urls]" value="https://source.invalid/source.json">

  <label>图标 URL</label>
  <input name="row[app_icon_url]" value="https://assets.invalid/icon.png">

  <label>启动图 URL</label>
  <input name="row[app_launch_icon_url]" value="https://assets.invalid/launch.png">

  <label>QQ群</label>
  <input name="row[group]" value="https://site.invalid/group">

  <label>联系我们</label>
  <input name="row[contact_url]" value="https://site.invalid/contact">

  <label>购买链接</label>
  <input name="row[buy_url]" value="https://site.invalid/buy">

  <label>教程地址</label>
  <input name="row[tutorial_url]" value="https://site.invalid/help">

  <label>站点公告</label>
  <input name="row[notice]" value="欢迎使用">


  <label>黑白名单</label>
  <label><input type="radio" name="row[whitelist]" value="true"> 开启</label>
  <label><input type="radio" name="row[whitelist]" value="false" checked> 关闭</label>

  <label>导入/导出权限</label>
  <label><input type="radio" name="row[import_permissions]" value="true" checked> 开启</label>
  <label><input type="radio" name="row[import_permissions]" value="false"> 关闭</label>

  <button type="submit">保存设置</button>
</form>

十、对接检查清单

十一、黑白名单、动态库注入与已签名 App

FreeSign-p12 使用证书站 fa_signtool.whitelist，对应 /application/index/view/index/signtool.html 中的黑白名单开关。它与 FreeSign / ioszj 签名后台的 runtime_lock_enabled 是两套协议，不可混用。

1. 组件 POST 请求 /api/signtool/index，携带签名工具的 app_bundle_id（不是被签名应用的 Bundle ID）。
2. 有效响应中 data.config.whitelist=false：放行，后续签名不注入；重签时清理已有权限动态库。
3. whitelist=true：继续 GET 请求下方资格接口。只有明确有效的结果才更新权限缓存。

GET /api/signconfig?udid=00008030-0012345678901234&appid=com.vendor.signer&version=1

{"code":0,"msg":"该 UDID 不是有效使用设备","data":[]}

断网保留上次有效结果：上次允许则继续允许，上次拒绝则保持拒绝；联网后重新获取。首次没有缓存时静默等待校验，尚未取得允许结果时不开放操作；校验失败或明确拒绝后提示“设备无使用权限，请联系客服”。当前没有本地到期计时。

已注入组件的 App 也会走上述流程；关闭 whitelist 后，下次联网校验成功会放行，但不会从已安装 App 中删除动态库。未注入组件的 App 不会因后台重新开启开关自动获得校验能力，需要重新签名安装。

产物仅使用与主程序同目录的 FSRuntimeAccess.dylib，加载路径为 @executable_path/FSRuntimeAccess.dylib，配置嵌入库内，不单独生成或读取 FSRuntimeAccess.json。组件封装不是不可篡改的设备身份认证。

十二、数据库字段与状态区别

当前资格接口不直接返回 zt：只要该 UDID 没有 normal 记录，就返回相同的无资格结果。因此 disabled、hidden 和不存在均可能导致拒绝，客户端不能据此准确区分人工禁用和掉签。若同一 UDID 仍存在 normal 记录，当前查询仍会允许。

下面把正常设备、无权限设备以及相关独立字段完整列在本 HTML 中。本次仅补全文档，不更改上述判定逻辑，也不需要执行数据库升级。

十三、正常设备与无权限设备字段

当前接口没有单独的 normal_device、allowed、banned 或 no_permission 字段。服务端先检查数据库 fa_deviceslist.zt，客户端再根据整个响应结构判断权限。

1. 请求字段

2. 数据库权限字段

3. 正常设备响应

只有以下三个条件同时满足，当前动态库才把本次资格响应解释为“正常 / 有权限”：code 是数字 1、data.app_bundle_id 与请求的工具 Bundle ID 完全一致、data.config 是非空对象。

{
  "code": 1,
  "msg": "返回成功",
  "data": {
    "domain": "cert.invalid",
    "app_bundle_id": "com.vendor.signer",
    "config": {
      "iid": 0,
      "app_type": 2,
      "app_name": "演示签名",
      "app_color": "#000000",
      "vip_time": "演示签名",
      "default_app_source_urls": "https://source.invalid/source.json",
      "app_source_urls_qx": false,
      "import_app_source": 1,
      "qq_url": "https://site.invalid/group",
      "contact_url": "https://site.invalid/contact",
      "buy_url": "https://site.invalid/buy",
      "buy_app": "https://site.invalid/buy",
      "jc_url": "https://site.invalid/help",
      "import_permissions": true,
      "export_permissions": true,
      "timelock": 0,
      "ver": "1.3.2",
      "notice": "",
      "plisturl": "cert.invalid",
      "cert_search_url": "/api/certall"
    }
  }
}

4. 无权限设备响应

当没有查询到 udid 相同且 zt=normal 的记录时，当前接口返回：

{
  "code": 0,
  "msg": "该 UDID 不是有效使用设备",
  "data": []
}

5. 其他失败响应

{
  "code": 0,
  "msg": "未找到相关配置",
  "data": []
}

这个响应表示 appid 没有匹配 fa_signtool，不是明确的设备封禁。网络错误、HTTP 非 200、重定向、JSON 错误、Bundle ID 不匹配、空 config 或其他消息同样属于“未知 / 校验失败”。它们不会把最后一次有效的允许或拒绝改写为相反状态。

6. 状态判断速查

十四、跨站点适配总览：当前实现与需要修改的位置

本节以当前 FreeSign-p12 为准。前面第十三节的成功示例来自本地 fa_signtool 版本，并不代表所有站点的 Signconfig.php 都使用相同数据库。下面明确区分接口约定与各站点内部字段。所列适配方案尚未实施。

1. 实际调用流程

配置和证书流程：
工具 Bundle ID
  → POST 配置入口 /api/signtool/index（app_bundle_id）
  → 读取 data.config；data.domain 决定证书 API 基址
  → POST 证书站 /api/signtool/udid（udids[]=设备 UDID）
  → 读取 data.profiles[].profile_id
  → POST 同证书站 /api/signtool/getcertificate（profile_id）
  → 解析 P12 和描述文件 → 保存本地 / 展示证书

权限流程（取得有效 UDID 后启动，与证书下载分别执行）：
  → POST 配置入口 /api/signtool/index（原工具 app_bundle_id）
  → whitelist=false：允许，后续签名不注入
  → whitelist=true：GET 证书站 /api/signconfig
       （udid=设备UDID、appid=原工具BundleID、version=1）
       → 明确允许 / 明确拒绝：更新缓存
       → 无效响应 / 请求失败：保留上次有效权限

签名产物含 FSRuntimeAccess.dylib 时：
  → 组件使用签名时嵌入的接口地址、原工具 Bundle ID 和设备 UDID
  → 独立执行同一套权限流程，不依赖原签名工具保持运行

权限组件可在云端证书同步前或过程中遮住界面，因此“打不开”和“证书下载失败”需要分别检查。组件只接受 HTTPS、HTTP 200 的有效 JSON，并拒绝跳转；一个能在浏览器中跳转打开的接口，不一定能被组件使用。

2. App 真正需要的接口字段

配置成功码是 1，证书成功码是 0，不要统一改成同一个值。当前 getcertificate 下载失败可能被逐个候选重试后转换成空列表，所以“暂无证书”也可能是下载阶段失败，不一定是设备没有证书。

3. 数据库字段不同，如何适配

最新上传的 Signconfig(1).php 还调用 Dsign()，并要求 fa_website.bidname 匹配、bidswitch=1、endtime 未到期；这些条件是这一版服务端的要求，不是所有 Signtool 站点原本都有的要求。仅上传这个控制器不代表站点已经具备它依赖的记录和函数。

4. 各种站点的适配选择

以“站点不修改”为前提，推荐在 App 中按已知协议增加适配，分别配置配置入口、证书接口和权限来源；这是后续方案，当前代码尚未实现通用多站点适配。无法从“没有证书”可靠推断“设备被禁用”，因为无证书还可能来自到期、鉴权失败、空数据或服务故障。

5. 适配前提供哪些信息

1. 工具实际 Bundle ID、配置入口，以及配置响应中的 domain。
2. 配置响应、UDID 查询响应和证书下载响应的 code、msg、字段结构；P12、描述文件和密码用占位符替换，不提供私钥内容。
3. 正常、人工禁用、掉签三种设备各自的权限响应，或对应服务端判断代码。
4. 是否存在 Signconfig；如果没有，哪个现有接口能够明确返回设备禁用状态。
5. 若接口有鉴权，提供鉴权实现或协议说明，不在公开文档中填写实际密钥。