📘 Documentation API – Pièces Attendues du Portail Clients du CAM

1. Introduction

Cette documentation présente l'API pour la gestion des Pièces Attendues dans le cadre des liasses documentaires du Portail Clients du CAM. Elle couvre les opérations de téléversement (upload), de téléchargement (download) des fichiers associés à une pièce, et la mise à jour de leur statut.

• Objectif : Fournir un guide technique pour l'intégration avec les services de gestion de fichiers des pièces attendues.
• Audience : Développeurs front-end, partenaires techniques.
• Version : v1

2. Informations Générales

• Base URL : https://[URL_DE_BASE_DE_VOTRE_API]/
• Protocoles : HTTPS
• Format : JSON pour les métadonnées, multipart/form-data pour le téléversement.
• Authentification : Bearer Token (JWT)

3. Authentification

L'accès à ces points de terminaison requiert un jeton d'authentification valide, qui doit être inclus dans l'en-tête Authorization de chaque requête. Les permissions spécifiques sont détaillées pour chaque endpoint.

Headers :

Authorization: Bearer <token>

4. Endpoints Pièce Attendue

Cette section détaille les points de terminaison pour la gestion des fichiers des pièces attendues.

📥 Téléverser un fichier pour une pièce attendue

Permet de téléverser un fichier pour une pièce spécifique. Le fichier subit une analyse antivirus et une compression avant d'être stocké. Le statut de la pièce est mis à jour en conséquence.

POST /api/app/piece-attendue/{id}/upload-fichier-piece

Permissions requises : PortailClients.Liasses.Default

Paramètres URL :

Paramètre	Type	Description
id	Guid	L'identifiant unique de la pièce attendue.

Headers :

Authorization: Bearer <token>
Content-Type: multipart/form-data

Corps de la requête (form-data) :

Clé	Type	Description
file	File	Le fichier à téléverser pour la pièce attendue.

Réponse (200 OK) :

Retourne les métadonnées de la pièce attendue mise à jour après le téléversement.

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "statut": "Déposée",
  "motif": null,
  "nomFichier": "identite_client.pdf",
  "lienFichier": "/api/app/piece-attendue/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/fichier-piece"
}

📤 Télécharger le fichier d'une pièce attendue

Récupère le fichier associé à une pièce attendue pour le téléchargement.

GET /api/app/piece-attendue/{id}/fichier-piece

Permissions requises : PortailClients.Liasses.Default

Paramètres URL :

Paramètre	Type	Description
id	Guid	L'identifiant unique de la pièce attendue.

Headers :

Authorization: Bearer <token>

Réponse (200 OK) :

Retourne le flux du fichier (application/octet-stream ou un type MIME spécifique) avec les en-têtes appropriés pour le téléchargement.

Content-Disposition: attachment; filename="identite_client.pdf"
Content-Type: application/pdf
Content-Length: 123456

✏️ Mettre à jour le statut d'une pièce attendue

Permet de modifier le statut d'une pièce attendue (par exemple, pour la valider, l'invalider ou la déroger).

PUT /api/app/piece-attendue/{id}/statut

Permissions requises : PortailClients.Liasses.ValiderPiece

Paramètres URL :

Paramètre	Type	Description
id	Guid	L'identifiant unique de la pièce attendue.

Headers :

Authorization: Bearer <token>
Content-Type: application/json

Corps de la requête (JSON) :

{
  "statut": "Valide",
  "motif": "Le document est conforme."
}

Réponse (200 OK) :

Retourne les métadonnées de la pièce attendue mise à jour.

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "statut": "Valide",
  "motif": "Le document est conforme.",
  "nomFichier": "identite_client.pdf",
  "lienFichier": "/api/app/piece-attendue/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/fichier-piece"
}

5. Modèles de Données

PieceAttendueDto

Représente l'objet de transfert de données pour une pièce attendue.

Champ	Type	Description
id	Guid	L'identifiant unique de la pièce attendue.
statut	string	Le statut actuel de la pièce (ex: "Attendue", "Déposée", "Valide").
motif	string	Un motif associé au statut (ex: la raison d'un rejet ou d'une infection par virus).
nomFichier	string	Le nom du fichier qui a été téléversé.
lienFichier	string	L'URL relative pour télécharger le fichier associé.

UpdateStatutPieceDto

Utilisé pour la mise à jour du statut d'une pièce.

Champ	Type	Description
statut	string	Le nouveau statut de la pièce (ex: "Valide", "Invalide", "Derogee").
motif	string	Le motif justifiant le changement de statut.

6. Gestion des Erreurs

Code HTTP	Signification	Détail
400	Requête incorrecte	Le nom du fichier est manquant, le statut de la pièce ne permet pas le téléversement, ou le fichier est détecté comme infecté.
401	Non autorisé	Token invalide, manquant ou expiré.
403	Interdit	L'utilisateur n'a pas les permissions requises (PortailClients.Liasses.Default ou PortailClients.Liasses.ValiderPiece).
404	Ressource non trouvée	La pièce attendue avec l'ID spécifié n'existe pas.
500	Erreur serveur	Une erreur interne est survenue (ex: échec de la communication avec l'antivirus, S3, etc.).

7. Sécurité

• Toutes les requêtes doivent être effectuées via HTTPS.
• L'authentification est gérée par des tokens JWT.
• Les permissions sont rigoureusement vérifiées côté serveur avant chaque opération.
• Une analyse antivirus est systématiquement effectuée sur tous les fichiers téléversés.

8. Changelog

v1.1.0 (Date de mise à jour)

• Ajout de l'endpoint pour la mise à jour du statut d'une pièce :
  • PUT /api/app/piece-attendue/{id}/statut

v1.0.0 (Date de création)

• Création des endpoints pour la gestion des fichiers des pièces attendues :
  • POST /api/app/piece-attendue/{id}/upload-fichier-piece : Téléverser un fichier.
  • GET /api/app/piece-attendue/{id}/fichier-piece : Télécharger un fichier.

9. Annexes

• 🔗 Swagger UI : https://[URL_DE_BASE_DE_VOTRE_API]/swagger/index.html
• 📦 Postman Collection : PortailClients API.postman_collection.json
• 📧 Contact support : // TODO