第 8 篇,共 8 篇

零售商的库存

您库存中的手表,包括制造商委托给您的手表:列出它们、查找其中一块,并将尚未售出的手表转移给同一制造商的另一家零售商。

您的库存包含什么

作为零售商,您的列表包含您创建的手表、您拥有的手表以及您库存中的手表:即制造商放在您处的手表,可以是护照,也可以是尚无卡片的手表。只有制造商可以将手表放入您的库存或将其收回。

您库存中的手表在售出之前都是委托给您的:尚未登记销售,且除其制造商外没有其他所有者。向买家登记的销售即使在买家确认之前也算作已售出。

列出您的库存

GET /certificates/list 加上 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 /watches/by-external-ref/{ref} 和 GET /certificates/by-external-ref/{ref}。委托给您的手表带有其制造商的参考编号,您看不到:请通过其卡片 ID、手表 ID 或表壳序列号查找。

读取手表

GET /certificates/{certificateCardId} 读取护照,GET /watches/{watchId} 读取尚无卡片的手表:字段与列表中相同,包括 canTransferToRetailer。不存在的卡片 ID 或手表 ID 返回 404。

选择接收的零售商

GET /users/list?usersListFilter=transfer-retailers 加上 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 /users/{userId}/certificates/{certificateCardId}/transfer,尚无卡片的手表使用 POST /users/{userId}/watches/{watchId}/transfer,无需请求体: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含义
403RETAILER_TRANSFER_DISABLED此环境未开放零售商之间的转移。
403RETAILER_TRANSFER_NOT_YOUR_STOCK手表不在您的库存中,或其制造商已不再将您列为其有效零售商。
409RETAILER_TRANSFER_SOLD手表已售出:已登记销售,或除其制造商外的其他人是其所有者,包括尚未确认的买家。
400RETAILER_TRANSFER_TO_YOURSELF接收的零售商是您自己。
403RETAILER_TRANSFER_TARGET_NOT_IN_NETWORK接收的零售商不是该手表制造商的有效零售商,或没有账户使用此 ID。
409OWNERSHIP_CHANGED转移期间手表发生了变化:登记了销售、其制造商将其收回,或两家零售商之一离开了其名单。未写入任何内容。

之后会发生什么

接收的零售商会收到一封邮件,告知手表已进入其库存;制造商会收到一封邮件,告知手表已被转移;同一十分钟内的变动合并在一封邮件中。您不会收到邮件。

转移不会在护照历史记录中添加任何内容,也不会消耗任何积分。