Contrat API — tickets RADIUS désignés par leur username (2026-10-01)

Réponse à la note MV7 « Suspension de vouchers RADIUS depuis la liste des utilisateurs actifs ». L’écran « Utilisateurs actifs » ne connaît que le username : toutes les actions de cycle de vie passent désormais par le backend, jamais directement par le MikroTik.

Toutes les routes : Authorization: Bearer <jeton client>, licence RADIUS active. Un username inconnu ou appartenant à un autre gérant renvoie 404 VOUCHER_NOT_FOUND.

1. Bloquer / débloquer — route existante étendue

PUT /api/v1/radius/vouchers/block/bulk

{ "usernames": ["TM-1234", "KVA-5678"], "action": "SUSPEND" }

voucher_ids ou usernames (tableau non vide, 1000 max), jamais les deux → sinon 400.
action : SUSPEND, SUSPENDRE, BLOQUER, BLOCK (statut DISABLED, compte retiré de RADIUS → Access-Reject à la prochaine tentative) ou ACTIVATE, ACTIVER, REACTIVER, DEBLOQUER, UNBLOCK (réactivation). La casse et les accents sont ignorés. Toute autre valeur renvoie 400 RADIUS_BULK_ACTION_INVALID avec la liste acceptée.
Après une suspension réussie, les sessions ouvertes de ces tickets sont coupées (PoD).

Réponse :

{
  "updated": 1,
  "status": "DISABLED",
  "introuvables": ["KVA-5678"],
  "deconnexions": [{ "username": "TM-1234", "nas": "10.255.0.15", "ok": true }]
}

introuvables : noms qui ne correspondent à aucun ticket de ce gérant.
deconnexions[].ok = false : la coupure n’a pas été acquittée par le routeur. La suspension reste effective (la reconnexion sera refusée) ; l’app peut proposer « Expulser » en plus.
502 RADIUS_SUSPENSION_ECHEC : le serveur RADIUS n’a pas pu retirer le compte, rien n’a été modifié. Ne PAS se rabattre sur un kick local : il ne bloque pas.

2. Routes unitaires par username

Méthode	Route	Effet
`POST`	`/api/v1/radius/vouchers/username/:username/suspend`	Comme `block/bulk` SUSPEND, pour un ticket
`POST`	`/api/v1/radius/vouchers/username/:username/unsuspend`	Réactive un ticket `DISABLED` (republié avec ses limites)
`DELETE`	`/api/v1/radius/vouchers/username/:username`	Suppression définitive + PoD des sessions ouvertes
`POST`	`/api/v1/radius/vouchers/username/:username/reset-mac`	Délie l’appareil (quota : 5/min)
`GET`	`/api/v1/radius/vouchers/username/:username`	État du ticket (ci-dessous)

suspend / unsuspend renvoient la même forme que block/bulk. unsuspend ne réactive qu’un ticket suspendu : un ticket épuisé reste épuisé (updated: 0).

`GET …/username/:username`

{
  "id": "28ce32d6-…",
  "username": "Pw445",
  "status": "USED",
  "premiere_connexion": "2026-09-23T11:07:30Z",
  "expiration": "2026-09-26T11:07:30.000Z",
  "expire": true,
  "duree_achetee_secondes": 345600,
  "temps_restant_secondes": null,
  "octets_consommes": 10700000000,
  "octets_restants": null,
  "derniere_activite": "2026-09-24T15:37:30Z",
  "mac_liee": "DE:4F:A0:D7:DE:1A",
  "sessions_actives": [
    { "nas": "10.255.0.121", "mac": "DE:4F:…", "ip": "10.100.90.240", "debut": "…" }
  ]
}

expiration = la plus proche entre la fin de validité (1re connexion + validité du forfait) et la date d’expiration d’achat. null = aucune limite calendaire.
octets_restants : null si le forfait n’a pas de limite de volume, ou si le serveur RADIUS n’a pas répondu (octets_consommes est alors null aussi).
⚠️ temps_restant_secondes est toujours null pour l’instant : le serveur ne fournit pas encore le temps cumulé de toutes les sessions. Ne pas l’afficher comme « 0 ».