Skip to main content
企业组织可以将鉴定照片和证书存放在公开 CDN 之外。上传写入私有存储桶,读取返回 CloudFront 签名 URL。公开分享页不会显示照片。 创建、读取和提交服务请求仍使用原来的合作伙伴 API。变化的只是上传路径和媒体 URL 的形态。 如果您的组织使用公开 CDN,请使用标准工作流程的上传路径(GET /intent)。

所需范围

您的 API 密钥除 sr:v2:createsr:v2:read 外,还必须包含 media:v2:private-read。当组织启用私有媒体时,Legitmark 会授予此范围。 以下所有调用都使用同一把 leo_ 密钥:
没有 media:v2:private-read 时,私有 CDN 组织的 GET /api/v2/sr/{sr_uuid} 会返回空的 media_url 数组,且 certificate_url 为 null。

集成步骤

与公开合作伙伴 API 相同,只有两处变化:不要调用 /intent,并将每条媒体 URL 视为短期有效。
1

创建服务请求

使用 leo_ 密钥和常规请求体调用 POST /api/v2/sr?sides=true&item=true。传入 sides=true&item=true 会在响应中直接返回必需/可选照片列表,上传前无需再请求一次。API 参考: POST /api/v2/sr
2

上传照片

对所有面调用一次 POST /api/media/signed-urls/{sr_uuid},然后将每张图片 PUT 到返回的 signed_url不要调用 GET /intent
3

读取照片

使用同一密钥调用 GET /api/v2/sr/{sr_uuid}?item=true&sides=truemedia_url(以及传入 summary=true 时的 summary.thumbnail)是有效约 15 分钟的私有 CDN 签名链接。
4

读取证书

使用最新 Get Full SR 返回的 certificate_url。如果收到 Access Denied403,请重新获取。也可以在控制台通过 Download certificate 重新生成。

上传照片

不要调用 GET https://asset.legitmark.com/intent(以及开发和预发布的资产主机)。该路径写入公开存储桶,无法路由私有组织的上传。 一次请求获取所有面的上传 URL,然后将图片字节 PUT 到每个 URL。 API 参考: POST /api/media/signed-urls/{sr_uuid}
请求体 响应
signed_url 发送 PUT 时不要携带 Authorization 头。该 URL 已经过签名,如果存在 Authorization 头,S3 会以 400 拒绝请求。只有 POST /api/media/signed-urls/{sr_uuid} 需要使用 API 密钥认证。
TypeScript SDK 目前仍使用 GET /intent。私有 CDN 组织应通过 HTTP 调用 POST /api/media/signed-urls/{sr_uuid},直到 SDK 更新。

浏览器上传(CORS)

如果仓库应用或 Web 应用从浏览器 PUT 图片,S3 必须允许该页面的来源。请将所有上传来源告知 Legitmark(精确来源和 https://*.example.com 通配符)。组织中已放行的来源可继续使用。PUT 出现 CORS 错误说明需要添加新来源 — 不要回退到 /intent

读取照片

使用同一把 API 密钥获取服务请求。media_url 是私有 CDN 主机上的 CloudFront 签名链接。 API 参考: GET /api/v2/sr/{sr_uuid}
签名读取 URL 形如(查询值已截断):
  • 保留 URL 上的 ExpiresKey-Pair-IdSignature。去掉查询字符串会返回 403
  • 传入 summary=true 时,summary.thumbnail 以同样方式签名。
  • 早期测试中的公开 cdn.legitmark.com 链接不再提供这些照片。

证书

最新 GET /api/v2/sr/{sr_uuid} 返回的 certificate_url 是同一私有主机上的签名 PDF 链接。请使用该 URL。如果收到 Access Denied403,说明签名已过期 — 再次调用 GET 并使用新 URL。 也可以在控制台(https://app.legitmark.com 或开发/预发布应用主机)通过 Download certificate 重新生成新链接。 不要复用之前保存的证书链接。

URL 有效期

签名读取 URL 自签发时起有效 15 分钟expires_in 默认 900 秒)。
  • 不要将签名 URL 持久化或缓存在自己的数据库中。
  • 不要把签名 URL 当作长期分享链接写入日志或转发给他人。持有该 URL 的人在过期前都能获取对象。
  • 每次需要显示或下载照片或证书时,重新调用 GET /api/v2/sr/{sr_uuid}
  • 过期或未签名的 URL 返回 403。这是预期行为。请获取新的 URL。
Webhook 负载不包含媒体 URL。收到 state_change 后,如需照片或证书,请再获取 SR。

公开分享页

公开分享页不会显示私有 CDN 组织的照片。这是预期行为。照片和证书仅可通过带密钥的合作伙伴 API 访问。

环境

{org} 替换为 Legitmark 为您的组织预配的主机名。请使用 API 返回的 URL,不要自行拼接 CDN 主机。

图片要求

与公开工作流程相同:
  • 格式: JPG/JPEG/PNG
  • 尺寸: 最小 600 x 600 像素
  • 文件大小: 每张图片最大 5 MB
  • 质量: 清晰、光线充足、对焦准确的图片