API et module hors ligne

L'API REST#

La plateforme expose une API sous /api/v1. Elle sert d'abord au module hors ligne, et peut servir à d'autres outils de l'organisation. Elle passe par les mêmes services que le site, donc par les mêmes règles : rôle du compte, périmètre géographique, paramètre « saisie par les organisations », montants masqués selon le rôle.

Les erreurs sont au format ProblemDetails (JSON) ; les énumérations sont écrites en texte (par exemple "Realisee").

Points d'accès#

La description complète (OpenAPI) est servie sur /api/v1/openapi.json, aux comptes connectés seulement (par le site ou par jeton).

Jetons#

1. Le client obtient ses jetons par POST /api/v1/jetons avec l'identifiant et le mot de passe d'un compte :

   Copier

   { "identifiant": "personne@example.org", "motDePasse": "…", "appareil": "Téléphone de terrain 3" }

2. Il reçoit un jeton d'accès (jetonAcces, valable expireDansSecondes) à présenter dans l'en-tête Authorization: Bearer <jeton>, et un jeton de renouvellement (jetonRenouvellement, valable jusqu'à renouvellementExpireLe).
3. Avant l'expiration du jeton d'accès, il échange le jeton de renouvellement contre un nouveau couple (/api/v1/jetons/renouveler).

Sécurité des jetons :

• la zone /api n'accepte que les jetons, jamais le cookie du site ;
• le jeton de renouvellement est à usage unique et seule son empreinte est enregistrée en base ;
• un jeton de renouvellement présenté une seconde fois au-delà du délai de rejeu est considéré comme volé : tous les jetons de l'appareil sont révoqués ;
• le compte est revérifié à chaque appel : désactivation, changement de rôle ou de mot de passe coupent l'accès aussitôt ;
• les connexions par l'API sont inscrites au journal d'audit (canal « api ») et comptent dans les statistiques.

Les jetons expirés ou révoqués depuis plus de 30 jours sont supprimés par la tâche quotidienne.

Le module hors ligne#

Le module (/terrain/) est une application WebAssembly installable (PWA), servie par la plateforme elle-même. Il est réservé aux comptes qui saisissent : l'équipe projet, et les organisations quand l'administrateur a ouvert la saisie aux organisations.

Ce qui est stocké sur le téléphone#

• l'application elle-même, en cache (service worker) : seules les adresses de /terrain/ passent par ce cache, l'API va toujours au réseau ;
• dans le stockage du navigateur (IndexedDB) : le profil, les listes de saisie, les activités à rapporter (au plus 500 : sans rapport, non annulées, commençant dans les 30 jours ou terminées depuis 90 jours au plus), les brouillons de rapport et le jeton de renouvellement. Le jeton d'accès reste en mémoire seulement.

Les rapports validés sont retirés du téléphone 30 jours après leur validation. Se déconnecter de ce téléphone révoque les jetons sur la plateforme puis les efface de l'appareil.

Synchronisation#

L'envoi n'a lieu que module ouvert : au démarrage, au retour du réseau, toutes les 5 minutes tant que des rapports attendent, et sur Synchroniser maintenant. Un rapport envoyé deux fois (réponse perdue sur un réseau instable) n'est jamais dupliqué : la plateforme reconnaît son identifiant et renvoie le rapport existant.

Mise à jour du module#

Un déploiement de la plateforme publie aussi la nouvelle version du module. Sur chaque téléphone :

1. à la connexion suivante avec du réseau, le service worker télécharge la nouvelle version ;
2. le module affiche « Une nouvelle version du module est prête. » et le bouton Mettre à jour (les saisies en cours sont enregistrées d'abord) ;
3. sans action de l'utilisateur, la nouvelle version s'active quand tous les onglets du module sont fermés.

Les fichiers du module sont servis avec Cache-Control: no-cache : le navigateur revérifie toujours la version disponible.