Contrat API editeur de portail TiketMOMO

Authentification

L’editeur appelle les routes avec Authorization: Bearer <token>. Le token est emis par GET /api/v1/clients/portal-editor/handshake, expire en 30 minutes, porte scope: "portal_editor" et est resolu comme une identite client liee.

Bootstrap

GET /api/v1/clients/portal-editor/bootstrap

La reponse conserve tous les champs existants (router, profiles, offers, editorConfig, editorConfigPersisted, importedAt) et ajoute :

{
  "store_slug": "demo-store",
  "router_state": {
    "mode": "ONLINE",
    "source": "ROUTER_LIVE",
    "read_at": "2026-09-29T12:00:00.000Z",
    "allocation_id": "8076cbf5-2a96-4263-8758-73d4aaf04eaa",
    "reason": null
  },
  "router_facts": {
    "serial": "HH40AF7YVNP",
    "identity": "MikroTik",
    "model": "hAP ax3",
    "routeros_version": "7.19.6",
    "mac": "AA:BB:CC:DD:EE:FF"
  },
  "nas_facts": {
    "declared_nas_name": "TM-950",
    "hotspot_servers": ["TM-950"],
    "dns_name": "demo.hotspot.local",
    "local_ip": "192.168.88.1",
    "profiles": [
      {
        "name": "100F-4H",
        "price": 100,
        "timelimit": "4h",
        "validity": null,
        "data_limit": null,
        "voucher_format": null
      }
    ]
  }
}

Modes :

mode	source	Sens
`ONLINE`	`ROUTER_LIVE`	Les profils ont ete lus directement sur le routeur.
`OFFLINE_CACHED`	`DATABASE_CACHE`	Le routeur est injoignable, les profils viennent du cache de l’allocation.
`OFFLINE_CACHED`	`NAS_DECLARATION`	Le routeur est injoignable et aucun cache profils n’existe ; la derniere declaration NAS fait foi.
`MANUAL_REQUIRED`	`NONE`	Le routeur est injoignable, sans cache et sans declaration NAS.
`NO_ROUTER`	`NONE`	Aucune allocation routeur n’est connue pour ce vendeur.

read_at est l’heure de lecture directe pour ROUTER_LIVE, l’heure connue du cache pour DATABASE_CACHE, et nas_declaration.declared_at pour NAS_DECLARATION.

La lecture directe des profils hotspot ne vaut ONLINE que si le routeur renvoie une liste non vide. Une liste vide ([]) est traitee comme un routeur non joignable, exactement comme une erreur transport : le bootstrap bascule alors vers le cache base, puis vers la derniere declaration NAS, puis vers MANUAL_REQUIRED.

store_slug reprend le slug de boutique charge par le bootstrap, ou null s’il est inconnu. router_facts contient uniquement serial, identity, model, routeros_version et mac : lecture directe quand router_state.mode vaut ONLINE, sinon metadata.router_facts, sinon les verrous routeur de l’allocation quand ils existent. Une valeur inconnue reste null.

nas_facts vient de la derniere declaration NAS stockee sur l’allocation. hotspot_servers vaut [] si la declaration ne les connait pas. profiles reprend store_settings.sales_profiles avec les seules cles name, price, timelimit, validity, data_limit et voucher_format.

Aucun de ces objets ne transporte de secret : pas de mot de passe routeur, pas de cle API, pas de jeton.

Declaration NAS depuis l’editeur

L’editeur reutilise la route existante :

POST /api/v1/clients/tiketmomo/nas-declaration

Il n’existe pas de voie parallele. declaration_id est idempotent : rejouer le meme identifiant renvoie la reponse deja stockee sans reecrire l’etat.

Exemple complet :

{
  "allocation_id": "8076cbf5-2a96-4263-8758-73d4aaf04eaa",
  "declaration_id": "portal-editor-2026-09-29T12:00:00.000Z",
  "declared_at": "2026-09-29T12:00:00.000Z",
  "store_slug": "demo-store",
  "router": {
    "serial": "HH40AF7YVNP",
    "identity": "MikroTik",
    "model": "hAP ax3",
    "routeros_version": "7.19.6",
    "mac": "AA:BB:CC:DD:EE:FF"
  },
  "nas": {
    "declared_nas_name": "TM-950",
    "hotspot_servers": ["TM-950"],
    "local_ip": "192.168.88.1",
    "dns_name": "demo.hotspot.local",
    "walled_garden_present": true
  },
  "profiles": [
    {
      "name": "100F-4H",
      "price": 100,
      "timelimit": "4h",
      "data_limit": null,
      "commercial": true
    }
  ]
}

Les declarations acceptees sont stockees sur remote_access_allocations.metadata : last_declared_at, nas_declaration et router_facts.

Walled garden manuel

GET /api/v1/clients/tiketmomo/walled-garden-script

Retourne le script RouterOS manuel a coller quand le backend ne peut pas joindre le routeur. La route reste protegee par la meme chaine client que la declaration NAS.

Erreurs

Erreurs transport habituelles : 401 token manquant, expire ou invalide ; 403 role interdit ou identite non provisionnee ; 400 validation de corps invalide.

La declaration NAS renvoie les decisions metier en 200 avec status : ALIGNED, RECONCILED ou REFUSED. Meme en REFUSED, le statut HTTP reste 200 ; le client lit status pour distinguer la decision. Un refus porte code, message et parfois details.