Factures

Endpoints de gestion des factures.

GET /:opcoId/factures/etats

Liste paginee des etats de toutes les factures du CFA. Tous les filtres sont optionnels.

Auth : X-API-KEY obligatoire.

Parametres de requete

Parametre	Type	Description
anneeFacture	string	Annee de la date de facture (ex: 2024)
numeroInterneDossier	string	Numero de dossier interne
numeroExterneDossier	string	Numero de dossier externe
referenceFactureCFA	string	Reference facture du CFA
referenceVirement	string	Reference du numero de virement OPCO
dateModification	string	Date a partir de laquelle restituer (YYYY-MM-DD)
numeroPage	string	Numero de page

Reponse 200

{
  "status": "success",
  "total": 42,
  "count": 20,
  "page": 1,
  "factures": [
    {
      "numeroInterneFacture": "FACT-001",
      "referenceFactureCFA": "REF-CFA-001",
      "organismeFormation": {
        "siret": "98765432101234",
        "IBAN": "FR7630006000011234567890189"
      },
      "montantFacture": 5000.00,
      "etatFacture": "REGLE",
      "referenceVirement": "VIR-001",
      "dateReglement": "2024-06-15",
      "commentaire": null,
      "dossiers": [
        {
          "numeroInterneDossier": "INT-001",
          "numeroExterneDossier": "EXT-001",
          "montant": 5000.00
        }
      ]
    }
  ]
}

Etats possibles : TRANSMIS, EN_COURS_REGLEMENT, REGLE, BLOQUE, REFUSE, ANNULE, RELANCE.

Erreurs

Code HTTP	Code erreur	Description
403	HTTP_ERROR	X-API-KEY manquant
501	NOT_SUPPORTED	Endpoint non supporte par cet OPCO

Exemple curl

curl -H "X-API-KEY: votre-cle" \
  "https://api.opcovia.com/opco-ep/factures/etats?anneeFacture=2024"

---

POST /:opcoId/factures

Depot d'une facture. Traitement asynchrone via file d'attente.

Auth : X-API-KEY obligatoire.

Body (JSON)

{
  "montantTotal": 5000.00,
  "numero": "FACT-2024-001",
  "dateEmission": "2024-06-01",
  "ibanEmetteur": "FR7630006000011234567890189",
  "siretEmetteur": "98765432101234",
  "estCertificatRealisation": false,
  "lignes": [
    {
      "montant": 5000.00,
      "natureLigne": "PEDAGOGIE",
      "quantite": 1,
      "numeroEcheance": 1,
      "numeroDossier": "INT-001"
    }
  ],
  "_files": { "facture": "base64..." }
}

Champs du body

Champ	Type	Requis	Description
montantTotal	number	Oui	Montant total TTC
numero	string	Oui	Numero de facture CFA
dateEmission	string	Oui	Date d'emission (YYYY-MM-DD)
ibanEmetteur	string	Oui	IBAN de l'emetteur
siretEmetteur	string	Oui	SIRET de l'emetteur
estCertificatRealisation	boolean	Non	Indique si c'est un certificat
lignes	array	Oui	Au moins 1 ligne de facture
_files	object	Non	Fichiers joints en base64

Champs d'une ligne de facture

Champ	Type	Requis	Description
montant	number	Oui	Montant de la ligne
natureLigne	enum	Oui	Nature (PEDAGOGIE, MOBILITE, HEBERGEMENT, RESTAURATION, PREMIEREQUIPEMENT, MAJORATION_RQTH)
quantite	number	Non	Quantite
numeroEcheance	number	Non	Numero d'echeance
codificationEcheance	number	Non	Codification de l'echeance
numeroDeca	string	Non	Numero DECA
numeroDossier	string	Oui	Numero interne du dossier

Reponse 202

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "statusUrl": "/opco-ep/jobs/550e8400-e29b-41d4-a716-446655440000"
}

Headers optionnels

Header	Description
Idempotency-Key	Cle d'idempotence. Si deja vue, retourne 200 + duplicate.

Suivez le job via GET /:opcoId/jobs/:jobId.

Exemple curl

curl -X POST -H "X-API-KEY: votre-cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: facture-2024-001" \
  -d '{"montantTotal": 5000, "numero": "FACT-001", ...}' \
  "https://api.opcovia.com/opco-ep/factures"