GETMéthode GET/01/{gtin}/21/{serial}

Vous transformez un GS1 Digital Link en adresse de la page publique de l'article. La réponse porte le code 302 et l'adresse de destination dans l'en-tête Location. Le corps de la réponse est vide.

#Autorisation

Aucune, point d'entrée public. Il n'attend ni clef d'API, ni cookie de session, ni en-tête Authorization. Un appel serveur à serveur est accepté.

Appelez ce point d'entrée sur https://api.sealtrust.io. La même route répond aussi sous le préfixe /v1, à https://api.sealtrust.io/v1/01/{gtin}/21/{serial}. Les deux adresses appellent le même code. Pour une intégration serveur nouvelle, utilisez la forme /v1. La forme sans préfixe existe parce que c'est la structure de chemin /01/…/21/… qui fait d'une adresse un GS1 Digital Link, donc c'est elle que rencontre un lecteur de code.

Le domaine que nous inscrivons dans les liens GS1 que nous produisons est réglable, et vaut https://id.gs1.org par défaut. L'identifiant que nous déclarons au registre européen des passeports numériques est l'adresse courte /p/{serial}, parce qu'un lien GS1 complet dépasse la limite de 50 caractères du registre. Le QR code que nous imprimons sur un article encode lui aussi /p/{serial}.

Un lien GS1 peut aussi ne porter que le GTIN, sans AI 21. Il désigne alors la référence commerciale et résout vers le passeport du modèle, partagé par tous les exemplaires qui portent ce même code produit. Voir GET /01/{gtin}. Le règlement ESPR autorise un passeport au niveau du modèle, du lot ou de l'exemplaire. Nous servons le niveau modèle et le niveau exemplaire. Rien ne vous oblige à sérialiser chaque unité.

#Plafond d'appels

Ce chemin n'a pas de plafond qui lui soit propre. Il relève du compteur général de l'API, compté par adresse IP appelante sur une fenêtre de 60 secondes. Ce compteur est unique pour toutes les routes qui n'ont pas de plafond propre, et il est unique pour toutes les valeurs de GTIN et de numéro de série. Parcourir mille liens différents consomme mille appels du même budget.

Toute réponse porte les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, ce dernier donnant l'heure de remise à zéro en secondes depuis le 1er janvier 1970.

Ce point d'entrée ne consomme aucun quota de votre offre.

#Paramètres de chemin et de requête

Nous ramenons les lettres I et L au chiffre 1, et la lettre O au chiffre 0, avant de chercher l'exemplaire. Vous obtenez donc la bonne réponse même pour un numéro ressaisi à la main avec un caractère sosie.

Nous ignorons tout autre paramètre de requête. Une adresse qui traîne les paramètres d'un scan NFC, ou les marqueurs de campagne d'un lien partagé, résout exactement comme l'adresse nue.

#Les cinq valeurs de linkType

Toute autre valeur donne la même réponse qu'un paramètre absent, donc la redirection va vers la page produit. Vous pouvez écrire le nom du paramètre linkType ou linktype.

#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. Nous la recalculons et nous comparons avant toute recherche.

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

#Ce que le GTIN doit vérifier

Nous comparons le GTIN du chemin au GTIN du modèle de l'exemplaire. Les deux doivent être identiques. Vous en tirez deux conséquences directes.

Un exemplaire dont le modèle ne porte aucun GTIN n'est pas adressable par cette forme. Il reste adressable par son adresse courte /p/{serial}.

Un numéro de série réel associé à un GTIN qui n'est pas le sien répond 404, avec exactement le même corps qu'un numéro de série inconnu. Vous ne pouvez pas distinguer les deux cas, et c'est voulu : la réponse ne confirme jamais l'existence d'un numéro de série.

#Un exemplaire retiré du catalogue continue de répondre

Un exemplaire remplacé par une frappe ultérieure et un exemplaire archivé restent résolvables. Nous les redirigeons vers leur passeport plutôt que vers la page produit, parce que la page produit ne les affiche plus. Un code imprimé sur un objet qui est encore entre les mains de quelqu'un ne doit pas répondre « inconnu ».

Un numéro de série désigne un seul exemplaire. Quand cet exemplaire a été remplacé par une frappe ultérieure, c'est la version en cours qui répond.

#Corps de la requête

Aucun. C'est une requête GET, tout passe par le chemin.

curl -i https://api.sealtrust.io/v1/01/03701234567891/21/0000000000AB

const gtin = "03701234567891";
const serial = "0000000000AB";

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

console.log(response.status);
console.log(response.headers.get("Location"));
console.log(response.headers.get("X-RateLimit-Remaining"));

import requests

gtin = "03701234567891"
serial = "0000000000AB"

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

print(response.status_code)
print(response.headers["Location"])
print(response.headers["X-RateLimit-Remaining"])

HTTP/1.1 302 Found
Location: https://sealtrust.io/fr/product/0000000000AB
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1786000020
Content-Length: 0

HTTP/1.1 302 Found
Location: https://sealtrust.io/fr/passport/0x0000000000000000000000000000000000000000000000000000000000000000
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1786000020
Content-Length: 0