POST /api/cycles

Cria um novo ciclo de pagamento.

Endpoint

POST /api/cycles

Cabecalhos

Cabecalho	Valor	Obrigatorio
Authorization	Bearer {token}	Sim
Content-Type	application/json	Sim

Corpo do Pedido

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

Campos

Campo	Tipo	Obrigatorio	Descricao
programme	IRI	Sim	Referencia ao programa
code	string	Sim	Codigo unico do ciclo
nom	string	Sim	Nome do ciclo
description	string	Nao	Descricao
dateDebut	date	Sim	Data de inicio (YYYY-MM-DD)
dateFin	date	Nao	Data de fim
montantParBeneficiaire	decimal	Sim	Montante por beneficiario
niveauxRequis	integer	Nao	Niveis de validacao necessarios (por defeito: 2)

Resposta de Sucesso

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

Respostas de Erro

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

Exemplos

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('Erro durante a criacao');
    }

    return response.json();
};

// Utilizacao
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(`Criado: ${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()

# Utilizacao
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"Criado: {cycle['code']}")

---

PUT /api/cycles/{id}

Modifica um ciclo existente.

Endpoint

PUT /api/cycles/{id}

Corpo do Pedido

Envie apenas os campos a modificar:

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

Resposta de Sucesso

Codigo: 200 OK

Exemplo cURL

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

---

Calculo Automatico dos Beneficiarios

Apos a criacao do ciclo, utilize este endpoint para calcular automaticamente os beneficiarios elegiveis.

Endpoint

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

Resposta de Sucesso

Codigo: 200 OK

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

Exemplo cURL

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

Notas

• O codigo do ciclo deve ser unico
• O estado inicial e planifie e a validacao e brouillon
• Os montantes estao em FCFA (formato decimal)
• O calculo dos beneficiarios pode ser lancado apos a criacao
• A modificacao so e possivel se o ciclo ainda nao estiver validado