Émettre les codes d'achat

Une marque peut exiger un code d'achat pour qu'un acheteur devienne propriétaire d'une pièce : c'est la règle « code d'achat exigé » (les règles de revendication). Le vendeur remet ce code court avec la pièce, sur le ticket ou la carte d'entretien. Posséder l'objet ne suffit plus.

Cette page s'adresse à la marque, ou au revendeur, qui a des centaines ou des milliers de pièces. Dans la console, le code s'émet pièce par pièce. Avec l'API, vous l'émettez pour une liste de pièces en un appel, ou en même temps que vous frappez un lot.

#Ce qu'il vous faut

• Une clef d'API qui porte le droit claim_codes:issue. Ce droit n'est jamais coché par défaut : un code permet à celui qui le détient de revendiquer la pièce. Vous le cochez vous-même, dans la console, Paramètres puis Développeurs.
• Une offre qui comprend l'accès API et l'identité des pièces. Une marque sur l'offre Conformité reçoit 403 avec le code OFFER_EXCLUDES_IDENTITY (les deux offres).
• Pour un revendeur, une clef revendeur : elle agit pour votre marque et pour chaque marque cliente de votre contrat.
• Votre serveur. Les codes ne doivent jamais passer par un navigateur.

#Ce qu'il faut savoir avant tout

Chaque code n'apparaît qu'une fois, dans la réponse. SealTrust n'en garde qu'une empreinte à clef, impossible à relire. Imprimez-le ou rangez-le tout de suite. Un code perdu se réémet : l'ancien cesse alors de marcher.

N'écrivez jamais un code dans un journal, ni dans un fichier que d'autres lisent. Envoyez-le seulement là où il sera imprimé, ou à l'acheteur.

#Les deux points d'entrée

Toutes les adresses existent aussi avec le préfixe /v1, qui est la forme recommandée.

{brand_code} est le code public de la marque, dix caractères comme 7K3QXW9M2A. GET /partner/catalog/brands liste ceux que votre clef peut servir.

#Émettre les codes

Nommez chaque pièce par son numéro de série (douze caractères, imprimé sous son QR code) ou par son numéro de jeton, jamais par un autre numéro. Au plus 500 pièces par appel.

POST /v1/partner/claim-codes/brands/7K3QXW9M2A/issue
Authorization: Bearer st_live_...
Content-Type: application/json

{
  "pieces": [
    { "serial": "Y5T2VGGF2NP9" },
    { "token_id": "1000" }
  ]
}

{
  "brand_code": "7K3QXW9M2A",
  "shown_once": true,
  "items": [
    { "serial": "Y5T2VGGF2NP9", "token_id": "1000", "code": "7KQ4MZ2P", "previous_status": "none" }
  ]
}

previous_status dit ce que la pièce avait avant :

• none : aucun code ;
• live : un code en service, qui ne marche plus. Le papier déjà imprimé est à jeter ;
• used : un code qui a déjà servi. Voir plus bas.

C'est tout ou rien. Si une seule pièce pose problème, aucun code n'est émis.

#Lire l'état, jamais le code

POST /v1/partner/claim-codes/brands/7K3QXW9M2A/status
Content-Type: application/json

{ "pieces": [{ "serial": "Y5T2VGGF2NP9" }] }

{
  "brand_code": "7K3QXW9M2A",
  "items": [
    { "serial": "Y5T2VGGF2NP9", "token_id": "1000", "status": "live", "issued_at": "2026-09-30T09:12:00+00:00", "used_at": null }
  ]
}

status vaut none, live ou used. Le code lui-même n'est jamais renvoyé.

#Un code déjà utilisé

Un code utilisé est la trace qu'un acheteur a revendiqué la pièce. Il n'est jamais remplacé sans que vous le demandiez : l'appel répond 409 avec le code PURCHASE_CODE_ALREADY_USED et la liste des pièces en cause, et rien n'est émis. Pour le remplacer quand même, par exemple après un retour, ajoutez "replace_used": true. La réponse dit alors previous_status: "used", et le journal d'audit de la marque le note.

#Au moment de la frappe

Vous pouvez demander les codes en même temps que vous frappez un lot. La clef doit porter mint:batch et claim_codes:issue.

POST /v1/partner/mint/batch?issue_purchase_codes=true

Le code ne peut pas exister avant la pièce. Le lot garde donc votre demande, et les codes arrivent avec la liste des pièces du lot :

GET /v1/partner/mint/batch/{job_id}/items

Chaque ligne porte alors purchase_code et purchase_code_status. Le code apparaît à la première lecture qui trouve la pièce frappée, puis null aux lectures suivantes, avec l'état live. Imprimez-le à côté du lien de print_url, qui est le QR code de la pièce. Une deuxième lecture ne remplace jamais un code déjà remis.

Une clef sans claim_codes:issue qui lit ce lot voit l'état, jamais le code.

#Depuis la console

La frappe d'un lot dans la console propose la même option : « Émettre un code d'achat pour chaque pièce ». Les codes arrivent dans l'archive des QR codes, dans le fichier purchase_codes.csv, à côté du fichier QR de chaque pièce. Le premier téléchargement les contient, les suivants disent seulement l'état.

#Depuis votre ERP

Les connecteurs n'envoient jamais de code à un outil tiers. Pour imprimer les codes depuis votre ERP ou votre outil d'étiquetage, faites-lui appeler ces points d'entrée avec votre clef.

#Ce qui est refusé

Le journal d'audit de la marque note qui a émis des codes, et pour quels numéros de série. Il ne contient jamais les codes.