# Émettre les codes d'achat

Émettre en masse les codes d'achat de la règle « code d'achat exigé », pour des pièces déjà créées ou au moment de la frappe d'un lot. Chaque code n'apparaît qu'une fois. Droit claim_codes:issue.

Source : https://docs.sealtrust.io/api-codes-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](/console/regles-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](/offres-conformite-et-identite/)).
- 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.

| Méthode et chemin | Ce qu'il fait | Droit |
| --- | --- | --- |
| `POST /partner/claim-codes/brands/{brand_code}/issue` | émet un code pour chaque pièce, et le montre une fois | `claim_codes:issue` |
| `POST /partner/claim-codes/brands/{brand_code}/status` | dit si chaque pièce a un code en service, déjà utilisé, ou aucun | `claim_codes:issue` |

`{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.

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

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

```json
{
  "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

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

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

```json
{
  "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`.

```http
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 :

```http
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é

| Réponse | Pourquoi |
| --- | --- |
| `403` | droit `claim_codes:issue` absent, marque que la clef ne sert pas, ou offre Conformité (`OFFER_EXCLUDES_IDENTITY`) |
| `404` `PIECE_NOT_FOUND` | une pièce inconnue, ou d'une autre marque : la même réponse dans les deux cas |
| `409` `PURCHASE_CODE_ALREADY_USED` | le code d'une pièce a déjà servi, et `replace_used` n'est pas à `true` |
| `422` | une référence mal formée, une pièce nommée deux fois, plus de 500 pièces, un code de marque mal formé |
| `429` | trop d'appels, ou plus de 20 000 codes émis pour la marque dans l'heure (`PURCHASE_CODE_BUDGET_EXCEEDED`, avec `Retry-After`) |

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.