.CopyPageActions-module__-WfCiq__principal,.CopyPageActions-module__-WfCiq__bascule{display:none}Voir en Markdown

Méthode GET/01/{gtin}

Résoudre un lien GS1 Digital Link qui ne porte qu'un GTIN, vers la page publique du passeport de référence du modèle. Réponse 302, aucune clef d'API.

Sur cette page

Autorisation
Plafond d'appels
Paramètres de chemin et de requête
Écrire le GTIN
La clef de contrôle du GTIN
Choisir la langue de la page d'arrivée
En-têtes de requête
Corps de la requête
Requête d'exemple
Réponse d'exemple
Une seule redirection
Sur le domaine personnalisé d'une marque
Le scan est compté, sans rien garder du lecteur
Quand la marque affiche ses passeports chez un partenaire
Erreurs
Voir aussi

Vous envoyez un GTIN et vous recevez une redirection vers la page publique du passeport de référence du modèle correspondant. Le GTIN, Global Trade Item Number, est le numéro d'article commercial imprimé sous le code-barres. En quittant cette page, vous saurez lire la redirection, choisir la langue de la page d'arrivée, et reconnaître les réponses d'erreur.

Adresse complète :

HTTP

GET https://api.sealtrust.io/01/{gtin}

Le même point d'entrée répond aussi sous le préfixe /v1, à https://api.sealtrust.io/v1/01/{gtin}. Les deux adresses appellent le même code. Un lien GS1 Digital Link porte le chemin /01/{gtin} sans préfixe, donc c'est cette forme que rencontre un lecteur de code.

Ce point d'entrée désigne un modèle

Le chemin porte un GTIN et aucun numéro de série. Il nomme donc une référence commerciale. Le passeport visé est celui qui est rattaché à un modèle et à aucune unité. Un passeport rattaché à un exemplaire n'est jamais servi ici, même quand son modèle porte ce GTIN : montrer des données propres à un exemplaire pour un autre exemplaire du même modèle serait faux.

Le règlement ESPR autorise un passeport au niveau du modèle, du lot ou de l'article. Un passeport de modèle couvre tous les exemplaires qui partagent le même code produit. Un passeport de lot se lit au lien qui porte aussi le numéro de lot, /01/{gtin}/10/{lot}, et ne répond jamais ici.

Pour désigner un exemplaire physique, utilisez le lien qui porte aussi le numéro de série, /01/{gtin}/21/{serial}.

#Autorisation

Aucune, point d'entrée public. Ce point d'entrée répond sans clef d'API, sans compte et sans cookie de session.

Une clef d'API partenaire présentée ici n'est pas lue. Elle ne change ni la réponse, ni les quotas de votre offre.

#Plafond d'appels

Ce point d'entrée a un plafond dédié et appliqué de 60 appels par 60 secondes, compté par adresse IP appelante. Le compteur porte sur tous les chemins /01/ confondus, et il est unique pour toutes les valeurs de GTIN : parcourir mille GTIN différents consomme mille appels du même budget.

Chaque réponse porte trois en-têtes qui décrivent ce compteur.

En-tête	Contenu
`X-RateLimit-Limit`	le plafond du compteur sur la fenêtre
`X-RateLimit-Remaining`	ce qu'il vous reste dans la fenêtre en cours
`X-RateLimit-Reset`	l'heure de remise à zéro, en secondes depuis le 1er janvier 1970

X-RateLimit-Remaining s'arrête à zéro. Ralentissez avant d'y arriver, et traitez le code 429 dans votre client dès votre première intégration.

Cet appel n'entame pas le quota quotidien d'une clef d'API, et ne compte aucune pièce.

#Paramètres de chemin et de requête

Nom	Type	Obligatoire	Description
`gtin`	`string`	oui	Le GTIN du modèle. Les formats GTIN-8, GTIN-12, GTIN-13 et GTIN-14 sont acceptés, avec ou sans séparateurs. Son dernier chiffre doit être la clef de contrôle des précédents : voir ci-dessous.

Ce point d'entrée ne lit aucun paramètre de requête. Tout ce que vous ajoutez après le ? est ignoré, y compris linkType, et n'est pas recopié dans la redirection. Le paramètre linkType n'a d'effet que sur les liens qui désignent un exemplaire, /p/{serial} et /01/{gtin}/21/{serial}. Ici la destination est déjà le passeport.

#Écrire le GTIN

Le serveur ramène votre GTIN à sa forme canonique de quatorze chiffres avant la recherche. Il retire tous les caractères qui ne sont pas des chiffres, puis il complète le résultat par des zéros à gauche jusqu'à quatorze chiffres.

Ces trois écritures désignent donc le même modèle : 3701234567891, 03701234567891 et 3-701234-567891. C'est toujours la forme à quatorze chiffres qui apparaît dans la redirection.

Une valeur qui ne contient aucun chiffre renvoie 400. Une valeur qui en contient plus de quatorze renvoie 400 également : 0003701234567891 compte seize chiffres et renvoie 400.

La recherche retrouve le modèle même si la marque a enregistré son GTIN sous une forme plus courte, en GTIN-8, GTIN-12 ou GTIN-13.

#La clef de contrôle du GTIN

Le dernier chiffre d'un GTIN est sa clef de contrôle : la règle GS1 modulo 10 le calcule à partir des chiffres qui le précèdent. Le serveur la recalcule et la compare avant de chercher le modèle.

Envoyez donc 8, 12, 13 ou 14 chiffres, les quatre longueurs qu'un GTIN peut avoir, et vérifiez que le dernier est bien la clef des précédents. Un GTIN qui sort de cette règle reçoit un code 400, avec le corps {"detail": "Invalid GTIN: the check digit does not match."}.

Recopiez le GTIN depuis le code-barres de la référence. Une faute de frappe sur un seul chiffre se voit alors dès l'appel.

#Choisir la langue de la page d'arrivée

La redirection pointe vers une page dont l'adresse commence par la langue. Le serveur choisit cette langue à partir de l'en-tête Accept-Language que vous envoyez : il retient la première valeur de l'en-tête dont la langue principale est fr ou en, et il ignore une langue que vous refusez par q=0.

Sans en-tête, ou sans valeur correspondante, il regarde le domaine appelé : sur le nom de domaine vérifié d'une marque, il choisit la langue que cette marque a retenue dans sa console ; sur le nôtre, ou si elle n'a rien retenu, il choisit en. Une langue que vous demandez passe toujours avant celle de la marque.

Le serveur sert deux langues, fr et en. La réponse porte Vary: Accept-Language, puisque sa destination dépend de cet en-tête.

#En-têtes de requête

En-tête	Obligatoire	Description
`Accept-Language`	non	Choisit la langue de la page d'arrivée. Sans cet en-tête, la langue de la marque sur son propre domaine, sinon `en`.

#Corps de la requête

Aucun. Cette requête n'a pas de corps.

#Requête d'exemple

Résolution du GTIN 03701234567891. La redirection n'est pas suivie, pour pouvoir lire l'en-tête Location.

curl -i "https://api.sealtrust.io/01/03701234567891"

const gtin = "03701234567891";

const response = await fetch(
  `https://api.sealtrust.io/01/${encodeURIComponent(gtin)}`,
  { method: "GET", redirect: "manual" },
);

console.log(response.status);
console.log(response.headers.get("location"));

import requests

gtin = "03701234567891"

response = requests.get(
    f"https://api.sealtrust.io/01/{gtin}",
    allow_redirects=False,
    timeout=30,
)

print(response.status_code)
print(response.headers["Location"])

Pour obtenir la page en anglais, ajoutez l'en-tête de langue.

curl -i \
  -H "Accept-Language: en" \
  "https://api.sealtrust.io/01/03701234567891"

const gtin = "03701234567891";

const response = await fetch(
  `https://api.sealtrust.io/01/${encodeURIComponent(gtin)}`,
  {
    method: "GET",
    redirect: "manual",
    headers: { "Accept-Language": "en" },
  },
);

console.log(response.status);
console.log(response.headers.get("location"));

import requests

gtin = "03701234567891"

response = requests.get(
    f"https://api.sealtrust.io/01/{gtin}",
    headers={"Accept-Language": "en"},
    allow_redirects=False,
    timeout=30,
)

print(response.status_code)
print(response.headers["Location"])

#Réponse d'exemple

Code HTTP 302Found

Code HTTP 302. La réponse n'a pas de corps. Toute l'information est dans l'en-tête Location.

HTTP

HTTP/1.1 302 Found
Location: https://sealtrust.io/en/passport/01/03701234567891
Vary: Accept-Language
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1786000020
Content-Length: 0

Avec l'en-tête Accept-Language: en, la même requête renvoie ceci.

HTTP

HTTP/1.1 302 Found
Location: https://sealtrust.io/en/passport/01/03701234567891
Vary: Accept-Language
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1786000020
Content-Length: 0

En-tête	Contenu
`Location`	L'adresse complète de la page publique du passeport de référence, au chemin `/{locale}/passport/01/{gtin}`. Le GTIN y figure sous sa forme à quatorze chiffres.

Lisez l'en-tête Location et suivez-le. N'écrivez pas l'hôte de destination en dur dans votre code : il change selon le domaine sur lequel l'appel arrive, et c'est la réponse qui fait autorité.

#Une seule redirection

Ce point d'entrée n'émet qu'un seul saut. La langue est déjà résolue dans l'adresse rendue, donc la page d'arrivée ne vous redirige pas une seconde fois.

Le registre européen des passeports numériques va chercher les adresses d'identifiant pour les valider, et il n'accepte pas plus de trois redirections. Le service d'assistance de la Commission a donné ce chiffre le 31 août 2026. Il précise aussi qu'aucune taille de réponse maximale n'est publiée, mais qu'une adresse de passeport doit éviter les réponses volumineuses et résoudre efficacement, et que les adresses pointant vers un point local, localhost ou 127.0.0.1, sont rejetées.

Un seul saut laisse donc deux de marge pour votre propre infrastructure, par exemple une redirection de http vers https et une de www vers le domaine nu.

#Sur le domaine personnalisé d'une marque

Quand une marque sert ce point d'entrée sur son propre nom de domaine, vérifié chez nous, la redirection reste sur ce domaine. Un consommateur qui scanne un produit ne quitte donc jamais le domaine de la marque.

Sur un tel domaine, seules les références commerciales de cette marque répondent. Un GTIN qui appartient à une autre marque renvoie 404, avec le même message que toutes les autres absences.

Sur le domaine partagé d'un revendeur, ce sont les références du revendeur et de ses marques clientes qui répondent, et elles seules. La marque est celle qui publie le passeport de référence de ce GTIN, lue dans notre base, jamais dans le nom de domaine.

#Le scan est compté, sans rien garder du lecteur

Chaque appel GET fait par un navigateur, qui mène à un passeport, ajoute un au nombre de scans de ce passeport pour le mois en cours. Ne sont pas comptés : les robots et les aperçus de liens, les requêtes HEAD, et un lien qui ne mène à rien. Aucune adresse, aucun pays et aucune heure ne sont gardés : seul le nombre de scans par passeport et par mois existe. La marque le lit par modèle et par lot. Le mois en cours se complète toutes les dix minutes.

#Quand la marque affiche ses passeports chez un partenaire

Une marque, ou son revendeur, peut afficher ses passeports dans la page d'un partenaire, voir Afficher le passeport dans votre page. Quand elle l'a activé dans la console, cette adresse répond 302 vers la page du partenaire au lieu de la nôtre, avec les paramètres level (qui vaut model), gtin et lang. Une demande qui porte ?linkType=dpp reçoit toujours notre passeport.

#Erreurs

Un navigateur, qui demande text/html dans son en-tête Accept, reçoit à la place du JSON une courte page dans sa langue : même statut, et même texte pour toutes les erreurs, pour ne rien révéler de plus que le JSON. Un programme qui demande du JSON, ou qui n'envoie pas d'en-tête Accept, reçoit les corps décrits ci-dessous.

Le corps d'une réponse d'erreur contient un seul champ, detail.

JSON

{
  "detail": "Unknown GS1 Digital Link"
}

Code	Condition	Que faire
400	La valeur envoyée ne contient aucun chiffre, ou en contient plus de quatorze. Message `Invalid GTIN`.	Corrigez la valeur. Un GTIN valide compte au plus quatorze chiffres, séparateurs exclus.
400	La valeur envoyée ne compte pas 8, 12, 13 ou 14 chiffres, ou son dernier chiffre n'est pas la clef de contrôle des précédents. Message `Invalid GTIN: the check digit does not match.`	Recopiez le GTIN depuis le code-barres de la référence, puis rappelez.
404	Aucune page publique de passeport de référence ne répond pour ce GTIN sur ce domaine. Message `Unknown GS1 Digital Link`.	Vérifiez le GTIN, puis vérifiez dans la console que le passeport de référence de ce modèle est publié et que sa visibilité est publique. Un passeport rattaché à un exemplaire ne répond jamais ici.
429	Plus de 60 appels en 60 secondes depuis la même adresse IP, tous chemins `/01/` confondus. Message `Rate limit exceeded: 60 requests per 60s`. La réponse porte un en-tête `Retry-After` en secondes.	Attendez le nombre de secondes indiqué par `Retry-After`, puis réessayez. Suivez votre consommation avec les en-têtes `X-RateLimit-*` et étalez vos appels dans le temps.
500	Erreur inattendue du serveur. Corps figé `{"detail": "Internal Server Error"}`.	Réessayez. L'en-tête `X-Request-Id` identifie l'appel, transmettez-le nous s'il se répète.

Ce point d'entrée ne renvoie pas de 422. Une valeur inexploitable ressort en 400, et un GTIN sans page publique ressort en 404.

#Voir aussi

GET /01/{gtin}/21/{serial}, résoudre un lien GS1 qui porte un GTIN et un numéro de série.
GET /passport/01/{gtin}, lire le passeport publié d'un modèle, à partir de son GTIN.
GET /p/{serial}, traduire le numéro de série imprimé en adresse de page consommateur.
Identification physique, QR et NFC, choisir le porteur physique et la forme exacte du lien GS1 Digital Link.

Cette page vous a-t-elle été utile ?

Votre réponse ouvre un courriel pré-rempli dans votre messagerie, à destination de contact@sealtrust.io. Vous le relisez avant de l'envoyer.

Proposer une correction Signaler un problème

GETMéthode GET/01/{gtin}

#Autorisation

#Plafond d'appels

#Paramètres de chemin et de requête

#Écrire le GTIN

#La clef de contrôle du GTIN

#Choisir la langue de la page d'arrivée

#En-têtes de requête

#Corps de la requête

#Requête d'exemple

#Réponse d'exemple

#Une seule redirection

#Sur le domaine personnalisé d'une marque

#Le scan est compté, sans rien garder du lecteur

#Quand la marque affiche ses passeports chez un partenaire

#Erreurs

#Voir aussi

Méthode GET/01/{gtin}