# API de Planify

Planify gère la prise de rendez-vous de plusieurs clients. Chaque client (un compte) a deux sortes de clés, créées
dans l'administration de Planify (fiche du client → Clés API) :

| Clé | Préfixe | Sert à | Où la mettre |
|-----|---------|--------|--------------|
| **Réservation** | `pl_pk_` | lire les créneaux libres et réserver (**API publique**) | dans les pages du site : elle est publiable |
| **Administration** | `pl_sk_` | régler les disponibilités, fermetures, visio ; lire et traiter les rendez-vous (**API de gestion**) | sur le serveur du site seulement : elle est secrète |

Modèles prêts à l'emploi : `https://planify.dev-rocket.fr/modele/planify.html` (HTML et JavaScript, sans dépendance) et
`https://planify.dev-rocket.fr/modele/PlanifyBooking.tsx` (composant React). Page de réservation hébergée : `https://planify.dev-rocket.fr/reserver/#<clé de réservation>`.

## Format

- Réponses en JSON (UTF-8). Instants en ISO 8601 UTC (`2026-12-01T08:00:00.000Z`), jours en `AAAA-MM-JJ`
  dans le fuseau du compte.
- Erreurs : un code HTTP et `{ "error": "message lisible", "field": "champ en cause" }` (`field` si une donnée est invalide).

---

## API publique (clé de réservation)

La clé se passe en paramètre `key`, ou dans l'en-tête `Authorization: Bearer pl_pk_…`. CORS ouvert à tous les
sites ; 120 requêtes par minute et par adresse IP. Sans clé valable : `401`.

### GET /api/public/agenda?key=pl_pk_…

Le compte et ce qu'il propose.

    {
      "name": "Boulangerie Martin",
      "slug": "boulangerie-martin",
      "timezone": "Europe/Paris",
      "duration": 60,          // durée d'un rendez-vous, en minutes (30, 60 ou 120)
      "step": 60,              // écart entre deux débuts de créneau (30 pour des rendez-vous de 30 min)
      "notice": 24,            // délai minimal de réservation, en heures
      "firstDay": "2026-11-18",
      "lastDay": "2027-01-17", // au-delà, rien n'est réservable
      "modes": [
        { "id": "google", "label": "Google Meet" },
        { "id": "onsite", "label": "Sur place", "address": "3 rue du Port, Marseille" }
      ]
    }

`modes[].id` : `onsite` (sur place), `google`, `teams`, `zoom`, `other` (lien fourni par le compte).

### GET /api/public/agenda/slots?key=pl_pk_…&from=AAAA-MM-JJ&days=7

Les créneaux libres, jour par jour (`days` de 1 à 62 ; `from` par défaut aujourd'hui). Un jour sans créneau n'apparaît pas.

    {
      "timezone": "Europe/Paris",
      "duration": 60,
      "days": [
        { "date": "2026-11-20", "slots": [
          { "start": "2026-11-20T08:00:00.000Z", "end": "2026-11-20T09:00:00.000Z", "instant": true },
          { "start": "2026-11-20T09:00:00.000Z", "end": "2026-11-20T10:00:00.000Z", "instant": false }
        ] }
      ]
    }

`instant` : vrai si la réservation de ce créneau est confirmée aussitôt, faux si le compte la valide d'abord.

### POST /api/public/agenda/bookings?key=pl_pk_…

Réserve un créneau.

    curl -X POST "https://planify.dev-rocket.fr/api/public/agenda/bookings?key=pl_pk_…" \
      -H "content-type: application/json" \
      -d '{"start":"2026-11-20T08:00:00.000Z","mode":"google","name":"Paul Durand","email":"paul@exemple.fr","phone":"06 12 34 56 78","message":"Projet de site"}'

| Champ     | Obligatoire | Description |
|-----------|-------------|-------------|
| `start`   | oui | le début d'un créneau, tel que rendu par `/slots` |
| `mode`    | oui | l'un des `modes[].id` proposés |
| `name`    | oui | 2 à 100 caractères |
| `email`   | oui | l'adresse où envoyer la confirmation |
| `phone`   | non | 30 caractères au plus |
| `message` | non | 2000 caractères au plus |
| `website` | —   | piège à robots : un champ caché du formulaire, à laisser vide |

Réponse `201` :

    {
      "booking": {
        "status": "confirmed",            // ou "pending" : en attente de validation
        "start": "…", "end": "…", "timezone": "Europe/Paris",
        "mode": "google", "modeLabel": "Google Meet",
        "link": "https://meet.google.com/abc-defg-hij",   // rendez-vous confirmé seulement
        "place": "",                                       // l'adresse, pour « sur place »
        "name": "Paul Durand", "reason": "",
        "account": { "name": "Boulangerie Martin", "slug": "boulangerie-martin" },
        "cancellable": true
      },
      "token": "12.Xy…",
      "manageUrl": "https://planify.dev-rocket.fr/rdv/#12.Xy…"
    }

Le visiteur reçoit un e-mail (demande reçue, ou confirmation avec le lien, l'invitation d'agenda et le lien
d'annulation) ; le compte aussi, s'il a une adresse d'avertissement. `409` : le créneau vient d'être pris, ou
l'adresse a déjà 3 rendez-vous à venir.

### Le rendez-vous du visiteur (sans clé, par le jeton de son lien)

- `GET /api/public/booking?token={token}` — le rendez-vous (même forme que `booking` ci-dessus).
- `POST /api/public/booking/cancel` — `{ "token": "…" }` : l'annule, tant qu'il n'a pas commencé ; `409` sinon.
- `GET /api/public/booking/rendez-vous.ics?token={token}` — l'invitation d'agenda d'un rendez-vous confirmé.

Le jeton est le secret du lien de gestion : il ne se met jamais dans le chemin d'une URL.

---

## API de gestion (clé d'administration)

Chaque requête porte la clé dans l'en-tête `Authorization`, depuis le serveur du site, jamais depuis un navigateur :

    Authorization: Bearer pl_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La clé ne donne accès qu'à son compte, désigné par son identifiant (`slug`, affiché dans la fiche du client).
Une clé ne s'affiche qu'à sa création. Sans clé valable : `401` ; une clé de réservation : `403`.

### Le compte

- `GET /api/v1/accounts/{slug}` — `{ "account": { "slug", "name", "email", "active", "createdAt" } }`
- `PATCH /api/v1/accounts/{slug}` — `{ "name"?, "email"? }` : le nom affiché aux visiteurs, l'adresse qui reçoit
  les avertissements (vide : aucun e-mail au compte).

### Réglages

`GET /api/v1/accounts/{slug}/settings`, `PUT` pour modifier (seuls les champs donnés changent) :

    {
      "timezone": "Europe/Paris",
      "week": [[9,10,11,14,15,16,17], [9,10,11], [], [], [], [], []],   // lundi … dimanche : heures de début (6 à 22)
      "duration": 60,          // 30, 60 ou 120
      "notice": 24,            // 1, 2, 4, 6, 12, 24 ou 48 heures
      "horizon": 60,           // jours réservables à l'avance (1 à 365)
      "holidays": false,       // vrai : ouvert les jours fériés
      "autoDefault": false,    // validation automatique par défaut
      "autoHours": { "8": true, "19": true },   // exceptions, par heure de début
      "modes": {
        "onsite": { "on": true, "address": "3 rue du Port, Marseille" },
        "google": { "on": true, "link": "" },            // lien fixe, si l'agenda Google n'est pas relié
        "teams":  { "on": false, "link": "" },
        "zoom":   { "on": false, "link": "" },
        "other":  { "on": false, "link": "https://…", "label": "Whereby" }
      }
    }

Un rendez-vous de 2 h ne commence qu'à une heure dont l'heure suivante est aussi cochée. La réponse ajoute
`connections` (les services reliés), `offered` (les modes réellement proposés), `publicApi` et `bookingPage`.

### Fermetures exceptionnelles

- `GET /api/v1/accounts/{slug}/closures`
- `POST /api/v1/accounts/{slug}/closures` — `{ "start": "2026-12-24", "end": "2027-01-02", "label": "Congés" }`,
  jours inclus. La réponse liste dans `conflicts` les rendez-vous déjà pris pendant la fermeture : ils restent, à
  annuler si besoin.
- `DELETE /api/v1/accounts/{slug}/closures/{id}`

### Rendez-vous

- `GET /api/v1/accounts/{slug}/bookings?from=AAAA-MM-JJ&to=AAAA-MM-JJ&status=pending,confirmed`
- `GET /api/v1/accounts/{slug}/bookings/{id}`
- `POST /api/v1/accounts/{slug}/bookings/{id}/confirm` — valide une demande ; crée le lien de visio.
  La réponse porte `warning` si le lien n'a pas pu être créé.
- `POST /api/v1/accounts/{slug}/bookings/{id}/refuse` — `{ "reason"? }`
- `POST /api/v1/accounts/{slug}/bookings/{id}/cancel` — `{ "reason"?, "notify"? }` (`notify: false` : le visiteur n'est pas prévenu)
- `PATCH /api/v1/accounts/{slug}/bookings/{id}` — `{ "link"?, "place"?, "notify"? }` : change le lien ou le lieu d'un
  rendez-vous confirmé ; `notify: true` l'envoie au visiteur.

Un rendez-vous : `{ "id", "status", "start", "end", "mode", "modeLabel", "name", "email", "phone", "message", "link",
"place", "reason", "createdAt", "decidedAt" }`. `status` : `pending`, `confirmed`, `refused`, `cancelled`, `expired`
(demande non traitée avant son heure).

### Visio

- `PUT /api/v1/accounts/{slug}/connections/zoom` — `{ "accountId", "clientId", "clientSecret" }` d'une application
  Zoom « Server-to-Server OAuth » (droit `meeting:write:admin`). Les identifiants sont vérifiés auprès de Zoom.
- `DELETE /api/v1/accounts/{slug}/connections/{google|teams|zoom}`
- Google Meet et Teams se relient depuis l'administration de Planify (fiche du client → Visio).
