API Opcovia -- Vue d'ensemble

Opcovia est un proxy intelligent entre les logiciels CFA et les APIs OPCO (API Convergence). Il normalise les requetes/reponses, gere le cache, le rate limiting et le suivi asynchrone des jobs.

Base URL

https://api.opcovia.com

Authentification

Toutes les routes (sauf /health et /doc) requierent le header :

Header	Description
X-API-KEY	Cle API attribuee au CFA par l'OPCO. Identifie le tenant.

Le Bearer token OAuth2 (authentification editeur aupres de l'OPCO) est gere automatiquement cote serveur via le Token Manager. Le CFA n'a pas a le fournir.

Headers communs

Header	Direction	Description
X-API-KEY	Request	Obligatoire. Cle API du CFA.
X-Request-ID	Request/Response	Optionnel en request (UUID genere sinon). Retourne dans la reponse.
Idempotency-Key	Request	Optionnel sur les POST. Evite les doublons (retourne 200 + duplicate).
Content-Type	Request	application/json pour tous les POST.

Format de reponse

Succes (GET synchrones)

{
  "status": "success",
  "comment": null,
  ...donnees
}

Succes (POST asynchrones -- 202)

{
  "jobId": "uuid",
  "status": "pending",
  "statusUrl": "/{opcoId}/jobs/{jobId}"
}

Erreur

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "description": "Message d'erreur lisible",
  "errors": ["champ1: message", "champ2: message"]
}

Voir errors.md pour la liste complete des codes.

Pagination

Les endpoints listes (/dossiers/etats, /factures/etats) retournent :

{
  "total": 150,
  "count": 50,
  "page": 1,
  ...donnees
}

Le parametre numeroPage controle la page courante.

Table des endpoints

Routes OPCO (prefixees par /:opcoId)

Methode	Path	Description	Mode
GET	/:opcoId/dossiers	Lecture d'un dossier	Synchrone
GET	/:opcoId/dossiers/etats	Liste des etats de dossiers	Synchrone
GET	/:opcoId/dossiers/liste	Recuperation batch (max 50)	Synchrone
POST	/:opcoId/dossiers	Transmission d'un contrat	Asynchrone (202)
GET	/:opcoId/factures/etats	Liste des etats de factures	Synchrone
POST	/:opcoId/factures	Depot d'une facture	Asynchrone (202)
POST	/:opcoId/conventions	Depot d'une convention	Asynchrone (202)
POST	/:opcoId/certificats	Depot d'un certificat	Asynchrone (202)
POST	/:opcoId/documents	Depot d'un document	Asynchrone (202)
GET	/:opcoId/jobs/:jobId	Suivi d'un job asynchrone	Synchrone
GET	/:opcoId/cfakeyinfo	Validite de la cle API	Synchrone
GET	/:opcoId/status	Statut de l'API OPCO	Synchrone

Routes globales

Methode	Path	Description	Mode
GET	/health	Health check (sans auth)	Synchrone
GET	/doc	Documentation OpenAPI JSON (sans auth)	Synchrone
POST	/webhooks	Enregistrer un webhook	Synchrone
GET	/webhooks	Lister ses webhooks	Synchrone
PATCH	/webhooks/:id	Modifier un webhook	Synchrone
DELETE	/webhooks/:id	Supprimer un webhook	Synchrone
GET	/webhooks/:id/logs	Historique des deliveries	Synchrone
POST	/sync/dossiers	Lancer un bulk sync	Asynchrone (202)
GET	/sync/:syncId	Statut d'un bulk sync	Synchrone
DELETE	/sync/:syncId	Annuler un bulk sync	Synchrone
POST	/poller/register	Enregistrer un poller	Synchrone
GET	/poller	Lister ses pollers	Synchrone
DELETE	/poller/:opcoId	Desactiver un poller	Synchrone