# CareFlow API — Espace développeurs

L'API REST de CareFlow expose la planification, le dispatch et la mesure de l'assistance PMR.
Elle est décrite par une spécification OpenAPI 3 et consommée par l'application elle-même ; les
intégrateurs autorisés y accèdent avec le même jeton que les utilisateurs.

- Spécification OpenAPI : https://careflow.opsis-aero.com/openapi.json (aussi `/api/openapi.json`)
- Base URL : `https://careflow.opsis-aero.com/api` — toujours le domaine canonique ; les alias
  `*.vercel.app` redirigent (308) et une redirection fait perdre l'en-tête `Authorization`.

## Authentification

Jeton JWT émis à la connexion (courriel professionnel OPSIS et mot de passe) par le fournisseur
d'identité de la plateforme ; l'API le vérifie par JWKS et en déduit le rôle (agent, superviseur,
coordonnateur, planificateur, administrateur) à partir du référentiel central des accès. Pas de
clés d'API anonymes ni d'inscription libre : un compte est créé par un gestionnaire OPSIS. Pour
une intégration de système à système : https://careflow.opsis-aero.com/contact (objet « API »).

```
curl -sS https://careflow.opsis-aero.com/api/me \
  -H "Authorization: Bearer <jeton>" -H "Accept: application/json"
```

## Endpoints publics (sans jeton)

| Méthode et chemin | Usage |
|---|---|
| `GET /api/health` | État du service, nom de l'application, environnement, horodatage UTC. |
| `GET /openapi.json` | Spécification OpenAPI 3 complète. |
| `GET /llms.txt` | Présentation de CareFlow pour les agents IA, avec les cas d'usage. |

```
curl -sS https://careflow.opsis-aero.com/api/health
{"status":"ok","app":"careflow-api","environment":"production","timestamp":"2026-11-01T15:05:18Z"}
```

## Familles d'endpoints (jeton requis)

Le rôle exigé varie selon l'opération : certaines acceptent tout compte authentifié, d'autres un
planificateur, un superviseur ou un administrateur. Une réponse `403` signale un rôle insuffisant.

| Préfixe | Domaine |
|---|---|
| `/api/me` | Identité et rôle de l'appelant. |
| `/api/scenarios`, `/api/planning`, `/api/forecast`, `/api/replanning` | Prévision de la demande, versions de planning, quarts générés, sauvegarde auditable. |
| `/api/planning/rules` | Règles métier éditables et leur journal. |
| `/api/coordinator`, `/api/confirmations`, `/api/derogations` | Quarts et vols du jour, rentabilité, confirmations de quart, dérogations. |
| `/api/agents`, `/api/flights` | Agents planifiés, recherche de vols à critères partiels. |
| `/api/charge`, `/api/qualite-service`, `/api/analyse`, `/api/anomalies`, `/api/reconciliation`, `/api/assistance-control` | Mesure : charge, attentes, biais de prévision, anomalies, réconciliation planning/réel. |
| `/api/admin`, `/api/settings`, `/api/studio` | Administration, destinataires des courriels, studio de revue des plannings. |

## Conventions

- JSON en entrée et en sortie ; dates civiles `YYYY-MM-DD`, instants ISO 8601 UTC ; fuseau
  d'affichage `America/Toronto`.
- Erreurs : `401` jeton absent ou invalide, `403` rôle insuffisant, `404` ressource inconnue,
  `422` corps ou paramètre invalide (détail dans `detail`).
- Les chemins inconnus hors `/api` répondent `404` avec un corps Markdown si l'en-tête
  `Accept: text/markdown` est présent.
- Pas de limite de débit publiée.

## Pour les agents IA

https://careflow.opsis-aero.com/llms.txt décrit quand faire appel à CareFlow et comment. La page
d'accueil et les pages publiques sont servies en Markdown avec `Accept: text/markdown`. Pas de
serveur MCP, de SDK ni d'outil en ligne de commande officiels : l'intégration passe par l'API REST.

## Code source

Organisation GitHub OPSIS-SA : https://github.com/OPSIS-SA (dépôts privés ; accès sur demande
aux partenaires).