Sync (Bulk)

Recuperation progressive de tous les dossiers d'un CFA. Opcovia orchestre la discovery (GET etats) puis le fetch par batches de 50 dossiers.

Fonctionnement

POST /sync/dossiers → 202 { syncId }
    |
    v
  Discovery : GET /dossiers/etats → recupere tous les IDs
    |
    v
  Webhook sync.started { total }
    |
    v
  N batches de 50 : GET /dossiers/liste
    |
    v
  Webhook sync.batch { batch, dossiers } (a chaque batch)
    |
    v
  Webhook sync.completed { total, durationMs }

Les operations de sync utilisent une priorite basse et ne bloquent pas les requetes normales.

Cycle de vie complet d'un sync

---

POST /sync/dossiers

Lancer un bulk sync de dossiers.

Auth : X-API-KEY obligatoire.

Body (JSON)

{
  "opcoId": "opco-ep",
  "minYear": 2023,
  "enablePoller": true
}

Champ	Type	Requis	Description
opcoId	string	Oui	Identifiant de l'OPCO
minYear	number	Non	Annee minimum des dossiers (defaut: toutes). Min: 2018.
enablePoller	boolean	Non	Activer le poller automatique apres le sync

Reponse 202

{
  "syncId": "sync_abc123",
  "status": "pending",
  "statusUrl": "/sync/sync_abc123"
}

Exemple curl

curl -X POST -H "X-API-KEY: votre-cle" \
  -H "Content-Type: application/json" \
  -d '{"opcoId": "opco-ep", "minYear": 2023}' \
  "https://api.opcovia.com/sync/dossiers"

---

GET /sync/:syncId

Statut et progression d'un bulk sync.

Auth : X-API-KEY obligatoire.

Reponse 200

{
  "syncId": "sync_abc123",
  "opcoId": "opco-ep",
  "status": "processing",
  "total": 500,
  "discovered": 500,
  "fetched": 250,
  "progress": 0.75,
  "batchesCompleted": 5,
  "totalBatches": 10,
  "estimatedEnd": "2024-06-01T10:15:00.000Z",
  "error": null,
  "startedAt": "2024-06-01T10:00:00.000Z",
  "completedAt": null
}

Champs de reponse

Champ	Type	Description
syncId	string	Identifiant du sync
opcoId	string	OPCO concerne
status	string	pending, processing, completed, failed, cancelled
total	number	Nombre total de dossiers
discovered	number	Nombre de dossiers decouverts (phase discovery)
fetched	number	Nombre de dossiers recuperes (phase fetch)
progress	number	Progression de 0 a 1 (discovery = 0-0.5, fetch = 0.5-1.0)
batchesCompleted	number	Batches termines
totalBatches	number	Total de batches
estimatedEnd	string	Estimation de fin (ISO 8601)
error	string	Message d'erreur si failed
startedAt	string	Date de debut
completedAt	string	Date de fin

Erreurs

Code HTTP	Code erreur	Description
404	NOT_FOUND	Sync introuvable

Exemple curl

curl -H "X-API-KEY: votre-cle" \
  "https://api.opcovia.com/sync/sync_abc123"

---

DELETE /sync/:syncId

Annuler un bulk sync en cours. Les syncs deja termines (completed, failed, cancelled) ne peuvent pas etre annules.

Auth : X-API-KEY obligatoire.

Reponse 200 (annulation reussie)

{
  "syncId": "sync_abc123",
  "status": "cancelled"
}

Reponse 200 (deja termine)

{
  "syncId": "sync_abc123",
  "status": "completed",
  "message": "Sync already terminated"
}

Erreurs

Code HTTP	Code erreur	Description
404	NOT_FOUND	Sync introuvable

Exemple curl

curl -X DELETE -H "X-API-KEY: votre-cle" \
  "https://api.opcovia.com/sync/sync_abc123"