記事 8 / 8

小売業者の在庫

メーカーから委託された時計を含む在庫の時計:一覧の取得、時計の検索、そして未販売の時計を同じメーカーの別の小売業者へ移管する方法。

在庫の内容

小売業者として、お客様の一覧には、お客様が作成した時計、所有している時計、そして在庫の時計が含まれます。在庫の時計とは、メーカーがお客様のもとに置いた時計で、パスポートまたはまだカードのない時計です。在庫に時計を入れたり戻したりできるのはメーカーだけです。

在庫の時計は、販売されていない間はお客様に委託されています。つまり、販売が登録されておらず、メーカー以外に所有者がいない状態です。購入者への販売が登録されると、購入者が確認する前でも販売済みとみなされます。

在庫の一覧

GET /certificates/listにorigin=entrustedを付けると、カードの有無にかかわらずお客様に委託された時計が返され、origin=ownでは一覧のそれ以外の時計が返されます。originを付けない場合は両方が返されます。originは小売業者のアカウントでのみ読み取られます。

一覧はページ単位で返されます。pageは0から、sizeは1ページの行数で、デフォルトは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:カードIDはcertificateCardIds(各9文字の英数字)、時計IDはwatchIds。いずれかに一致する行が返されます。
  • ブランド、モデル、リファレンス: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移管中に時計が変わりました(販売の登録、メーカーによる引き戻し、またはいずれかの小売業者がメーカーの一覧から外れた)。何も書き込まれていません。

その後

受け取る小売業者には時計が在庫に届いたことを知らせるメールが、メーカーには移管されたことを知らせるメールが届きます。同じ10分間の移動は1通のメールにまとめられます。お客様にはメールは届きません。

移管によってパスポートの履歴に何かが追加されることはなく、クレジットも消費されません。