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

Méthode GET/passport/01/{gtin}

Lire le passeport numérique publié pour un modèle de produit, à partir de son GTIN. Aucune clef d'API pour le niveau public.

Sur cette page

Autorisation
Plafond d'appels
Paramètres de chemin et de requête
Écrire le GTIN
Choisir le niveau d'accès
En-têtes de requête
Corps de la requête
Requête d'exemple
Réponse d'exemple
En-têtes de la réponse
Lire le champ data
Erreurs
Ordre des contrôles
Voir aussi

Vous lisez le passeport numérique publié pour un modèle de produit, à partir de son GTIN. Le GTIN, Global Trade Item Number, est le numéro d'article commercial imprimé sous le code-barres. En quittant cette page, vous saurez récupérer le contenu du passeport, son numéro de version, son empreinte et sa copie IPFS, et vous saurez demander un niveau d'accès plus large que le niveau public.

Adresse complète :

HTTP

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

Le même point d'entrée répond aussi sans le préfixe /v1, à https://api.sealtrust.io/passport/01/{gtin}. Les deux adresses appellent le même code. Utilisez la forme /v1 pour une nouvelle intégration.

#Autorisation

Aucune pour le niveau public, qui est le niveau par défaut. Ce point d'entrée répond sans clef d'API.

Le niveau public répond sans compte. Les niveaux end_user, repairer, recycler, upstream et authority exigent un compte. Vous demandez un niveau par le paramètre access_tier décrit plus bas. Vous vous authentifiez par un jeton de session présenté en Authorization: Bearer <jeton>, ou par le cookie de session posé lors de la connexion.

Une clef d'API partenaire ne donne accès à aucun de ces niveaux. Elle n'est pas un jeton de session, elle est ignorée ici, et la réponse est celle d'un appelant anonyme.

Niveau demandé	Qui l'obtient
`public`	tout le monde, sans compte Pour un passeport batterie, s'y ajoutent les champs que le point 1 de l'annexe XIII rend publics : substances dangereuses, matières premières critiques, empreinte carbone et sa classe, rapport de diligence raisonnable, contenu recyclé après consommation par métal et part de contenu renouvelable. À l'inverse, les références de pièces, l'état de la batterie et la durée de vie en cycles en sont retirés : les points 2 et 4 les réservent aux personnes ayant un intérêt légitime. Pour un passeport textile, s'y ajoutent le nom et le pourcentage de chaque matière, la composition en fibres que le règlement (UE) n° 1007/2011 impose sur l'étiquette. Pour un passeport chaussure, la matière de la tige, de la doublure, de la première de propreté et de la semelle, que la directive 94/11/CE fait figurer sur la chaussure.
`end_user`	tout compte connecté
`repairer`	les administrateurs de la marque du produit, les partenaires portant une accréditation de réparateur active délivrée par cette marque, et les autorités de surveillance du marché
`recycler`	les administrateurs de la marque du produit, les partenaires portant une accréditation de recycleur active délivrée par cette marque, et les autorités de surveillance du marché
`upstream`	les administrateurs de la marque du produit et les autorités de surveillance du marché
`authority`	les comptes portant le rôle d'autorité de surveillance du marché

#Plafond d'appels

600 appels par fenêtre de 60 secondes, comptés par adresse IP appelante.

Ce compteur est commun à toutes les lectures (GET) dont l'adresse commence par /passport. Les appels que vous faites sur le passeport d'un exemplaire et sur les résumés de preuve entament donc le 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 appliqué sur la fenêtre
`X-RateLimit-Remaining`	ce qu'il vous reste dans la fenêtre en cours
`X-RateLimit-Reset`	l'horodatage de fin de la fenêtre, en secondes

Ce compteur est indépendant du quota quotidien d'une clef d'API. Cet appel n'entame pas ce quota quotidien, 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, aux formats GTIN-8, GTIN-12, GTIN-13 ou GTIN-14, séparateurs compris. Son dernier chiffre doit être la clef de contrôle des chiffres qui le précèdent. La valeur est ramenée à quatorze chiffres avant la recherche.
`access_tier`	`string`	non	Le niveau d'accès aux données. Six niveaux livrés par défaut, alignés sur la méthodologie DPP du JRC (JRC145830, annexe 8) ; l'ESPR n'en fixe lui-même aucun. Valeur par défaut `public`. Les six valeurs acceptées sont `public`, `end_user`, `repairer`, `recycler`, `upstream` et `authority`. Toute autre valeur renvoie 422.

#Écrire le GTIN

Le GTIN que vous envoyez est ramené à sa forme canonique de 14 chiffres avant la recherche. Tous les caractères qui ne sont pas des chiffres sont retirés, puis le résultat est complété par des zéros à gauche jusqu'à 14 chiffres.

Ces trois écritures désignent donc le même modèle : 3701234567891, 03701234567891 et 3-701234-567890. Elles donnent toutes la même forme canonique, 03701234567891. Une valeur qui ne contient aucun chiffre, ou qui en contient plus de quatorze, renvoie 404.

Le dernier chiffre d'un GTIN est une clef de contrôle, calculée à partir de ceux qui le précèdent. Nous la vérifions, et un GTIN dont le dernier chiffre ne correspond pas renvoie 400. Recopiez le code imprimé sur le produit, chiffre pour chiffre.

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.

#Choisir le niveau d'accès

access_tier sélectionne les sections du passeport que vous recevez. Ces niveaux forment six destinataires distincts. Un réparateur et un recycleur reçoivent des sections différentes, décidées par le métier de chacun.

Les niveaux repairer, recycler et upstream donnent chacun les sections de leur métier, et rien de plus. Ce sont des publics distincts, et aucun ne contient les autres : une accréditation de recycleur n'ouvre pas ce que voit le réparateur, et n'ouvre pas non plus la fabrication ni la chaîne d'approvisionnement du fournisseur amont.

Valeur	Ce qu'elle ajoute
`public`	identification du produit, conformité déclarée, taux de recyclabilité et de contenu recyclé, étiquettes libres de la marque (`labels`), spécification générale pour une batterie, marquages des articles 13(4) et 13(5), agent extincteur, lien vers la déclaration UE de conformité et son contenu structuré quand la marque l'a rempli, information sur la gestion des déchets
`end_user`	tout le niveau public, plus impact environnemental, circularité complète, matière principale, mention de matière certifiée biologique (`materials.certified_organic`), durabilité, efficacité énergétique, empreinte carbone
`repairer`	tout le niveau `end_user`, plus nomenclature des composants, notice de démontage, indice de réparabilité, état de santé pour une batterie
`recycler`	tout le niveau `end_user`, plus composition des matériaux, substances préoccupantes, notice de démontage, état de santé pour une batterie
`upstream`	tout le niveau `end_user`, plus composition des matériaux, substances préoccupantes, données de fabrication et de chaîne d'approvisionnement
`authority`	l'intégralité du passeport, sans filtrage

Les champs que la console écrit à la racine du passeport ont chacun leur propre niveau, nommé un par un : voir Les règles d'accès au passeport.

Une marque peut redéfinir ces règles pour ses propres produits. Le tableau ci-dessus donne le comportement par défaut, appliqué tant qu'une marque n'a rien redéfini.

#En-têtes de requête

Aucun en-tête n'est obligatoire pour le niveau public.

En-tête	Obligatoire	Description
`Authorization`	non	`Bearer <jeton de session>`. Obligatoire seulement pour les niveaux `repairer`, `recycler`, `upstream` et `authority`.

#Corps de la requête

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

#Requête d'exemple

Lecture du passeport de référence publié pour le GTIN 03701234567891, au niveau public.

curl -i "https://api.sealtrust.io/v1/passport/01/03701234567891?access_tier=public"

const gtin = "03701234567891";

const url = new URL(
  `https://api.sealtrust.io/v1/passport/01/${encodeURIComponent(gtin)}`,
);
url.searchParams.set("access_tier", "public");

const response = await fetch(url, { method: "GET" });
const passeport = await response.json();

console.log(response.status);
console.log(JSON.stringify(passeport, null, 2));

import requests

gtin = "03701234567891"

response = requests.get(
    f"https://api.sealtrust.io/v1/passport/01/{gtin}",
    params={"access_tier": "public"},
    timeout=30,
)

print(response.status_code)
print(response.json())

Pour un niveau qui exige un compte, ajoutez l'en-tête d'autorisation et changez la valeur du paramètre.

curl -i \
  -H "Authorization: Bearer votre-jeton-de-session" \
  "https://api.sealtrust.io/v1/passport/01/03701234567891?access_tier=recycler"

const gtin = "03701234567891";

const url = new URL(
  `https://api.sealtrust.io/v1/passport/01/${encodeURIComponent(gtin)}`,
);
url.searchParams.set("access_tier", "recycler");

const response = await fetch(url, {
  method: "GET",
  headers: { Authorization: "Bearer votre-jeton-de-session" },
});
const passeport = await response.json();

console.log(response.status);
console.log(JSON.stringify(passeport, null, 2));

import requests

gtin = "03701234567891"

response = requests.get(
    f"https://api.sealtrust.io/v1/passport/01/{gtin}",
    params={"access_tier": "recycler"},
    headers={"Authorization": "Bearer votre-jeton-de-session"},
    timeout=30,
)

print(response.status_code)
print(response.json())

#Réponse d'exemple

Code HTTP 200OK

Code HTTP 200.

JSON

{
  "id": 4821,
  "product_id": null,
  "product_model_id": 317,
  "gtin": "03701234567891",
  "level": "model",
  "brand_id": 12,
  "brand_code": "K7Q2M9XH4B",
  "schema_version": "1.0",
  "passport_version": 3,
  "data": {
    "product_identity": {
      "gtin": "03701234567891",
      "model": "Sac Modèle Exemple",
      "brand": "Exemple SAS",
      "made_in": "FR",
      "production_facility": "Atelier Exemple, Nantes"
    },
    "compliance": {
      "eu_espr": true,
      "reach": true,
      "ce_marking": true
    },
    "circularity": {
      "recyclability_percentage": 62,
      "recycled_content_percentage": 0
    }
  },
  "data_hash": "4444444444444444444444444444444444444444444444444444444444444444",
  "ipfs_uri": null,
  "visibility": "public",
  "published_at": "2026-05-14T09:12:44.201000+00:00",
  "product_name": "Sac Modèle Exemple",
  "brand_name": "Exemple SAS",
  "image_url": "https://exemple-sas.test/images/sac-modele.jpg",
  "access_tier": "public",
  "available_tiers": ["public"],
  "passport_service_provider": null
}

Quand plusieurs versions publiées et publiques coexistent pour ce modèle, c'est celle qui porte le plus grand numéro de version qui vous est rendue.

La réponse compte vingt champs et rien d'autre.

Champ	Type	Description
`id`	`integer`	Le numéro de cette version de passeport.
`product_id`	`null`	Ce champ vaut toujours `null` ici. Un passeport de référence n'est rattaché à aucun exemplaire.
`product_model_id`	`integer`	Le numéro du modèle auquel ce passeport est rattaché. Ce point d'entrée ne cherche que parmi les passeports rattachés à un modèle, donc ce champ n'est jamais `null` ici.
`gtin`	`string`	Le GTIN que vous avez demandé, ramené à quatorze chiffres.
`level`	`string`	Vaut toujours `model` sur ce point d'entrée.
`brand_id`	`integer`	Le numéro de la marque qui publie ce passeport.
`schema_version`	`string`	La version du schéma de données du passeport.
`passport_version`	`integer`	Le numéro de version du passeport. Une correction se publie sous un numéro de version plus grand, et la version déjà publiée reste telle quelle.
`data`	`object`	Le contenu du passeport, filtré selon le niveau demandé. Voir plus bas.
`data_hash`	`string \| null`	L'empreinte SHA-256 du contenu complet du passeport, en hexadécimal. `null` quand aucune empreinte n'a été enregistrée pour cette version.
`ipfs_uri`	`string \| null`	L'adresse `ipfs://` de la copie publiée du passeport. Toujours `null` aux niveaux `public` et `end_user`, qui ne reçoivent pas cette adresse. `null` aussi quand aucune copie n'a été déposée.
`visibility`	`string`	Vaut toujours `public` ici. Ce point d'entrée ne sert que les passeports dont la visibilité est publique.
`published_at`	`string`	Date et heure de publication de cette version, au format ISO 8601. Ce point d'entrée ne sert que des passeports publiés, donc ce champ n'est jamais `null` ici.
`product_name`	`string`	Le nom du modèle qui porte ce GTIN.
`brand_name`	`string`	Le nom de la marque qui publie ce passeport.
`image_url`	`string \| null`	L'adresse complète de la photographie du modèle : sa photo principale, ou à défaut la première image de sa médiathèque. La même que sur le passeport d'une pièce de ce modèle. `null` quand le modèle n'en a pas, ou quand il appartient à une autre marque que ce passeport. C'est la copie allégée de la photo (WebP, 800 pixels au plus sur le grand côté, 100 Ko au plus, sans données EXIF) quand elle existe, sinon l'original. Une adresse d'un autre site est rendue telle quelle.
`access_tier`	`string`	Le niveau réellement servi : celui demandé, ou `public` par défaut.
`available_tiers`	`array` de `string`	Les niveaux que VOTRE appel peut demander sur ce passeport, dans l'ordre `public`, `end_user`, `repairer`, `recycler`, `upstream`, `authority` : `["public"]` sans authentification, `end_user` en plus pour un compte connecté, le métier accrédité par la marque pour un partenaire, tous pour une autorité. La liste ne donne aucun droit : chaque niveau demandé reste vérifié. Une réponse qui la porte pour un compte connecté ne doit aller dans aucun cache partagé.
`brand_code`	`string`	L'identifiant public de la marque, dix caractères. C'est celui à citer et à conserver.
`passport_service_provider`	`object` ou `null`	Le prestataire de services de passeport qui tient la copie de sauvegarde de cette version (règlement (UE) 2024/1781, article 10(4) et annexe III point (l)) : `identifier`, sa référence, `name`, sa raison sociale, et `backed_up_at`, la date de la copie au format ISO 8601. `null` tant que la copie de cette version n'existe pas, ou quand sa dernière vérification a échoué. Hors de `data`, donc hors de l'empreinte `data_hash`.

#En-têtes de la réponse

Une réponse 200 porte X-DPP-Access-Tier, en plus de Cache-Control, X-Request-Id et de la famille X-RateLimit-* que porte toute réponse.

En-tête	Contenu
`X-DPP-Access-Tier`	le niveau d'accès qui a servi à filtrer la réponse
`Cache-Control`	`public, max-age=60, s-maxage=300` au niveau `public`, `private, no-store` à tout autre niveau. Seule la réponse publique, la même pour tout appelant anonyme, peut être gardée par un cache.

Seul X-DPP-Access-Tier est propre à la réponse 200. Une réponse d'erreur ne le porte pas. Cache-Control, X-Request-Id et la famille X-RateLimit-* accompagnent aussi les réponses d'erreur.

#Lire le champ `data`

data porte le contenu du passeport, sous forme de sections nommées. Les sections présentes dépendent du niveau demandé, des règles définies par la marque, et de ce que la marque a réellement renseigné. Une section absente du passeport n'apparaît pas, et une section que votre niveau ne couvre pas n'apparaît pas non plus.

Le filtrage descend à l'intérieur des sections. Dans l'exemple ci-dessus, la section compliance est présente au niveau public, mais elle ne montre que les mentions de conformité ouvertes à ce niveau. Ne concluez jamais qu'un champ n'existe pas parce qu'il est absent de votre réponse.

#Erreurs

Le corps d'une réponse d'erreur porte un champ detail.

Code	Condition	Que faire
400	Le dernier chiffre du GTIN envoyé n'est pas la clef de contrôle des chiffres qui le précèdent. `detail` vaut `Invalid GTIN: the check digit does not match.` Une longueur autre que 8, 12, 13 ou 14 chiffres donne le même 400 avec le même message, même quand la clef de contrôle est juste. Une valeur sans aucun chiffre, ou de plus de quatorze chiffres, renvoie 404 et non 400.	Recopiez le code imprimé sur le produit, chiffre pour chiffre, sans en ajouter ni en omettre.
401	Vous demandez `access_tier=end_user` sans être authentifié. `detail` vaut `End-user-tier access requires authentication`.	Présentez un jeton de session valide dans l'en-tête `Authorization`, ou demandez le niveau `public`.
401	Vous demandez `access_tier=authority` sans être authentifié. `detail` vaut `Authority-tier access requires authentication`.	Présentez un jeton de session valide dans l'en-tête `Authorization`.
401	Vous demandez `access_tier=repairer`, `recycler` ou `upstream` sans être authentifié. `detail` vaut `Professional-tier access requires authentication`.	Présentez un jeton de session valide dans l'en-tête `Authorization`. Une clef d'API partenaire ne convient pas ici.
403	Vous demandez `access_tier=authority` avec un compte qui ne porte pas le rôle d'autorité. `detail` vaut `Authority-tier access is restricted to market surveillance authorities`.	Demandez un niveau qui correspond à votre compte.
403	Vous demandez un niveau professionnel avec un compte qui n'y a pas droit sur cette marque. `detail` commence par `This tier is restricted to the product's brand`.	Demandez à la marque du produit une accréditation active du métier correspondant, puis réessayez.
404	`detail` vaut `Unknown GS1 Digital Link`. Trois situations donnent cette même réponse : le GTIN envoyé ne contient aucun chiffre ou en contient plus de quatorze, aucun modèle ne porte ce GTIN, ou aucun passeport de référence public n'est publié pour ce modèle.	Vérifiez le GTIN. Si le GTIN est bon, demandez à la marque de publier le passeport de référence de ce modèle. La réponse est volontairement identique dans les trois cas, donc elle ne vous dira pas laquelle s'applique.
404	L'appel arrive sur le nom de domaine vérifié d'une marque, et le passeport de référence appartient à une autre marque. `detail` vaut `Unknown GS1 Digital Link`.	Appelez cette adresse sur le domaine de la marque concernée, ou sur `api.sealtrust.io`. Le message est le même que pour un identifiant inconnu, pour ne pas confirmer qu'il existe.
422	La valeur de `access_tier` ne fait pas partie des six valeurs acceptées. `detail` porte la liste des erreurs de validation, avec le nom du paramètre en cause.	Corrigez la valeur du paramètre.
429	Le plafond de 600 appels par 60 secondes sur les lectures `/passport` est dépassé. `detail` vaut `Rate limit exceeded: 600 requests per 60s`. La réponse porte `Retry-After` et la famille `X-RateLimit-*`.	Attendez le nombre de secondes indiqué par `Retry-After`, puis réessayez.
500	Une erreur inattendue s'est produite pendant le traitement de votre appel. `detail` vaut `Internal Server Error`.	Réessayez. Si l'erreur persiste, contactez le support en indiquant l'heure de l'appel et la valeur de l'en-tête `X-Request-Id`, que porte cette réponse comme toutes les autres.

#Ordre des contrôles

Le contrôle du niveau authority a lieu avant la recherche du passeport. Un appel access_tier=authority sans authentification renvoie donc 401, même si le GTIN est inconnu.

Les contrôles des niveaux professionnels ont lieu après la recherche. Un appel access_tier=recycler sur un GTIN inconnu renvoie donc 404, et jamais 401.

#Voir aussi

GET /passport/01/{gtin}/proof, rassembler les preuves publiques du passeport annoncé par un GTIN.
GET /passport/{identifier}, lire le passeport publié d'un article.
GET /01/{gtin}, résoudre un lien GS1 qui ne porte qu'un GTIN.
Notions de base, distinguer modèle, lot et article avant de commander la moindre étiquette.

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/passport/01/{gtin}