Documentos do Beneficiario

Endpoints para gerir os documentos de identidade e comprovativos dos beneficiarios.

GET /api/beneficiaires/{id}/documents

Obtem a lista de documentos de um beneficiario.

Endpoint

GET /api/beneficiaires/{id}/documents

Cabecalhos

Cabecalho	Valor	Obrigatorio
Authorization	Bearer {token}	Sim

Resposta de Sucesso

Codigo: 200 OK

{
    "@context": "/api/contexts/BeneficiaireDocument",
    "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000/documents",
    "@type": "hydra:Collection",
    "hydra:totalItems": 3,
    "hydra:member": [
        {
            "@id": "/api/beneficiaire_documents/660e8400-e29b-41d4-a716-446655440001",
            "@type": "BeneficiaireDocument",
            "id": "660e8400-e29b-41d4-a716-446655440001",
            "type": "cni",
            "typeLabel": "Carte Nationale d'Identité",
            "originalFilename": "cni_fatou_diallo.pdf",
            "mimeType": "application/pdf",
            "fileSize": 245760,
            "fileSizeFormatted": "240.00 KB",
            "verificationStatus": "verified",
            "verifiedAt": "2024-01-20T14:30:00+00:00",
            "verifiedBy": "Admin PCH",
            "rejectionReason": null,
            "expiryDate": "2030-06-15",
            "isExpired": false,
            "uploadedBy": "Agent Terrain 1",
            "createdAt": "2024-01-15T10:30:00+00:00"
        },
        {
            "@id": "/api/beneficiaire_documents/660e8400-e29b-41d4-a716-446655440002",
            "@type": "BeneficiaireDocument",
            "id": "660e8400-e29b-41d4-a716-446655440002",
            "type": "photo",
            "typeLabel": "Photo d'Identité",
            "originalFilename": "photo_fatou.jpg",
            "mimeType": "image/jpeg",
            "fileSize": 102400,
            "fileSizeFormatted": "100.00 KB",
            "verificationStatus": "verified",
            "verifiedAt": "2024-01-20T14:35:00+00:00",
            "verifiedBy": "Admin PCH",
            "rejectionReason": null,
            "expiryDate": null,
            "isExpired": false,
            "uploadedBy": "Agent Terrain 1",
            "createdAt": "2024-01-15T10:32:00+00:00"
        }
    ]
}

Tipos de Documentos

Tipo	Descricao
cni	Bilhete de Identidade
certificat_residence	Certificado de Residencia
acte_naissance	Certidao de Nascimento
photo	Fotografia de Identidade
certificat_scolaire	Certificado de Escolaridade
certificat_medical	Certificado Medico
justificatif_revenu	Comprovativo de Rendimentos
autre	Outro Documento

Estados de Verificacao

Estado	Descricao
pending	A aguardar verificacao
verified	Documento verificado e validado
rejected	Documento rejeitado

---

POST /api/beneficiaire_documents

Carrega um novo documento para um beneficiario.

Endpoint

POST /api/beneficiaire_documents

Cabecalhos

Cabecalho	Valor	Obrigatorio
Authorization	Bearer {token}	Sim
Content-Type	multipart/form-data	Sim

Corpo do Pedido (multipart)

Campo	Tipo	Obrigatorio	Descricao
beneficiaire	IRI	Sim	Referencia ao beneficiario
type	string	Sim	Tipo de documento
file	file	Sim	Ficheiro a carregar
expiryDate	date	Nao	Data de validade
notes	string	Nao	Notas adicionais

Formatos Aceites

• PDF: application/pdf
• JPEG: image/jpeg, image/jpg
• PNG: image/png
• WebP: image/webp

Tamanho maximo: 10 MB

Resposta de Sucesso

Codigo: 201 Created

{
    "@id": "/api/beneficiaire_documents/660e8400-e29b-41d4-a716-446655440003",
    "@type": "BeneficiaireDocument",
    "id": "660e8400-e29b-41d4-a716-446655440003",
    "type": "cni",
    "originalFilename": "cni_nouveau.pdf",
    "mimeType": "application/pdf",
    "fileSize": 512000,
    "verificationStatus": "pending",
    "createdAt": "2024-06-20T09:00:00+00:00"
}

Exemplo cURL

curl -X POST https://sig.ucp-pch.org/api/beneficiaire_documents \
  -H "Authorization: Bearer TOKEN" \
  -F "beneficiaire=/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000" \
  -F "type=cni" \
  -F "file=@/path/to/cni.pdf" \
  -F "expiryDate=2030-06-15"

---

POST /api/beneficiaire_documents/{id}/verify

Verifica (valida) um documento.

Endpoint

POST /api/beneficiaire_documents/{id}/verify

Resposta de Sucesso

Codigo: 200 OK

{
    "@id": "/api/beneficiaire_documents/660e8400-e29b-41d4-a716-446655440003",
    "verificationStatus": "verified",
    "verifiedAt": "2024-06-20T10:00:00+00:00",
    "verifiedBy": "Admin PCH"
}

Exemplo cURL

curl -X POST https://sig.ucp-pch.org/api/beneficiaire_documents/660e8400-e29b-41d4-a716-446655440003/verify \
  -H "Authorization: Bearer TOKEN"

---

POST /api/beneficiaire_documents/{id}/reject

Rejeita um documento com motivo.

Endpoint

POST /api/beneficiaire_documents/{id}/reject

Corpo do Pedido

{
    "reason": "Document illisible, veuillez renvoyer une copie de meilleure qualité"
}

Resposta de Sucesso

Codigo: 200 OK

{
    "@id": "/api/beneficiaire_documents/660e8400-e29b-41d4-a716-446655440003",
    "verificationStatus": "rejected",
    "verifiedAt": "2024-06-20T10:00:00+00:00",
    "rejectionReason": "Document illisible, veuillez renvoyer une copie de meilleure qualité"
}

---

DELETE /api/beneficiaire_documents/{id}

Elimina um documento (eliminacao logica).

Endpoint

DELETE /api/beneficiaire_documents/{id}

Resposta de Sucesso

Codigo: 204 No Content

---

Exemplos Completos

JavaScript

// Obter os documentos de um beneficiario
const getDocuments = async (beneficiaireId) => {
    const response = await fetch(
        `https://sig.ucp-pch.org/api/beneficiaires/${beneficiaireId}/documents`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );
    return response.json();
};

// Carregar um documento
const uploadDocument = async (beneficiaireId, file, type, expiryDate = null) => {
    const formData = new FormData();
    formData.append('beneficiaire', `/api/beneficiaires/${beneficiaireId}`);
    formData.append('type', type);
    formData.append('file', file);
    if (expiryDate) {
        formData.append('expiryDate', expiryDate);
    }

    const response = await fetch(
        'https://sig.ucp-pch.org/api/beneficiaire_documents',
        {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            },
            body: formData
        }
    );

    if (!response.ok) {
        const error = await response.json();
        throw new Error(error['hydra:description']);
    }

    return response.json();
};

// Verificar um documento
const verifyDocument = async (documentId) => {
    const response = await fetch(
        `https://sig.ucp-pch.org/api/beneficiaire_documents/${documentId}/verify`,
        {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );
    return response.json();
};

// Rejeitar um documento
const rejectDocument = async (documentId, reason) => {
    const response = await fetch(
        `https://sig.ucp-pch.org/api/beneficiaire_documents/${documentId}/reject`,
        {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ reason })
        }
    );
    return response.json();
};

// Utilizacao
const docs = await getDocuments('550e8400-e29b-41d4-a716-446655440000');
console.log(`${docs['hydra:totalItems']} documentos`);

// Carregar com input de ficheiro
const fileInput = document.querySelector('input[type="file"]');
const doc = await uploadDocument(
    '550e8400-e29b-41d4-a716-446655440000',
    fileInput.files[0],
    'cni',
    '2030-12-31'
);
console.log(`Documento carregado: ${doc.id}`);

Python

import requests

class DocumentsAPI:
    def __init__(self, token):
        self.token = token
        self.base_url = 'https://sig.ucp-pch.org/api'
        self.headers = {'Authorization': f'Bearer {token}'}

    def get_documents(self, beneficiaire_id):
        response = requests.get(
            f'{self.base_url}/beneficiaires/{beneficiaire_id}/documents',
            headers=self.headers
        )
        return response.json()

    def upload_document(self, beneficiaire_id, file_path, doc_type, expiry_date=None):
        with open(file_path, 'rb') as f:
            files = {'file': f}
            data = {
                'beneficiaire': f'/api/beneficiaires/{beneficiaire_id}',
                'type': doc_type
            }
            if expiry_date:
                data['expiryDate'] = expiry_date

            response = requests.post(
                f'{self.base_url}/beneficiaire_documents',
                headers=self.headers,
                files=files,
                data=data
            )
        return response.json()

    def verify_document(self, document_id):
        response = requests.post(
            f'{self.base_url}/beneficiaire_documents/{document_id}/verify',
            headers=self.headers
        )
        return response.json()

    def reject_document(self, document_id, reason):
        response = requests.post(
            f'{self.base_url}/beneficiaire_documents/{document_id}/reject',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json={'reason': reason}
        )
        return response.json()

# Utilizacao
api = DocumentsAPI(token)

# Listar documentos
docs = api.get_documents('550e8400-e29b-41d4-a716-446655440000')
for doc in docs['hydra:member']:
    status = 'V' if doc['verificationStatus'] == 'verified' else 'P'
    print(f"{status} {doc['typeLabel']}: {doc['originalFilename']}")

# Carregar um documento
novo = api.upload_document(
    '550e8400-e29b-41d4-a716-446655440000',
    '/path/to/cni.pdf',
    'cni',
    '2030-06-15'
)
print(f"Carregado: {novo['id']}")

# Verificar o documento
api.verify_document(novo['id'])

Notas

• Os documentos sao armazenados de forma segura no servidor
• A eliminacao e uma "eliminacao logica" (o ficheiro e mantido mas marcado como eliminado)
• A verificacao de um documento atualiza o campo documentVerifie do beneficiario
• Os documentos expirados sao sinalizados atraves do campo isExpired
• Apenas utilizadores com as permissoes apropriadas podem verificar ou rejeitar documentos