Skip to content

Latest commit

Β 

History

History
685 lines (542 loc) Β· 27 KB

README.md

File metadata and controls

685 lines (542 loc) Β· 27 KB

printer β€” agent d'impression de la caisse

Agent d'impression des points de vente Chapitre Neuf : il récupère les jobs de l'API (Mercure SSE + polling de secours) et imprime tickets ESC/POS, étiquettes et stickers, ouvre le tiroir-caisse.

Tout tient dans un seul binaire, printer : l'agent lui-mΓͺme (printer run, lancΓ© par systemd) et les commandes d'exploitation (printer status, printer log, printer update…). Il tourne en arriΓ¨re-plan comme service systemd utilisateur, dΓ©marre au boot sans session ouverte (linger) et se met Γ  jour depuis les GitHub Releases.

Emplacement RΓ΄le
~/.local/bin/printer le binaire (printer.prev : version prΓ©cΓ©dente, pour printer rollback)
~/.local/bin/print-agent lien vers printer (compatibilitΓ© avec l'ancienne installation)
~/.config/print-agent/env la configuration (identifiants API, imprimantes, adresse du magasin), droits 600
~/.config/systemd/user/print-agent.service le service (réécrit par printer setup, ne pas l'éditer)
~/.config/systemd/user/printer-update.{service,timer} la mise Γ  jour automatique (dΓ©sactivΓ©e par dΓ©faut)

Installation sur un PC neuf

PrΓ©-requis : Ubuntu (ou dΓ©rivΓ©) avec systemd, curl, l'utilisateur de la caisse. Pas besoin de Go.

# en tant qu'utilisateur de la caisse (pas root, pas sudo)
curl -fsSL https://raw.githubusercontent.com/ICTools/printer-agent/main/deploy/install.sh | bash

Le script télécharge le binaire de la dernière release pour le processeur du PC (amd64 ou arm64), vérifie son sha256 contre checksums.txt, puis lance printer setup, qui :

  1. installe ~/.local/bin/printer ;
  2. crée ~/.config/print-agent/env depuis le modèle s'il n'existe pas (une config existante n'est jamais écrasée) ;
  3. installe les unités systemd utilisateur et active le service au boot (dès que la config est valide) ;
  4. active le linger (loginctl enable-linger) : le service dΓ©marre au boot sans que personne ne se connecte ;
  5. vérifie le PATH, l'accès aux imprimantes, python3 et brother_ql ;
  6. dΓ©marre le service si la config est remplie.

Ensuite :

printer config edit     # renseigner PRINT_AGENT_API_URL / _KEY / _SECRET ; valide puis redΓ©marre
printer status
printer test            # imprime un ticket de test

Si printer n'est pas trouvΓ©, ouvrir un nouveau terminal (Ubuntu ajoute ~/.local/bin au PATH Γ  la connexion) ou utiliser ~/.local/bin/printer.

Options : une version prΓ©cise curl -fsSL …/install.sh | bash -s -- --version v1.2.0. Relancer le script (ou printer setup) est sans risque : il rΓ©pare l'installation et garde la config.

Dépendances système

sudo usermod -aG lp $USER          # accès à /dev/usb/lp* (puis redémarrer la session / le PC)
sudo apt install python3-pil       # Γ©tiquettes et stickers
python3 -m pip install brother_ql  # Γ©tiquettes Brother QL (ou pipx install brother_ql)

Les scripts Python d'Γ©tiquettes (scripts/print.py, scripts/print_sticker.py) et scripts/sticker.png sont embarquΓ©s dans le binaire et extraits ensemble au besoin dans ~/.cache/print-agent/scripts/<hash>/. LABEL_SCRIPT_PATH / STICKER_SCRIPT_PATH restent prioritaires si le fichier existe ; sinon l'agent journalise un avertissement et prend la copie embarquΓ©e (printer config check et printer setup signalent un chemin absent).

DΓ©pΓ΄t privΓ©

Le dΓ©pΓ΄t est public aujourd'hui : rien Γ  faire. S'il devient privΓ©, les releases demandent une authentification :

  • installation : raw.githubusercontent.com ne sert plus le script ; avec gh connectΓ© (gh auth login) : gh api repos/ICTools/printer-agent/contents/deploy/install.sh -H 'Accept: application/vnd.github.raw' | bash. Le script bascule tout seul sur gh release download quand le tΓ©lΓ©chargement public Γ©choue (gh utilise GH_TOKEN/GITHUB_TOKEN s'ils sont dΓ©finis) ;
  • printer update (manuel ou automatique) prend, dans l'ordre : PRINTER_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN (environnement, ou ligne PRINTER_GITHUB_TOKEN=… dans ~/.config/print-agent/env), puis le token de gh. Un token fine-grained en lecture seule sur ce seul dΓ©pΓ΄t (Contents: read) suffit.

Commandes

Commande Effet
printer status version, Γ©tat du service, dΓ©marrage au boot, linger, config, imprimantes, derniers logs
printer start / stop / restart pilote le service ; start/restart refusent une config invalide et vΓ©rifient que l'agent reste dΓ©marrΓ©
printer log suit les logs en temps réel (50 dernières lignes puis la suite)
printer log -n 200 les 200 dernières lignes, sans suivre (-f pour suivre aussi)
printer log --since today --errors erreurs du jour (--since "1 hour ago", --since 2026-11-06…)
printer update --check compare la version installée à la dernière release
printer update installe la dernière release (voir ci-dessous)
printer update --version v1.2.0 installe une version précise (aussi pour revenir en arrière)
printer rollback revient au binaire remplacé par la dernière mise à jour (et inversement)
printer version version, commit, date de build (--short : juste la version)
printer config affiche la config, secrets masquΓ©s (PRINT_AGENT_API_SECRET=********, clΓ© API tronquΓ©e)
printer config edit ouvre $VISUAL/$EDITOR/nano, valide, propose de corriger, puis active et redΓ©marre le service
printer config check / path valide la config / affiche son chemin
printer test imprime un ticket Β« TEST IMPRESSION Β» (version, poste, date, device) sur l'imprimante ticket, sans tiroir
printer autoupdate on / off / status mise Γ  jour automatique quotidienne
printer setup installe ou rΓ©pare tout (idempotent)
printer run l'agent au premier plan (ce que lance systemd) β€” options : printer run --help
printer detect, receipt-test, open-drawer, label, sticker-address, sticker-image outils d'impression manuels (voir Β« Mode CLI Β»)

Mise Γ  jour

printer update --check
printer update

printer update :

  1. interroge l'API GitHub (releases/latest) et compare les versions (semver ; un build de dev est toujours remplacΓ©) ;
  2. tΓ©lΓ©charge printer_linux_<arch> et checksums.txt, vΓ©rifie le sha256 (rien n'est installΓ© sinon) ;
  3. exΓ©cute le nouveau binaire (version --short) pour vΓ©rifier qu'il tourne et annonce la bonne version ;
  4. remplace ~/.local/bin/printer par un rename atomique, l'ancien est gardΓ© en printer.prev ;
  5. si le service tournait, le redΓ©marre et vΓ©rifie pendant 20 s (--wait) qu'il reste actif sans redΓ©marrage automatique de systemd ;
  6. sinon rollback : remet l'ancien binaire et redémarre. Si l'ancien ne tient pas non plus, le problème n'est pas la mise à jour (réseau, API, config) : voir printer log -n 100.

Un verrou empΓͺche deux mises Γ  jour (ou un rollback, un setup) simultanΓ©s. Une version annulΓ©e par le rollback automatique est mΓ©morisΓ©e (~/.local/bin/.printer-refused-version) : printer update et le timer ne la rΓ©installent plus ; une version plus rΓ©cente est installΓ©e normalement, et printer update --version vX.Y.Z force celle-lΓ . --version avec une version plus ancienne fait un downgrade (annoncΓ© comme tel).

Les tΓ©lΓ©chargements passent uniquement en https vers GitHub (github.com, api.github.com, *.githubusercontent.com, redirections comprises) et sont limitΓ©s Γ  100 Mo. PRINTER_GITHUB_API (GitHub Enterprise) doit Γͺtre en https ; PRINTER_UPDATE_INSECURE=1 lΓ¨ve ces contrΓ΄les pour un serveur de test local, jamais en production.

Si les unitΓ©s systemd changent entre deux versions, les notes de release le disent : lancer alors printer setup.

Mise Γ  jour automatique (dΓ©sactivΓ©e par dΓ©faut)

printer autoupdate on      # tous les jours vers 05:00 (+ jusqu'Γ  30 min alΓ©atoires)
printer autoupdate off
journalctl --user -u printer-update.service   # historique

Désactivée par défaut : une mise à jour redémarre l'agent, et une caisse doit changer de version quand on l'a décidé (après une release testée). Le timer n'est pas persistent : un PC éteint à 05:00 n'est pas mis à jour au démarrage, en pleine ouverture. Le rollback automatique s'applique aussi.

Logs

Les logs vont dans journald (rotation gΓ©rΓ©e par journald) :

printer log                         # suivi temps rΓ©el
printer log -n 100                  # 100 dernières lignes
printer log --since today --errors  # erreurs du jour
journalctl --user -u print-agent --since "2026-11-06 09:00" --until "2026-11-06 10:00"

DΓ©pannage

SymptΓ΄me Piste
printer: command not found nouveau terminal, ou ~/.local/bin/printer
status : activating (auto-restart), restarts qui montent l'agent quitte au dΓ©marrage : printer log -n 50 ; souvent identifiants refusΓ©s ou API injoignable (printer config check)
Failed to connect to bus / systemctl --user Γ©choue lancer les commandes en session normale de l'utilisateur de la caisse, pas via sudo
le service ne démarre qu'après connexion linger off : printer setup (ou sudo loginctl enable-linger $USER)
Permission denied sur /dev/usb/lp0 sudo usermod -aG lp $USER puis redémarrer ; printer status liste les devices et leur accès
aucune imprimante dΓ©tectΓ©e cΓ’ble / alimentation ; printer detect
brother_ql not found installer brother_ql (voir DΓ©pendances) ; vΓ©rifier PATH/PYTHON_PATH
update : checksum mismatch tΓ©lΓ©chargement corrompu ou release modifiΓ©e : rien n'a Γ©tΓ© installΓ©, relancer ; sinon vΓ©rifier la release
update : no matching release aucune release publiΓ©e, ou dΓ©pΓ΄t privΓ© sans token (voir Β« DΓ©pΓ΄t privΓ© Β»)
une mise à jour pose problème printer rollback, ou printer update --version vX.Y.Z
texte illisible sur le ticket les accents sont convertis en ASCII (normal)
TLS en local printer run -insecure

Migration depuis l'ancienne installation

Ancienne installation (deploy/install.sh d'avant, build Go local) : binaire ~/.local/bin/print-agent, service print-agent, config ~/.config/print-agent/env. Le nouveau binaire garde le mΓͺme nom de service et la mΓͺme config, la migration est donc :

cp ~/.config/print-agent/env ~/print-agent-env.backup     # sΓ©curitΓ©
grep -E '^(LABEL|STICKER)_SCRIPT_PATH' ~/.config/print-agent/env   # chemins vers l'ancien clone ?
curl -fsSL https://raw.githubusercontent.com/ICTools/printer-agent/main/deploy/install.sh | bash
printer status          # active (running), config OK
printer test            # ticket de test

printer setup (lancé par le script) : garde ~/.config/print-agent/env tel quel (droits passés à 600), réécrit print-agent.service avec ExecStart=%h/.local/bin/printer run, déplace l'ancien binaire en ~/.local/bin/print-agent.legacy et le remplace par un lien vers printer, puis redémarre le service.

Avant de supprimer l'ancien clone Go : si la config contient LABEL_SCRIPT_PATH ou STICKER_SCRIPT_PATH pointant dans ce clone, retirer ces lignes (printer config edit) pour utiliser les scripts embarquΓ©s. printer config check avertit si un de ces chemins n'existe pas. Le clone n'est ensuite plus nΓ©cessaire.

Retour arrière (si besoin) : mv ~/.local/bin/print-agent.legacy ~/.local/bin/print-agent (remplace le lien), remettre ExecStart=%h/.local/bin/print-agent run dans ~/.config/systemd/user/print-agent.service, puis systemctl --user daemon-reload && systemctl --user restart print-agent.

DΓ©sinstallation

systemctl --user disable --now print-agent printer-update.timer
rm ~/.config/systemd/user/print-agent.service ~/.config/systemd/user/printer-update.*
systemctl --user daemon-reload
rm ~/.local/bin/printer ~/.local/bin/printer.prev ~/.local/bin/print-agent
# la config ~/.config/print-agent/env contient les identifiants : la supprimer si le poste est retirΓ©

DΓ©veloppement

go vet ./... && go test ./...
go build -o printer ./cmd/printer
./deploy/install.sh --from-source     # installe le build local (version = git describe)

Publier une release

Les releases sont produites par .github/workflows/release.yml sur un tag v* : tests, build linux/amd64 et linux/arm64 (statiques, CGO_ENABLED=0, version injectΓ©e par -ldflags -X main.version), checksums.txt, puis GitHub Release avec notes gΓ©nΓ©rΓ©es. Un tag vX.Y.Z-rc.1 crΓ©e une prΓ©-release (ignorΓ©e par printer update).

git checkout main && git pull
git tag -a v1.0.0 -m "v1.0.0"
git push origin v1.0.0

Mode Agent (printer run)

Ce que lance le service. Γ€ la main (tests) :

printer run -api-url https://api.monsite.com -api-key $API_KEY -api-secret $API_SECRET

Options

Flag Variable d'env DΓ©faut Description
-api-url PRINT_AGENT_API_URL - URL de l'API (requis)
-api-key PRINT_AGENT_API_KEY - ClΓ© API (requis)
-api-secret PRINT_AGENT_API_SECRET - Secret API (requis)
-poll-interval PRINT_AGENT_POLL_INTERVAL 2s Intervalle polling jobs
-ping-interval PRINT_AGENT_PING_INTERVAL 30s Intervalle heartbeat
-sync-interval PRINT_AGENT_SYNC_INTERVAL 10s Intervalle dΓ©tection imprimantes
-health-addr PRINT_AGENT_HEALTH_ADDR - Serveur health (ex: :8080)
-timeout - 30s Timeout HTTP
-verbose - false Logs dΓ©taillΓ©s
-dry-run - false Log jobs sans exΓ©cuter
-insecure - false DΓ©sactive vΓ©rification TLS
-disable-sse - false Force le mode polling (dΓ©sactive Mercure SSE)

Test local (sans imprimante)

printer run \
  -api-url https://localhost \
  -api-key $API_KEY \
  -api-secret $API_SECRET \
  -insecure \
  -dry-run \
  -verbose

Architecture

L'agent supporte deux modes de rΓ©cupΓ©ration des jobs :

Mode Event-Driven (SSE/Mercure) - RecommandΓ©

Si le serveur supporte Mercure, l'agent utilise Server-Sent Events pour recevoir les notifications en temps rΓ©el.

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                              SERVEUR (Symfony + FrankenPHP)                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
β”‚  β”‚   POS/App   │────▢│ PrintJob    │────▢│      Hub Mercure            β”‚   β”‚
β”‚  β”‚             β”‚     β”‚ Service     β”‚     β”‚  (FrankenPHP intΓ©grΓ©)       β”‚   β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
β”‚        β”‚                   β”‚                            β”‚                   β”‚
β”‚        β”‚              CrΓ©e job +                   SSE Push                 β”‚
β”‚        β”‚              Publie event             (notification)               β”‚
β”‚        β”‚                   β”‚                            β”‚                   β”‚
β”‚        β”‚                   β–Ό                            β”‚                   β”‚
β”‚        β”‚             β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                    β”‚                   β”‚
β”‚        β”‚             β”‚  Base de    β”‚                    β”‚                   β”‚
β”‚        β”‚             β”‚  donnΓ©es    β”‚                    β”‚                   β”‚
β”‚        β”‚             β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                    β”‚                   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”‚β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”‚β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚                    β”‚                           β”‚
         β”‚                    β”‚ GET /jobs/next            β”‚
         β”‚                    β”‚ (fetch complet)           β”‚
         β”‚                    β”‚                           β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”‚β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”‚β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚        β”‚                    β”‚                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”           β”‚
β”‚        β”‚                    └─────────────────────│  SSE Loop   │◀──────────│
β”‚        β”‚                                          β”‚  (Mercure)  β”‚           β”‚
β”‚        β”‚    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜           β”‚
β”‚        β”‚    β”‚  Dispatcher │◀────│  Poll Loop  β”‚β—€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β”‚
β”‚        β”‚    β”‚             β”‚     β”‚  (fallback) β”‚    notification            β”‚
β”‚        β”‚    β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                            β”‚
β”‚        β”‚           β”‚                                                        β”‚
β”‚        β”‚           β–Ό                                                        β”‚
β”‚        β”‚    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                                                 β”‚
β”‚        β”‚    β”‚ Imprimantes β”‚                                                 β”‚
β”‚        β”‚    β”‚ (USB/RΓ©seau)β”‚                                                 β”‚
β”‚        β”‚    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                                                 β”‚
β”‚                           AGENT (Go)                                        β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Flux :

  1. Le POS crΓ©e une vente β†’ PrintJobService crΓ©e un job en base
  2. PrintJobService publie une notification sur Mercure : {event: "new_job", job_id, type, printer_code}
  3. L'agent reΓ§oit la notification via SSE (connexion persistante)
  4. L'agent fait immΓ©diatement GET /jobs/next pour rΓ©cupΓ©rer le job complet
  5. Le job est exΓ©cutΓ© et acquittΓ© via POST /jobs/{id}/ack

SΓ©curitΓ© :

  • Chaque agent a un topic privΓ© : /printer-agent/{agent-id}/jobs
  • Le JWT Mercure restreint l'accΓ¨s au seul topic de l'agent
  • Seules les mΓ©tadonnΓ©es transitent par SSE (pas de donnΓ©es sensibles)
  • Le payload complet est rΓ©cupΓ©rΓ© via HTTPS (API REST)

Mode Polling (fallback)

Si Mercure n'est pas disponible ou dΓ©sactivΓ© (--disable-sse), l'agent poll l'API toutes les 2 secondes.

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                      β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚     SERVEUR     β”‚                      β”‚      AGENT      β”‚
β”‚                 β”‚  GET /jobs/next      β”‚                 β”‚
β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”   │◀─────────────────────│   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
β”‚   β”‚  Jobs   β”‚   β”‚       (2s)           β”‚   β”‚  Poll   β”‚   β”‚
β”‚   β”‚  Queue  β”‚   │─────────────────────▢│   β”‚  Loop   β”‚   β”‚
β”‚   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚    job ou null       β”‚   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
β”‚                 β”‚                      β”‚                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                      β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Comparaison

Event-Driven (SSE) Polling
Latence ~instantanΓ© 0-2s
Charge serveur Faible (1 connexion) Γ‰levΓ©e (requΓͺte/2s)
ComplexitΓ© Mercure requis Simple
Fallback Poll toutes les 30s -

Contrat API

Authentification

POST /api/authentication_token
Headers:
  X-Api-Key: <apiKey>
  X-Api-Secret: <apiSecret>

Response:
{
  "token": "eyJ...",
  "expires_in": 3600,
  "expires_at": 1767972859,
  "type": "printer_agent",
  "agent": {
    "id": "01KEHJ71KY45DBZZAFY67XJBC9",
    "name": "Poste 1",
    "store": "Magasin principal"
  },
  "mercure": {
    "token": "eyJ...",
    "url": "https://example.com/.well-known/mercure",
    "topic": "/printer-agent/01KEHJ71KY45DBZZAFY67XJBC9/jobs"
  }
}

mercure est optionnel. PrΓ©sent uniquement si le serveur supporte Mercure SSE.

Heartbeat

POST /api/printer-agent/ping
Headers:
  Authorization: Bearer <token>
Body: {}

β†’ 200 OK

RΓ©cupΓ©rer le prochain job

GET /api/printer-agent/jobs/next
Headers:
  Authorization: Bearer <token>

Query params (optionnels):
  - type: receipt | label | sticker_image
  - printer_code: code imprimante spΓ©cifique
  - lease_duration: durΓ©e lease en secondes (dΓ©faut 60)

Response (job disponible):
{
  "success": true,
  "data": {
    "job_id": "01KXXX...",
    "lease_id": "uuid-du-lease",
    "lease_until": "2026-01-09T15:30:00+00:00",
    "type": "receipt",
    "payload": { ... },
    "retry_count": 0,
    "printer": {
      "code": "USB001",
      "name": "EPSON TM-T20",
      "type": "receipt"
    }
  }
}

Response (aucun job):
{
  "success": true,
  "data": null
}

Confirmer un job

POST /api/printer-agent/jobs/{jobId}/ack
Headers:
  Authorization: Bearer <token>
Body:
{
  "lease_id": "uuid-du-lease",
  "success": true,
  "error_message": ""
}

β†’ 200 OK

Synchroniser les imprimantes

POST /api/printer-agent/printers
Headers:
  Authorization: Bearer <token>
Body:
{
  "printers": [
    {
      "code": "epson-receipt",
      "name": "EPSON TM-T20III",
      "type": "receipt",
      "description": "/dev/usb/epson_tmt20iii"
    }
  ]
}

Types valides: receipt, label, a4

Response:
{
  "success": true,
  "data": {
    "created": 1,
    "updated": 0,
    "removed": 0,
    "total": 1
  }
}

Payloads par type de job

receipt (ticket de caisse)

{
  "barcode": "POS-20260109-001",
  "items": [
    {
      "name": "Livre neuf",
      "quantity": 2,
      "unit_price": "12.50"
    },
    {
      "name": "Carnet A5",
      "quantity": 1,
      "unit_price": "4.90"
    }
  ],
  "payments": ["Carte bancaire", "Espèces"],
  "store_address_1": "Mon Magasin",
  "store_address_2": "123 Rue du Commerce, 75001 Paris",
  "store_phone": "01 23 45 67 89",
  "store_vat": "BE 1234.567.890",
  "store_social": "@monmagasin",
  "store_website": "www.monmagasin.fr"
}
Champ Type Requis Description
barcode string Oui Code-barres imprimΓ© en bas du ticket
items array Oui Liste des articles
items[].name string Oui Nom (max 22 caractères affichés)
items[].quantity int Oui QuantitΓ©
items[].unit_price string Oui Prix unitaire (ex: "12.50")
payments string[] Non Modes de paiement
store_address_1 string Non Ligne 1 adresse
store_address_2 string Non Ligne 2 adresse
store_phone string Non TΓ©lΓ©phone
store_vat string Non NumΓ©ro TVA
store_social string Non RΓ©seaux sociaux
store_website string Non Site web

Le total est calculΓ© automatiquement. La date/heure est prise Γ  l'impression. Les champs store_* peuvent Γͺtre configurΓ©s via variables d'environnement.

label (Γ©tiquette prix)

{
  "name": "Livre - Les MisΓ©rables",
  "price_text": "19.99 €",
  "barcode": "3760123456789",
  "footer": "Occasion - Bon Γ©tat"
}
Champ Type Requis Description
name string Oui Nom du produit
price_text string Oui Prix formatΓ© avec devise
barcode string Oui Code-barres EAN/ISBN
footer string Non Texte additionnel

sticker_image (image)

{
  "image_url": "https://example.com/image.png"
}

ou

{
  "image_data": "iVBORw0KGgo..."
}
Champ Type Requis Description
image_url string Oui* URL de l'image
image_data string Oui* Image en base64

*Un des deux requis. image_data prioritaire si les deux prΓ©sents.

Formats: PNG, JPEG, GIF, WebP. Taille max: 10 Mo.

open_drawer (tiroir-caisse)

{}

Payload vide.


Mode CLI

Commandes pour tests manuels ou intΓ©gration scripts.

DΓ©tecter les imprimantes

printer detect

Imprimer un ticket test

printer receipt-test --device /dev/usb/epson_tmt20iii --logo /path/logo.png

Ouvrir le tiroir-caisse

printer open-drawer --device /dev/usb/epson_tmt20iii

Imprimer une Γ©tiquette prix

printer label "Livre" "12.90 €" 9781234567890 --footer "Chapitre Neuf"

Imprimer un sticker adresse

printer sticker-address "Chapitre Neuf" "21 Avenue des Combattants" "1370 Jodoigne"

Imprimer une image

printer sticker-image ./path/to/image.png

Variables d'environnement

Agent

Variable Description
PRINT_AGENT_API_URL URL de l'API
PRINT_AGENT_API_KEY ClΓ© API
PRINT_AGENT_API_SECRET Secret API
PRINT_AGENT_POLL_INTERVAL Intervalle polling (ex: 2s)
PRINT_AGENT_PING_INTERVAL Intervalle ping (ex: 30s)
PRINT_AGENT_SYNC_INTERVAL Intervalle sync (ex: 10s)
PRINT_AGENT_HEALTH_ADDR Adresse health server

Imprimantes

Variable Description
RECEIPT_PRINTER_DEVICE Device imprimante ticket
RECEIPT_LOGO_PATH Logo pour tickets
STORE_ADDRESS_LINE1 Adresse ligne 1
STORE_ADDRESS_LINE2 Adresse ligne 2
STORE_PHONE TΓ©lΓ©phone
STORE_VAT_NUMBER NumΓ©ro TVA
STORE_SOCIAL_HANDLE RΓ©seaux sociaux
STORE_WEBSITE Site web
PYTHON_PATH Chemin Python
LABEL_SCRIPT_PATH Script Γ©tiquettes
STICKER_SCRIPT_PATH Script stickers

Test sans imprimante

Tickets et tiroir (ESC/POS vers fichier)

RECEIPT_PRINTER_DEVICE=/tmp/receipt.bin printer receipt-test
printer open-drawer --device /tmp/drawer.bin

Γ‰tiquettes (mock brother_ql)

export PATH="$(pwd)/scripts:$PATH"
chmod +x scripts/mock_brother_ql.sh
ln -sf mock_brother_ql.sh scripts/brother_ql
printer label "Test" "9.99 €" 1234567890123

Health Server

Si -health-addr est configurΓ©, l'agent expose :

  • GET /health - Statut (healthy/degraded)
  • GET /metrics - Compteurs jobs/imprimantes
  • GET /status - Statut combinΓ© local + serveur