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

Les niveaux public et end_user répondent sans compte. Les niveaux 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
`end_user`	tout le monde, sans compte
`repairer`	les comptes 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 comptes 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 comptes 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

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

Ce compteur est commun à toutes les adresses qui commencent 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 ni ce quota quotidien, ni le quota mensuel de produits de votre offre.

#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, au sens du règlement ESPR. 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 : 3701234567890, 03701234567890 et 3-701234-567890. Elles donnent toutes la même forme canonique, 03701234567890. 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
`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

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 03701234567890, au niveau public.

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

const gtin = "03701234567890";

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 = "03701234567890"

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/03701234567890?access_tier=recycler"

const gtin = "03701234567890";

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 = "03701234567890"

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": "03701234567890",
  "level": "model",
  "brand_id": 12,
  "schema_version": "1.0",
  "passport_version": 3,
  "data": {
    "product_identity": {
      "gtin": "03701234567890",
      "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"
}

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 quinze 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.

#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`	`no-store, max-age=0`, quel que soit le niveau servi. Ne placez cette réponse derrière aucun cache partagé.

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.` C'est la seule cause de ce code sur ce point d'entrée : 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=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.
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 60 appels par 60 secondes sur les adresses `/passport` est dépassé. `detail` vaut `Rate limit exceeded: 60 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}