GET /api/cycles

Obtem a lista paginada dos ciclos de pagamento.

Endpoint

GET /api/cycles

Cabecalhos

Cabecalho	Valor	Obrigatorio
Authorization	Bearer {token}	Sim

Parametros de Consulta

Paginacao

Parametro	Tipo	Por Defeito	Descricao
page	integer	1	Numero da pagina
itemsPerPage	integer	30	Elementos por pagina (max: 100)

Filtros

Parametro	Tipo	Descricao
programme	IRI	Filtrar por programa
statut	string	Filtrar por estado do ciclo
statutValidation	string	Filtrar por estado de validacao
search	string	Pesquisa textual (codigo, nome)

Valores de Estado

Valor	Descricao
planifie	Ciclo planeado, ainda nao iniciado
en_cours	Ciclo em execucao
termine	Ciclo terminado
annule	Ciclo anulado

Valores de Estado de Validacao

Valor	Descricao
brouillon	Em preparacao
en_attente	Submetido, a aguardar validacao
valide	Validado em todos os niveis
rejete	Rejeitado

Ordenacao

Parametro	Valores	Descricao
order[dateDebut]	asc, desc	Ordenar por data de inicio
order[createdAt]	asc, desc	Ordenar por data de criacao
order[code]	asc, desc	Ordenar por codigo

Resposta de Sucesso

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

Exemplos

cURL - Lista Simples

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

cURL - Com Filtros

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

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

console.log(`Total: ${data['hydra:totalItems']} ciclos`);
data['hydra:member'].forEach(cycle => {
    console.log(`${cycle.code}: ${cycle.nom} - Taxa: ${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()

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

# Com filtros
cycles = get_cycles(
    token,
    statut='en_cours',
    statutValidation='valide'
)

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

Campos da Resposta

Informacoes Gerais

Campo	Tipo	Descricao
id	UUID	Identificador unico
code	string	Codigo unico do ciclo
nom	string	Nome do ciclo
description	string	Descricao
dateDebut	date	Data de inicio
dateFin	date	Data de fim

Montantes

Campo	Tipo	Descricao
montantParBeneficiaire	decimal	Montante por beneficiario
montantTotalPrevu	decimal	Montante total previsto
montantTotalPaye	decimal	Montante total pago

Estatisticas

Campo	Tipo	Descricao
nbBeneficiairesPrevu	integer	Numero de beneficiarios previstos
nbBeneficiairesPaye	integer	Numero de beneficiarios pagos
tauxExecution	float	Taxa de execucao (%)

Validacao

Campo	Tipo	Descricao
statut	string	Estado do ciclo
statutValidation	string	Estado de validacao
niveauValidation	integer	Nivel de validacao atual
niveauxRequis	integer	Niveis necessarios para validacao completa

Notas

• Os ciclos estao ligados a um programa
• A taxa de execucao e calculada automaticamente (pagos/previstos * 100)
• A validacao multi-nivel e configuravel por programa
• Os ciclos podem ser gerados automaticamente (recorrencia)