# API cible — My Amana Mobile

> Document destiné à l'équipe backend Amana. Il accompagne `openapi.yaml`, la
> spécification **OpenAPI 3.0.3** de l'API dont l'application mobile **My Amana**
> (React Native, dépôt `amana-mobile`) a **idéalement** besoin.

## Mode d'emploi en une minute

Ce document est le **critère d'acceptation** des corrections demandées dans l'outil de
ticketing. Il ne remplace pas les tickets : il dit, pour chacun, à quoi ressemble la réponse
attendue.

1. **Partir du ticket.** Chaque commentaire de notre part pointe vers l'opération concernée
   (lien direct dans le lecteur du dashboard). Sa description commence par « **Écart vs API
   actuelle** » : ce qui ne va pas aujourd'hui, puis ce qui est attendu.
2. **Implémenter jusqu'à l'exemple.** Chaque réponse porte un exemple et ses codes HTTP. Une
   correction est terminée quand l'appel réel en pré-production répond comme l'exemple.
3. **Vérifier avant de livrer.** Le serveur de simulation (§3) sert la cible en une commande ;
   comparer sa réponse à celle de la pré-production suffit. Pour rejouer ce que l'application
   envoie aujourd'hui, la collection Postman du §3 bis reprend ses 83 requêtes.
4. **Passer le ticket en `done`.** Nous rejouons l'appel contre la même opération et nous
   clôturons, ou nous disons précisément quelle ligne de la cible manque encore.

**Pour planifier**, la colonne « État actuel » du §7 suffit : `existant` (rien à faire),
`à corriger`, `manquant`. **Pour gagner du temps**, les conventions du §8 s'appliquent une fois
et corrigent plusieurs tickets à la fois (enveloppe d'erreur, dates, pagination, casse).

**En cas de désaccord** avec un choix de la cible, dites-le dans le ticket : la cible est un
contrat partagé et versionné, nous la mettons à jour. Elle ne décrit que ce dont l'application
a besoin ; les endpoints que l'application n'utilise pas n'y figurent pas (liste en fin de §5).

## 1. Objet

L'application consomme aujourd'hui l'API « ShiftIn v4 » (94 chemins, passerelle
`https://gateway.amana.dz/MOBILE/api/v1`). Toutes ses fonctions sont câblées sur cette API,
mais au prix d'une couche d'adaptation lourde (`app/api/adapters/`), de contournements
et de fonctions qui ne peuvent pas aboutir (déclaration de sinistre, résiliation, paiement
en Points Verts, retour après 3-D Secure, …). Les défauts sont consignés dans le registre
`amana-support` (90 tickets au 27/09/2026, `docs/test-tickets/TICKETS_AMANA_SUPPORT.md`).

`openapi.yaml` décrit **l'API cible** :

- elle **conserve** les chemins et les formes qui fonctionnent, pour que le backend s'y
  reconnaisse ;
- elle **change** ce qui doit l'être, et le dit opération par opération — chaque
  `description` commence par « **Écart vs API actuelle :** … » (ou « Identique à l'API
  actuelle ») et cite les tickets concernés ;
- elle **ajoute** les endpoints qui manquent pour ce que l'application affiche
  (`app/api/types.ts`, le contrat de vue figé de l'application : 149 entités, toutes
  couvertes — voir §6).

Deux usages :

1. **Simuler** l'API avec un serveur de simulation (§3), pour que l'application et les
   tests tournent sur le contrat cible avant qu'il existe ;
2. **Implémenter ou aligner** le backend : chaque opération porte `x-etat-actuel`
   (`existant` · `à corriger` · `manquant`) et `x-tickets`.

## 2. Ouvrir la spécification

Rien à installer ni à cloner : la spécification est publiée sur le dashboard de suivi du
projet, accessible sans connexion.

| Pour                                                              | Lien                                                                |
| ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| Lire et naviguer, avec un lien direct par opération               | https://amana-reporting.shiftin-demo.com/api/api-cible              |
| Télécharger `openapi.yaml` (Postman, Insomnia, Swagger Editor, …) | https://amana-reporting.shiftin-demo.com/api/docs/api-cible-openapi |
| Ce guide                                                          | https://amana-reporting.shiftin-demo.com/api/docs/api-cible-readme  |

Le lien direct vers une opération a la forme `…/api/api-cible#tag/<domaine>/operation/<operationId>`,
par exemple https://amana-reporting.shiftin-demo.com/api/api-cible#tag/Sinistres/operation/addDemandeSinistreImplement.
C'est ce lien que portent nos commentaires dans l'outil de ticketing.

Outils locaux, **facultatifs** — pour comparer la cible à votre propre spécification ou
l'annoter : importer le fichier téléchargé dans <https://editor.swagger.io> (_File → Import
file_), ou l'ouvrir dans VS Code avec l'extension « OpenAPI (Swagger) Editor » ou « Redocly
OpenAPI ».

## 3. Lancer un serveur de simulation (mock)

Une commande, directement depuis le lien publié (Node.js 18 ou plus) :

```bash
npx --yes @stoplight/prism-cli mock -p 4010 https://amana-reporting.shiftin-demo.com/api/docs/api-cible-openapi
```

Prism sert, pour chaque opération, **l'exemple** déclaré dans la spécification (chaque
réponse en porte un) et valide les requêtes contre les schémas (une requête invalide
répond `422` avec le détail — comportement de Prism, indépendant de l'API). Il lit la
spécification au démarrage : le relancer après une mise à jour.

```bash
BASE=http://localhost:4010
JWT=mock   # Prism vérifie la présence de l'en-tête, pas la signature

curl -s -X POST "$BASE/auth/login" -H 'Content-Type: application/json' \
  -d '{"username":"client@exemple.dz","password":"x"}' | jq .
curl -s "$BASE/contrats?page=0&size=20" -H "Authorization: Bearer $JWT" | jq .
curl -s "$BASE/members/tiers-payant-card" -H "Authorization: Bearer $JWT" | jq .

# forcer une réponse d'erreur documentée
curl -s -X POST "$BASE/souscriptions" -H "Authorization: Bearer $JWT" -H 'Prefer: code=422' \
  -H 'Content-Type: application/json' -d '{}' | jq .

# forcer le défi MFA du login
curl -s -X POST "$BASE/auth/login" -H 'Prefer: code=420' -H 'Content-Type: application/json' \
  -d '{"username":"client@exemple.dz","password":"x"}' | jq .
```

**Comparer avec la pré-production.** Rejouer le même appel sur
`https://gateway.amana.dz/MOBILE/api/v1` : une correction est terminée quand les deux
réponses ont la même forme — mêmes champs, mêmes types, mêmes codes HTTP.

### Note pour l'équipe mobile — pointer l'application sur le mock

_Cette partie concerne le dépôt de l'application ; l'équipe backend peut l'ignorer._

`API_URL` vit dans `app/config/config.dev.ts` :

```ts
API_URL: "https://gateway.amana.dz/MOBILE/api/v1",
```

Remplacer par l'adresse du mock, selon la cible :

| Cible             | `API_URL`                                                                      |
| ----------------- | ------------------------------------------------------------------------------ |
| Simulateur iOS    | `http://localhost:4010`                                                        |
| Émulateur Android | `http://10.0.2.2:4010`                                                         |
| Appareil physique | `http://<IP du Mac sur le réseau local>:4010` (lancer Prism avec `-h 0.0.0.0`) |

Puis redémarrer Metro avec le cache vidé (`yarn ios --clear` / `npx expo start -c`).

> ⚠️ Les adaptateurs de l'application (`app/api/adapters/`) lisent aujourd'hui les formes
> de l'API **actuelle**. Pointer l'application sur ce mock sert à développer et tester
> l'alignement sur le contrat cible, écran par écran ; ce n'est pas un remplacement
> immédiat de la pré-production.

## 3 bis. Rejouer les requêtes de l'application

La spécification décrit l'API **cible**. Pour rejouer ce que l'application envoie **aujourd'hui**,
sans l'application, une collection Postman reprend ses 83 requêtes, dans la forme exacte où elle
les envoie : chaque corps d'écriture a été construit par le code de l'application lui-même, puis
anonymisé. Elle s'importe aussi dans Insomnia ou Bruno.

| Fichier                                | Lien                                                                         |
| -------------------------------------- | ---------------------------------------------------------------------------- |
| Collection (83 requêtes)               | https://amana-reporting.shiftin-demo.com/api/docs/requetes-app-collection    |
| Environnement « Amana pré-production » | https://amana-reporting.shiftin-demo.com/api/docs/requetes-app-environnement |

**Démarrer** : dans Postman, _Import → Link_ avec le lien de la collection. Renseigner
`username` et `password` d'un compte de recette dans l'onglet _Variables_ de la collection —
l'adresse de la passerelle y est déjà. Avec l'environnement, l'importer **et le sélectionner**
(menu en haut à droite de Postman) : un environnement importé mais non sélectionné ne s'applique
pas, et Postman envoie alors `{{baseUrl}}` tel quel (`getaddrinfo ENOTFOUND {{baseurl}}`). Lancer
ensuite le dossier **A · Lecture et devis — sans effet** (_Run folder_) : la connexion se fait
toute seule et les identifiants (contrat, sinistre, remboursement, personne à charge) sont
relevés dans les listes.

**Deux dossiers.** Le dossier A (45 requêtes : lectures, devis, vérifications) ne crée, ne paie
et n'envoie rien : il peut être lancé en entier après chaque déploiement. Le dossier B
(37 écritures) crée des contrats, paie, modifie des fiches ou envoie des e-mails : une requête à
la fois, sur un compte de recette, après avoir renseigné les variables `w_…` — vides par défaut
pour qu'aucune écriture ne parte par mégarde. Les deux requêtes marquées ⛔ (changer le mot de
passe, résilier un contrat) sont irréversibles sur le compte.

**En ligne de commande**, pour un rapport après chaque déploiement :

```bash
npx newman run https://amana-reporting.shiftin-demo.com/api/docs/requetes-app-collection \
  -e https://amana-reporting.shiftin-demo.com/api/docs/requetes-app-environnement \
  --env-var username=… --env-var password=… \
  --folder "A · Lecture et devis — sans effet"
```

**Lire le résultat.** Chaque requête vérifie le code que l'application sait traiter
(« L'application attend : 200 »). Un échec est un écart entre ce dont l'application a besoin et
ce que la passerelle répond ; la description de la requête cite le ticket et le lien vers
l'opération de la cible. Au 29/09, le dossier A passe à 42 sur 45 ; les trois échecs sont des
tickets ouverts : devis de renouvellement Santé (`409`), devis d'adjonction Santé (`500`), photo
d'une personne à charge (`404`, #86).

## 4. Valider la spécification

```bash
npx --yes @redocly/cli lint https://amana-reporting.shiftin-demo.com/api/docs/api-cible-openapi
```

Résultat attendu : `Woohoo! Your API description is valid.` avec un seul avertissement
(`no-server-example.com`) : il vise le serveur `http://localhost:4010`, qui est le serveur
de simulation voulu. Depuis le dépôt de l'application, la configuration fournie le fait
taire : `npx --yes @redocly/cli lint --config docs/api-cible/redocly.yaml docs/api-cible/openapi.yaml`.

## 5. Synthèse

**106 opérations** sur 14 domaines, **157 schémas**.

| `x-etat-actuel` | Nombre | Sens                                                                       |
| --------------- | ------ | -------------------------------------------------------------------------- |
| `existant`      | 14     | Identique à l'API actuelle (au plus une précision de documentation)        |
| `à corriger`    | 77     | Le chemin existe ; la forme, la validation ou le comportement doit changer |
| `manquant`      | 15     | Aucun endpoint aujourd'hui — l'écran affiche une fixture ou n'envoie rien  |

| Domaine (tag)                                     | Opérations |
| ------------------------------------------------- | ---------- |
| Auth                                              | 12         |
| Compte                                            | 7          |
| Produits & tarifs                                 | 12         |
| Devis & souscription                              | 9          |
| Contrats                                          | 5          |
| Avenants                                          | 8          |
| Sinistres                                         | 9          |
| Remboursements                                    | 6          |
| Santé (profil, membres, documents)                | 18         |
| Paiement (CIB, Edahabia, Points Verts, livraison) | 7          |
| Documents                                         | 3          |
| Agences & Allo Docteur                            | 3          |
| Notifications                                     | 3          |
| Contenu                                           | 4          |

Les défauts connus que la cible corrige, avec leur ticket :

| Défaut                                                                                                                                                                                                                                                                                        | Ticket(s)              | Où dans la cible                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------- |
| `POST /claims` répond `500` pour toute entrée ; parties snake_case documentées, camelCase lues ; trois formats de date                                                                                                                                                                        | #87 (ex-P0-K), #37     | `POST /claims` — parties camelCase, `contratId` + `garantieId`, dates ISO |
| Listes en page Spring (`content`) contre `data` ailleurs ; base d'index variable ; `500` sans `page`                                                                                                                                                                                          | #33                    | pagination unique `{items, page, size, total}`, `page` optionnel base 0   |
| `POST /souscriptions/voyage` répond `201 success:true` sur un échec ; trois appels non atomiques                                                                                                                                                                                              | #20, #21               | `404` / `400` réels, `membres[]` dans la souscription                     |
| `/auth/me` : DTO plat déclaré, réponse imbriquée, `nom` / `prenom` vides à la racine                                                                                                                                                                                                          | #31, #25               | `Me` plat, `hasSouscripteurRecord`, `nin`, `sante{}`                      |
| `/tarifs` : `tarif` brut + `reduction` à part, `200 []` sans paramètre                                                                                                                                                                                                                        | #44, #61, #90          | `tarifNet`, `coutPolice`, `droitTimbre`, `400`                            |
| Points Verts : `GET` qui débite et répond `500 « Erreur lors de la construction du DTO »`                                                                                                                                                                                                     | #7                     | `POST`, reçu en `200`, `409 INSUFFICIENT_BALANCE`                         |
| Encaissement carte 10-30 min après Satim ; retour 3-D Secure vers le site vitrine                                                                                                                                                                                                             | #6, #5                 | `settlementStatus PENDING/SETTLED`, `returnUrl`                           |
| Login `420` avec le jeton MFA dans une enveloppe non déclarée ; `419` idem                                                                                                                                                                                                                    | #30, #75               | `AuthChallenge {challenge, challengeToken}`                               |
| Devis d'avenant Santé : `500` de désérialisation / `409 « problem devis »`, `status/error/errorMessage` mêlés au payload                                                                                                                                                                      | #29, #28, #42          | `AvenantDevis`, erreurs en `ServerError` avec `code`                      |
| `GET /members/bulletinAdhesion` : `500`, puis `{fileName, mimeType, downloadUrl}` exigeant le jeton                                                                                                                                                                                           | #15, #4                | URL signée sans en-tête, ou binaire selon `Accept`                        |
| Aucun endpoint : suppression de compte, carte tiers-payant / QR, présentation des formules Accident-Scolaire, chronologie d'un sinistre, préférences de notification, compteur de non-lues, motifs de résiliation, suivi de résiliation, état d'une livraison, remplacement des bénéficiaires | #43, #55, #8, #91, #26 | opérations `manquant` du tableau §7                                       |
| `POST /promoCode/validate` : `PromoDTO` jamais observé, `404` sur code inconnu                                                                                                                                                                                                                | #50, #73               | `PromoCode` documenté, `404` conservé                                     |

**Hors cible.** Dix-sept opérations de l'API actuelle n'y figurent pas : aucun écran de
l'application ne les appelle (vérifié le 29/09 écran par écran, dans le code et par appel en
lecture). La cible ne demande ni de les modifier ni de les supprimer, sauf une (sécurité).

- **Redondantes** — l'application obtient déjà la même donnée par un appel qu'elle fait :
  `GET /actes`, `GET /actes/{acte_id}`, `GET /actes/groups/{group_acte_id}` (tout est chargé
  en une fois par `GET /actes/groups`) ; `GET /ayantDroits/{ayantDroitId}` et
  `GET /beneficiaries/{beneficiaireId}` (les écrans lisent les listes) ; `GET /destination`
  (le formulaire Voyage lit les types, puis les pays par type) ; `GET /users/photo/{photo_name}`
  (l'application lit la photo de l'appelant par `GET /users/photo`) ;
  `DELETE /beneficiaries/allDelete` (un bénéficiaire retiré est supprimé seul).
- **Sans écran dans la maquette** : `POST /avenants/{contratId}/adjonctions/devis` et
  `…/adjonctions/voyage` (un contrat Voyage propose le report de date et la résiliation, pas
  d'adjonction ; les deux répondaient `500` le 27/09) ; `PUT /beneficiaries/{beneficiaireId}`
  (les écrans ajoutent, retirent et répartissent, sans modifier l'identité) ; `GET /tarifs/asi`
  (répond `[]`) ; `GET /users/photo/altern` (photo d'un compte migré, utile au seul rattachement
  de comptes, en attente des réponses de #71).
- **À trancher** — l'application ne les appelle pas, mais la question se pose :
  - `POST /avenants/{contratId}/radiations/sante` — retrait d'un assuré au niveau du contrat.
    L'application retire un ayant droit par `…/ayantDroits/{id}/demandeSuppression`, qui répond
    `500` sur le chemin nominal (#79). Laquelle des deux est la route voulue ?
  - `PUT /refunds/{refundId}` et `POST /refunds/{refundId}/createRefundCancellation` — modifier
    ou annuler une demande de remboursement. Les états « En cours d'annulation » et « Annulée »
    existent, et l'application affiche « Action requise » sur une demande « En attente » sans
    rien proposer pour agir : faut-il « Annuler » et « Compléter ma demande » dans le suivi ?
  - `GET /nousContacter` — **à fermer aux clients** : un jeton client lit les messages de contact
    de tous les utilisateurs (nom, e-mail, téléphone, message ; même liste de 28 messages vue
    par deux comptes différents le 29/09). L'application n'utilise que `POST /nousContacter`.

Deux autres changent seulement de méthode et sont décrits dans la cible :
`DELETE /ayantDroits/{id}/demandeSuppression` devient `POST`, et
`GET /points-verts/paiement/{quittanceId}` devient `POST` (livré le 28/09).

## 6. Couverture du contrat de vue (`app/api/types.ts`)

Toutes les entités servies par le backend ont une opération source. Trois familles n'en
ont pas **par nature** et restent locales à l'application : les types de navigation et de
saisie (`VoyageSimulationInput`, `SouscriptionInput`, `DeclarationSinistrePayload`, …),
les fixtures explicitement nommées `*Mock` (`DevisSanteMock`, `AvenantAdjonctionMock` —
remplacées par les devis d'avenant), et la présentation locale (`RemboursementActeIllustration`
est une clé, servie par `Acte.illustration`).

## 7. Toutes les opérations

Colonnes : endpoint · `x-etat-actuel` · résumé de l'écart (le détail est dans la
`description` de l'opération) · ticket(s) du registre `amana-support` (`#n`) ou référence
interne (`P2.5`, `P2.8`).

#### Auth

| Endpoint                    | État actuel | Écart                                                                                                                                                                                                               | Ticket(s)               |
| --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `POST /auth/login`          | à corriger  | le chemin et les codes `200` / `401` / `419` / `420` sont conservés. Trois corrections : · les deux **défis** (`419` changement de mot de passe forcé, `420` code MFA) sortent dans une enveloppe **déclarée** et … | #30, #40, #65, #25, #71 |
| `POST /auth/refresh`        | à corriger  | le `500` sur jeton valide est corrigé (#1, clos). Reste à aligner la réponse sur `Session` : `refreshToken` au lieu de `refresh`, et `expiresAt` en ISO-8601 au lieu de `validUntil` en `DD/MM/YYYY HH:mm:ss` …     | #1, #39                 |
| `GET /auth/me`              | à corriger  | l'endpoint le plus consommé de l'application (10 hooks) est documenté comme un DTO plat de 5 champs alors qu'il renvoie 18 champs plus 4 objets imbriqués, `nom` / `prenom` vides à la racine et peuplés dans …     | #31, #25, #40, #39, #89 |
| `POST /auth/otp`            | à corriger  | chemin conservé. Corrections : · le code fait **toujours 6 chiffres** (`%06d`) — un code sur dix en a cinq aujourd'hui et bloque la saisie (#82) ; · le canal `SMS` résout l'utilisateur par son numéro …           | #2, #67, #82, #69, #64  |
| `POST /auth/otp/validate`   | à corriger  | chemin conservé. `token` est renvoyé **nu**, sans le préfixe `Bearer ` dans la valeur (#70) ; un `code` vide répond `400` sans exposer d'exception SQL (#68) ; le code est à usage unique (#66, clos) ; un code …   | #70, #68, #66           |
| `POST /auth/mfa/send`       | existant    | Identique à l'API actuelle (délivrance par e-mail corrigée, #16 clos). Le jeton porteur est le `challengeToken` du `420`. Un jeton expiré répond `401 MFA_CHALLENGE_EXPIRED`. Le corps ne porte que le canal — …    | #16                     |
| `POST /auth/mfa/verify`     | à corriger  | chemin conservé. Le jeton porteur est le `challengeToken` du `420`. Un code faux répond `422 MFA_CODE_INVALID` et non `401`, réservé au jeton absent ou expiré (#75). La réponse `200` porte la \*\*session …       | #75, #16                |
| `PATCH /auth/password`      | existant    | Identique à l'API actuelle. Le jeton porteur est celui de `POST /auth/otp/validate` (mot de passe oublié) ou le `challengeToken` du `419`. Un mot de passe hors politique répond `422 PASSWORD_POLICY` en nommant … | #65                     |
| `POST /auth/check`          | existant    | Identique à l'API actuelle : `200` si le mot de passe est celui du compte connecté, `401` sinon.                                                                                                                    | —                       |
| `GET /auth/password-policy` | existant    | Identique à l'API actuelle (tableau de phrases françaises), enrichi d'un `code` par règle pour que l'application puisse valider localement et traduire : la réponse devient `{rules: [{code, label, value}]}`. …    | #65                     |
| `POST /auth/attach`         | à corriger  | l'endpoint existe sans `summary` ni `description`, et n'a jamais été appelé faute de savoir ce qu'il modifie (#71, questions Q1-Q9). Contrat cible, à confirmer par le backend : le JWT identifie le compte …       | #71                     |
| `POST /users`               | à corriger  | chemin conservé. La politique de mot de passe est **appliquée à la création** (`422 PASSWORD_POLICY`), et non découverte au premier login par un `419` (#65). Un champ `nin` est ajouté : l'inscription collecte …  | #65, #64, #71, #39      |

#### Compte

| Endpoint                              | État actuel | Écart                                                                                                                                                                                                             | Ticket(s) |
| ------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `PUT /users`                          | à corriger  | chemin et champs conservés ; `dateNaissance` passe en ISO (#39), `wilaya` devient `wilayaId` (entier). Tous les champs sont optionnels : seuls ceux présents sont modifiés. Un changement de `telephone` …        | #39       |
| `PATCH /users`                        | existant    | Identique à l'API actuelle : un OTP est envoyé à la **nouvelle** adresse, à valider par `POST /auth/otp/validate`. `409` si l'adresse est déjà utilisée.                                                          | —         |
| `DELETE /users`                       | manquant    | `DELETE /users` figure dans la spécification v4 avec la description « user created » et n'a jamais été vérifié ; l'écran « Supprimer mon compte » ne fait qu'ouvrir un courriel au support. App Store (5.1.1 v) … | —         |
| `GET /users/photo`                    | à corriger  | l'endpoint renvoie déjà l'image binaire, mais la spécification la déclare en base64 (`format: byte`) et une absence de photo répond `200` vide. Cible : `200` binaire avec `Content-Disposition`, `404` quand …   | —         |
| `POST /users/photo`                   | existant    | Identique à l'API actuelle (`multipart/form-data`, partie `image`). Limite 10 Mo, `413` au-delà (#12).                                                                                                            | #12       |
| `GET /users/notification-preferences` | manquant    | aucun endpoint. L'écran « Notifications » des paramètres (`NotificationPreferences` dans `app/api/types.ts`) porte six interrupteurs qui ne sont aujourd'hui enregistrés nulle part.                              | —         |
| `PUT /users/notification-preferences` | manquant    | aucun endpoint (voir `GET`). Remplacement complet des six valeurs.                                                                                                                                                | —         |

#### Produits & tarifs

| Endpoint                             | État actuel | Écart                                                                                                                                                                                                               | Ticket(s)     |
| ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `GET /produits`                      | à corriger  | chemin conservé, `produitid` → `id`, `descriptionCourte` / `descriptionLongue` → `libelle` / `description`. Ajouts : `type` (énumération stable `VOYAGE \| SANTE \| ACCIDENT \| SCOLAIRE` — aujourd'hui déduit du … | #44           |
| `GET /produits/{produitId}/detail`   | à corriger  | chemin conservé et payload déjà conforme au modèle de l'application, mais **enveloppé** sous une clé variable (`{"voyage": {…}}`, `{"sante": {…}}`) : la cible renvoie le nœud **directement**. `type` devient …    | #48, #49, #63 |
| `GET /produits/{produitId}/formules` | existant    | Identique à l'API actuelle. C'est la source des `formuleId` / `typeContratId` que la simulation et la souscription exigent (Scolaire 4 / 526-532-527, Accident 7 / 528-533-529, Santé 6-8-9 / 530-531, Voyage …     | —             |
| `GET /produits/{produitId}/avenants` | existant    | Identique à l'API actuelle (même forme que `/produits/{produitId}/formules`).                                                                                                                                       | —             |
| `GET /tarifs`                        | à corriger  | chemin et paramètre conservés. `codeProduit` absent ou inconnu répond `400` et non `200 []` (#44). `tarif` est un montant **brut** et `reduction` un montant à part, non nul sur Santé seulement : la cible garde … | #44, #61, #90 |
| `GET /garanties/{codeProduit}`       | existant    | Identique à l'API actuelle (`{garantie, values}`, `values` indexé par libellé de formule), hors localisation : le contenu doit suivre `Accept-Language` (#49). La granularité par formule est conservée ; la …      | #48, #49      |
| `GET /coverages/{produitId}`         | existant    | Identique à l'API actuelle. `garanties[].id` est la valeur que `POST /claims` attend dans `garantieId`. Le détail de contrat cesse d'en dépendre une fois ses garanties valorisées (#53).                           | #53           |
| `GET /destination/getGlobal`         | à corriger  | chemin conservé ; `{key, value}` (clé en chaîne) devient `{id, code, label, subtitle}` (#40). `code` est le slug stable que la fiche produit et l'écran de devis utilisent (`schengen \| tunisie \| turquie \| …    | #40           |
| `GET /destination/filter/{filterId}` | à corriger  | chemin conservé ; clés en camelCase — `destinationid` → `id`, `libelledestination` → `label`, `formuleid` → `zoneId` (#40). `zoneId` est la **zone géographique** que le tarificateur facture (Turquie/Schengen …   | #40           |
| `GET /wilayas`                       | existant    | Identique à l'API actuelle (`wilayaId`, `libelle`), libellé localisé. Anonyme (utilisé à l'inscription).                                                                                                            | —             |
| `GET /wilayas/{wilayaId}/communes`   | à corriger  | chemin conservé ; `communeid` / `codecommune` / `wilayaid` deviennent `communeId` / `codeCommune` / `wilayaId` (#40).                                                                                               | #40           |
| `GET /professions`                   | existant    | Identique à l'API actuelle (354 lignes, identifiants et libellés uniques) ; la cible les renvoie **triées** par libellé (#34) et sans les champs techniques (`userId`, `createDate`, `modifiedDate`). …             | #34           |

#### Devis & souscription

| Endpoint                                       | État actuel | Écart                                                                                                                                                                                                              | Ticket(s)                         |
| ---------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| `POST /souscriptions/simulation`               | à corriger  | chemin et corps conservés, dates en ISO (#39), `souscripteur: null` retiré (résolu par le JWT). La réponse ne porte plus le seul `montantTTC` : elle détaille `montantHT`, `reduction`, `coutPolice` …             | #73, #90, #83, #39                |
| `POST /souscriptions/devis-souscription-sante` | à corriger  | chemin et corps conservés, dates en ISO (#39). `dateFin` est **déclarée requise** (aujourd'hui « optionnelle » mais `400` sans elle) ; l'écart `dateEffet` → `dateFin` doit faire 365 ou 366 jours inclus, sinon … | #61, #39, #73                     |
| `POST /simulation-voyage`                      | à corriger  | chemin conservé. Corrections : · la réponse est déclarée `type: string` dans la spécification alors que c'est du JSON (#63) ; sa casse mélangée (`list_formule`, `cout_police`, `Capital`, `montantPrime`) …       | #22, #23, #76, #51, #40, #39, #63 |
| `POST /promoCode/validate`                     | à corriger  | chemin conservé ; `404` sur code inconnu conservé. La réponse `200` (`PromoDTO`) n'a jamais pu être observée faute de code valide en base (#50, #73) : elle est **documentée ici** — `reductionType` …             | #50, #73                          |
| `POST /souscriptions`                          | à corriger  | chemin conservé. Corrections : · `personneId` et le bloc `souscripteur` ne sont plus exigés : le souscripteur est **résolu par le JWT** ; un compte sans enregistrement souscripteur répond `409 …                 | #9, #59, #25, #39, #42            |
| `POST /souscriptions/voyage`                   | à corriger  | chemin conservé. Corrections : · **plus jamais `201 success: true` sur un échec** (#20, V8b) : un `assurePrincipalId` inconnu répond `404`, un corps invalide `400`, et un `201` signifie que `GET …               | #20, #21, #59, #40, #39           |
| `POST /personnes/assure`                       | à corriger  | chemin conservé. `professionId` (référentiel `/professions`) remplace la chaîne libre `profession` (#34) ; dates en ISO (#39) ; les énumérations réelles sont **déclarées** (`civiliteCode` `M \| Mme \| Mlle` …   | #34, #39, #63                     |
| `POST /personnes/membre-assure`                | à corriger  | chemin conservé. Devient un **ajout a posteriori** : la création nominale passe désormais par `membres[]` de `POST /souscriptions/voyage` (#21). `dateExpirationPassport` (une seule « t ») est aligné sur …       | #21, #39                          |
| `POST /carteFlash/checkTicketValidation`       | à corriger  | chemin et corps conservés. `statut` est une chaîne libre qui vaut `"false"` sur un code invalide (référence P2.8, retirée de l'outil) : la cible expose un booléen `valid`, un `message` en cas de refus, et …     | P2.8                              |

#### Contrats

| Endpoint                                           | État actuel | Écart                                                                                                                                                                                                              | Ticket(s)                     |
| -------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| `GET /contrats`                                    | à corriger  | chemin conservé. Enveloppe **unique** `{items, page, size, total}`, `page` base 0, `size` par défaut 20 (#33) ; ordre de tri **garanti** `createdAt` décroissant, et paramètre `status` pour filtrer (#46). …      | #33, #46, P2.5, #39, #40, #49 |
| `GET /contrats/{contratId}`                        | à corriger  | chemin conservé. Trois données affichées par l'écran n'ont **aucune source** (#53) : les **personnes assurées** (`assurePrincipal`, `membres[]`), le **moyen de paiement** (`paiement.code` / `libelle` — …        | #53, #83, #39, #40, P2.5      |
| `GET /contrats/{contratId}/documents`              | à corriger  | chemin conservé. Répond `404 « contrat not found »` sur un contrat réel (#52) ; la cible distingue `404` (contrat inconnu ou d'un autre souscripteur) de `200 []` (aucun document). Le tableau de …                | #52, #4                       |
| `GET /contrats/{contratId}/documents/{documentId}` | manquant    | aucune route binaire par document. Renvoie le fichier avec `Content-Disposition`. Accepte le jeton porteur **ou** la signature portée par `downloadUrl` (paramètres `sig` / `exp`), car le navigateur du …         | #52, #4                       |
| `POST /voyages/{contratId}/report`                 | à corriger  | chemin et corps conservés. Un contrat inconnu répond `404`, une date absente ou invalide `400` nommant `dateDebut` — aujourd'hui le même `500 « Cannot format given Object as a Date »` dans les deux cas (#78). … | #78, #39                      |

#### Avenants

| Endpoint                                                 | État actuel | Écart                                                                                                                                                                                                             | Ticket(s)          |
| -------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `GET /avenant/motifs`                                    | manquant    | aucun endpoint ; `motifId` est un `int32` sans énumération documentée, l'application envoie 1 à 4 dans l'ordre de l'écran et répète le libellé dans le commentaire (#55). Localisé.                               | #55                |
| `POST /avenant/resiliation`                              | à corriger  | chemin conservé ; le corps devient `multipart/form-data`. Aujourd'hui l'endpoint répond `500` **pour toute entrée**, corps vide compris, en exposant le chemin du service amont …                                 | #81, #62, #54, #55 |
| `GET /contrats/{contratId}/resiliation`                  | manquant    | aucun endpoint. L'écran « Suivi de résiliation » (`ResiliationTracking` dans `app/api/types.ts`) affiche l'état, une chronologie, les pièces déposées et les pièces que le back-office réclame ; tout cela est …  | #81                |
| `POST /contrats/{contratId}/resiliation/documents`       | manquant    | aucun endpoint. Répond à `requiredDocuments[]` du suivi : `requiredDocumentId` nomme la pièce réclamée, `fichier` la porte.                                                                                       | #81                |
| `POST /avenants/{contratId}/adjonctions/sante/devis`     | à corriger  | chemin conservé. La passerelle plante sur sa propre gestion d'erreur (`DevisAdjonctionSanteResponseDTO.error` typé `int`, amont `"409 :"`) et masque le refus métier (#29). La cible **retire** `status` / …      | #29, #42, #39      |
| `POST /avenants/{contratId}/adjonctions/sante`           | à corriger  | chemin conservé, même corps que le devis plus `couponCode` et `consents`. La réponse `{status, error, errorMessage, quittanceid}` devient `AvenantCreated` (#42) avec `quittanceId` et `montant` : c'est ce qui … | #29, #94, #42      |
| `POST /avenants/{contratId}/renouvellements/sante/devis` | à corriger  | chemin conservé. Répond `409 « problem devis Renouvellement Sante »` à **tout** payload, sans nommer de champ ni de raison (#28) ; le renouvellement est le dernier écran de l'application encore alimenté par …  | #28, #42, #39      |
| `POST /avenants/{contratId}/renouvellements/sante`       | à corriger  | chemin conservé, même corps que le devis plus `consents`. Réponse `AvenantCreated` (#42) avec la quittance à régler par `POST /modePaiement/CIB` / `DAHABIA` / Points Verts, comme une souscription. En-tête …    | #28, #42           |

#### Sinistres

| Endpoint                             | État actuel | Écart                                                                                                                                                                                                               | Ticket(s)          |
| ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `GET /claims`                        | à corriger  | chemin conservé. `page` devient **optionnel** (défaut 0) — aujourd'hui `500 « Required request parameter 'page' »` sans lui — et l'enveloppe est la page unique (#33). Chaque ligne porte un `id` (déjà livré) …    | #33, #39, #40      |
| `POST /claims`                       | à corriger  | chemin conservé, `multipart/form-data`. Aujourd'hui **aucune entrée n'aboutit** : la validation passe puis `500 « Attempt to read property "produit_sinistre_id" on null »` pour toute valeur de `produit` (#87 …   | #87, #37, #12, #39 |
| `GET /claims/{demandeId}`            | à corriger  | chemin conservé. Le bloc `contrat` (titre, période, numéro de police) est ajouté — aujourd'hui `contrat` est une chaîne ; `etats[]` (chronologie, vide en pré-production) est le même objet que `GET …              | #39, #40           |
| `GET /claims/{demandeId}/etats`      | manquant    | aucun endpoint ; `etats` du détail est toujours vide en pré-production. L'écran « Suivi de sinistre » affiche une chronologie (`timeline` dans `SinistreTracking`) avec, par étape, une date, un titre, un état …   | —                  |
| `GET /claims/{demandeId}/documents`  | à corriger  | chemin conservé ; répond `404` aujourd'hui. Le `DocsInfoDto` (base64) devient une liste de descripteurs avec `downloadUrl` signée (#4).                                                                             | #4                 |
| `POST /claims/{demandeId}/documents` | manquant    | aucun endpoint ; quand un état `actionRequise` réclame une pièce, l'application n'a nulle part où l'envoyer.                                                                                                        | —                  |
| `GET /chat/history`                  | à corriger  | chemin et curseur conservés (`pageSize`, `beforeId` exclusif, du plus récent au plus ancien). Ajout du paramètre **`sinistreId`** : aujourd'hui le fil est unique par utilisateur, et un message envoyé depuis un … | #11, #39           |
| `POST /chat/send`                    | à corriger  | chemin conservé ; `sinistreId` optionnel ajouté (#11) ; `login` et `senderType` retirés du corps — l'expéditeur est le JWT, un client ne doit jamais pouvoir écrire pour un autre. Répond `201` (la spécification … | #11                |
| `POST /chat/read`                    | à corriger  | chemin et `204` conservés ; `readerType` retiré (c'est toujours l'adhérent connecté qui lit), `sinistreId` optionnel ajouté (#11).                                                                                  | #11                |

#### Remboursements

| Endpoint                             | État actuel | Écart                                                                                                                                                                                                             | Ticket(s)               |
| ------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `GET /refunds`                       | à corriger  | chemin conservé, page unique base 0 avec `page` optionnel (#33). Chaque ligne porte un bloc `acte{codeActe, libelle, groupeId, categorie}` distinct de la ligne de produit — aujourd'hui `type` mélange « …       | #33, #88, #93, #39      |
| `POST /refunds`                      | à corriger  | chemin conservé, `multipart/form-data`. Les parties sont **déclarées** (#37) : `codeActe` (et non `type`, renommé sans préavis — #19, clos), `ayantDroitId`, `dateSoins` en ISO (#39), `montant`, puis \*\*une …  | #19, #37, #12, #42, #39 |
| `GET /refunds/{refundId}`            | à corriger  | chemin conservé. Le détail renvoie aujourd'hui la même ligne plate que la liste : la cible ajoute le bloc `contrat` (titre, période, numéro de police), `etats[]` (chronologie `SuiviStatutRefundDto`, vide en …  | #57, #39                |
| `GET /refunds/{refundId}/documents`  | à corriger  | chemin conservé ; répondait `200` avant le 03/08/2026, `404 « Aucun fichier valide trouvé »` depuis (#57). La spécification lui déclare par erreur un corps de requête `AddRemboursementDto` : retiré. Le …       | #57, #4                 |
| `POST /refunds/{refundId}/documents` | manquant    | aucun endpoint. Quand un remboursement est retourné pour pièce (`RETOUR`, `actionRequise: true`, Q6 #93), l'adhérent doit pouvoir déposer la pièce manquante sans recréer la demande. `type` reprend le nom de …  | #93                     |
| `GET /actes/groups`                  | à corriger  | chemin conservé ; la page Spring réduite devient un **tableau** (référentiel non paginé, 5 groupes / 27 actes). Chaque acte porte une `category` stable, un `categoryLabel` localisé, une clé `illustration` et … | #56, #49                |

#### Santé (profil, membres, documents)

| Endpoint                                                 | État actuel | Écart                                                                                                                                                                                                                                           | Ticket(s)               |
| -------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `GET /members`                                           | à corriger  | chemin conservé. Corrections et ajouts : · `policeId` — déjà livré en camelCase (renommage constaté le 28/09, #40) ; dates ISO (#39) ; · `questionnaire` : réponses **booléennes** (`bonneSante: true`) au lieu des chaînes `"Oui"` / `"Non"` … | #18, #89, #40, #39, #47 |
| `PUT /members`                                           | à corriger  | chemin conservé. Aujourd'hui un **remplacement complet** non documenté (`422` listant tous les autres champs), un bloc `questionnaire` que la spécification nomme `bonneSanteQuestion`, des réponses en chaînes …                               | #18, #39                |
| `POST /members/validation`                               | à corriger  | chemin et corps conservés. `declare: false` produit le même effet que `true` : la cible **honore** le drapeau (`400` si `false`) (#38). La réponse porte l'état de validation et le bulletin d'adhésion à signer …                              | #38                     |
| `POST /members/addPieceJointe`                           | à corriger  | chemin conservé. Les six parties ont été établies par sondage le 26/09 (#13) : la cible les **déclare** (#37), en camelCase, et **aucune n'est exigée à chaque appel** — aujourd'hui `rib` + `justificatifRib` …                                | #13, #37, #12           |
| `GET /members/documents`                                 | à corriger  | chemin conservé ; la spécification déclare un `DocumentDTO` unique et le serveur répond `[]` : la cible renvoie une liste de descripteurs, un par `type` de pièce (`justificatifRib`, `bulletinAdhesion` …                                      | #4                      |
| `GET /members/bulletinAdhesion`                          | à corriger  | chemin conservé. Répond `500` puis ne répond plus au-delà de 12 s (#15). Le `DocumentDTO {fileName, mimeType, downloadUrl}` est le bon contrat, à condition que `downloadUrl` soit **ouvrable sans en-tête** (URL …                             | #15, #4                 |
| `GET /members/bulletinSoins`                             | à corriger  | chemin conservé ; le PDF encodé en base64 dans `{filename, mime, fichier}` devient le même descripteur que le bulletin d'adhésion (URL signée, #4) ou le binaire selon `Accept`.                                                                | #4                      |
| `GET /members/tiers-payant-card`                         | manquant    | aucun endpoint. La carte est aujourd'hui reconstituée depuis `/members` (numéro = `PoliceId`) et le QR code encode une chaîne inventée par l'application (`AMANA\|TiersPayant\|…`) qu'aucun lecteur ne reconnaît. …                             | #91, #89                |
| `GET /members/dependents/{id}/photo`                     | à corriger  | chemin conservé ; répond `404` ou `500` sur toutes les lignes du compte de test, la partie `photo` de `POST /ayantDroits` étant acceptée puis jetée (#86). Cible : `200` binaire, `404` franc sans photo, et …                                  | #86                     |
| `GET /ayantDroits`                                       | à corriger  | chemin conservé, page unique (#33). Ajout de `removalRequested` / `removalRequestedAt` : après une demande de retrait, l'ayant droit continue d'apparaître sans aucun indicateur et l'application garde l'état « …                              | #47, #39, #27           |
| `POST /ayantDroits`                                      | à corriger  | chemin conservé, `multipart/form-data`. Les parties sont **plates** (`nom`, `prenom`, …) et non indexées `ayantsDroits[0].nom` — un corps mal formé répond `400` nommant la partie et non un `500` nu (#85, #14) …                              | #85, #86, #14, #27, #39 |
| `POST /ayantDroits/{ayantDroitId}/demandeSuppression`    | à corriger  | chemin conservé, méthode **`POST`** au lieu de `DELETE` (un `DELETE` avec corps multipart est mal supporté par les clients HTTP, et la demande n'est pas une suppression immédiate). Aujourd'hui `500` page …                                   | #79, #47, #62           |
| `PUT /ayantDroits/{ayantDroitId}/demandeChangementPhoto` | à corriger  | chemin et partie `photo` conservés ; répond `500` aujourd'hui (#86). Cible : `200` avec la ligne mise à jour et sa nouvelle `photoUrl`.                                                                                                         | #86                     |
| `GET /beneficiaries`                                     | à corriger  | chemin conservé, page unique base 0 (#33 — aujourd'hui base 1 ici). `sexe` et `telephone` sont **persistés** (exigés à la création puis relus à `null`, #80) ; dates ISO (#39) ; `lienParente` étendu à …                                       | #33, #80, #39, #27      |
| `POST /beneficiaries`                                    | à corriger  | chemin et tableau conservés. `dateNaissance` en ISO — aujourd'hui seule la forme compacte `yyyyMMdd`, documentée nulle part, passe, et l'endpoint relit `DD/MM/YYYY` (#32, #39) ; énumérations `sexe` / …                                       | #32, #27, #80, #39      |
| `PUT /beneficiaries`                                     | manquant    | aucun endpoint. L'écran édite la liste **comme un tout** (mode de désignation + lignes + parts) ; l'application diffère aujourd'hui en « créer puis supprimer » sans transaction, et la part saisie n'est jamais …                              | #26                     |
| `DELETE /beneficiaries/{beneficiaireId}`                 | existant    | Identique à l'API actuelle (`204`, `404 « le beneficiaire n'est pas trouvé »` propre — la forme de `404` que les autres endpoints doivent suivre,                                                                                               | —                       |
| `PUT /beneficiaries/updateTaux`                          | existant    | Identique à l'API actuelle. La règle « la somme des taux doit être égale à 100 % » est **documentée ici** (`409 TAUX_SUM_INVALID`, #26) ; le compte de pré-production doit être réamorcé pour la satisfaire. Voir …                             | #26                     |

#### Paiement (CIB, Edahabia, Points Verts, livraison)

| Endpoint                                     | État actuel | Écart                                                                                                                                                                                                               | Ticket(s)         |
| -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `POST /modePaiement/CIB`                     | à corriger  | chemin et corps conservés. Ajout de **`returnUrl`** : après le 3-D Secure, Satim redirige vers `site-test.amana.dz` (le site vitrine) et non vers l'application, qui n'a aucun signal de fin de paiement (#5) — …   | #5, #59, #42      |
| `POST /modePaiement/DAHABIA`                 | à corriger  | identique à `POST /modePaiement/CIB` — même corps (`returnUrl` ajouté, #5), même réponse, même confirmation ensuite ; seul le réseau de carte diffère. L'`operationId` `payerAvecDhahabia` est celui de la …        | #5, #59, #42      |
| `GET /modePaiement/confirmPayment/{orderId}` | à corriger  | chemin conservé. Aujourd'hui `valid: false` sur un paiement encaissé (l'encaissement suit le retour de Satim de **10 à 30 minutes**), et `404` tant que l'ordre n'est pas traité : l'application relit le contrat … | #6, #39           |
| `GET /points-verts/check-solde`              | à corriger  | chemin conservé ; `{montant, status, errorCode, errorMessage}` devient `{balance, currency, isAvailable}` (#42) — un solde indisponible est `isAvailable: false`, une erreur un `5xx`.                              | #42               |
| `POST /points-verts/paiement/{quittanceId}`  | à corriger  | chemin conservé, méthode **`POST`** au lieu de `GET` — un `GET` qui débite est rejoué par tout rafraîchissement et a été déclenché par un simple balayage en lecture (#7). Aujourd'hui l'appel \*\*débite puis …    | #7, #59           |
| `POST /modePaiement/livraison`               | à corriger  | chemin et champs conservés. `adresse` et `tel` vides sont **refusés** (`400`, #84) ; `livraisonDate` en ISO (#39) ; la réponse `{message}` devient `LivraisonStatus` (#42) avec un `demandeId` et un `status` …     | #84, #8, #39, #42 |
| `GET /modePaiement/livraison/{quittanceId}`  | manquant    | le backend a décrit un `confirmPayment/livraison` qui n'existe dans aucune spécification (#8). Cible : l'état de la demande — `EN_ATTENTE` (créée), `PLANIFIEE` (livreur affecté), `ENCAISSEE` (réglée, contrat …   | #8                |

#### Documents

| Endpoint                               | État actuel | Écart                                                                                                                                                                                                               | Ticket(s)   |
| -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `GET /documents`                       | à corriger  | chemin conservé ; servi à tout compte authentifié (#3, clos). Chaque ligne porte un **`id`** (aucun aujourd'hui, l'application indexe par chemin de fichier) et une **`downloadUrl`** ouvrable par le navigateur …  | #4, #3, #49 |
| `GET /documents/{documentId}/download` | à corriger  | remplace `GET /documents/download?path=<chemin>` (livré le 22/09, mais exigeant le jeton porteur, #4). Route **par identifiant**, acceptant le jeton porteur **ou** la signature de `downloadUrl` (`sig` / `exp`) … | #4          |
| `GET /assets`                          | à corriger  | chemin et paramètre conservés. `path` absent répond `400` (aujourd'hui `500`), fichier absent `404` (#45). Les URL `mediaUrl` des actualités pointent ici, **signées**, pour qu'un composant image puisse les …     | #45         |

#### Agences & Allo Docteur

| Endpoint                      | État actuel | Écart                                                                                                                                                                                                              | Ticket(s) |
| ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `GET /Agence`                 | à corriger  | chemin et filtres conservés (`wilayaId`, `search`). `agenceid` → `id`, `wilayaid{}` → `wilaya{id, libelle}` (#40). `horaires`, chaîne libre vide en pré-production, devient un tableau structuré `{jours …         | #40       |
| `GET /alloDocteur`            | à corriger  | chemin conservé. `medecinid` → `id` (#40) ; ajout de `wilayaId` (l'écran filtre par wilaya en comparant des libellés aujourd'hui) et de `cabinet` (sans source). Filtres optionnels `specialiteId` et `wilayaId` … | #40       |
| `GET /alloDocteur/Specialite` | à corriger  | chemin conservé ; `specialitesanteid` → `id` (#40), champs internes (`remarque`, `actif`, `userid`) retirés, libellé localisé (#49).                                                                               | #40, #49  |

#### Notifications

| Endpoint                                    | État actuel | Écart                                                                                                                                                                                                          | Ticket(s)          |
| ------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `GET /notifications`                        | à corriger  | chemin conservé, page unique (#33). Ajout de **`category`** en énumération fermée — l'écran filtre en quatre familles et l'application déduit aujourd'hui la famille du préfixe de l'`id` (`sh_`, `ap_`), un … | #77, #33, #39, #49 |
| `GET /notifications/unread-count`           | manquant    | répond `404` (#43). Le badge est aujourd'hui compté sur la première page du fil (`size=50`) dans quatre écrans, donc plafonné par la taille de page.                                                           | #43                |
| `POST /notifications/{notificationId}/open` | manquant    | aucun endpoint ; `unOpened` ne peut jamais passer à `false` depuis l'application, le badge ne décroît donc pas.                                                                                                | #43                |

#### Contenu

| Endpoint                         | État actuel | Écart                                                                                                                                                                                                            | Ticket(s)     |
| -------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `GET /a-propos-amana/actualites` | à corriger  | chemin et champs conservés (déjà camelCase). `datePublication` en ISO (#39) ; `pathMedia` → `mediaUrl`, URL **signée** ouvrable par un composant image ; `typeMedia` → `mediaType`. Il n'existe pas de `GET …    | #39, #49      |
| `GET /a-propos-amana/decouvrir`  | à corriger  | chemin conservé ; `path_media` / `type_media` → `mediaUrl` (signée) / `mediaType` (#40). Localisé (#49).                                                                                                         | #40, #49      |
| `GET /a-propos-amana/sos`        | à corriger  | chemin et champs conservés. Ajout de `type` (`PHONE \| NOTE`) : une ligne de prose (horaires du service client) est mêlée aux numéros et l'application la filtre en cherchant une lettre dans `value`. Contenu … | #49           |
| `POST /nousContacter`            | à corriger  | chemin conservé, `multipart/form-data`. `nom`, `email`, `tel` sont **retirés** : l'expéditeur est résolu par le JWT (l'écran ne les collecte pas) ; `sujet` devient une énumération documentée ; une partie …    | #37, #42, #12 |

## 8. Conventions

1. **Une enveloppe d'erreur** : `ServerError {status, error, message, path, timestamp}`,
   plus `code` (machine, stable, à traduire côté client) et `fields` (règle violée par
   champ ou partie multipart). Codes HTTP constants : `400` validation · `401` jeton
   absent/expiré · `403` interdit · `404` inconnu · `409` conflit métier · `413` fichier
   trop volumineux · `422` donnée sémantiquement invalide · `429` anti-abus · `500`
   inattendu. **Jamais** de `200` portant `status: false`, jamais de chemin de service
   interne dans un message. Exception assumée : `419` et `420` de `POST /auth/login`,
   déjà consommés par l'application, désormais **déclarés** avec `AuthChallenge`.
2. **camelCase partout**, y compris dans les objets imbriqués ; un identifiant est un
   entier `int64` (les identifiants de notification restent des chaînes opaques).
3. **Dates ISO-8601** : `yyyy-MM-dd` (`format: date`) pour un jour, RFC 3339
   (`format: date-time`, UTC) pour un instant. Aucun `DD/MM/YYYY`, aucun `yyyyMMdd`,
   aucune époque en millisecondes, `null` plutôt que `""`.
4. **Montants** : nombres décimaux arrondis à 2 décimales à la source, toujours
   accompagnés d'un `currency` (`DZD`). Le montant **facturé** est toujours nommé
   (`montantTTC`, `primeTotale`, `montantTotal`, `prime`) et vaut
   `net − réduction + coutPolice + droitTimbre`, sur les quatre produits.
5. **Pagination unique** : `{items, page, size, total}`, `page` base 0, `page=0` et
   `size=20` par défaut, tri déclaré dans la description de l'opération.
6. **Énumérations fermées** et publiées (statuts, sexe, lien de parenté, catégories),
   jamais de chaîne libre pour un état.
7. **Téléversements** : `multipart/form-data`, parties nommées en camelCase et déclarées
   dans le schéma, 10 Mo par fichier, `413` nommant la partie et la limite, `400` sur
   partie manquante (jamais `500`).
8. **Téléchargements** : le binaire avec `Content-Disposition`, ou le descripteur
   `{fileName, mimeType, downloadUrl}` quand l'application affiche avant de télécharger ;
   `downloadUrl` est **signée et temporaire** (`sig`, `exp`) et s'ouvre **sans** en-tête
   `Authorization` — le navigateur du téléphone et les composants image n'en envoient pas.
   Négociation de contenu par `Accept` là où les deux formes existent.
9. **Localisation** : `Accept-Language: fr | ar` honoré sur tout contenu éditorial et tout
   libellé (produits, garanties, actes, SOS, documents, notifications).
10. **Idempotence** : les écritures du tunnel (`/souscriptions*`, `/avenants/*`,
    `/modePaiement/*`, `/points-verts/paiement/*`) acceptent un en-tête `Idempotency-Key`
    (UUID) ; le rejeu d'une même clé renvoie la réponse initiale sans recréer.
11. **Identité résolue par le JWT** : aucune écriture ne prend le `login`, le
    `personneId` ou le `souscripteur` de l'appelant dans son corps.
12. **Méthodes** : une opération qui change un état est `POST` / `PUT` / `PATCH` /
    `DELETE`, jamais `GET`.
13. **Un exemple de requête fonctionnelle par opération d'écriture** (#41), dans la
    spécification (`example`) et rejouable en `curl` : un corps qui passe la validation en
    pré-production, avec les parties multipart nommées ; les `required` déclarés sont ceux
    que le validateur applique (#63).
14. **Jeton au moindre privilège** (#60) : le JWT d'un client ne porte que `user_type` et
    les claims d'identité (`personne_id`, `adherent_sante_id`, `user_sante_id`) — aucun rôle
    de back-office ; la documentation (`/api-docs`) est lisible avec ce jeton, ou publiée.
15. **Environnement de recette stable** (#74) : purge sur préavis, comptes et contrats de
    référence réamorçables, un compte distinct pour les tests du backend.

---

_Spécification et README rédigés le 27/09/2026 à partir de `app/api/types.ts`,
`app/api/generated.ts`, `app/api/api-prepar/api-doc-live.json`, des adaptateurs et des
registres de tickets du dépôt `amana-mobile`._
