第 6 篇,共 8 篇
API 返回什么
JSON 格式,始终返回完整资源;出现阻碍时返回稳定的错误代码。
响应
- 创建手表会返回该手表及其
watchId。之后关联卡片时要提供的正是这个watchId(而不是id)。 - 检查卡片(
can-link-card)返回canLinkCard和一个passportCheck:采用的级别、缺少的字段、已登记的序列号。 - 关联卡片会返回已创建的护照及其卡号(
certificateCardId)。 - 读取护照会返回其全部信息:手表、照片、认证级别、失窃状态、保修,以及您有权查看范围内的所有者信息。
列表采用分页。标签遵循 accept-language 请求头中指定的语言(默认英语)。
通过您的参考编号查找护照
GET /certificates/by-external-ref/{ref} 返回为您的参考编号创建的护照,响应与 GET /certificates/{certificateCardId} 相同。您只能看到自己创建的内容。搜索不区分大小写并忽略空格,包含 / 的参考编号需编码为 %2F。
在卡片关联之前,响应为 404:GET /watches/by-external-ref/{ref} 可在任何阶段找到该手表。
错误
出错时会返回一个 HTTP 状态码,响应体中包含一个稳定的代码(code)、一条使用请求语言的消息(message),有时还有详细信息(params)。请读取代码而不是消息,消息可能会变化。例如:
| HTTP 状态码 | code | 含义 |
|---|---|---|
| 422 | PASSPORT_ | 缺少字段:params.missingFields 会列出它们 |
| 409 | PASSPORT_ | 该制造商的另一本护照已使用此序列号 |
| 403 | PASSPORT_ | 此认证级别不向您的行业开放 |
| 400 | OWNERSHIP_ | 登记为所有者的邮箱地址属于专业人士 |