第 8 篇,共 8 篇
零售商的库存
您库存中的手表,包括制造商委托给您的手表:列出它们、查找其中一块,并将尚未售出的手表转移给同一制造商的另一家零售商。
您的库存包含什么
作为零售商,您的列表包含您创建的手表、您拥有的手表以及您库存中的手表:即制造商放在您处的手表,可以是护照,也可以是尚无卡片的手表。只有制造商可以将手表放入您的库存或将其收回。
您库存中的手表在售出之前都是委托给您的:尚未登记销售,且除其制造商外没有其他所有者。向买家登记的销售即使在买家确认之前也算作已售出。
列出您的库存
GET / 加上 origin=entrusted 返回委托给您的手表(无论有无卡片),origin=own 返回列表中的其余手表;不带 origin 时两者都会返回。origin 仅对零售商账户生效。
列表按页返回:page 从 0 开始,size 为每页行数,默认 20。sort 用于排序:recent(最近更新的在前,默认)、brand(品牌按 A 到 Z,然后按型号)或 created(最近创建的在前)。totalCertificatesCount 统计所有页的行数,但使用 format=medium 或 format=extra_small 时除外。
curl "https://api.watchcertificate.org/api/v1/certificates/list?origin=entrusted&page=0&size=20&sort=recent" \
-H "api-key: YOUR_API_KEY"对于委托给您的手表,该行包含:
watchMakerUser:其制造商,包括其 ID、角色和公司名称;entrustedBy:委托人,即其制造商或将其转移给您的零售商;entrustedAt:它进入您库存的时间;canTransferToRetailer:您现在是否可以转移它(见下文);serialCase:其表壳序列号,完整显示;externalRef:null。只有创建该手表的账户(此处为其制造商)才能读取参考编号。
调用需要在 api-key 请求头中提供您的 API 密钥,且密钥包含“手表”范围(watches)。没有“客户”范围时,行中保留手表数据,但其中的人员(例如所有者)返回 null。
查找手表
将这些参数与 origin=entrusted 一起使用,即可只在委托给您的手表中查找。筛选只会缩小您的列表:绝不会触及其他零售商的库存,也不会触及制造商的其他手表。
- 搜索:
searchText,逐词匹配,每个词可出现在品牌、型号、参考编号、卡片 ID 或表壳序列号(不含机芯序列号)中的任意位置,也可出现在所有者和零售商的名称中; - 精确 ID:
certificateCardIds用于卡片 ID(每个 9 位字母或数字),watchIds用于手表 ID。与其中任意一个匹配的行都会返回; - 品牌、型号、参考编号:
brands、models和references,按文本开头匹配,不区分大小写; - 最近更新时间:
startDate为该日期当天或之后,endDate为该日期当天或之前。
curl "https://api.watchcertificate.org/api/v1/certificates/list?origin=entrusted&searchText=AB12345" \
-H "api-key: YOUR_API_KEY"您自己的参考编号只能找到您创建的手表:列表中的 externalRefs、GET / 和 GET /。委托给您的手表带有其制造商的参考编号,您看不到:请通过其卡片 ID、手表 ID 或表壳序列号查找。
读取手表
GET / 读取护照,GET / 读取尚无卡片的手表:字段与列表中相同,包括 canTransferToRetailer。不存在的卡片 ID 或手表 ID 返回 404。
选择接收的零售商
GET / 加上 certificateCardId(尚无卡片的手表则用 watchId)会列出您可以将其转移给的零售商:即其制造商的其他有效零售商。每行只包含其 id 以及公司名称、城市和国家,searchText 可按名称或城市筛选。该 id 就是转移所用的 userId。
对于转移会拒绝的手表(不在您的库存中或已售出),此调用会以相同的代码拒绝(见下文)。您的密钥需要“网络”范围(network)。
curl "https://api.watchcertificate.org/api/v1/users/list?usersListFilter=transfer-retailers&certificateCardId=ABC123456" \
-H "api-key: YOUR_API_KEY"转移尚未售出的手表
护照使用 POST /,尚无卡片的手表使用 POST /,无需请求体:userId 为接收的零售商。之后已关联卡片的手表仍可通过其手表 ID 访问。您的密钥需要“网络”范围(network),只读密钥无法转移。
满足以下条件时转移才会完成:
- 手表在您的库存中,且其制造商仍将您列为其有效零售商之一;
- 按上文的定义,它尚未售出;
- 接收的零售商是同一制造商的另一家有效零售商:绝不能是您自己,也绝不能是其他制造商的零售商。
转移只在该手表制造商的零售商之间进行,只有制造商可以收回手表。
curl -X POST https://api.watchcertificate.org/api/v1/users/1234/certificates/ABC123456/transfer \
-H "api-key: YOUR_API_KEY"响应(201)为接收的零售商,格式与上面的零售商列表相同:
{
"id": 1234,
"company": {
"name": "Boutique Exemple",
"city": "Lyon",
"countryCode": "FR"
}
}手表转入接收零售商的库存,并自此委托给该零售商;其 entrustedBy 显示为您。其他一切不变:其制造商、所有者和卡片保持不变。
写入之前会先检查所有条件:出错后手表不会被移动。未知的卡片 ID 或手表 ID 返回 404;其他拒绝按检查顺序如下:
| HTTP 状态码 | code | 含义 |
|---|---|---|
| 403 | RETAILER_ | 此环境未开放零售商之间的转移。 |
| 403 | RETAILER_ | 手表不在您的库存中,或其制造商已不再将您列为其有效零售商。 |
| 409 | RETAILER_ | 手表已售出:已登记销售,或除其制造商外的其他人是其所有者,包括尚未确认的买家。 |
| 400 | RETAILER_ | 接收的零售商是您自己。 |
| 403 | RETAILER_ | 接收的零售商不是该手表制造商的有效零售商,或没有账户使用此 ID。 |
| 409 | OWNERSHIP_ | 转移期间手表发生了变化:登记了销售、其制造商将其收回,或两家零售商之一离开了其名单。未写入任何内容。 |
之后会发生什么
接收的零售商会收到一封邮件,告知手表已进入其库存;制造商会收到一封邮件,告知手表已被转移;同一十分钟内的变动合并在一封邮件中。您不会收到邮件。
转移不会在护照历史记录中添加任何内容,也不会消耗任何积分。