Documents du Bénéficiaire

Endpoints pour gérer les documents d'identité et justificatifs des bénéficiaires.

GET /api/beneficiaires/{id}/documents

Récupère la liste des documents d'un bénéficiaire.

Endpoint

GET /api/beneficiaires/{id}/documents

Headers

Header	Valeur	Requis
Authorization	Bearer {token}	Oui

Réponse succès

Code: 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"
        }
    ]
}

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
autre	Autre Document

Statuts de vérification

Statut	Description
pending	En attente de vérification
verified	Document vérifié et validé
rejected	Document rejeté

---

POST /api/beneficiaire_documents

Upload un nouveau document pour un bénéficiaire.

Endpoint

POST /api/beneficiaire_documents

Headers

Header	Valeur	Requis
Authorization	Bearer {token}	Oui
Content-Type	multipart/form-data	Oui

Corps de la requête (multipart)

Champ	Type	Requis	Description
beneficiaire	IRI	Oui	Référence au bénéficiaire
type	string	Oui	Type de document
file	file	Oui	Fichier à uploader
expiryDate	date	Non	Date d'expiration
notes	string	Non	Notes complémentaires

Formats acceptés

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

Taille maximale : 10 MB

Réponse succès

Code: 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"
}

Exemple 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

Vérifie (valide) un document.

Endpoint

POST /api/beneficiaire_documents/{id}/verify

Réponse succès

Code: 200 OK

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

Exemple 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

Rejette un document avec motif.

Endpoint

POST /api/beneficiaire_documents/{id}/reject

Corps de la requête

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

Réponse succès

Code: 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}

Supprime un document (soft delete).

Endpoint

DELETE /api/beneficiaire_documents/{id}

Réponse succès

Code: 204 No Content

---

Exemples complets

JavaScript

// Récupérer les documents d'un bénéficiaire
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();
};

// Uploader un document
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();
};

// Vérifier un document
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();
};

// Rejeter un document
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();
};

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

// Upload avec input file
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(`Document uploadé: ${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()

# Utilisation
api = DocumentsAPI(token)

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

# Uploader un document
nouveau = api.upload_document(
    '550e8400-e29b-41d4-a716-446655440000',
    '/path/to/cni.pdf',
    'cni',
    '2030-06-15'
)
print(f"Uploadé: {nouveau['id']}")

# Vérifier le document
api.verify_document(nouveau['id'])

Notes

• Les documents sont stockés de manière sécurisée sur le serveur
• La suppression est un "soft delete" (le fichier est conservé mais marqué comme supprimé)
• La vérification d'un document met à jour le champ documentVerifie du bénéficiaire
• Les documents expirés sont signalés via le champ isExpired
• Seuls les utilisateurs avec la permission appropriée peuvent vérifier ou rejeter des documents