Créer des produits, à l'unité et en lot

En quittant cette page, vous saurez créer un produit seul, créer une série complète à partir d'un modèle, importer un fichier de plusieurs centaines de lignes, et lire chaque refus affiché par la console. Vous saurez aussi ce qui devient définitif au moment de la création.

#Trois objets, trois rôles

• Un modèle produit décrit un article de votre catalogue : son nom, sa référence interne, sa catégorie, sa photo de couverture.
• Un lot de production regroupe les exemplaires fabriqués ensemble, sous un code de lot et une date.
• Un produit est l'exemplaire. C'est lui qui porte un code imprimé ou une puce, et c'est lui qui se vérifie.

Cette page parle de la création des produits. Le modèle et le lot restent facultatifs pour y arriver. Ils changent ce que verra la personne qui scanne.

#Ce qu'il faut préparer

#La marque et son numéro

Chaque produit appartient à une marque. Le sélecteur de marque de la console affiche le nom suivi de son numéro, sous la forme Exemple SAS (#12). Quand votre compte ne donne accès qu'à une seule marque, le sélecteur est verrouillé sur elle. Notez ce numéro : les imports par fichier le réclament dans la colonne brand_id.

#La catégorie

Elle est obligatoire pour chaque produit, et vous la choisissez dans la liste que la console propose. Elle alimente l'attribut « Category » des métadonnées du jeton.

#Le modèle produit

Facultatif, et c'est lui qui décide de l'image. Sans modèle lié, le jeton ne portera aucune image de couverture. Avec un modèle dépourvu d'image, non plus. L'image retenue est l'image de couverture du modèle ; à défaut, le premier média de type image rattaché à ce modèle.

Les modèles se créent dans Catalogue > Modèles produit. La liste affiche une colonne ID : c'est ce numéro que les imports attendent dans product_model_id.

#Le lot de production

Facultatif pour créer un produit. Il se crée dans Catalogue > Lots de production. La référence de lot, la marque et le modèle produit sont obligatoires. La quantité, le site de fabrication, le pays d'origine et les notes sont facultatifs. Le formulaire a deux étapes, et la première ne se valide pas sans ces trois valeurs. La liste des lots affiche également une colonne ID, à reporter dans product_batch_id.

#Ce que votre offre autorise

Deux contrôles s'exécutent, et le moment change selon la méthode d'authentification, c'est-à-dire ce que l'exemplaire portera physiquement, un code imprimé, une puce, ou les deux. C'est le libellé employé par la console dans ses formulaires, et vos fichiers d'import le nomment auth_method.

• La méthode d'authentification autorisée par votre offre. Une marque dont l'offre n'inclut pas le NFC reçoit un refus 403 portant le code AUTH_METHOD_NOT_ALLOWED, avec la liste des méthodes autorisées.
• Le quota de produits. Il se compte par mois, sur la période de facturation. Un dépassement renvoie un refus 403 portant le code QUOTA_EXCEEDED, avec le nombre déjà créé, le maximum et la période.

Pour un exemplaire en qr, le serveur vérifie les deux au moment de la création. Pour un exemplaire à puce, il vérifie les deux plus tard, au moment où la puce est encodée et le jeton frappé. Préparer 500 exemplaires NFC peut donc réussir, et le refus AUTH_METHOD_NOT_ALLOWED ou QUOTA_EXCEEDED n'apparaître qu'à l'encodage.

#Choisir la méthode d'authentification

Un produit porte une seule des trois valeurs suivantes.

#Créer un produit à l'unité

Ouvrez Catalogue > Créer un produit, onglet « Produit unique ».

Le bouton de création reste inactif tant que le nom, la marque et la catégorie ne sont pas renseignés.

#Prévisualisez avant de créer

Le bouton « Prévisualiser ce qui sera écrit en chaîne » affiche les métadonnées exactes que portera le jeton et l'image de couverture. L'adresse du contrat figure dans les métadonnées affichées, sous l'attribut « Contract ». La console n'envoie rien et ne frappe rien pendant cet aperçu.

Quatre avertissements peuvent apparaître. Le serveur les écrit en anglais et la console les affiche tels quels.

• « No product model linked », aucun modèle lié, le jeton ne portera aucune image de couverture ;
• « The linked model has no image », le modèle lié n'a pas d'image, même conséquence ;
• « No category », aucune catégorie, l'attribut « Category » resterait vide ;
• « No active contract in the registry », aucun contrat actif dans le registre, la frappe échouerait.

Votre navigateur charge l'image, donc une adresse morte apparaît comme une image cassée. C'est le dernier moment où vous voyez encore une erreur d'image.

#Ce qui se passe ensuite

Pour un produit en qr, la frappe est mise en file et la console affiche « Mint en cours sur la blockchain ». Le code est ensuite téléchargeable en image PNG depuis Catalogue > Produits, colonne QR.

Pour un produit en nfc ou nfc+qr, la console crée un lot dont les articles sont en attente d'encodage, avec le statut ready_to_scan. Aucun jeton n'existe encore à ce stade. Selon le profil de votre compte, la console affiche en plus un lien vers l'écran d'encodage, ou masque ce lien.

#Créer plusieurs produits d'un coup

L'onglet « Lot (plusieurs produits) » affiche un tableau. Chaque ligne est un exemplaire, avec son nom, sa marque, sa catégorie, son modèle et sa méthode d'authentification. « Ajouter une ligne » en ajoute une, l'icône de corbeille en retire une.

Le bouton « Créer le lot » reste inactif tant qu'une ligne n'a pas son nom, sa marque et sa catégorie.

Cet onglet envoie toutes les lignes au même endroit. Si une seule ligne porte du NFC, la totalité du tableau part en file d'encodage, y compris les lignes en qr, et la console ne frappe rien. Pour mélanger des méthodes d'authentification dans un même envoi, passez par l'onglet « Depuis CSV », qui sépare les lignes.

Votre saisie est conservée dans le navigateur. Si votre session expire pendant la préparation, l'onglet actif et les lignes en cours sont restaurés après la reconnexion.

#Créer une série depuis un modèle

Ce chemin crée le lot de production, les exemplaires, leurs noms et leurs références en une fois.

Selon le profil de votre compte, le bouton décrit ci-dessous n'apparaît pas, y compris pour une série en qr. Créez alors vos exemplaires depuis Catalogue > Créer un produit, qui reste disponible.

Ouvrez Catalogue > Modèles produit, ouvrez le modèle, puis « Minter un lot depuis ce modèle ». Le bouton reste inactif tant que le modèle n'a pas de catégorie.

La console crée le lot de production, puis les exemplaires demandés. Chaque exemplaire prend le nom du modèle suivi de son rang sur trois chiffres, par exemple Sac Exemple #001, et une référence externe formée du code de lot suivi du même rang, par exemple SAC-20260820-1030-001.

Sur ce chemin, la création d'une série depuis un modèle ne frappe rien, quelle que soit la méthode d'authentification choisie, y compris en qr. Les deux autres chemins se comportent autrement : l'onglet « Produit unique » et l'import CSV frappent les exemplaires en qr dès la création.

Pour une série en qr, la console vous dépose sur la page du lot. Vous y frappez le lot avec « Frapper le lot (groupé) », vous attendez la confirmation, puis vous préparez les codes à imprimer avec « Préparer les QR à imprimer ». Ce sont deux boutons distincts, la frappe étant asynchrone, et le second n'apparaît qu'une fois des exemplaires frappés. Ces deux boutons sont eux aussi masqués selon le profil de votre compte.

Pour une série qui porte du NFC, la console vous dépose sur l'écran d'encodage. Les exemplaires y attendent leur puce, et la frappe a lieu à l'encodage.

#Importer un fichier

L'onglet « Depuis CSV » lit le fichier dans votre navigateur, vous montre ce qu'il a compris, puis envoie les lignes acceptées.

#Les colonnes

Un fichier d'exemple minimal :

product_name,brand_id,category_id,product_model_id,auth_method
Sac Exemple 001,12,3,45,qr
Sac Exemple 002,12,3,45,qr
Sac Exemple 003,12,3,45,nfc+qr

#Comment le fichier est lu

• La première ligne est l'en-tête et compte comme la ligne 1. Les numéros affichés dans les refus sont ceux que votre tableur affiche.
• Le lecteur retire les espaces au bord des valeurs.
• Le lecteur ignore les lignes entièrement vides, sans message.
• Quand external_ref est vide, le lecteur le remplit avec le numéro de ligne sur quatre chiffres, par exemple csv-0002.
• Quand metadata_uri est vide, le serveur génère les métadonnées et les dépose sur IPFS.
• Un auth_method vide prend la valeur du sélecteur affiché au-dessus de l'aperçu, et l'aperçu marque alors cette ligne comme venant du sélecteur. Ce sélecteur ne propose que nfc et qr. Pour obtenir nfc+qr, écrivez la valeur dans le fichier.
• auth_method ignore la casse et les espaces. Les seuls séparateurs acceptés sont la virgule et le plus : QR, NFC+QR, nfc,qr et qr + nfc sont compris, nfc/qr et nfc qr font refuser la ligne.

#Ce qui fait refuser le fichier entier

• Une colonne obligatoire absente de l'en-tête. La console nomme les colonnes manquantes et n'importe rien.
• Le même nom de colonne deux fois, une fois les espaces retirés, par exemple brand_id et brand_id. Rien n'est importé, parce qu'une des deux cellules serait gardée et l'autre perdue sans message.

La console affiche à part les colonnes que l'import n'utilise pas, sous leur propre libellé. Le fichier reste utilisable. Cette liste sert à repérer un authmethod écrit sans le tiret bas, qui serait sinon ignoré en silence.

#Ce qui fait refuser une ligne

La console n'importe pas une ligne refusée, et le produit correspondant n'existera pas. Le message porte le numéro de ligne, la colonne fautive et la valeur écrite dans le fichier.

La console ne remplace jamais une valeur illisible par une supposition. Le résultat partirait dans les métadonnées du jeton, dont l'empreinte est inscrite sur la chaîne à la frappe, sans retour possible.

#Le mode de frappe

Avant l'envoi, la console vous propose deux choix pour les exemplaires qui partent en frappe directe.

• Une transaction par produit. C'est le mode par défaut et celui qui a toujours été utilisé. Si une frappe échoue, elle échoue seule.
• Regrouper jusqu'à 50 produits par transaction. Ce mode divise les frais de chaîne. Il n'a jamais tourné sur un vrai lot en production. Essayez-le sur un petit lot avant de l'employer sur une série.

Ce choix n'engage que cet import et ne modifie aucun réglage.

#Après l'envoi

Les lignes à puce partent en file d'encodage, les lignes en qr partent en file de frappe. La console affiche le compte de chacune. Le serveur refuse un envoi de plus de 10 000 lignes destinées à la frappe directe, et vous demande de découper le fichier.

#Le point d'entrée de création en lot de l'API

Voici ce que ce point d'entrée accepte et refuse aujourd'hui.

• Adresse : POST https://api.sealtrust.io/v1/partner/mint/batch.
• Droit requis sur la clef : mint:batch. Votre offre doit inclure l'accès API.
• Cinq champs par ligne, et cinq seulement : product_name, brand_id, category_id, metadata_uri sont obligatoires, external_ref est facultatif. Tout autre champ fait échouer la requête en 400.
• 500 articles au maximum par appel. L'API refuse un lot vide.
• Toutes les lignes doivent porter le numéro de marque de la clef. Une seule ligne d'une autre marque fait refuser le lot entier en 403.
• Aucun champ de méthode d'authentification, et aucun champ d'identifiant technique. Le serveur pose les deux sur chaque ligne : la méthode vaut qr, et l'identifiant technique est émis par le serveur. Vous ne choisissez donc ni l'un ni l'autre par cette voie. L'attribut « Authentication » des métadonnées prend la valeur « QR Code + Blockchain », et cette méthode est définitive. Pour créer des exemplaires en nfc ou en nfc+qr, passez par la console.
• Votre offre doit autoriser la méthode qr. Sinon le lot entier est refusé en 403 avec le code AUTH_METHOD_NOT_ALLOWED.

La réponse arrive en 200 dès que le lot est mis en file. Elle contient quatre champs. Aucun ne dit qu'un exemplaire est déjà créé, la création ayant lieu ensuite, hors de votre appel.

{
  "job_id": "0000a1b2c3d4e5f6",
  "status": "queued",
  "items_count": 2,
  "brand_id": 12
}

Vous lisez ensuite l'état du lot avec GET https://api.sealtrust.io/v1/partner/mint/batch/status/0000a1b2c3d4e5f6, qui demande le même droit mint:batch. Le champ status reprend telle quelle la valeur de la file d'exécution. Vous verrez le plus souvent queued, started, finished et failed. La file peut aussi renvoyer deferred, scheduled, stopped et canceled. unknown signifie qu'aucun lot accessible avec votre clef ne correspond à cet identifiant.

Bouclez tant que le statut vaut queued ou started. Arrêtez-vous sur toute autre valeur, finished, failed et unknown comprises, et arrêtez-vous aussi sur une valeur que vous ne connaissez pas. Une boucle qui repart sur tout ce qu'elle ne reconnaît pas ne se termine jamais. Un lot finished ne vous dit rien du nombre de produits créés.

#Erreurs fréquentes