> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avest.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Planning de permanence

> Alimenter et relire le planning de permanence d'une agence depuis votre propre outil.

Si vous tenez déjà vos plannings de permanence dans votre outil, vous pouvez les
pousser dans Avest au lieu de les ressaisir. Deux routes : une pour écrire une
semaine, une pour la relire.

> [!WARNING]
>
> Le planning de permanence **pilote l'attribution des leads entrants**. Un
> créneau sans personne de permanence envoie les leads de ce créneau à la
> pioche, au lieu du négociateur attendu. Traitez ces routes comme une écriture
> sensible, pas comme un réglage d'affichage.

## Endpoints

| Méthode | URL |
| - | - |
| `POST` | `/external-integration/agency/{agencyId}/shift-planning/{transaction}` |
| `GET` | `/external-integration/agency/{agencyId}/shift-planning/{transaction}` |

| Paramètre d'URL | Description |
| - | - |
| `agencyId` | Agence visée. Doit être dans le périmètre de votre clé. |
| `transaction` | `sale`, `acquisition` ou `rental` — un planning par type de transaction. |

**Clé requise** : `GET` avec toutes les clés ; `POST` en lecture-écriture (une clé en lecture seule reçoit `403 Not authorized to access this resource`). Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

## Le modèle : une semaine à la fois

Avest raisonne en **semaine ISO** (`year` + `weekNumber`), du lundi au dimanche,
en **matin / après-midi / journée**. Si votre outil raisonne en mois et en dates,
c'est à vous de convertir avant d'appeler.

**Un appel = une semaine.** Le corps décrit l'**état complet** de cette semaine :
tout créneau que vous n'envoyez pas est supprimé. Rejouer le même corps donne le
même résultat — la route est idempotente.

> [!NOTE]
>
> L'écriture ne touche **que** la semaine visée. Les autres semaines, et les
> plannings récurrents (« semaine type »), ne sont jamais modifiés.

## Écrire une semaine

```bash theme={null}
POST /external-integration/agency/618a35a36d932054e195ca0a/shift-planning/sale
Authorization: Bearer your-linked-api-token
Content-Type: application/json

{
  "year": 2026,
  "weekNumber": 37,
  "shifts": [
    { "userId": "618a35a36d932054e195ca0b", "day": "mon", "time": "am" },
    { "userId": "618a35a36d932054e195ca0c", "day": "mon", "time": "pm" },
    { "userId": "618a35a36d932054e195ca0b", "day": "tue", "time": "all" }
  ]
}
```

### Corps de la requête

| Champ | Type | Requis | Description |
| - | - | - | - |
| `year` | Integer | ✅ | Année ISO de la semaine. |
| `weekNumber` | Integer | ✅ | Numéro de semaine ISO, de `1` au nombre de semaines de l'année : `52`, ou `53` les années longues (2026 en compte 53 : la semaine 53 va du 28 décembre 2026 au 3 janvier 2027). |
| `shifts` | Array | ✅ | État complet de la semaine. Max **500** entrées. |
| `allowEmpty` | Boolean | ❌ | Obligatoire à `true` pour envoyer une semaine **vide**. |
| `dryRun` | Boolean | ❌ | `true` = valide et compte, **n'écrit rien**. Défaut `false`. |

Chaque entrée de `shifts` :

| Champ | Type | Description |
| - | - | - |
| `userId` | String | Identifiant Avest du collaborateur. |
| `day` | String | `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. |
| `time` | String | `am` (matin), `pm` (après-midi) ou `all` (journée). |

> [!WARNING]
>
> Tout champ de corps non listé → `400`.

### Réponse

```json theme={null}
{
  "success": true,
  "agencyId": "618a35a36d932054e195ca0a",
  "transactionType": "sale",
  "year": 2026,
  "weekNumber": 37,
  "dryRun": false,
  "deletedCount": 2,
  "createdCount": 3,
  "warnings": []
}
```

| Champ | Description |
| - | - |
| `deletedCount` | Créneaux de cette semaine remplacés. |
| `createdCount` | Créneaux écrits (ou qui l'auraient été si `dryRun`). |
| `warnings` | Anomalies **non bloquantes** — à lire, voir plus bas. |

## Désigner un collaborateur

Par son **identifiant Avest**, jamais par son nom. Récupérez l'annuaire une fois
via [GET Users](https://developers.avest.fr/endpoints/get-users.md) et conservez nos `id` de votre côté.

> [!WARNING]
>
> Le rapprochement sur prénom + nom n'est pas supporté, et pour de bonnes
> raisons : il casse au premier homonyme, au premier départ, au premier nom
> composé — et il vous ferait affecter les leads à la mauvaise personne sans
> aucune erreur visible.

## Une semaine vide, c'est explicite

Une agence fermée toute une semaine est un cas légitime. Un `shifts` vide par
bug de votre côté ne l'est pas — et les deux se ressemblent.

Une semaine vide est donc refusée, sauf si vous le dites :

```json theme={null}
{ "year": 2026, "weekNumber": 33, "shifts": [], "allowEmpty": true }
```

## Vérifier avant que ça compte

Deux outils, à utiliser dans cet ordre lors de votre mise en service.

**1. Simuler**

`dryRun: true` fait passer **toutes** les validations et renvoie les
compteurs, sans rien écrire. Les mêmes erreurs qu'un vrai appel, sans le
risque.

**2. Relire**

Le `GET` renvoie ce qui est réellement enregistré pour la semaine, avec le
nom des collaborateurs — de quoi comparer à votre écran avant de brancher
l'automatisation.

```bash theme={null}
GET /external-integration/agency/618a35a36d932054e195ca0a/shift-planning/sale?year=2026&weekNumber=37
Authorization: Bearer your-linked-api-token
```

```json theme={null}
{
  "success": true,
  "agencyId": "618a35a36d932054e195ca0a",
  "transactionType": "sale",
  "year": 2026,
  "weekNumber": 37,
  "shifts": [
    {
      "userId": "618a35a36d932054e195ca0b",
      "firstName": "Thomas",
      "lastName": "Godard",
      "day": "mon",
      "time": "am",
      "allocationEligible": true
    }
  ]
}
```

Le `GET` ne renvoie que les créneaux **datés** de la semaine demandée — pas ceux
d'une semaine type.

## Warnings

Un warning ne fait pas échouer l'appel : l'écriture a bien eu lieu. Il signale
un créneau qui **ne servira à rien**.

| Code | Sens |
| - | - |
| `USER_NOT_ELIGIBLE_FOR_ALLOCATION` | Le collaborateur est exclu de l'attribution pour ce type de transaction dans cette agence. Son créneau est enregistré mais **ne recevra jamais de lead**. Le réglage se corrige dans Avest, pas via l'API. |

```json theme={null}
{
  "warnings": [
    {
      "code": "USER_NOT_ELIGIBLE_FOR_ALLOCATION",
      "userId": "618a35a36d932054e195ca0c",
      "message": "User 618a35a36d932054e195ca0c is not eligible for sale allocation in this agency : its shifts will never receive a lead"
    }
  ]
}
```

## Erreurs

L'appel est **tout ou rien** par semaine : en cas d'erreur, rien n'est écrit.
Toutes en `400`, sauf mention contraire.

| Message | Cause |
| - | - |
| `agencyId is not in the authorized scope of this LinkedAPI` | L'agence n'est pas dans le périmètre de votre clé. |
| `This route does not exist` (`404`) | `transaction` n'est pas `sale`, `acquisition` ou `rental`. |
| `Invalid year` | `year` absent ou invalide. |
| `Invalid weekNumber` | `weekNumber` hors des semaines ISO de l'année (`1`-`52` ou `1`-`53`). |
| `Cannot modify past shifts` | La semaine est déjà passée. |
| `shifts is empty : set allowEmpty to true to clear the week on purpose` | Garde-fou : vider une semaine doit être explicite. |
| `Agency runs on a recurring planning : dated shifts would be ignored by lead allocation` | L'agence est en **semaine type** — voir ci-dessous. |
| `User {id} does not belong to agency {agencyId}` | Collaborateur non rattaché à cette agence. |
| `User {id} is inactive and cannot be given a shift` | Collaborateur désactivé. |
| `Overlapping shift for user {id} on {day} {time}` | Deux créneaux du même collaborateur se chevauchent (`all` couvre `am` **et** `pm`). |
| `Invalid bearer token` (`401`) | Token invalide. |
| `Not authorized to access this resource` (`403`) | Header `Authorization` absent, token en lecture seule, ou IP non whitelistée. |

### « Agency runs on a recurring planning »

Une agence est paramétrée soit sur un planning **qui se répète** (semaine type),
soit sur un planning **saisi semaine par semaine**. Les deux régimes sont
exclusifs.

Si l'agence est en semaine type, un planning daté serait enregistré puis
**ignoré** par l'attribution : la route refuse plutôt que de vous laisser
pousser dans le vide. Le régime se change dans les réglages de l'agence, dans
Avest.

> [!WARNING]
>
> Corollaire, une fois l'agence en semaine par semaine : **une semaine que vous
> n'alimentez pas n'a aucun collaborateur de permanence.** Poussez vos semaines
> à l'avance, et surveillez votre propre synchronisation.

## Rate limits

* `POST` : **100 req / minute** par groupe d'agences (bucket d'écriture commun).
* `GET` : **500 req / minute** par groupe d'agences (bucket de lecture commun).

Headers `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`. Dépassement
→ `429` avec `Retry-After`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.