POST /api/cycles

Creates a new payment cycle.

Endpoint

POST /api/cycles

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Request Body

{
    "programme": "/api/programmes/1",
    "code": "CYC-2024-003",
    "nom": "Cycle Mars 2024",
    "description": "Cycle de paiement pour le mois de mars 2024",
    "dateDebut": "2024-03-01",
    "dateFin": "2024-03-31",
    "montantParBeneficiaire": "25000.00",
    "niveauxRequis": 2
}

Fields

Field	Type	Required	Description
programme	IRI	Yes	Reference to the program
code	string	Yes	Unique cycle code
nom	string	Yes	Cycle name
description	string	No	Description
dateDebut	date	Yes	Start date (YYYY-MM-DD)
dateFin	date	No	End date
montantParBeneficiaire	decimal	Yes	Amount per beneficiary
niveauxRequis	integer	No	Required validation levels (default: 2)

Success Response

Code: 201 Created

{
    "@context": "/api/contexts/Cycle",
    "@id": "/api/cycles/770e8400-e29b-41d4-a716-446655440003",
    "@type": "Cycle",
    "id": "770e8400-e29b-41d4-a716-446655440003",
    "code": "CYC-2024-003",
    "nom": "Cycle Mars 2024",
    "description": "Cycle de paiement pour le mois de mars 2024",
    "dateDebut": "2024-03-01",
    "dateFin": "2024-03-31",
    "montantParBeneficiaire": "25000.00",
    "statut": "planifie",
    "nbBeneficiairesPrevu": 0,
    "nbBeneficiairesPaye": 0,
    "montantTotalPrevu": "0",
    "montantTotalPaye": "0",
    "niveauValidation": 0,
    "niveauxRequis": 2,
    "statutValidation": "brouillon",
    "createdAt": "2024-02-15T10:00:00+00:00"
}

Error Responses

422 Unprocessable Entity

{
    "@context": "/api/contexts/ConstraintViolationList",
    "@type": "ConstraintViolationList",
    "violations": [
        {
            "propertyPath": "code",
            "message": "This value is already used."
        },
        {
            "propertyPath": "montantParBeneficiaire",
            "message": "This value should be positive."
        }
    ]
}

Examples

cURL

curl -X POST https://sig.ucp-pch.org/api/cycles \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "programme": "/api/programmes/1",
    "code": "CYC-2024-003",
    "nom": "Cycle Mars 2024",
    "dateDebut": "2024-03-01",
    "dateFin": "2024-03-31",
    "montantParBeneficiaire": "25000.00"
  }'

JavaScript

const createCycle = async (data) => {
    const response = await fetch('https://sig.ucp-pch.org/api/cycles', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${localStorage.getItem('token')}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
    });

    if (response.status === 422) {
        const errors = await response.json();
        throw new Error(errors['hydra:description']);
    }

    if (!response.ok) {
        throw new Error('Error during creation');
    }

    return response.json();
};

// Usage
const cycle = await createCycle({
    programme: '/api/programmes/1',
    code: 'CYC-2024-003',
    nom: 'Cycle Mars 2024',
    dateDebut: '2024-03-01',
    dateFin: '2024-03-31',
    montantParBeneficiaire: '25000.00'
});

console.log(`Created: ${cycle.code}`);

Python

import requests

def create_cycle(token, data):
    response = requests.post(
        'https://sig.ucp-pch.org/api/cycles',
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        },
        json=data
    )

    if response.status_code == 422:
        errors = response.json()
        raise Exception(errors['hydra:description'])

    response.raise_for_status()
    return response.json()

# Usage
cycle = create_cycle(token, {
    'programme': '/api/programmes/1',
    'code': 'CYC-2024-003',
    'nom': 'Cycle Mars 2024',
    'dateDebut': '2024-03-01',
    'dateFin': '2024-03-31',
    'montantParBeneficiaire': '25000.00'
})

print(f"Created: {cycle['code']}")

---

PUT /api/cycles/{id}

Modifies an existing cycle.

Endpoint

PUT /api/cycles/{id}

Request Body

Send only the fields to modify:

{
    "nom": "Cycle Mars 2024 - Modifié",
    "dateFin": "2024-04-05",
    "montantParBeneficiaire": "27500.00"
}

Success Response

Code: 200 OK

cURL Example

curl -X PUT https://sig.ucp-pch.org/api/cycles/770e8400-e29b-41d4-a716-446655440003 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Cycle Mars 2024 - Modifié",
    "montantParBeneficiaire": "27500.00"
  }'

---

Automatic Beneficiary Calculation

After creating the cycle, use this endpoint to automatically calculate eligible beneficiaries.

Endpoint

POST /api/cycles/{id}/calculer-beneficiaires

Success Response

Code: 200 OK

{
    "success": true,
    "nbBeneficiairesPrevu": 850,
    "montantTotalPrevu": "21250000.00",
    "message": "850 bénéficiaires éligibles identifiés"
}

cURL Example

curl -X POST https://sig.ucp-pch.org/api/cycles/770e8400-e29b-41d4-a716-446655440003/calculer-beneficiaires \
  -H "Authorization: Bearer TOKEN"

Notes

• The cycle code must be unique
• The initial status is planifie and validation status is brouillon
• Amounts are in FCFA (decimal format)
• Beneficiary calculation can be triggered after creation
• Modification is only possible if the cycle is not yet validated