GET /api/cycles

Retrieves the paginated list of payment cycles.

Endpoint

GET /api/cycles

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Query Parameters

Pagination

Parameter	Type	Default	Description
page	integer	1	Page number
itemsPerPage	integer	30	Items per page (max: 100)

Filters

Parameter	Type	Description
programme	IRI	Filter by program
statut	string	Filter by cycle status
statutValidation	string	Filter by validation status
search	string	Text search (code, name)

Status Values

Value	Description
planifie	Planned cycle, not yet started
en_cours	Cycle in progress
termine	Completed cycle
annule	Cancelled cycle

Validation Status Values

Value	Description
brouillon	In preparation
en_attente	Submitted, awaiting validation
valide	Validated at all levels
rejete	Rejected

Sorting

Parameter	Values	Description
order[dateDebut]	asc, desc	Sort by start date
order[createdAt]	asc, desc	Sort by creation date
order[code]	asc, desc	Sort by code

Success Response

Code: 200 OK

{
    "@context": "/api/contexts/Cycle",
    "@id": "/api/cycles",
    "@type": "hydra:Collection",
    "hydra:totalItems": 24,
    "hydra:member": [
        {
            "@id": "/api/cycles/770e8400-e29b-41d4-a716-446655440001",
            "@type": "Cycle",
            "id": "770e8400-e29b-41d4-a716-446655440001",
            "code": "CYC-2024-001",
            "nom": "Cycle Janvier 2024",
            "description": "Premier cycle de paiement de l'année 2024",
            "dateDebut": "2024-01-01",
            "dateFin": "2024-01-31",
            "montantParBeneficiaire": "25000.00",
            "statut": "termine",
            "nbBeneficiairesPrevu": 850,
            "nbBeneficiairesPaye": 842,
            "montantTotalPrevu": "21250000.00",
            "montantTotalPaye": "21050000.00",
            "tauxExecution": 99.06,
            "niveauValidation": 2,
            "niveauxRequis": 2,
            "statutValidation": "valide",
            "genereAutomatiquement": false,
            "programme": {
                "@id": "/api/programmes/1",
                "nom": "Transferts Monétaires 2024"
            },
            "createdAt": "2023-12-15T10:00:00+00:00"
        }
    ],
    "hydra:view": {
        "@id": "/api/cycles?page=1",
        "@type": "hydra:PartialCollectionView",
        "hydra:first": "/api/cycles?page=1",
        "hydra:last": "/api/cycles?page=1",
        "hydra:next": "/api/cycles?page=2"
    }
}

Examples

cURL - Simple List

curl https://sig.ucp-pch.org/api/cycles \
  -H "Authorization: Bearer TOKEN"

cURL - With Filters

curl "https://sig.ucp-pch.org/api/cycles?statut=en_cours&statutValidation=valide" \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getCycles = async (filters = {}) => {
    const params = new URLSearchParams();

    if (filters.programme) params.append('programme', filters.programme);
    if (filters.statut) params.append('statut', filters.statut);
    if (filters.statutValidation) params.append('statutValidation', filters.statutValidation);
    if (filters.search) params.append('search', filters.search);
    if (filters.page) params.append('page', filters.page);

    const response = await fetch(
        `https://sig.ucp-pch.org/api/cycles?${params}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );

    return response.json();
};

// Usage
const data = await getCycles({
    statut: 'en_cours',
    statutValidation: 'valide'
});

console.log(`Total: ${data['hydra:totalItems']} cycles`);
data['hydra:member'].forEach(cycle => {
    console.log(`${cycle.code}: ${cycle.nom} - Rate: ${cycle.tauxExecution}%`);
});

Python

import requests

def get_cycles(token, **filters):
    response = requests.get(
        'https://sig.ucp-pch.org/api/cycles',
        headers={'Authorization': f'Bearer {token}'},
        params=filters
    )
    return response.json()

# Simple list
cycles = get_cycles(token)
print(f"Total: {cycles['hydra:totalItems']}")

# With filters
cycles = get_cycles(
    token,
    statut='en_cours',
    statutValidation='valide'
)

for cycle in cycles['hydra:member']:
    print(f"- {cycle['code']}: {cycle['nom']}")
    print(f"  Expected: {cycle['nbBeneficiairesPrevu']} | Paid: {cycle['nbBeneficiairesPaye']}")

Response Fields

General Information

Field	Type	Description
id	UUID	Unique identifier
code	string	Unique cycle code
nom	string	Cycle name
description	string	Description
dateDebut	date	Start date
dateFin	date	End date

Amounts

Field	Type	Description
montantParBeneficiaire	decimal	Amount per beneficiary
montantTotalPrevu	decimal	Total expected amount
montantTotalPaye	decimal	Total paid amount

Statistics

Field	Type	Description
nbBeneficiairesPrevu	integer	Number of expected beneficiaries
nbBeneficiairesPaye	integer	Number of paid beneficiaries
tauxExecution	float	Execution rate (%)

Validation

Field	Type	Description
statut	string	Cycle status
statutValidation	string	Validation status
niveauValidation	integer	Current validation level
niveauxRequis	integer	Levels required for complete validation

Notes

• Cycles are linked to a program
• The execution rate is automatically calculated (paid/expected * 100)
• Multi-level validation is configurable per program
• Cycles can be automatically generated (recurrence)