> ## Documentation Index
> Fetch the complete documentation index at: https://docs-pos.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents & MCP

> La surface prête pour les agents : x-agent-tier, x-required-permissions, le flux de découverte MCP search → describe → invoke, et whoami.

L'API Solya POS est conçue pour être pilotée par un **agent autonome** aussi bien
que par une intégration classique. Chaque opération documentée porte les
métadonnées dont un agent a besoin pour la choisir et l'appeler en sécurité, et
la passerelle MCP les exploite pour la découverte.

## La surface servie

Le document OpenAPI **masque** toute route qui n'a pas explicitement opté pour la
documentation : `GET /openapi.json` est donc la surface **intentionnelle**,
prête pour les agents. Ajouter une route non documentée ailleurs ne pollue pas
cette surface.

## `x-required-permissions`

Chaque opération documentée porte l'extension **`x-required-permissions`** : la
liste des scopes `pos.*` exigés pour l'appeler. Elle est **dérivée** du scope de
la route et de la méthode (scope de lecture pour un `GET`/`HEAD`, scope
d'écriture pour une mutation) — jamais écrite à la main, donc jamais divergente
de ce que les gardes de route appliquent réellement.

Un agent croise ces permissions avec ses propres droits (via
[`whoami`](#découverte-sensible-aux-droits-whoami)) pour ne tenter que les
opérations qu'il est autorisé à appeler.

## `x-agent-tier`

Chaque opération porte aussi un **niveau agent** (`x-agent-tier`) qui indique à
quel point l'opération doit être mise en avant. Le vocabulaire d'écriture interne
est mappé sur celui de la passerelle au dernier moment :

| Niveau interne (écriture) | Niveau servi (passerelle) | Comportement de la passerelle                                                                                                            |
| ------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `preferred`               | `preferred`               | Mis en avant en premier lors de la découverte (par défaut).                                                                              |
| `supported`               | `preferred`               | Mutation ordinaire et pleinement utilisable — de première classe.                                                                        |
| `avoid`                   | `advanced`                | Appelable mais **exclue** de la découverte sauf opt-in explicite de l'agent — l'opération dangereuse/irréversible n'est jamais suggérée. |

Le mapping vers `advanced` (et non `deprecated`) préserve l'intention
« appelable, mais non suggérée par défaut » sans mentir sur le cycle de vie :
ces opérations sont actuelles et supportées. Un garde de lexique interdit
d'écrire une opération à verbe dangereux en `preferred`.

## Le flux de découverte MCP

Un agent qui découvre l'API via MCP suit le flux **search → describe → invoke** :

1. **search** — trouver les opérations pertinentes pour la tâche (les
   `preferred`/`supported` en tête ; les `advanced` sur opt-in seulement).
2. **describe** — lire la description, les paramètres, les exemples et les
   `x-required-permissions` de l'opération choisie. Les descriptions sont
   **écrites pour un agent** : ce que fait l'opération, quand la préférer, ses
   préconditions et ses conditions d'échec en clair.
3. **invoke** — appeler l'opération avec un corps valide (les exemples fournis
   sont garantis valides vis-à-vis du schéma).

## Découverte sensible aux droits : `whoami`

Avant d'appeler, l'agent introspecte ses droits :

```http theme={null}
GET /v1/auth/whoami
```

```json theme={null}
{ "data": { "effectivePermissions": ["pos.catalog.read", "pos.checkout.finalize"] } }
```

C'est ce qui permet à l'agent de savoir, **avant** d'appeler, quelles opérations
documentées il est autorisé à invoquer. La passerelle `solya-api-mcp` utilise ce
point d'accès (sous l'alias `${baseUrl}/api/auth/whoami`) pour sa découverte
sensible aux droits.

## Voir aussi

* [Authentification](/fr/developers/authentication) — les deux principaux acceptés.
* [Faire des requêtes](/fr/developers/making-requests) — enveloppes et pagination.
* [Codes d'erreur](/fr/developers/error-codes) — la correspondance statut ↔ code.