Contrat API - préférences client

Les préférences Mikhmon/PWA sont rattachées au compte authentifié. Le PHP appelle ces routes avec le jeton utilisateur déjà utilisé pour GET /api/v1/clients/store-access.

Routes

GET `/api/v1/clients/preferences/:app`

app vaut mikhmon ou pwa.

Réponse sans préférences enregistrées :

{
  "success": true,
  "data": {
    "app": "mikhmon",
    "prefs": {},
    "updated_at": null
  }
}

PUT `/api/v1/clients/preferences/:app`

Le corps contient uniquement les clés à modifier. La fusion est partielle au premier niveau ; une valeur null supprime la clé.

{
  "prefs": {
    "theme": "dark",
    "themecolor": "#0af",
    "lang": "fr",
    "last_router": "rb5009",
    "ui": {
      "sidebar": "compact",
      "tickets.pageSize": 50
    }
  }
}

Réponse :

{
  "success": true,
  "data": {
    "app": "mikhmon",
    "prefs": {
      "theme": "dark",
      "themecolor": "#0af",
      "lang": "fr",
      "last_router": "rb5009",
      "ui": {
        "sidebar": "compact",
        "tickets.pageSize": 50
      }
    },
    "updated_at": "2026-10-11T10:00:00.000Z"
  }
}

Pour pwa, seule la clé ui est acceptée.

Erreurs

400 PREFERENCES_APP_INVALID : application hors liste blanche.
400 PREFERENCES_KEY_INVALID : clé de premier niveau inconnue, ou clé ui invalide.
400 PREFERENCES_VALUE_INVALID : valeur hors format.
400 PREFERENCES_SECRET_FORBIDDEN : clé contenant password, pass, token, secret ou key, à n’importe quel niveau.
413 PREFERENCES_TOO_LARGE : JSON final supérieur à 16 Ko.
500 PREFERENCES_UNAVAILABLE : stockage indisponible.

Règle PWA/PHP

Le PHP lit les préférences au chargement, écrit à chaque changement, et garde le cookie seulement comme cache local. Le backend ignore tout identifiant de compte envoyé dans le corps : le compte vient toujours du jeton.