Aller au contenu
GS-Apps

API — api-portail

Vous êtes ici : Référence — la porte publique de la suite (api-portail). Les endpoints réellement montés d’api-portail (portail.groupesignalisation.ca). Lecture 6 min. Audience : devs, intégrateurs internes. Date : 2026-07-07 | Version : 1.0 — remplace le stub ; inventaire par analyse statique du code (juillet 2026)

TL;DR

Section intitulée « TL;DR »
Question Réponse
Surface publique ? GET /p/:qrCode (scan, HTML SSR) + GET /health / GET /ready
Tout le reste ? Authentifié — cookie de session (flow OIDC /admin/login) ou Bearer JWT Entra, rôle ADMIN ou GESTIONNAIRE requis
D’où viennent les rôles ? De la BD (ug.UserCompanyBcRoles, module Portail) — pas des groupes Entra
Format ? HTML SSR pour les pages, JSON pour /api/*, PDF binaire pour les planches QR

La surface en une image

Section intitulée « La surface en une image »

Deux zones, une seule publique. La surface publique (rouge) répond sans authentification ; tout le reste est derrière une porte — cookie de session ou Bearer JWT, plus le rôle ADMIN ou GESTIONNAIRE résolu en base.

La surface d’api-portail — zone publique et zone admin derrière une porteÀ gauche, la zone publique d’api-portail, sans authentification : la page de scan GET /p/:qrCode et les sondes /health et /ready. À droite, la zone admin : toutes les autres routes passent d’abord par une porte d’authentification (cookie de session ou Bearer JWT, plus un rôle ADMIN ou GESTIONNAIRE résolu en base), puis atteignent les routes de gestion des stickers, batches, véhicules et réattribution. Les deux zones lisent la base Azure SQL ; la zone publique n’y lit que des colonnes non personnelles.ZONE PUBLIQUEaucune authentificationGET /p/:qrCodescan · SSR · non-PIIGET /health · /readyrate-limit par IPLA PORTEsession cookieOU Bearer JWT (JWKS)+ rôle ADMIN /GESTIONNAIRE (BD)sinon → 401 / 403fail-closedZONE ADMINgestion authentifiéestickers · batches (PDF)véhicules · réattributionlogin OIDC · callbackJSON · SSR · PDFtout chemin non listé → 404 · corps JSON ≤ 64 kb, validé (Zod / motif QR)
La surface d’api-portail : une zone publique sans compte, tout le reste derrière la porte d’authentification. Détail des routes ci-dessous.

Principes

Section intitulée « Principes »
  • Deux modes d’authentification pour l’admin : un cookie de session (httpOnly, 8 h) posé par le flow OIDC Authorization Code + PKCE, ou un Bearer JWT Entra validé par JWKS (signature, audience, issuers v1/v2). Les routes d’administration exigent le rôle ADMIN ou GESTIONNAIRE, résolu en base (Système C — voir Modèle d’accès).
  • Fail-closed : utilisateur sans rôle → 403 ; contexte compagnie manquant → refus. La page publique de scan lit sous un contexte public restreint (aucune PII — voir Sécurité).
  • Rate limiting : la surface publique de scan et la porte de login sont limitées par IP.
  • Corps JSON limité à 64 kb ; toute entrée est validée (Zod ou motif strict QR-#####).

Surface publique

Section intitulée « Surface publique »
Endpoint Réponse Description
GET /p/:qrCode HTML SSR La page de scan (CNESST) : fiche véhicule bilingue du sticker QR-#####, données non-PII uniquement. Si le sticker n’est pas attribué et qu’une session admin/gestionnaire est présente, la page d’attribution s’affiche à la place.
GET /health JSON Liveness — statut, app, version.
GET /ready JSON Readiness — ping base de données (503 si indisponible).

Tout autre chemin non listé répond 404. Il n’y a pas de route /api/version dans cette app.

Authentification admin (OIDC)

Section intitulée « Authentification admin (OIDC) »
Endpoint Réponse Description
GET /admin/login 302 Démarre le flow OIDC Authorization Code + PKCE vers Entra ID (client public, sans secret). Paramètre next borné aux chemins relatifs.
GET /admin/callback 302 Échange le code, résout l’identité et le rôle en base ; refuse si aucun rôle ou rôle insuffisant ; pose le cookie de session.
GET /admin/logout 302 Efface le cookie de session.

API admin — stickers QR

Section intitulée « API admin — stickers QR »

Toutes les routes ci-dessous exigent session ou Bearer + rôle ADMIN/GESTIONNAIRE + contexte compagnie.

Endpoint Réponse Description
GET /api/admin/stickers/ JSON paginé Liste des stickers — filtre etat (all / attributed / reserve), recherche plaque/QR/description, limit ≤ 200.
GET /api/admin/stickers/:qrCode JSON Détail d’un sticker (+ véhicule joint le cas échéant).
POST /api/admin/stickers/:qrCode/attribute JSON Attribue un sticker libre à un véhicule (entity_type: 'VEHICLE', entity_id UUID) — 409 si déjà attribué.
POST /api/admin/stickers/:qrCode/unattribute JSON Désattribue un sticker.
GET /api/admin/stickers/sequence JSON État de la séquence — prochain numéro QR-#####.
GET /api/admin/stickers/batches JSON paginé Liste des batches de planches QR.
POST /api/admin/stickers/batches PDF Crée un batch de count codes (1–500, purpose optionnel) et retourne la planche PDF (id du batch en en-tête).
GET /api/admin/stickers/batches/:batchId/pdf PDF Régénère et télécharge la planche d’un batch existant.

API admin — véhicules et réattribution

Section intitulée « API admin — véhicules et réattribution »
Endpoint Réponse Description
GET /admin/api/vehicles?q=… JSON Autocomplete des véhicules actifs (référentiel dim), limit ≤ 50.
GET /admin/reassign?qr=QR-##### HTML SSR Page de confirmation de réattribution d’un sticker.
POST /admin/api/reassign-step1 302 Étape 1 : désattribue le sticker puis redirige vers /p/:qr où la page d’attribution prend le relais.

Pour aller plus loin

Section intitulée « Pour aller plus loin »