Tutoriel API de liaison ESL : connecter des étiquettes aux articles

2026-09-21 pdf labels barcodes label merge browser based graphical layout editor google sheets addin microsoft excel addon electronic shelf labels esl barcode3 labels label editor

Tutoriel de l’API de liaison ESL : connecter des étiquettes à des articles

Vous avez une étiquette électronique de gondole (ESL) en main et un article dans votre catalogue. Vous devez faire en sorte que cette étiquette affiche le bon prix, le bon nom de produit et les bonnes données supplémentaires, sans passer par un flux de travail propriétaire sur terminal portable. Ce tutoriel montre comment utiliser l’API de liaison ESL dans le système d’impression d’étiquettes de nouvelle génération (LPSNG) pour connecter une étiquette ESL à un article via un simple appel HTTPS.

À la fin de ce tutoriel, vous serez en mesure de lier programmatiquement une étiquette depuis un système externe tel qu’une unité de saisie mobile (MDE), de vérifier la liaison, puis de délier ou de relier une étiquette lorsqu’elle est affectée à un autre article.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un compte LPSNG avec accès à l’API de liaison ESL. L’API de liaison fait partie des fonctionnalités de base de LPSNG et est disponible dans toutes les éditions.
Du matériel ESL compatible prenant en charge l’interface de liaison, par exemple les appareils ESL CATIC.
Une station de base ESL sous tension, avec les étiquettes à lier à portée.
Une connaissance de base des API REST et de JSON.
L’URL de base de votre service web LPSNG, telle qu’indiquée dans la configuration de votre compte.
Des identifiants client OAuth2 pour l’authentification. Si vous n’avez pas encore enregistré de système externe, suivez d’abord la documentation OAuth2.

Vous n’avez pas besoin de communiquer directement avec un protocole de station de base spécifique à un fournisseur. La méthode difficile consisterait à rétro-ingénierie la communication de bas niveau utilisée par votre matériel ESL. La voie prise en charge consiste à laisser le service géré LPSNG assurer cette traduction pendant que vous utilisez une seule API HTTPS.

Étape par étape : lier une étiquette ESL à un article

Étape 1 : obtenir un jeton d’accès OAuth2

LPSNG utilise un protocole d’enregistrement OAuth2 simplifié pour les systèmes externes. Une fois votre intégration enregistrée, vous demandez un jeton d’accès auprès du point de terminaison de jeton de votre locataire et vous l’incluez dans chaque appel API.

Le point de terminaison exact et le flux d’enregistrement dépendent de votre compte. Dans la plupart des configurations, une demande d’identifiants client ressemble à ceci :

curl -s -X POST "https://<VOTRE-BASE-LPSNG>/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials"

Une réponse réussie inclut un jeton porteur :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Utilisez cette valeur access_token dans l’en-tête Authorization de la demande de liaison. Consultez le guide OAuth2 si votre locataire utilise une forme de demande de jeton différente.

Étape 2 : identifier l’article et l’étiquette

Vous avez besoin de deux identifiants avant de pouvoir lier quoi que ce soit :

Identifiant de l’article : généralement le SKU, l’EAN ou le numéro de matériel interne qui existe déjà dans votre source de données LPSNG.
Identifiant de l’étiquette : l’identifiant unique de l’étiquette ESL. Il est souvent imprimé sur l’étiquette elle-même ou capturé en scannant l’étiquette avec une unité MDE.

Par exemple, un article peut être identifié comme EAN-4001234567890, et une étiquette comme CATIC-001234. Gardez ces deux valeurs à portée de main pour la charge utile JSON.

Étape 3 : construire la demande de liaison

Une demande de liaison est un objet JSON envoyé au point de terminaison de liaison. Les champs obligatoires sont l’identifiant de l’article et l’identifiant de l’étiquette. Selon la mise en page de vos étiquettes et la configuration ESL, vous pouvez également envoyer des champs facultatifs tels que price ou un objet labelData.

{
  "itemId": "EAN-4001234567890",
  "tagId": "CATIC-001234",
  "price": "19.90",
  "labelData": {
    "name": "Lait d'avoine bio 1L",
    "unit": "L"
  }
}

Tous les déploiements n’utilisent pas price et labelData. Si vos étiquettes sont entièrement pilotées par les données de base des articles dans LPSNG, vous pouvez envoyer uniquement itemId et tagId. Vérifiez la mise en page de vos étiquettes pour savoir quels champs supplémentaires l’étiquette doit afficher.

Étape 4 : envoyer une requête POST au point de terminaison de liaison

Pour ce tutoriel, nous utilisons /api/esl/bind comme point de terminaison de liaison. Votre installation LPSNG peut exposer le même chemin ou un chemin spécifique au locataire ; confirmez donc le point de terminaison exact dans la documentation de l’API de liaison ESL pour votre environnement.

Enregistrez la charge utile dans un fichier pour que la commande curl reste lisible :

{
  "itemId": "EAN-4001234567890",
  "tagId": "CATIC-001234",
  "price": "19.90",
  "labelData": {
    "name": "Lait d'avoine bio 1L",
    "unit": "L"
  }
}

Envoyez ensuite la requête :

curl -s -X POST "https://<VOTRE-BASE-LPSNG>/api/esl/bind" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  --data @binding-payload.json

LPSNG reçoit la requête, résout les données de l’article dans votre source de données et ordonne à la station de base ESL de mettre à jour l’étiquette.

Étape 5 : gérer la réponse

Une liaison réussie renvoie normalement une réponse 200 OK avec un objet de statut :

{
  "status": "bound",
  "tagId": "CATIC-001234",
  "itemId": "EAN-4001234567890",
  "updatedAt": "2026-09-21T10:15:00Z"
}

Les réponses d’erreur courantes incluent :

400 pour des données invalides, par exemple un corps JSON mal formé ou un champ obligatoire manquant.
401 pour un échec d’authentification, par exemple un jeton d’accès expiré ou manquant.

Inspectez le corps de la réponse pour trouver un message d’erreur expliquant quel champ a échoué. Si l’API renvoie un autre statut 4xx, vérifiez si l’étiquette ou l’article est inconnu ou si l’étiquette est déjà liée ailleurs.

Étape 6 : vérifier la liaison en interrogeant le statut de l’étiquette

Si votre déploiement expose un point de terminaison de statut d’étiquette, vous pouvez interroger la liaison actuelle. Le point de terminaison exact peut varier ; voici un exemple de forme :

curl -s "https://<VOTRE-BASE-LPSNG>/api/esl/status/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Une réponse similaire à celle-ci confirme que l’étiquette est liée à l’article attendu :

{
  "tagId": "CATIC-001234",
  "boundItemId": "EAN-4001234567890",
  "lastSeen": "2026-09-21T10:15:00Z"
}

Si votre locataire n’expose pas de point de terminaison de statut, utilisez le tableau de bord de gestion ESL dans LPSNG pour voir le statut de l’étiquette.

Étape 7 : facultatif — délier ou relier une étiquette

Lorsqu’un article est déplacé vers un nouvel emplacement ou qu’une étiquette est réutilisée, vous devez la délier ou la relier. La méthode exacte dépend de votre point de terminaison de liaison LPSNG.

Une demande de déliaison courante utilise DELETE :

curl -s -X DELETE "https://<VOTRE-BASE-LPSNG>/api/esl/bind/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Pour relier la même étiquette à un autre article, envoyez une requête PUT :

curl -s -X PUT "https://<VOTRE-BASE-LPSNG>/api/esl/bind/CATIC-001234" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"EAN-4001234567891"}'

Consultez la documentation de l’API de liaison ESL pour connaître le comportement exact de déliaison et de reliaison dans votre installation.

Vérifier la liaison

Après que l’appel API a renvoyé un succès, confirmez la liaison de plusieurs manières :

Vérifiez physiquement l’affichage ESL — l’étiquette doit maintenant afficher le prix et le nom de l’article. Si l’affichage est encore vide ou montre d’anciennes données, attendez quelques secondes et vérifiez à nouveau.
Interrogez le statut de l’étiquette via l’interface ESL si votre déploiement en fournit une. La réponse de statut doit montrer le boundItemId attendu.
Ouvrez le tableau de bord de gestion ESL dans LPSNG et recherchez l’étiquette. Son statut doit passer de non liée ou de l’article précédent au nouvel article.
Testez avec un autre article et reliez la même étiquette. Si l’affichage se met à jour correctement, votre intégration fonctionne de bout en bout.

Résolution des problèmes courants

Erreurs d’authentification

Vérifiez votre identifiant client et votre secret OAuth2. Les jetons d’accès expirent ; renouvelez donc le jeton si vous recevez une réponse 401 après un certain temps.

Étiquette introuvable

Assurez-vous que l’identifiant de l’étiquette est exactement correct, y compris les préfixes ou les zéros initiaux. Confirmez également que l’étiquette est allumée et à portée de la station de base ESL. Une étiquette qui ne s’est pas signalée récemment peut ne pas être disponible pour la liaison.

Article introuvable

Vérifiez que l’identifiant de l’article existe dans votre source de données LPSNG. L’API de liaison résout les données par rapport aux mêmes données que celles utilisées par vos étiquettes ; une faute de frappe dans l’EAN ou le SKU empêchera donc la liaison.

Conflit de liaison

L’étiquette est peut-être déjà liée à un autre article. Déliez d’abord l’étiquette, puis envoyez une nouvelle demande de liaison. Certaines installations refusent une reliaison directe sans étape de déliaison explicite.

Problèmes de réseau

Si la requête expire, vérifiez la connectivité entre votre client, le service web LPSNG et la station de base ESL. La station de base doit être joignable depuis LPSNG, et non directement depuis votre client.

FAQ

Qu’est-ce que l’API de liaison ESL ?

L’API de liaison ESL est un service web fourni par le système d’impression d’étiquettes de nouvelle génération (LPSNG) qui permet à des systèmes externes tels que des unités de saisie mobile de lier des étiquettes électroniques de gondole à des articles spécifiques. Elle utilise une simple requête JSON sur HTTPS.

Puis-je lier plusieurs étiquettes à un seul article ?

En règle générale, une étiquette est liée à un article. Cependant, selon votre matériel ESL et la configuration LPSNG, vous pouvez être en mesure de lier plusieurs étiquettes au même article à des fins de redondance ou pour différents emplacements d’affichage. Consultez la documentation de votre matériel.

Comment délier une étiquette ?

Pour délier une étiquette, vous pouvez envoyer une requête au point de terminaison de liaison avec un identifiant d’article vide ou nul, ou utiliser une méthode de déliaison dédiée si elle est disponible. Reportez-vous à la documentation de l’API pour connaître le point de terminaison et la charge utile exacts.

L’API de liaison est-elle disponible dans toutes les éditions de LPSNG ?

Oui, l’API de liaison ESL fait partie des fonctionnalités de base de LPSNG et est disponible dans toutes les éditions, y compris la solution cloud et l’édition embarquée. Cependant, vous avez besoin de matériel ESL compatible pour l’utiliser.

Conclusion

Le flux de travail de liaison est une petite boucle : s’authentifier, collecter les identifiants de l’article et de l’étiquette, envoyer la demande de liaison et vérifier l’affichage. Une fois cette boucle opérationnelle, vous pouvez l’appeler depuis une unité MDE, un processus de préparation de commandes ou tout autre système externe qui doit affecter des étiquettes ESL à des articles.

L’API de liaison ESL n’est qu’une partie de la solution ESL plus large de LPSNG. LPSNG fournit également l’interface ESL neutre vis-à-vis des fournisseurs pour la mise à jour des affichages, le guide OAuth2 pour l’authentification et le lecteur LPSNG pour les flux de travail ESL en ligne de commande.

Si vous intégrez du matériel ESL pour la première fois, commencez par la documentation de l’API de liaison ESL et testez avec une étiquette de rechange avant de passer en production.

Articles connexes

Tutoriel API de liaison ESL : connecter des étiquettes aux articles