Skip to content

Commit e9c331c

Browse files
author
Richard Capraro
committed
docs: Add API doc
1 parent 40880ef commit e9c331c

File tree

2 files changed

+230
-0
lines changed

2 files changed

+230
-0
lines changed

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@ This repository is a multi-module Kotlin/JVM project built with Gradle. It uses:
88

99
Below are the most common developer commands and usage notes.
1010

11+
## API Documentation
12+
13+
- User-facing API homepage (Markdown), including endpoints, headers (`login`, `tenantId`, `X-Gravitee-Api-Key`), curl examples, and error format: see `doc/API.md`.
14+
- Swagger UI (OpenAPI) available at runtime: `GET /swagger`.
15+
1116
## Prerequisites
1217

1318
- JDK 21

‎doc/API.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Page d'accueil de l'API — Connaissance Client
2+
3+
Cette page décrit fonctionnellement l’API « Connaissance Client » (KYC) exposée par le service. Ce n’est pas une spécification OpenAPI, mais une documentation opérationnelle avec des exemples d’appels.
4+
5+
### Définition — API Personne (assurance)
6+
7+
Une API Personne complète dans l’assurance centralise la gestion des données d’identité et de relation d’un assuré: KYC/connaissance client (PPE, proches PPE, niveaux de vigilance), état civil, adresses (postales et électroniques), moyens de contact, liens familiaux/contractuels, consentements et préférences, ainsi que l’historique/audit des mises à jour. Elle fournit des opérations cohérentes et traçables pour alimenter les processus métier (souscription, indemnisation/sinistre, conformité LCB-FT, CRM) tout en respectant la gouvernance des données et la réglementation (RGPD).
8+
9+
Pour l’exploration interactive de la spec OpenAPI: Swagger UI est disponible sur `/swagger` quand l’application tourne en local.
10+
11+
## Objectifs
12+
13+
- Créer/mettre à jour les informations de connaissance client d’une personne
14+
- Consulter les informations actuelles
15+
- Consulter l’historique des modifications
16+
- Vérifier la santé du service
17+
18+
## Base URL
19+
20+
- Local: `http://localhost:8080`
21+
- Exemple d’environnement: `{{baseUrl}} = http://localhost:8080`
22+
23+
## Authentification et en-têtes
24+
25+
- X-Gravitee-Api-Key: clé API fournie par la plateforme d’API Management (Gravitee). À transmettre dans l’en-tête `X-Gravitee-Api-Key` lorsqu’un gateway la requiert. Le service applicatif n’en fait pas le contrôle directement, mais l’appel en production passera via le gateway.
26+
- login (obligatoire): identifiant de l’utilisateur appelant (ex. `dev.user`).
27+
- tenantId (obligatoire): identifiant du tenant/pack (ex. `pack`).
28+
29+
Notes:
30+
- Les en-têtes `login` et `tenantId` sont obligatoires pour toutes les routes métier. En leur absence, l’API retourne `400 Bad Request` avec un `application/problem+json`.
31+
- Les routes `/health`, `/swagger` et `/metrics` ne requièrent pas ces en-têtes.
32+
33+
## Formats
34+
35+
- Content-Type des requêtes JSON: `application/json`
36+
- Content-Type des erreurs: `application/problem+json`
37+
38+
## Endpoints
39+
40+
### 1) Récupérer la connaissance client
41+
42+
- Méthode/URL: `GET /personnes/{idPersonne}/connaissance-client`
43+
- En-têtes requis: `login`, `tenantId` (+ éventuellement `X-Gravitee-Api-Key` via gateway)
44+
- Réponse: 200 avec le JSON de la connaissance client
45+
46+
Exemple curl:
47+
48+
```bash
49+
curl -X GET \
50+
"http://localhost:8080/personnes/1/connaissance-client" \
51+
-H "login: dev.user" \
52+
-H "tenantId: pack" \
53+
-H "X-Gravitee-Api-Key: ${GRAVITEE_KEY}"
54+
```
55+
56+
Exemple de réponse (indicatif):
57+
58+
```json
59+
{
60+
"idPersonne": 1,
61+
"statutPPE": { "mandat": { "fonction": "CHEF_ETAT", "dateFin": null } },
62+
"statutProchePPE": { "lienParente": "CONJOINT", "mandat": { "fonction": "MEMBRE_GOUVERNEMENT", "dateFin": "2030-12-31" } },
63+
"vigilance": { "vigilanceRenforcee": true, "motifs": ["MONTANT_ELEVE", "OPERATION_COMPLEXE"] }
64+
}
65+
```
66+
67+
### 2) Créer ou mettre à jour (modification) la connaissance client
68+
69+
- Méthode/URL: `POST /personnes/{idPersonne}/connaissance-client`
70+
- En-têtes requis: `login`, `tenantId`
71+
- Corps attendu (exemple):
72+
73+
```json
74+
{
75+
"statutPPE": { "mandat": { "fonction": "CHEF_ETAT" } },
76+
"statutProchePPE": {
77+
"lienParente": "CONJOINT",
78+
"mandat": { "fonction": "MEMBRE_GOUVERNEMENT", "dateFin": "2030-12-31" }
79+
},
80+
"vigilance": { "vigilanceRenforcee": true, "motifs": ["MONTANT_ELEVE", "OPERATION_COMPLEXE"] }
81+
}
82+
```
83+
84+
- Réponses possibles:
85+
- `201 Created` avec l’objet envoyé (succès)
86+
- `304 Not Modified` si aucune modification n’a été détectée
87+
- `500 Internal Server Error` avec `application/problem+json` en cas d’erreur métier (ex. vigilance renforcée obligatoire non respectée)
88+
89+
Exemple curl:
90+
91+
```bash
92+
curl -X POST \
93+
"http://localhost:8080/personnes/1/connaissance-client" \
94+
-H "Content-Type: application/json" \
95+
-H "login: dev.user" \
96+
-H "tenantId: pack" \
97+
-d '{
98+
"statutPPE": { "mandat": { "fonction": "CHEF_ETAT" } },
99+
"statutProchePPE": { "lienParente": "CONJOINT", "mandat": { "fonction": "MEMBRE_GOUVERNEMENT", "dateFin": "2030-12-31" } },
100+
"vigilance": { "vigilanceRenforcee": true, "motifs": ["MONTANT_ELEVE", "OPERATION_COMPLEXE"] }
101+
}'
102+
```
103+
104+
### 3) Corriger (correction) la connaissance client
105+
106+
- Méthode/URL: `PUT /personnes/{idPersonne}/connaissance-client`
107+
- En-têtes requis: `login`, `tenantId`
108+
- Corps attendu (exemple):
109+
110+
```json
111+
{
112+
"statutPPE": { "mandat": { "fonction": "CHEF_ETAT" } },
113+
"statutProchePPE": {
114+
"lienParente": "ENFANT",
115+
"mandat": { "fonction": "MEMBRE_GOUVERNEMENT", "dateFin": "2031-12-31" }
116+
},
117+
"vigilance": { "vigilanceRenforcee": true, "motifs": ["AGE_AVANCE"] }
118+
}
119+
```
120+
121+
- Réponses possibles:
122+
- `201 Created` avec l’objet envoyé (succès)
123+
- `500 Internal Server Error` avec `application/problem+json` en cas d’erreur métier
124+
125+
Exemple curl:
126+
127+
```bash
128+
curl -X PUT \
129+
"http://localhost:8080/personnes/1/connaissance-client" \
130+
-H "Content-Type: application/json" \
131+
-H "login: dev.user" \
132+
-H "tenantId: pack" \
133+
-d '{
134+
"statutPPE": { "mandat": { "fonction": "CHEF_ETAT" } },
135+
"statutProchePPE": { "lienParente": "ENFANT", "mandat": { "fonction": "MEMBRE_GOUVERNEMENT", "dateFin": "2031-12-31" } },
136+
"vigilance": { "vigilanceRenforcee": true, "motifs": ["AGE_AVANCE"] }
137+
}'
138+
```
139+
140+
### 4) Historique des modifications
141+
142+
- Méthode/URL: `GET /personnes/{idPersonne}/historique-connaissance-client`
143+
- En-têtes requis: `login`, `tenantId`
144+
- Réponse: `200 OK` avec un JSON contenant l’historique (liste d’événements)
145+
146+
Exemple curl:
147+
148+
```bash
149+
curl -X GET \
150+
"http://localhost:8080/personnes/1/historique-connaissance-client" \
151+
-H "login: dev.user" \
152+
-H "tenantId: pack"
153+
```
154+
155+
Exemple de réponse (indicatif):
156+
157+
```json
158+
{
159+
"idPersonne": 1,
160+
"modifications": [
161+
{
162+
"date": "2025-01-01T12:34:56Z",
163+
"type": "MODIFICATION",
164+
"user": "dev.user"
165+
},
166+
{
167+
"date": "2025-02-10T08:10:00Z",
168+
"type": "CORRECTION",
169+
"user": "ops.user"
170+
}
171+
]
172+
}
173+
```
174+
175+
### 5) Santé du service
176+
177+
- `GET /health` (réponse JSON) et `HEAD /health` (statut uniquement)
178+
- En-têtes requis: aucun
179+
- Réponses: `200 OK` si UP, `503 Service Unavailable` sinon
180+
181+
Exemple curl:
182+
183+
```bash
184+
curl -I http://localhost:8080/health
185+
```
186+
187+
## Gestion des erreurs (Problem Details)
188+
189+
Le service renvoie des erreurs au format RFC 9457 (« Problem Details ») avec `Content-Type: application/problem+json`.
190+
191+
Exemple — en-tête manquant:
192+
193+
```http
194+
HTTP/1.1 400 Bad Request
195+
Content-Type: application/problem+json
196+
197+
{
198+
"type": "about:blank",
199+
"status": 400,
200+
"title": "Bad Request",
201+
"detail": "le header login est manquant",
202+
"code": "BAD_REQUEST"
203+
}
204+
```
205+
206+
## Swagger UI / OpenAPI
207+
208+
- UI: `GET /swagger`
209+
- Fichier OpenAPI: `rest/src/main/resources/openapi/documentation.yaml`
210+
211+
## Exemples rapides avec variables d’environnement
212+
213+
```bash
214+
export BASE_URL=http://localhost:8080
215+
export LOGIN=dev.user
216+
export TENANT=pack
217+
export GRAVITEE_KEY=xxxxx # si requis par le gateway
218+
219+
curl -H "login: $LOGIN" -H "tenantId: $TENANT" -H "X-Gravitee-Api-Key: $GRAVITEE_KEY" "$BASE_URL/personnes/1/connaissance-client"
220+
```
221+
222+
## Remarques
223+
224+
- Les exemples de corps de requête proviennent des fichiers `.http` du projet.
225+
- Les valeurs de code métier (fonctions, motifs de vigilance, etc.) doivent respecter les énumérations attendues par le service.

0 commit comments

Comments
 (0)