Create products, one at a time and in batches

By the end of this page, you will know how to create a single product, create a complete run from a model, import a file of several hundred rows, and read every refusal the console displays. You will also know what becomes permanent at the moment of creation.

#Three objects, three roles

• A product model describes an item in your catalog: its name, its internal reference, its category, its cover photo.
• A production batch groups the units manufactured together, under a batch code and a date.
• A product is the unit. It is the one that carries a printed code or a chip, and it is the one that gets verified.

This page is about creating products. The model and the batch stay optional to get there. They change what the person who scans will see.

#What to prepare

#The brand and its number

Every product belongs to a brand. The brand selector of the console shows the name followed by its number, in the form Exemple SAS (#12). When your account gives access to only one brand, the selector is locked on it. Note this number: file imports ask for it in the brand_id column.

#The category

It is required for every product, and you choose it from the list the console offers. It feeds the "Category" attribute of the token metadata.

#The product model

Optional, and it is what decides the image. With no model linked, the token will carry no cover image. With a model that has no image, likewise. The image used is the cover image of the model; failing that, the first media of image type attached to that model.

Models are created in Catalog > Product models. The list shows an ID column: that is the number the imports expect in product_model_id.

#The production batch

Optional in order to create a product. It is created in Catalog > Production batches. The batch reference, the brand and the product model are required. The quantity, the manufacturing site, the country of origin and the notes are optional. The form has two steps, and the first one does not validate without these three values. The batch list also shows an ID column, to be carried over into product_batch_id.

#What your plan allows

Two checks run, and the moment changes according to the authentication method, that is, what the unit will physically carry, a printed code, a chip, or both. This is the label the console uses in its forms, and your import files name it auth_method.

• The authentication method your plan allows. A brand whose plan does not include NFC receives a 403 refusal carrying the code AUTH_METHOD_NOT_ALLOWED, with the list of allowed methods.
• The product quota. It is counted by month, over the billing period. Exceeding it returns a 403 refusal carrying the code QUOTA_EXCEEDED, with the number already created, the maximum and the period.

For a qr unit, the server checks both at the moment of creation. For a chip unit, it checks both later, at the moment the chip is encoded and the token minted. Preparing 500 NFC units can therefore succeed, and the AUTH_METHOD_NOT_ALLOWED or QUOTA_EXCEEDED refusal appear only at encoding.

#Choosing the authentication method

A product carries only one of the three following values.

#Create a product one at a time

Open Catalog > Create product, "Single product" tab.

The creation button stays inactive as long as the name, the brand and the category are not filled in.

#Preview before you create

The "Preview what will be written on-chain" button shows the exact metadata the token will carry and the cover image. The address of the contract appears in the metadata shown, under the "Contract" attribute. The console sends nothing and mints nothing during this preview.

Four warnings can appear. The server writes them in English and the console displays them as they are.

• "No product model linked", no model linked, the token will carry no cover image;
• "The linked model has no image", the linked model has no image, same consequence;
• "No category", no category, the "Category" attribute would stay empty;
• "No active contract in the registry", no active contract in the registry, minting would fail.

Your browser loads the image, so a dead address shows up as a broken image. This is the last moment when you can still see an image error.

#What happens next

For a qr product, the minting is queued and the console shows "Minting in progress on blockchain". The code can then be downloaded as a PNG image from Catalog > Products, QR column.

For an nfc or nfc+qr product, the console creates a batch whose items are waiting for encoding, with the status ready_to_scan. No token exists yet at this stage. Depending on the profile of your account, the console also shows a link to the encoding screen, or hides that link.

#Create several products at once

The "Batch (multiple products)" tab shows a table. Each row is a unit, with its name, its brand, its category, its model and its authentication method. "Add row" adds one, the trash icon removes one.

The "Create batch" button stays inactive as long as a row does not have its name, its brand and its category.

This tab sends all the rows to the same place. If a single row carries NFC, the whole table goes into the encoding queue, including the qr rows, and the console mints nothing. To mix authentication methods in the same submission, go through the "From CSV" tab, which separates the rows.

What you type is kept in the browser. If your session expires during the preparation, the active tab and the rows in progress are restored after you sign in again.

#Create a run from a model

This path creates the production batch, the units, their names and their references in one go.

Depending on the profile of your account, the button described below does not appear, including for a qr run. In that case create your units from Catalog > Create product, which stays available.

Open Catalog > Product models, open the model, then "Mint batch from this model". The button stays inactive as long as the model has no category.

The console creates the production batch, then the units requested. Each unit takes the name of the model followed by its rank on three digits, for example Sac Exemple #001, and an external reference formed from the batch code followed by the same rank, for example SAC-20260820-1030-001.

On this path, creating a run from a model mints nothing, whatever the authentication method chosen, including qr. The two other paths behave differently: the "Single product" tab and the CSV import mint qr units as soon as they are created.

For a qr run, the console drops you on the page of the batch. There you mint the batch with "Mint the batch (grouped)", you wait for the confirmation, then you prepare the codes to print with "Prepare the QR codes". These are two distinct buttons, minting being asynchronous, and the second one appears only once units have been minted. These two buttons are hidden as well, depending on the profile of your account.

For a run that carries NFC, the console drops you on the encoding screen. There the units wait for their chip, and the minting happens at encoding.

#Import a file

The "From CSV" tab reads the file in your browser, shows you what it understood, then sends the accepted rows.

#The columns

A minimal example file:

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

#How the file is read

• The first line is the header and counts as line 1. The numbers shown in the refusals are the ones your spreadsheet shows.
• The reader strips the spaces at the edges of the values.
• The reader ignores entirely empty lines, with no message.
• When external_ref is empty, the reader fills it with the line number on four digits, for example csv-0002.
• When metadata_uri is empty, the server generates the metadata and posts it on IPFS.
• An empty auth_method takes the value of the selector shown above the preview, and the preview then marks that row as coming from the selector. That selector offers only nfc and qr. To obtain nfc+qr, write the value in the file.
• auth_method ignores case and spaces. The only separators accepted are the comma and the plus sign: QR, NFC+QR, nfc,qr and qr + nfc are understood, nfc/qr and nfc qr make the row refused.

#What makes the whole file refused

• A required column missing from the header. The console names the missing columns and imports nothing.
• The same column name twice, once the spaces are removed, for example brand_id and brand_id. Nothing is imported, because one of the two cells would be kept and the other lost with no message.

The console shows separately the columns the import does not use, under their own label. The file stays usable. That list serves to spot an authmethod written without the underscore, which would otherwise be ignored silently.

#What makes a row refused

The console does not import a refused row, and the corresponding product will not exist. The message carries the line number, the column at fault and the value written in the file.

The console never replaces an unreadable value with a guess. The result would go into the token metadata, whose hash is written on the chain at minting, with no way back.

#The minting mode

Before the submission, the console offers you two choices for the units that go to direct minting.

• One transaction per product. This is the default mode and the one that has always been used. If a minting fails, it fails alone.
• Group up to 50 products per transaction. This mode divides the chain fees. It has never run on a real batch in production. Try it on a small batch before using it on a run.

This choice commits only this import and changes no setting.

#After the submission

The chip rows go into the encoding queue, the qr rows go into the minting queue. The console shows the count of each. The server refuses a submission of more than 10,000 rows intended for direct minting, and asks you to split the file.

#The batch creation endpoint of the API

Here is what this endpoint accepts and refuses today.

• Address: POST https://api.sealtrust.io/v1/partner/mint/batch.
• Scope required on the key: mint:batch. Your plan must include API access.
• Five fields per row, and only five: product_name, brand_id, category_id, metadata_uri are required, external_ref is optional. Any other field makes the request fail with a 400.
• 500 items at most per call. The API refuses an empty batch.
• All the rows must carry the brand number of the key. A single row from another brand makes the whole batch refused with a 403.
• No authentication method field, and no technical identifier field. The server sets both on every row: the method is qr, and the technical identifier is issued by the server. You therefore choose neither of them by this path. The "Authentication" attribute of the metadata takes the value "QR Code + Blockchain", and that method is permanent. To create nfc or nfc+qr units, go through the console.
• Your plan must allow the qr method. Otherwise the whole batch is refused with a 403 carrying the code AUTH_METHOD_NOT_ALLOWED.

The response comes back as a 200 as soon as the batch is queued. It contains four fields. None of them says that a unit is already created, the creation taking place afterwards, outside your call.

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

You then read the state of the batch with GET https://api.sealtrust.io/v1/partner/mint/batch/status/0000a1b2c3d4e5f6, which requires the same mint:batch scope. The status field repeats, as is, the value from the execution queue. You will most often see queued, started, finished and failed. The queue can also return deferred, scheduled, stopped and canceled. unknown means that no batch accessible with your key matches that identifier.

Loop as long as the status is queued or started. Stop on any other value, finished, failed and unknown included, and stop as well on a value you do not know. A loop that starts again on everything it does not recognize never ends. A finished batch tells you nothing about the number of products created.

#Common errors