Introduction

Opcovia est un proxy intelligent qui se place entre les logiciels CFA et les APIs OPCO (API Convergence). Il normalise les echanges, gere le rate limiting, le cache, les jobs asynchrones, les webhooks et la synchronisation bulk.

A qui s'adresse Opcovia ?

Aux editeurs de logiciels CFA qui integrent les APIs OPCO via le standard API Convergence. Plutot que d'implementer dans chaque logiciel la gestion OAuth2, le rate limiting, les retries et les specificites de chaque OPCO, Opcovia centralise cette complexite.

Fonctionnalites principales

Proxy avec normalisation

Chaque OPCO a ses propres formats et contraintes. Opcovia utilise des profils OPCO ecrits en DSL declaratif pour transformer les requetes et reponses a la volee.

POST asynchrone (202 + job)

Les operations d'ecriture (dossiers, factures, conventions, certificats) sont traitees de maniere asynchrone. Opcovia retourne immediatement un 202 Accepted avec un jobId, puis traite la requete via BullMQ. Le client peut suivre l'avancement via polling ou webhook.

Cache Redis

Les lectures (GET) sont cachees dans Redis avec un TTL configurable. Les appels repetes sont servis instantanement sans solliciter l'API OPCO.

Webhooks

Les clients enregistrent des endpoints de callback et recoivent des notifications signees HMAC-SHA256 quand des evenements se produisent :

• dossier.etat_changed -- un dossier change d'etat
• facture.etat_changed -- une facture change d'etat
• sync.started, sync.batch, sync.completed -- progression d'un bulk sync

Bulk sync

Un seul appel POST /sync/dossiers declenche la recuperation progressive de tous les dossiers d'un CFA : discovery des IDs, puis fetch par batches de 50, avec progression en temps reel et webhooks par batch.

Hub multi-instance

Pour les deployments avec plusieurs instances Opcovia, le Hub (ecrit en Go) coordonne le rate limiting global via WebSocket. Chaque instance acquiert un token avant d'appeler l'OPCO, garantissant le respect des quotas.

Routes de l'API

Methode	Route	Description
GET	/:opcoId/dossiers	Lecture d'un dossier
GET	/:opcoId/dossiers/etats	Liste des etats de dossiers
GET	/:opcoId/dossiers/liste	Recuperation batch (max 50)
GET	/:opcoId/factures/etats	Liste des etats de factures
GET	/:opcoId/cfakeyinfo	Validite de la X-API-KEY
GET	/:opcoId/status	Statut de l'API OPCO
POST	/:opcoId/dossiers	Transmission d'un contrat (async)
POST	/:opcoId/factures	Depot d'une facture (async)
POST	/:opcoId/conventions	Depot d'une convention (async)
POST	/:opcoId/certificats	Depot d'un certificat (async)
POST	/:opcoId/documents	Depot d'un document (async)
GET	/:opcoId/jobs/:jobId	Statut d'un job async
POST	/sync/dossiers	Lancer un bulk sync
GET	/sync/:syncId	Statut d'un sync
POST	/webhooks	Enregistrer un webhook
GET	/webhooks	Lister ses webhooks

Prochaines etapes

• Demarrage rapide -- installer et lancer Opcovia
• Configuration -- reference des variables d'environnement
• SDK TypeScript -- integrer Opcovia dans votre code