Contrat API — Résoudre un routeur → sa boutique (pré-détection éditeur)

Date : 2026-10-26 · Pour : dev Éditeur Portail / PWA · API : https://live.jmoai.net

1. À quoi ça sert

Dès qu’un routeur physique est branché, l’éditeur peut détecter automatiquement le propriétaire et sa boutique à partir du numéro de série (ou d’un nasid à suffixe unique -TM<n>), sans demander d’identifiant technique au gérant.

C’est la réponse à la Demande #3, version sûre : la route est protégée (jamais publique) et en lecture seule.

2. Endpoint

GET /api/v1/clients/store/resolve?serial=HEW0975P75W
GET /api/v1/clients/store/resolve?nasid=hotspot1-TM1390
Authorization: Bearer <JWT éditeur (scope portal_editor) ou jeton client>   (ou x-admin-token)

Auth OBLIGATOIRE. Aucune résolution anonyme (anti-énumération). L’éditeur utilise son JWT issu du handshake. Débit limité (actionLimiter). Chaque appel est audité.
Lecture seule : aucune écriture, aucun sondage du routeur (réponse immédiate).

3. Paramètres

Param	Obligatoire	Note
`serial`	l’un des deux	recommandé — clé physique forte. Résout l’allocation ACTIVE de ce serial.
`nasid`	l’un des deux	résout uniquement s’il porte le suffixe unique `-TM<n>` (ex. `…-TM1390`). Un `nasid` simple (« hotspot1 », « MoailtePro ») est NON unique → `404`.

Au moins un des deux est requis, sinon 400 RESOLVE_PARAM_REQUIRED.

4. Réponse `200`

{
  "success": true,
  "data": {
    "client_id": "client_afced2751f05479f86ce2cc4d9ac0b29",
    "store_slug": "bocar-daouda-deme-client-a",
    "store_name": "Bocar Daouda",
    "is_aligned": true
  }
}

is_aligned = contrôle léger (sans sonder le routeur) : vrai quand l’allocation a des identifiants API stockés et une boutique (slug) et un nas_id. Faux = il reste à aligner (voir CONTRAT-API-ALIGNEMENT-ROUTEUR-TECHNICIEN).

5. Erreurs (dans `error.code`)

HTTP	`error.code`	Sens
401	`UNAUTHORIZED`	Pas de jeton valide (jamais public)
400	`RESOLVE_PARAM_REQUIRED`	Ni `serial` ni `nasid` fourni
404	`ROUTER_NOT_FOUND`	Aucune allocation active pour ce serial / nasid-unique (générique, pas de fuite)

6. Enchaînement typique côté éditeur

Routeur branché → lire son serial (live probe).
GET /clients/store/resolve?serial=… → client_id + store_slug + store_name + is_aligned.
Si is_aligned=false → proposer l’alignement via POST /clients/technique/align-router (email + identifiants routeur) — voir CONTRAT-API-ALIGNEMENT-ROUTEUR-TECHNICIEN.
Charger l’éditeur avec GET /clients/portal-editor/bootstrap (qui renvoie désormais client_id, store_name, webhook_token).