Article 8 of 8

A retailer's stock

The watches of your stock, those a manufacture entrusted to you included: list them, find one, and transfer a watch not sold yet to another retailer of its manufacture.

What your stock holds

As a retailer, your list holds the watches you created, those you own, and those of your stock: the watches a manufacture placed with you, passports or watches with no card yet. Only the manufacture places a watch in your stock or takes it back.

A watch of your stock is entrusted to you as long as it is not sold: no sale is declared, and nobody owns it but its manufacture. A sale declared to a buyer counts, even before they confirm it.

Listing your stock

GET /certificates/list with origin=entrusted returns the watches entrusted to you, with or without a card, and origin=own the rest of your list; without origin, you get both. origin is read for a retailer's account only.

The list comes a page at a time: page from 0, size rows a page, 20 by default. sort orders it: recent (the last updated first, by default), brand (the brands from A to Z, then the model) or created (the last created first). totalCertificatesCount counts the rows of every page, except with format=medium or 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"

On a watch entrusted to you, the row tells:

  • watchMakerUser: its manufacture, by its id, its role and its company's name;
  • entrustedBy: who entrusted it to you, its manufacture or the retailer that transferred it to you;
  • entrustedAt: since when it is in your stock;
  • canTransferToRetailer: whether you may transfer it now (see below);
  • serialCase: its case serial number, in clear;
  • externalRef: null. A reference is read only by the account that created the watch, here its manufacture.

The call needs your API key, in the api-key header, with the Watches area (watches). Without the Customers area, the rows keep the watch's data, but the people in them, its owner for example, come back null.

Finding a watch

Add these parameters to origin=entrusted to stay among the watches entrusted to you. A filter only narrows your list: it never reaches another retailer's stock, nor the manufacture's other watches.

  • A search: searchText, word by word, each word anywhere in the brand, the model, the reference, the card id or the case serial number (not the movement's), and in the owner's and the retailer's names;
  • Exact ids: certificateCardIds for card ids (9 letters or digits each), watchIds for watch ids. A row matching any one of them comes back;
  • The brand, the model, the reference: brands, models and references, matched on the start of the text, case-insensitive;
  • The last update: startDate on or after a date, endDate on or before.
curl "https://api.watchcertificate.org/api/v1/certificates/list?origin=entrusted&searchText=AB12345" \
  -H "api-key: YOUR_API_KEY"

Your own reference finds only the watches you created: externalRefs in the list, GET /watches/by-external-ref/{ref} and GET /certificates/by-external-ref/{ref}. A watch entrusted to you carries its manufacture's reference, which you do not see: find it by its card id, its watch id or its case serial number.

Reading a watch

GET /certificates/{certificateCardId} reads a passport, GET /watches/{watchId} a watch with no card yet: the same fields as in the list, canTransferToRetailer included. A card id or a watch id that does not exist answers 404.

Choosing the receiving retailer

GET /users/list?usersListFilter=transfer-retailers with certificateCardId, or watchId for a watch with no card yet, lists the retailers you may transfer it to: the other active retailers of its manufacture. Each row gives only its id and its company's name, city and country, and searchText filters them by name or city. That id is the transfer's userId.

This call refuses a watch the transfer would refuse, not in your stock or sold, with the same codes (below). Your key needs the Network area (network).

curl "https://api.watchcertificate.org/api/v1/users/list?usersListFilter=transfer-retailers&certificateCardId=ABC123456" \
  -H "api-key: YOUR_API_KEY"

Transferring a watch not sold yet

POST /users/{userId}/certificates/{certificateCardId}/transfer for a passport, POST /users/{userId}/watches/{watchId}/transfer for a watch with no card yet, without a body: userId is the receiving retailer. A watch whose card was linked since still answers to its watch id. Your key needs the Network area (network), and a read-only key does not transfer.

The transfer goes through when:

  • the watch is in your stock, and its manufacture still counts you among its active retailers;
  • it is not sold yet, as defined above;
  • the receiving retailer is another active retailer of the same manufacture: never yourself, never another manufacture's retailer.

A transfer stays among the retailers of the watch's manufacture, and only the manufacture takes a watch back.

curl -X POST https://api.watchcertificate.org/api/v1/users/1234/certificates/ABC123456/transfer \
  -H "api-key: YOUR_API_KEY"

The answer, 201, is the receiving retailer as the list of retailers above shows it:

{
  "id": 1234,
  "company": {
    "name": "Boutique Exemple",
    "city": "Lyon",
    "countryCode": "FR"
  }
}

The watch moves to the receiving retailer's stock and is entrusted to it from then on; its entrustedBy names you. Nothing else changes: its manufacture, its owner and its card stay the same.

Everything is checked before anything is written: after an error, the watch has not moved. An unknown card id or watch id answers 404; the other refusals, in the order they are checked:

HTTP codecodeWhat it means
403RETAILER_TRANSFER_DISABLEDTransfers between retailers are not open on this environment.
403RETAILER_TRANSFER_NOT_YOUR_STOCKThe watch is not in your stock, or its manufacture no longer counts you among its active retailers.
409RETAILER_TRANSFER_SOLDThe watch is sold: a sale is declared, or someone other than its manufacture owns it, a buyer who has not confirmed yet included.
400RETAILER_TRANSFER_TO_YOURSELFThe receiving retailer is you.
403RETAILER_TRANSFER_TARGET_NOT_IN_NETWORKThe receiving retailer is not an active retailer of the watch's manufacture, or no account has this id.
409OWNERSHIP_CHANGEDThe watch changed during the transfer: a sale declared, its manufacture taking it back, or one of the two retailers leaving its list. Nothing was written.

What happens next

The receiving retailer receives an email saying the watch arrived in its stock, and the manufacture one saying it was transferred; the moves of the same ten minutes come in one email. You receive none.

The transfer adds nothing to the passport's history and uses no credit.