Documentos do Beneficiário

Documentos de identidade e comprovativos ligados a um beneficiário. Todas as rotas estão aninhadas sob o beneficiário e exigem a permissão registre.documents.

Método	Endpoint	Descrição
GET	/api/beneficiaires/{beneficiaireId}/documents	Lista dos documentos
POST	/api/beneficiaires/{beneficiaireId}/documents	Carregar um documento
GET	/api/beneficiaires/{beneficiaireId}/documents/types	Tipos de documentos aceites
GET	/api/beneficiaires/{beneficiaireId}/documents/{documentId}	Metadados de um documento
GET	/api/beneficiaires/{beneficiaireId}/documents/{documentId}/download	Descarregar o ficheiro
POST	/api/beneficiaires/{beneficiaireId}/documents/{documentId}/verify	Verificar o documento
POST	/api/beneficiaires/{beneficiaireId}/documents/{documentId}/reject	Rejeitar o documento
DELETE	/api/beneficiaires/{beneficiaireId}/documents/{documentId}	Eliminar o documento

Um beneficiário ou documento inexistente devolve 404 ({"error": "Beneficiaire non trouve"} ou Document non trouve).

GET /api/beneficiaires/{beneficiaireId}/documents

Parâmetros opcionais: type (tipo de documento) e status (pending, verified, rejected). Os documentos eliminados são excluídos.

{
    "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
}

Tipos de documentos

Tipo	Descrição
cni	Bilhete de Identidade
certificat_residence	Certificado de Residência
acte_naissance	Certidão de Nascimento
photo	Fotografia de Identidade
certificat_scolaire	Certificado de Escolaridade
certificat_medical	Certificado Médico
justificatif_revenu	Comprovativo de Rendimento
contrat_signe	Contrato Assinado
autre	Outro Documento

A lista atualizada é devolvida por GET /api/beneficiaires/{beneficiaireId}/documents/types.

POST /api/beneficiaires/{beneficiaireId}/documents

Envio em multipart/form-data.

Campo	Tipo	Obrigatório	Descrição
file	file	Sim	Ficheiro (PDF, JPEG, PNG ou WebP, no máximo 10 MB)
type	string	Sim	Tipo de documento (lista acima)
expiryDate	date	Não	Data de validade (AAAA-MM-DD)
notes	string	Não	Notas complementares

Resposta 201 Created: { "success": true, "message": "Document uploade avec succes", "data": { … } }. Ficheiro ausente, tipo desconhecido, formato ou tamanho recusados devolvem 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

Corpo opcional: { "notes": "…" }. Passa o documento a verified. Um documento já verificado ou rejeitado devolve 400 Document deja traite.

POST …/documents/{documentId}/reject

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

reason é obrigatório (400 Motif de rejet requis). Mesma regra que a verificação para um documento já tratado.

DELETE …/documents/{documentId}

Eliminação lógica: o documento desaparece das listas, mas o ficheiro é conservado. Um administrador pode forçar a eliminação física com ?hard=true; para os outros perfis o parâmetro é ignorado.

Resposta: { "success": true, "message": "Document supprime" }.

Exemplo 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' }),
});