Méthode GET/01
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
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 :
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.
#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
Aucun plafond propre à ce point d'entrée. Il relève du compteur général de l'API, commun à toutes les routes sans plafond dédié et compté par adresse IP appelante sur une fenêtre de 60 secondes. Ce compteur est aussi 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 ni le quota quotidien d'une clef d'API, 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. 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. Sans en-tête, ou sans valeur correspondante, il choisit fr.
Le serveur sert deux langues, fr et en.
#En-têtes de requête
| En-tête | Obligatoire | Description |
|---|---|---|
Accept-Language | non | Choisit la langue de la page d'arrivée. fr par défaut. |
#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/1.1 302 Found
Location: https://sealtrust.io/fr/passport/01/03701234567891
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1786000020
Content-Length: 0Avec l'en-tête Accept-Language: en, la même requête renvoie ceci.
HTTP/1.1 302 Found
Location: https://sealtrust.io/en/passport/01/03701234567891
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
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 pénalise les chaînes de redirections.
#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.
#Erreurs
Le corps d'une réponse d'erreur contient un seul champ, detail.
{
"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.