Documentation J+SERVICES Guides Référence API

Contrat API — Résolution Data-Plane des Ports d’Accès

Dernière mise à jour : 26 Septembre 2026

Ce document est normatif. Il définit comment l’application mobile doit obtenir les ports de redirection publics d’un routeur (la “matrice de ports”) lorsqu’elle tente de s’y connecter, notamment en mode délégué (technicien).

1. Topologie des ports

Deux familles de ports coexistent, et les confondre est l’erreur la plus fréquente :

   App  ──────►  vpn.mikhmoai.com : 23000        ──────►  routeur : 22
                 └── vpnRedirection.ssh_port              └── local_ports.ssh
                     (port PUBLIC sur le relais)              (port NATIF du routeur)

2. GET /api/v1/clients/remote-access/ports

Requête

Paramètre Requis Rôle
router_serial ✅ numéro de série du routeur (alias acceptés : router_sn, sn)
port — un port de redirection connu/actif du routeur. Requis en cas de routeurs virtuels (CHR) ou d’accès partagé (§3). Alias : current_port, active_port 
GET /api/v1/clients/remote-access/ports?router_serial=HXX0EXEMPLE01
GET /api/v1/clients/remote-access/ports?router_serial=HXX0EXEMPLE01&port=17000

Réponse — succès

{
  "success": true,
  "data": {
    "found": true,
    "online": true,
    "router_serial": "HXX0EXEMPLE01",

    // Si le routeur est sur une passerelle de secours tierce (ex: Back To Home)
    "is_third_party_gateway": false,

    "ports": {
      "public_host": "vpn.mikhmoai.com",
      "webfig_port": 17000,
      "rest_port": 17000,
      "winbox_port": 19000,
      "api_port": 22000,
      "ssh_port": 23000,

      // Injectés automatiquement si is_third_party_gateway: true
      "vpn_dns_name": "xyz123.sn.mynetname.net",
      "vpn_port": 12345,
    },

    "local_ports": { "webfig": 8081, "winbox": 8291, "api": 8728, "ssh": 22 },
    "urls": {/* URLs prêtes à ouvrir */},
  },
}

Réponse — Routeur non provisionné / Refus silencieux

HTTP 200, retourné quand le SN n’existe pas, ou quand l’appelant n’est ni propriétaire ni porteur d’une preuve de délégation (mauvais port).

{
  "success": true,
  "data": {
    "found": false,
    "online": false,
    "router_serial": "…",
    "message": "Aucun équipement provisionné pour ce numéro de série.",
  },
}

Erreurs

Code HTTP Cause
ROUTER_SERIAL_REQUIRED 400 router_serial absent ou vide
AMBIGUOUS_ROUTER_CLONES 409 Plusieurs routeurs virtuels (CHR) partagent ce numéro de série. Vous DEVEZ fournir un port pour désambiguïser.

3. Clé de Sécurité : La preuve par le Port & Désambiguïsation

L’accès à cette route est conditionné par un principe fort : [Numéro de Série + 1 Port Connu] = La Clé d’Accès.

A. Le Partage Délégué (Techniciens)

Quand un client partage sa passerelle avec un technicien, l’application ne transmet ni compte ni adresse e-mail. Le serveur refuse de lui donner la liste des ports s’il ne prouve pas son accès. Règle d’implémentation : Envoyez le paramètre port= dès que vous l’avez. Le fait de posséder un port de redirection actif prouve que le propriétaire vous a donné l’accès.

B. Le Cas des Routeurs Virtuels (CHR)

Lors du clonage de VM (Cloud Hosted Routers), plusieurs routeurs J+SERVICES peuvent partager le même numéro de série. Si l’application appelle l’API sans port, le serveur ne saura pas quelle VM vous essayez de joindre et renverra une erreur 409 Conflict. L’injection du port= lève l’ambiguïté de façon instantanée.

4. Ce que le serveur garantit (Arrière-plan)

5. Pièges à éviter