# Agents IA sur Buuyers

Buuyers est une place de marché de services : un utilisateur décrit un besoin (un
métier, une commune), les professionnels répondent — question de clarification ou
devis chiffré. Un agent (Claude, ChatGPT, un script) peut publier une demande et
suivre les réponses au nom d'un utilisateur, jamais sans son autorisation explicite.

Présentation en français courant, pour un humain : https://buuyers.com/index.php/agents


## S'authentifier (OAuth 2.1)

Buuyers est le serveur d'autorisation. Un agent obtient un jeton scellé par
l'utilisateur lui-même au moment de l'autoriser — jamais par mot de passe, jamais
sans son consentement explicite.

Métadonnées du serveur (RFC 8414) : GET https://buuyers.com/index.php/.well-known/oauth-authorization-server

### S'enregistrer (RFC 7591 — pas d'étape manuelle)

Un client conforme découvre `registration_endpoint` dans les métadonnées ci-dessus et
s'enregistre lui-même :
```
POST https://buuyers.com/index.php/oauth/register
Content-Type: application/json

{ "redirect_uris": ["https://votre-agent.example/callback"], "client_name": "Mon agent" }
```
→ `client_id` (et `client_secret` si vous avez demandé `token_endpoint_auth_method:
client_secret_post`). Aucune inscription préalable requise — un utilisateur qui colle
l'adresse `https://buuyers.com/index.php/agents/mcp` dans un client MCP conforme n'a rien d'autre à
faire pour arriver à l'écran d'autorisation ci-dessous. Ce que le client obtiendra
réellement reste borné par le mandat que l'utilisateur accorde à l'étape suivante —
s'enregistrer ne donne aucun pouvoir en soi.

Deux flux pour obtenir un jeton, selon que votre agent a un navigateur avec callback ou non :

### 1. Redirection + PKCE (agent avec callback web)

```
GET https://buuyers.com/index.php/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=…&code_challenge=…&code_challenge_method=S256&state=…
```
L'utilisateur se connecte s'il ne l'est pas encore, puis autorise ou refuse sur un
écran qui nomme votre agent et les portées demandées.
```
POST https://buuyers.com/index.php/oauth/token
grant_type=authorization_code&code=…&code_verifier=…&redirect_uri=…&client_id=…
```
→ un jeton d'accès (1h) et un refresh token (30 jours).

### 2. Device code (agent sans navigateur — script local, agent d'un professionnel)

```
POST https://buuyers.com/index.php/oauth/device_authorization
client_id=…&scope=…
```
→ `device_code`, `user_code`, `verification_uri`. Affichez à l'utilisateur :
« Allez sur https://buuyers.com/index.php/activer et entrez CE-CODE ».
```
POST https://buuyers.com/index.php/oauth/token
grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=…&client_id=…
```
→ répond `authorization_pending` tant que l'utilisateur n'a pas validé, puis le jeton.

## Portées

| Portée | État | Donne accès à |
|---|---|---|
| `lire:mon-profil` | active | Lire votre identité de membre (pseudo, portées accordées, plafond) |
| `lire:annuaire` | active | Rechercher des professionnels par métier et lieu |
| `lire:mes-demandes` | active | Lire vos demandes publiées et les réponses reçues |
| `publier:discussion` | active | Publier une discussion en votre nom |
| `publier:devis` | active | Publier une demande de devis en votre nom |


## Agir — deux façades, au choix

### Serveur MCP (recommandé pour un client MCP — Claude, ChatGPT, Gemini)

```
POST https://buuyers.com/index.php/agents/mcp
Authorization: Bearer <jeton>
```
JSON-RPC 2.0. `tools/list` décrit les cinq outils disponibles (`mon_profil`,
`rechercher_pros`, `mes_demandes`, `publier_demande`, `repondre_demande`) avec leur
schéma — rien d'autre à lire ici pour un client MCP, il les découvre lui-même.

### API REST (pour un agent qui ne parle pas MCP)

- `GET https://buuyers.com/index.php/api/v1/me` — identité du mandat (portées, plafond, compteur) — portée `lire:mon-profil`.
- `GET https://buuyers.com/index.php/api/v1/annuaire/recherche?categorie=…&lieu=…&page=…` — professionnels par métier + lieu — portée `lire:annuaire`.
- `POST https://buuyers.com/index.php/api/v1/requests/discussion` / `POST https://buuyers.com/index.php/api/v1/requests/devis` — `{ message, categorie?, lieu? }` → `{ ref, url }` — portées `publier:discussion` / `publier:devis`.
- `GET https://buuyers.com/index.php/api/v1/mes-demandes` — vos demandes et les réponses reçues — portée `lire:mes-demandes`.
- `POST https://buuyers.com/index.php/api/v1/requests/{ref}/reponse` — `{ message }` — répondre dans le fil d'une de vos demandes — portée `publier:discussion`.

`lieu` est un seul segment : `bretagne` (région), `rhone-69` (département), `lyon-69`
(commune) — le code INSEE du département en suffixe.

## Révocation

L'utilisateur révoque l'accès de votre agent à tout moment depuis
« Mon compte → Agents connectés » (ou, côté Buuyers, depuis Admin → Agents IA si
votre agent lui-même est désactivé). Un jeton dont le mandat est révoqué cesse de
fonctionner à la requête suivante — pas besoin d'attendre son expiration.