Documents du Bénéficiaire

Pièces d'identité et justificatifs rattachés à un bénéficiaire. Toutes les routes sont imbriquées sous le bénéficiaire et demandent la permission registre.documents.

Méthode	Endpoint	Description
GET	/api/beneficiaires/{beneficiaireId}/documents	Liste des documents
POST	/api/beneficiaires/{beneficiaireId}/documents	Téléverser un document
GET	/api/beneficiaires/{beneficiaireId}/documents/types	Types de documents acceptés
GET	/api/beneficiaires/{beneficiaireId}/documents/{documentId}	Métadonnées d'un document
GET	/api/beneficiaires/{beneficiaireId}/documents/{documentId}/download	Télécharger le fichier
POST	/api/beneficiaires/{beneficiaireId}/documents/{documentId}/verify	Vérifier le document
POST	/api/beneficiaires/{beneficiaireId}/documents/{documentId}/reject	Rejeter le document
DELETE	/api/beneficiaires/{beneficiaireId}/documents/{documentId}	Supprimer le document

Un bénéficiaire ou un document introuvable renvoie 404 ({"error": "Beneficiaire non trouve"} ou Document non trouve).

GET /api/beneficiaires/{beneficiaireId}/documents

Paramètres optionnels : type (type de document) et status (pending, verified, rejected). Les documents supprimés sont exclus.

{
    "success": true,
    "data": [
        {
            "id": "660e8400-e29b-41d4-a716-446655440001",
            "beneficiaireId": "550e8400-e29b-41d4-a716-446655440000",
            "type": "cni",
            "typeLabel": "Carte Nationale d'Identite",
            "originalFilename": "cni.pdf",
            "mimeType": "application/pdf",
            "fileSize": 245760,
            "fileSizeFormatted": "240.00 KB",
            "verificationStatus": "verified",
            "verifiedAt": "2026-01-20 14:30:00",
            "verifiedBy": "Agent Exemple",
            "rejectionReason": null,
            "notes": null,
            "expiryDate": "2030-06-15",
            "isExpired": false,
            "uploadedBy": "Agent Exemple",
            "createdAt": "2026-01-15 10:30:00",
            "updatedAt": null
        }
    ],
    "total": 1
}

Types de documents

Type	Description
cni	Carte Nationale d'Identité
certificat_residence	Certificat de Résidence
acte_naissance	Acte de Naissance
photo	Photo d'Identité
certificat_scolaire	Certificat de Scolarité
certificat_medical	Certificat Médical
justificatif_revenu	Justificatif de Revenu
contrat_signe	Contrat Signé
autre	Autre Document

La liste à jour est renvoyée par GET /api/beneficiaires/{beneficiaireId}/documents/types.

POST /api/beneficiaires/{beneficiaireId}/documents

Envoi en multipart/form-data.

Champ	Type	Requis	Description
file	file	Oui	Fichier (PDF, JPEG, PNG ou WebP, 10 Mo au plus)
type	string	Oui	Type de document (liste ci-dessus)
expiryDate	date	Non	Date d'expiration (AAAA-MM-JJ)
notes	string	Non	Notes complémentaires

Réponse 201 Created : { "success": true, "message": "Document uploade avec succes", "data": { … } }. Un fichier absent, un type inconnu, un format ou une taille refusés renvoient 400.

curl -X POST https://sig.example.com/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000/documents \
  -H "Authorization: Bearer TOKEN" \
  -F "type=cni" \
  -F "file=@/chemin/vers/cni.pdf" \
  -F "expiryDate=2030-06-15"

POST …/documents/{documentId}/verify

Corps optionnel : { "notes": "…" }. Passe le document en verified. Un document déjà vérifié ou rejeté renvoie 400 Document deja traite.

POST …/documents/{documentId}/reject

{ "reason": "Document illisible, merci d'envoyer une copie plus nette" }

reason est obligatoire (400 Motif de rejet requis). Même règle que la vérification pour un document déjà traité.

DELETE …/documents/{documentId}

Suppression logique : le document disparaît des listes mais le fichier est conservé. Un administrateur peut forcer la suppression physique avec ?hard=true ; pour les autres rôles le paramètre est ignoré.

Réponse : { "success": true, "message": "Document supprime" }.

Exemple JavaScript

const base = (id) => `https://sig.example.com/api/beneficiaires/${id}/documents`;
const headers = { Authorization: `Bearer ${token}` };

const { data } = await (await fetch(base(beneficiaireId), { headers })).json();

const form = new FormData();
form.append('type', 'cni');
form.append('file', fichier);
await fetch(base(beneficiaireId), { method: 'POST', headers, body: form });

await fetch(`${base(beneficiaireId)}/${documentId}/reject`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ reason: 'Document illisible' }),
});