Beneficiary Documents

Endpoints for managing beneficiary identity documents and supporting files.

GET /api/beneficiaires/{id}/documents

Retrieves the list of documents for a beneficiary.

Endpoint

GET /api/beneficiaires/{id}/documents

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Success Response

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

Document Types

Type	Description
cni	National Identity Card
certificat_residence	Residence Certificate
acte_naissance	Birth Certificate
photo	Identity Photo
certificat_scolaire	School Certificate
certificat_medical	Medical Certificate
justificatif_revenu	Proof of Income
autre	Other Document

Verification Statuses

Status	Description
pending	Awaiting verification
verified	Document verified and validated
rejected	Document rejected

---

POST /api/beneficiaire_documents

Uploads a new document for a beneficiary.

Endpoint

POST /api/beneficiaire_documents

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	multipart/form-data	Yes

Request Body (multipart)

Field	Type	Required	Description
beneficiaire	IRI	Yes	Reference to the beneficiary
type	string	Yes	Document type
file	file	Yes	File to upload
expiryDate	date	No	Expiry date
notes	string	No	Additional notes

Accepted Formats

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

Maximum size: 10 MB

Success Response

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

cURL Example

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

Verifies (validates) a document.

Endpoint

POST /api/beneficiaire_documents/{id}/verify

Success Response

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

cURL Example

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

Rejects a document with a reason.

Endpoint

POST /api/beneficiaire_documents/{id}/reject

Request Body

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

Success Response

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}

Deletes a document (soft delete).

Endpoint

DELETE /api/beneficiaire_documents/{id}

Success Response

Code: 204 No Content

---

Complete Examples

JavaScript

// Retrieve documents for a beneficiary
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();
};

// Upload a 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();
};

// Verify a 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();
};

// Reject a 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();
};

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

// Upload with file input
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 uploaded: ${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()

# Usage
api = DocumentsAPI(token)

# List documents
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']}")

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

# Verify the document
api.verify_document(nouveau['id'])

Notes

• Documents are stored securely on the server
• Deletion is a "soft delete" (the file is kept but marked as deleted)
• Verifying a document updates the beneficiary's documentVerifie field
• Expired documents are flagged via the isExpired field
• Only users with appropriate permissions can verify or reject documents