# Équipes

> Créer des équipes dans un client, y ajouter des membres et régler leur niveau et leurs droits d'équipe par l'API publique.

Une [équipe](/v1.0/glossaire#équipe) regroupe des utilisateurs d'un même client. Chaque membre y a un [niveau d'équipe](/v1.0/glossaire#niveau-déquipe) et, en option, des droits d'équipe codés par des lettres que votre application interprète. Votre serveur peut ensuite contrôler l'appartenance d'un utilisateur avec [`POST /api/token/check/team`](/v1.0/reference-api/jeton-et-me#vérifier-le-jeton-dun-utilisateur).

**Accès commun** : appelant de niveau Administrateur client (`CUSTOMER_ADMIN`) au minimum, avec le droit applicatif indiqué. Les modifications exigent en plus un niveau suffisant **dans l'équipe** : `MANAGER` au moins pour modifier l'équipe et gérer ses membres, `ADMIN` pour la supprimer.

## L'objet Équipe

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant technique |
| `wid` | chaîne (6) | Identifiant court |
| `customerId` | UUID | Client de l'équipe |
| `name` | chaîne (100) | Nom |
| `description` | chaîne ou `null` | Description |
| `createdAt`, `updatedAt` | chaîne ISO 8601 | Dates de création et de modification |

## Niveaux d'équipe

| Niveau | Chiffre | Ce que le membre peut faire |
|---|---|---|
| `ADMIN` | 1 | Tout sur l'équipe : la renommer, la supprimer, gérer ses membres et ses données |
| `MANAGER` | 2 | Gérer les membres et toutes les données |
| `MEMBER` | 3 | Ajouter, modifier, supprimer et voir les données (niveau par défaut) |
| `CONTRIBUTOR` | 4 | Ajouter et voir les données |
| `VIEWER` | 5 | Voir les données |
| `NONE` | 0 | Aucun droit |

Ce que recouvrent « les données » d'une équipe est défini par votre application. Les droits d'équipe (`appRights`) sont une chaîne de 52 lettres au plus, de `A` à `Z` et de `a` à `z`, dont votre application fixe la signification.

## Lister les équipes

::endpoint{method="GET" path="/api/config/teams"}

**Droit requis** : `teams.read`. Pagination `page` et `limit` (1 à 100, défaut 20), filtres de portée `customerWid` ou `customerId`.

```bash
curl -s "https://api.wakastart.app/api/config/teams?customerWid=EXCLI1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
{
  "data": [
    {
      "id": "f6a8b0c2-5e7f-4a91-8c3d-4e5f6a7b8c90",
      "wid": "EXTEA1",
      "customerId": "c3d5e7f9-2b4c-4d6e-9f0a-1b2c3d4e5f60",
      "name": "Accueil",
      "description": "Équipe d'accueil des patients",
      "createdAt": "2026-04-02T09:30:00.000Z",
      "updatedAt": "2026-04-02T09:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```

## Lire une équipe

::endpoint{method="GET" path="/api/config/teams/{wid}"}

**Droit requis** : `teams.read`. Réponse : l'objet Équipe.

**Erreurs** : `403` `Team not found or not accessible` ; `404` `Team with WID <wid> not found`.

## Créer une équipe

::endpoint{method="POST" path="/api/config/teams"}

**Droit requis** : `teams.create`.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `name` | chaîne | oui | 100 caractères au plus |
| `customerId` | UUID | non | Client de l'équipe |
| `description` | chaîne | non | — |

```bash
curl -s -X POST https://api.wakastart.app/api/config/teams \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Cardiologie", "description": "Service de cardiologie" }'
```

**Réponse `201`** : l'objet Équipe créé.

## Modifier une équipe

::endpoint{method="PUT" path="/api/config/teams/{wid}"}

**Droit requis** : `teams.update`. Champs facultatifs : `name` (100 caractères au plus), `description`.

**Erreurs** : `403` `Vous n'avez pas les droits pour modifier cette équipe`.

## Supprimer une équipe

::endpoint{method="DELETE" path="/api/config/teams/{wid}"}

**Droit requis** : `teams.delete`. Retirez d'abord tous les membres.

**Erreurs** : `403` `Vous n'avez pas les droits pour supprimer cette équipe` ; `409` `Impossible de supprimer cette équipe car elle possède encore des membres. Retirez d'abord les membres de l'équipe.`

## Lister les membres d'une équipe

::endpoint{method="GET" path="/api/config/teams/{wid}/members"}

**Droit requis** : `teams.read`. Renvoie un tableau, sans pagination : un élément par membre, avec son niveau, ses droits d'équipe et sa fiche utilisateur.

```bash
curl -s https://api.wakastart.app/api/config/teams/EXTEA1/members \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
[
  {
    "userId": "e5f7a9b1-4d6e-4f80-9b2c-3d4e5f6a7b80",
    "teamId": "f6a8b0c2-5e7f-4a91-8c3d-4e5f6a7b8c90",
    "teamLevel": "MANAGER",
    "appRights": "AB",
    "user": {
      "id": "e5f7a9b1-4d6e-4f80-9b2c-3d4e5f6a7b80",
      "wid": "EXUSR1",
      "email": "alice@clinique-exemple.fr",
      "firstName": "Alice",
      "lastName": "Martin",
      "isActive": true
    }
  }
]
```

L'objet `user` reprend les champs de l'[objet Utilisateur](/v1.0/reference-api/utilisateurs#lobjet-utilisateur) ; l'exemple n'en montre qu'une partie.

## Ajouter un membre

::endpoint{method="POST" path="/api/config/teams/{wid}/members"}

**Droit requis** : `teams.members.add`.

| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
| `userId` | UUID | oui | Utilisateur du même client | Utilisateur à ajouter |
| `teamLevel` | chaîne | non | `ADMIN`, `MANAGER`, `MEMBER`, `CONTRIBUTOR`, `VIEWER`, `NONE` | Défaut `MEMBER` |
| `appRights` | chaîne | non | 52 lettres au plus, `^[a-zA-Z]*$` | Droits d'équipe |

```bash
curl -s -X POST https://api.wakastart.app/api/config/teams/EXTEA1/members \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "e5f7a9b1-4d6e-4f80-9b2c-3d4e5f6a7b80",
    "teamLevel": "CONTRIBUTOR",
    "appRights": "AB"
  }'
```

**Erreurs** : `403` `Vous n'avez pas les droits pour ajouter des membres à cette équipe` ; `409` `La valeur du champ "<champs>" existe déjà. Veuillez en choisir une autre.` : l'utilisateur est déjà membre.

## Modifier le niveau d'un membre

::endpoint{method="PATCH" path="/api/config/teams/{teamWid}/members/{userWid}/role"}

**Droit requis** : `teams.members.add`.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `teamLevel` | chaîne | oui | `ADMIN`, `MANAGER`, `MEMBER`, `CONTRIBUTOR`, `VIEWER`, `NONE` |
| `appRights` | chaîne | non | 52 lettres au plus |

```bash
curl -s -X PATCH https://api.wakastart.app/api/config/teams/EXTEA1/members/EXUSR2/role \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "teamLevel": "MANAGER" }'
```

**Erreurs** : `403` `Vous n'avez pas les droits pour modifier les niveaux dans cette équipe`.

## Retirer un membre

::endpoint{method="DELETE" path="/api/config/teams/{teamWid}/members/{userWid}"}

**Droit requis** : `teams.members.add`.

**Erreurs** : `403` `Vous n'avez pas les droits pour retirer des membres de cette équipe`.
