Pagamentos de um Ciclo

Endpoints para gerir os pagamentos individuais de um ciclo.

GET /api/cycles/{id}/paiements

Obtem a lista de pagamentos de um ciclo.

Endpoint

GET /api/cycles/{id}/paiements

Cabecalhos

Cabecalho	Valor	Obrigatorio
Authorization	Bearer {token}	Sim

Parametros de Consulta

Parametro	Tipo	Descricao
page	integer	Numero da pagina
itemsPerPage	integer	Elementos por pagina
statut	string	Filtrar por estado
search	string	Pesquisar por nome ou codigo do beneficiario

Estados de Pagamento

Estado	Descricao
brouillon	Em preparacao
en_attente	Submetido, a aguardar validacao RAF
valide_raf	Validado pelo RAF
valide_coord	Validado pelo Coordenador, pronto
en_cours	Execucao em curso
execute	Executado com sucesso
echoue	Pagamento falhado
rejete_raf	Rejeitado pelo RAF
rejete_coord	Rejeitado pelo Coordenador
annule	Anulado

Resposta de Sucesso

Codigo: 200 OK

{
    "@context": "/api/contexts/Paiement",
    "@id": "/api/cycles/770e8400-e29b-41d4-a716-446655440001/paiements",
    "@type": "hydra:Collection",
    "hydra:totalItems": 850,
    "hydra:member": [
        {
            "@id": "/api/paiements/880e8400-e29b-41d4-a716-446655440001",
            "@type": "Paiement",
            "id": "880e8400-e29b-41d4-a716-446655440001",
            "beneficiaire": {
                "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000",
                "codeBeneficiaire": "BEN-2024-00001",
                "nomComplet": "Fatou Diallo",
                "telephone": "771234567"
            },
            "montant": "25000.00",
            "montantNet": "24750.00",
            "fraisTransaction": "250.00",
            "statut": "execute",
            "statutLabel": "Exécuté",
            "methodePaiement": "orange_money",
            "operateur": "Orange Money",
            "referenceTransaction": "OM-2024-001234",
            "dateExecution": "2024-01-15T14:30:00+00:00",
            "dateConfirmation": "2024-01-15T14:30:05+00:00",
            "tauxConformite": "95.00",
            "estArriere": false
        }
    ],
    "hydra:view": {
        "@id": "/api/cycles/770e8400.../paiements?page=1",
        "hydra:first": "...?page=1",
        "hydra:last": "...?page=29",
        "hydra:next": "...?page=2"
    }
}

---

GET /api/paiements/{id}

Obtem os detalhes de um pagamento.

Endpoint

GET /api/paiements/{id}

Resposta de Sucesso

Codigo: 200 OK

{
    "@id": "/api/paiements/880e8400-e29b-41d4-a716-446655440001",
    "@type": "Paiement",
    "id": "880e8400-e29b-41d4-a716-446655440001",
    "beneficiaire": {
        "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000",
        "codeBeneficiaire": "BEN-2024-00001",
        "nomComplet": "Fatou Diallo",
        "telephone": "771234567",
        "modePaiement": "orange_money",
        "compteMobile": "771234567"
    },
    "cycle": {
        "@id": "/api/cycles/770e8400-e29b-41d4-a716-446655440001",
        "code": "CYC-2024-001",
        "nom": "Cycle Janvier 2024"
    },
    "montant": "25000.00",
    "montantNet": "24750.00",
    "fraisTransaction": "250.00",
    "statut": "execute",
    "methodePaiement": "orange_money",
    "operateur": "Orange Money",
    "referenceTransaction": "OM-2024-001234",
    "referenceExterne": "EXT-REF-001",
    "dateSoumission": "2024-01-15T10:00:00+00:00",
    "dateExecution": "2024-01-15T14:30:00+00:00",
    "dateConfirmation": "2024-01-15T14:30:05+00:00",
    "nbTentatives": 1,
    "codeReponse": "200",
    "messageReponse": "Transaction réussie",
    "tauxConformite": "95.00",
    "alertesConditionnalite": null,
    "datePrevue": "2024-01-15T00:00:00+00:00",
    "joursRetard": 0,
    "estArriere": false,
    "valideParRaf": {
        "email": "raf@pch-sig.sn",
        "nom": "RAF PCH"
    },
    "dateValidationRaf": "2024-01-15T11:00:00+00:00",
    "valideParCoord": {
        "email": "coord@pch-sig.sn",
        "nom": "Coordinateur PCH"
    },
    "dateValidationCoord": "2024-01-15T12:00:00+00:00",
    "historiqueValidation": [
        {
            "action": "soumission",
            "user": "agent@pch-sig.sn",
            "userName": "Agent Terrain",
            "date": "2024-01-15T10:00:00+00:00",
            "details": "Paiement soumis pour validation"
        },
        {
            "action": "validation_raf",
            "user": "raf@pch-sig.sn",
            "userName": "RAF PCH",
            "date": "2024-01-15T11:00:00+00:00",
            "details": "Validé par RAF"
        },
        {
            "action": "validation_coord",
            "user": "coord@pch-sig.sn",
            "userName": "Coordinateur PCH",
            "date": "2024-01-15T12:00:00+00:00",
            "details": "Validé par Coordinateur"
        }
    ]
}

---

POST /api/paiements/{id}/soumettre

Submete um pagamento para validacao.

Endpoint

POST /api/paiements/{id}/soumettre

Resposta de Sucesso

Codigo: 200 OK

{
    "success": true,
    "statut": "en_attente",
    "message": "Paiement soumis pour validation"
}

---

POST /api/paiements/{id}/valider-raf

Validacao pelo RAF (Responsavel Administrativo e Financeiro).

Endpoint

POST /api/paiements/{id}/valider-raf

Corpo do Pedido

{
    "commentaire": "Validation conforme"
}

Resposta de Sucesso

Codigo: 200 OK

{
    "success": true,
    "statut": "valide_raf",
    "message": "Paiement validé par RAF"
}

---

POST /api/paiements/{id}/rejeter-raf

Rejeicao pelo RAF.

Endpoint

POST /api/paiements/{id}/rejeter-raf

Corpo do Pedido

{
    "motif": "Numéro de téléphone invalide"
}

---

POST /api/paiements/{id}/valider-coordinateur

Validacao pelo Coordenador.

Endpoint

POST /api/paiements/{id}/valider-coordinateur

Corpo do Pedido

{
    "commentaire": "Approuvé pour exécution"
}

---

POST /api/paiements/{id}/executer

Inicia a execucao do pagamento.

Endpoint

POST /api/paiements/{id}/executer

Pre-requisitos

O pagamento deve ter o estado valide_coord.

Resposta de Sucesso

Codigo: 200 OK

{
    "success": true,
    "statut": "execute",
    "referenceTransaction": "OM-2024-001234",
    "dateExecution": "2024-01-15T14:30:00+00:00",
    "message": "Paiement exécuté avec succès"
}

Resposta de Falha

Codigo: 200 OK (a API retorna sempre 200, o estado indica a falha)

{
    "success": false,
    "statut": "echoue",
    "codeReponse": "INSUFFICIENT_BALANCE",
    "messageReponse": "Solde insuffisant sur le compte opérateur",
    "nbTentatives": 1
}

---

Exemplos Completos

JavaScript

class PaiementsAPI {
    constructor(token) {
        this.token = token;
        this.baseUrl = 'https://sig.ucp-pch.org/api';
    }

    async getPaiements(cycleId, filters = {}) {
        const params = new URLSearchParams(filters);
        const response = await fetch(
            `${this.baseUrl}/cycles/${cycleId}/paiements?${params}`,
            {
                headers: { 'Authorization': `Bearer ${this.token}` }
            }
        );
        return response.json();
    }

    async soumettre(paiementId) {
        const response = await fetch(
            `${this.baseUrl}/paiements/${paiementId}/soumettre`,
            {
                method: 'POST',
                headers: { 'Authorization': `Bearer ${this.token}` }
            }
        );
        return response.json();
    }

    async validerRaf(paiementId, commentaire) {
        const response = await fetch(
            `${this.baseUrl}/paiements/${paiementId}/valider-raf`,
            {
                method: 'POST',
                headers: {
                    'Authorization': `Bearer ${this.token}`,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({ commentaire })
            }
        );
        return response.json();
    }

    async executer(paiementId) {
        const response = await fetch(
            `${this.baseUrl}/paiements/${paiementId}/executer`,
            {
                method: 'POST',
                headers: { 'Authorization': `Bearer ${this.token}` }
            }
        );
        return response.json();
    }
}

// Utilizacao
const api = new PaiementsAPI(token);

// Lista de pagamentos de um ciclo
const paiements = await api.getPaiements('770e8400-...');
console.log(`${paiements['hydra:totalItems']} pagamentos`);

// Fluxo completo
await api.soumettre('880e8400-...');
await api.validerRaf('880e8400-...', 'Conforme');
await api.validerCoord('880e8400-...', 'Aprovado');
const result = await api.executer('880e8400-...');
console.log(result.success ? 'Sucesso' : 'Falha');

Python

import requests

class PaiementsAPI:
    def __init__(self, token):
        self.token = token
        self.base_url = 'https://sig.ucp-pch.org/api'
        self.headers = {'Authorization': f'Bearer {token}'}

    def get_paiements(self, cycle_id, **filters):
        response = requests.get(
            f'{self.base_url}/cycles/{cycle_id}/paiements',
            headers=self.headers,
            params=filters
        )
        return response.json()

    def soumettre(self, paiement_id):
        response = requests.post(
            f'{self.base_url}/paiements/{paiement_id}/soumettre',
            headers=self.headers
        )
        return response.json()

    def valider_raf(self, paiement_id, commentaire=None):
        response = requests.post(
            f'{self.base_url}/paiements/{paiement_id}/valider-raf',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json={'commentaire': commentaire}
        )
        return response.json()

    def executer(self, paiement_id):
        response = requests.post(
            f'{self.base_url}/paiements/{paiement_id}/executer',
            headers=self.headers
        )
        return response.json()

# Utilizacao
api = PaiementsAPI(token)

# Estatisticas por estado
paiements = api.get_paiements(cycle_id)
stats = {}
for p in paiements['hydra:member']:
    statut = p['statut']
    stats[statut] = stats.get(statut, 0) + 1
print(stats)

Notas

• Um beneficiario so pode ter um pagamento por ciclo
• O fluxo de validacao segue: brouillon -> en_attente -> valide_raf -> valide_coord -> execucao
• Os pagamentos em atraso (pagamentos falhados reportados) sao marcados com estArriere: true
• As taxas de transacao sao calculadas automaticamente de acordo com o operador
• O historico de validacao e conservado para auditoria