Article 8 sur 8
Le stock d'un détaillant
Les montres de votre stock, y compris celles qu'une manufacture vous a confiées : les lister, en retrouver une, et transférer une montre pas encore vendue à un autre détaillant de sa manufacture.
Ce que contient votre stock
En tant que détaillant, votre liste contient les montres que vous avez créées, celles dont vous êtes propriétaire, et celles de votre stock : les montres qu'une manufacture a placées chez vous, passeports ou montres encore sans carte. Seule la manufacture place une montre dans votre stock ou la reprend.
Une montre de votre stock vous est confiée tant qu'elle n'est pas vendue : aucune vente n'est déclarée, et personne d'autre que sa manufacture n'en est propriétaire. Une vente déclarée à un acheteur compte, même avant qu'il la confirme.
Lister votre stock
GET / avec origin=entrusted renvoie les montres qui vous sont confiées, avec ou sans carte, et origin=own le reste de votre liste ; sans origin, vous recevez les deux. origin n'est lu que pour un compte de détaillant.
La liste arrive page par page : page à partir de 0, size lignes par page, 20 par défaut. sort la trie : recent (la dernière mise à jour d'abord, par défaut), brand (les marques de A à Z, puis le modèle) ou created (la dernière créée d'abord). totalCertificatesCount compte les lignes de toutes les pages, sauf avec format=medium ou 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"Sur une montre qui vous est confiée, la ligne indique :
watchMakerUser: sa manufacture, par son identifiant, son rôle et le nom de sa société ;entrustedBy: qui vous l'a confiée, sa manufacture ou le détaillant qui vous l'a transférée ;entrustedAt: depuis quand elle est dans votre stock ;canTransferToRetailer: si vous pouvez la transférer maintenant (voir plus bas) ;serialCase: son numéro de série du boîtier, en clair ;externalRef:null. Une référence n'est lue que par le compte qui a créé la montre, ici sa manufacture.
L'appel demande votre clé API, dans l'en-tête api-key, avec le domaine Montres (watches). Sans le domaine Clients, les lignes gardent les données de la montre, mais les personnes qu'elles contiennent, son propriétaire par exemple, valent null.
Retrouver une montre
Ajoutez ces paramètres à origin=entrusted pour rester parmi les montres qui vous sont confiées. Un filtre ne fait que réduire votre liste : il n'atteint jamais le stock d'un autre détaillant, ni les autres montres de la manufacture.
- Une recherche :
searchText, mot par mot, chaque mot n'importe où dans la marque, le modèle, la référence, l'identifiant de carte ou le numéro de série du boîtier (pas celui du mouvement), et dans les noms du propriétaire et du détaillant ; - Des identifiants exacts :
certificateCardIdspour des identifiants de carte (9 lettres ou chiffres chacun),watchIdspour des identifiants de montre. Une ligne qui correspond à l'un d'eux est renvoyée ; - La marque, le modèle, la référence :
brands,modelsetreferences, par le début du texte, sans tenir compte de la casse ; - La dernière mise à jour :
startDateà partir d'une date,endDatejusqu'à une date incluse.
curl "https://api.watchcertificate.org/api/v1/certificates/list?origin=entrusted&searchText=AB12345" \
-H "api-key: YOUR_API_KEY"Votre propre référence ne retrouve que les montres que vous avez créées : externalRefs dans la liste, GET / et GET /. Une montre qui vous est confiée porte la référence de sa manufacture, que vous ne voyez pas : retrouvez-la par son identifiant de carte, son identifiant de montre ou son numéro de série du boîtier.
Lire une montre
GET / lit un passeport, GET / une montre encore sans carte : les mêmes champs que dans la liste, canTransferToRetailer compris. Un identifiant de carte ou de montre qui n'existe pas répond 404.
Choisir le détaillant qui la reçoit
GET / avec certificateCardId, ou watchId pour une montre encore sans carte, liste les détaillants à qui vous pouvez la transférer : les autres détaillants actifs de sa manufacture. Chaque ligne ne donne que son id et le nom, la ville et le pays de sa société, et searchText les filtre par nom ou par ville. Cet id est le userId du transfert.
Cet appel refuse une montre que le transfert refuserait, hors de votre stock ou vendue, avec les mêmes codes (plus bas). Votre clé a besoin du domaine Réseau (network).
curl "https://api.watchcertificate.org/api/v1/users/list?usersListFilter=transfer-retailers&certificateCardId=ABC123456" \
-H "api-key: YOUR_API_KEY"Transférer une montre pas encore vendue
POST / pour un passeport, POST / pour une montre encore sans carte, sans corps : userId est le détaillant qui la reçoit. Une montre dont la carte a été liée depuis répond toujours à son identifiant de montre. Votre clé a besoin du domaine Réseau (network), et une clé en lecture seule ne transfère pas.
Le transfert aboutit quand :
- la montre est dans votre stock, et sa manufacture vous compte toujours parmi ses détaillants actifs ;
- elle n'est pas encore vendue, au sens défini plus haut ;
- le détaillant qui la reçoit est un autre détaillant actif de la même manufacture : jamais vous-même, jamais le détaillant d'une autre manufacture.
Un transfert reste entre les détaillants de la manufacture de la montre, et seule la manufacture reprend une montre.
curl -X POST https://api.watchcertificate.org/api/v1/users/1234/certificates/ABC123456/transfer \
-H "api-key: YOUR_API_KEY"La réponse, 201, est le détaillant qui la reçoit, tel que la liste des détaillants ci-dessus le montre :
{
"id": 1234,
"company": {
"name": "Boutique Exemple",
"city": "Lyon",
"countryCode": "FR"
}
}La montre passe dans le stock du détaillant qui la reçoit et lui est confiée dès ce moment ; son entrustedBy vous nomme. Rien d'autre ne change : sa manufacture, son propriétaire et sa carte restent les mêmes.
Tout est vérifié avant la moindre écriture : après une erreur, la montre n'a pas bougé. Un identifiant de carte ou de montre inconnu répond 404 ; les autres refus, dans l'ordre où ils sont vérifiés :
| Code HTTP | code | Ce que cela veut dire |
|---|---|---|
| 403 | RETAILER_ | Les transferts entre détaillants ne sont pas ouverts sur cet environnement. |
| 403 | RETAILER_ | La montre n'est pas dans votre stock, ou sa manufacture ne vous compte plus parmi ses détaillants actifs. |
| 409 | RETAILER_ | La montre est vendue : une vente est déclarée, ou quelqu'un d'autre que sa manufacture en est propriétaire, y compris un acheteur qui n'a pas encore confirmé. |
| 400 | RETAILER_ | Le détaillant qui la reçoit, c'est vous. |
| 403 | RETAILER_ | Le détaillant qui la reçoit n'est pas un détaillant actif de la manufacture de la montre, ou aucun compte n'a cet identifiant. |
| 409 | OWNERSHIP_ | La montre a changé pendant le transfert : une vente déclarée, sa manufacture qui la reprend, ou l'un des deux détaillants qui quitte sa liste. Rien n'a été écrit. |
Et ensuite
Un email dit au détaillant qui la reçoit que la montre est arrivée dans son stock, et un autre dit à la manufacture qu'elle a été transférée ; les mouvements des mêmes dix minutes arrivent dans un seul email. Vous n'en recevez aucun.
Le transfert n'ajoute rien à l'historique du passeport et ne consomme aucun crédit.