Paiements d'un Cycle

Endpoints pour gérer les paiements individuels d'un cycle.

GET /api/cycles/{id}/paiements

Récupère la liste des paiements d'un cycle.

Endpoint

GET /api/cycles/{id}/paiements

Headers

Header	Valeur	Requis
Authorization	Bearer {token}	Oui

Paramètres de requête

Paramètre	Type	Description
page	integer	Numéro de page
itemsPerPage	integer	Éléments par page
statut	string	Filtrer par statut
search	string	Recherche par nom ou code bénéficiaire

Statuts de paiement

Statut	Description
brouillon	En préparation
en_attente	Soumis, en attente validation RAF
valide_raf	Validé par RAF
valide_coord	Validé par Coordinateur, prêt
en_cours	Exécution en cours
execute	Exécuté avec succès
echoue	Échec du paiement
rejete_raf	Rejeté par RAF
rejete_coord	Rejeté par Coordinateur
annule	Annulé

Réponse succès

Code: 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}

Récupère les détails d'un paiement.

Endpoint

GET /api/paiements/{id}

Réponse succès

Code: 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

Soumet un paiement pour validation.

Endpoint

POST /api/paiements/{id}/soumettre

Réponse succès

Code: 200 OK

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

---

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

Validation par le RAF (Responsable Administratif et Financier).

Endpoint

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

Corps de la requête

{
    "commentaire": "Validation conforme"
}

Réponse succès

Code: 200 OK

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

---

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

Rejet par le RAF.

Endpoint

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

Corps de la requête

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

---

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

Validation par le Coordinateur.

Endpoint

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

Corps de la requête

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

---

POST /api/paiements/{id}/executer

Lance l'exécution du paiement.

Endpoint

POST /api/paiements/{id}/executer

Prérequis

Le paiement doit avoir le statut valide_coord.

Réponse succès

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

Réponse échec

Code: 200 OK (l'API retourne toujours 200, le statut indique l'échec)

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

---

Exemples complets

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

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

// Liste des paiements d'un cycle
const paiements = await api.getPaiements('770e8400-...');
console.log(`${paiements['hydra:totalItems']} paiements`);

// Workflow complet
await api.soumettre('880e8400-...');
await api.validerRaf('880e8400-...', 'Conforme');
await api.validerCoord('880e8400-...', 'Approuvé');
const result = await api.executer('880e8400-...');
console.log(result.success ? 'Succès' : 'Échec');

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

# Utilisation
api = PaiementsAPI(token)

# Statistiques par statut
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)

Notes

• Un bénéficiaire ne peut avoir qu'un seul paiement par cycle
• Le workflow de validation suit : brouillon → en_attente → valide_raf → valide_coord → exécution
• Les arriérés (paiements échoués reportés) sont marqués avec estArriere: true
• Les frais de transaction sont calculés automatiquement selon l'opérateur
• L'historique de validation est conservé pour l'audit