# 04 — API

> Contrat et conventions de l'API consommée par la **PWA Ionic** et les intégrations. L'auth est décrite en [03 — Sécurité](03-securite.md).

## Principes

- **REST JSON**, stateless, JWT Bearer.
- **Enveloppe standard** via `ApiResponseFormatter` :
  ```json
  { "code": 200, "success": true, "message": "…", "data": { … }, "meta": { "timestamp": "…" } }
  ```
- **Codes** : 200 OK, 201 créé, 202 (challenge : 2FA/appareil/pays), 400 requête invalide, 401 non authentifié, 403 non autorisé, 404 introuvable, 409 conflit, 422 validation, 500 erreur serveur.
- **Localisation** : messages en français ; montants en centimes XOF ; dates ISO 8601.
- **Documentation** : OpenAPI via `nelmio/api-doc` (`/api/doc`).

## Conventions

- **Préfixe & version** : introduire `/api/v1/...` pour les nouveaux endpoints métier (l'auth existante reste sur `/api/...`). Décision à acter en ADR ([notes/decisions.md](notes/decisions.md)).
- **Nommage** : ressources au pluriel (`/api/v1/products`, `/api/v1/sales`).
- **Scoping boutique** : la boutique courante est résolue via l'utilisateur (ou en-tête `X-Boutique-Id` si multi-boutiques) ; le serveur **impose** le scope (jamais de confiance au client).
- **Pagination** : `?page=&limit=` → `meta: { total, page, limit, pages }`.
- **Filtres/tri** : `?sort=-createdAt&filter[status]=paid`.
- **Idempotence** : les créations sensibles (vente, paiement) acceptent un en-tête `Idempotency-Key` (évite les doublons hors-ligne).
- **Autorisation** : chaque endpoint gate une permission (`pos.sell`, `report.view`…) via `PermissionVoter`.

## Endpoints existants (auth) ✅

| Méthode | Route | Auth | Réponse |
|---|---|---|---|
| POST | `/api/login` | public | token + refresh + user (200) / challenge (202) |
| POST | `/api/login/2fa/verify` | public | token + refresh |
| GET | `/api/me` | Bearer | utilisateur courant |
| POST | `/api/token/refresh` | Bearer + `{refresh_token}` | nouveau token + refresh |
| POST | `/api/logout` | Bearer | révocation |
| GET | `/api/version/check` | public | version |
| … | `/api/profile`, `/api/settings/security`, `/api/media` | Bearer | profil, sécurité, médias |

## Endpoints métier à concevoir (par module)

Esquisse (détail dans chaque fiche module) :

| Domaine | Endpoints (v1) | Permission |
|---|---|---|
| Catalogue | `GET/POST /products`, `GET /products/{uuid}`, `PUT /products/{uuid}`, catégories | `catalogue.*` |
| Stock | `GET /stock`, `POST /stock/movements`, `POST /inventories` | `stock.*` |
| Ventes | `POST /sales` (dont **anonyme**), `GET /sales`, `GET /sales/{uuid}`, `POST /sales/{uuid}/refund` | `pos.sell`, `pos.refund` |
| Caisse | `POST /cash-sessions/open`, `POST /cash-sessions/{id}/close`, `GET /cash-sessions/current` | `pos.session.*` |
| Paiements | `POST /sales/{uuid}/payments` | `pos.sell` |
| Clients | `GET/POST /customers` | `customer.*` |
| Rapports | `GET /reports/sales`, `GET /reports/z`, exports | `report.view/export` |
| PWA mobile | `/api/mobile/auth/*`, telemetry, diagnostics (`X-Device-UID`) | selon route |

## Hors-ligne (PWA)

- Lectures mises en cache (service worker ; `ngsw-bypass` disponible pour forcer le réseau).
- Écritures (ventes) mises en **file locale** puis rejouées avec `Idempotency-Key` à la reconnexion.
- Le serveur doit être **idempotent** et tolérant au rejeu (clé métier + Idempotency-Key).

## Erreurs & résilience

- Toujours renvoyer l'enveloppe standard, message FR exploitable par la PWA.
- Validation → 422 avec détail des champs.
- Journaliser côté serveur (`FileLogger`) sans secret ; alertes dédupliquées.

## Intégration Ionic

Les specs PWA (écrans, appels, offline) seront fournies et déposées dans [integration-ionic/](integration-ionic/README.md). L'API doit rester **stable et versionnée** pour ne pas casser la PWA.

## Suite

Roadmap : [05 — Roadmap & phases](05-roadmap.md).