Contrat API — profils RADIUS et FUP

Base : /api/v1/radius. Les routes exigent une authentification client liée, une licence J+RADIUS active et un NAS principal actif.

Créer ou modifier un profil

POST /profiles crée un profil (ou actualise le même nom pour ce client). PUT /profiles/:profileId applique une modification partielle.

{
  "name": "Premium",
  "speed_down_kbps": 4096,
  "speed_up_kbps": 1024,
  "shared_users": 2,
  "duration_minutes": 1440,
  "data_limit_mb": 10240,
  "fup_enabled": true,
  "fup_limit_mb": 5120,
  "fup_speed_down_kbps": 512,
  "fup_speed_up_kbps": 128,
  "price_xof": 1000
}

speed_* et shared_users sont le forfait normal, porté par le groupe RADIUS privé. duration_minutes et data_limit_mb restent individuels à chaque ticket. data_limit_mb coupe au plafond ; il est distinct du seuil FUP.

FUP

Quand fup_enabled vaut true, les trois champs fup_limit_mb, fup_speed_down_kbps et fup_speed_up_kbps sont obligatoires, entiers positifs. Les débits FUP ne peuvent pas dépasser les débits normaux et doivent réduire au moins l’un des deux.

Pour le désactiver :

{ "fup_enabled": false }

Le serveur efface alors seuil et débits FUP du profil. Il refuse 400 avec l’un des codes RADIUS_FUP_FIELDS_REQUIRED, RADIUS_FUP_BASE_SPEED_REQUIRED, RADIUS_FUP_SPEED_NOT_REDUCED ou RADIUS_FUP_INVALID si la politique est incohérente.

Chaque ticket fige la politique FUP à sa création. Une modification du profil ne change donc que les futurs tickets ; une ancienne vente n’est jamais réécrite silencieusement. Dès que sa consommation RADIUS atteint le seuil, le serveur :

écrit le débit réduit sur le ticket (Mikrotik-Rate-Limit, qui prime sur les WISPr-Bandwidth-* du profil) — une reconnexion retrouve donc ce débit ;
envoie une CoA (Mikrotik-Rate-Limit, UDP 3799) à chaque session active : le débit change sans coupure, la session Hotspot reste active ;
en repli seulement, si le routeur n’acquitte pas la CoA (/radius incoming désactivé, port 3799 fermé), envoie un Disconnect : le client se réauthentifie au débit réduit.

Le moyen employé est tracé sur le ticket (radius_fup_mode : COA, DISCONNECT ou SANS_SESSION). DISCONNECT signale un routeur à régler depuis l’application. Un échec des deux est journalisé et repris : il n’est jamais annoncé comme un FUP appliqué.

Déviations intentionnelles

Les noms historiques fup_limit_mb et fup_speed_* sont désormais le contrat. Les champs RADIUS bruts et le nom de groupe ne sont jamais fournis par l’application. Le groupe ne porte pas le FUP : un seuil est individuel, donc il vit sur le ticket.

Synchronisation depuis un NAS Hotspot

POST /nas/:nasId/profile-sync relit les profils Hotspot et les schedulers du routeur lié. Il met à jour les profils RADIUS correspondants sans modifier les tickets, les sessions ni les comptes Hotspot locaux. Le bouton peut envoyer { "force": true }.

Le serveur rejoue automatiquement cette opération toutes les dix minutes pour les NAS actifs. Une empreinte évite les écritures inutiles. Les changements de débit, partage, validité et volume sont repris. Un scheduler FUP dont le seuil n’est pas déterminable sans ambiguïté est conservé en diagnostic REVIEW_REQUIRED, jamais transformé en politique RADIUS inventée. Si le scheduler est illisible, les profils sont quand même synchronisés et le FUP de chaque profil est rapporté UNREADABLE (mesure indisponible, pas « aucun FUP »).

Réponse indicative :

{
  "success": true,
  "nas_id": "uuid",
  "changed": true,
  "profiles_seen": 4,
  "profiles_updated": 4,
  "fup_review_required": ["FUP-130F-1gb-24h"]
}

Cette route synchronise le catalogue. L’application doit afficher le diagnostic FUP et demander une validation lorsque le routeur encode le seuil uniquement dans un script customisé.