Jobs

Suivi des operations asynchrones. Chaque POST (dossiers, factures, conventions, certificats, documents) retourne un jobId permettant de suivre l'avancement.

GET /:opcoId/jobs/:jobId

Recupere le statut et le resultat d'un job asynchrone.

Auth : X-API-KEY obligatoire. Le job n'est visible que par le tenant qui l'a cree.

Parametres de chemin

Parametre	Type	Description
opcoId	string	Identifiant de l'OPCO
jobId	string	UUID du job (retourne par le POST initial)

Statuts possibles

Statut	Description
pending	Job en file d'attente
processing	Job en cours de traitement
completed	Job termine avec succes
failed	Job echoue

Reponse 200 -- Job simple (en attente)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "opcoId": "opco-ep",
  "type": "post-dossier",
  "status": "pending",
  "retries": 0,
  "createdAt": "2024-06-01T10:00:00.000Z",
  "startedAt": null,
  "completedAt": null
}

Reponse 200 -- Job simple (termine)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "opcoId": "opco-ep",
  "type": "post-dossier",
  "status": "completed",
  "result": {
    "status": "success",
    "numeroInterne": "INT-12345",
    "comment": "Dossier transmis"
  },
  "retries": 0,
  "createdAt": "2024-06-01T10:00:00.000Z",
  "startedAt": "2024-06-01T10:00:05.000Z",
  "completedAt": "2024-06-01T10:00:12.000Z"
}

Reponse 200 -- Job simple (echoue)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "opcoId": "opco-ep",
  "type": "post-dossier",
  "status": "failed",
  "error": {
    "message": "OPCO returned 400",
    "code": "UPSTREAM_ERROR",
    "upstream": { "errors": ["SIRET invalide"] }
  },
  "retries": 3,
  "createdAt": "2024-06-01T10:00:00.000Z",
  "startedAt": "2024-06-01T10:00:05.000Z",
  "completedAt": "2024-06-01T10:01:30.000Z"
}

Reponse 200 -- Job composite (multi-etapes)

Certains jobs (ex: dossier + convention) sont composites et comportent plusieurs etapes.

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "opcoId": "opco-ep",
  "type": "post-dossier",
  "status": "processing",
  "currentStep": 2,
  "totalSteps": 3,
  "steps": [
    { "step": 1, "name": "dossier", "status": "completed", "result": { ... } },
    { "step": 2, "name": "convention", "status": "processing" },
    { "step": 3, "name": "document", "status": "pending" }
  ],
  "retries": 0,
  "createdAt": "2024-06-01T10:00:00.000Z",
  "startedAt": "2024-06-01T10:00:05.000Z",
  "completedAt": null
}

Reponse 200 -- Job composite (echoue a une etape)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "opcoId": "opco-ep",
  "type": "post-dossier",
  "status": "failed",
  "currentStep": 2,
  "totalSteps": 3,
  "steps": [
    { "step": 1, "name": "dossier", "status": "completed", "result": { ... } },
    { "step": 2, "name": "convention", "status": "failed" }
  ],
  "error": {
    "message": "OPCO returned 400",
    "code": "UPSTREAM_ERROR",
    "step": 2
  },
  "retries": 2,
  "createdAt": "2024-06-01T10:00:00.000Z",
  "startedAt": "2024-06-01T10:00:05.000Z",
  "completedAt": "2024-06-01T10:01:00.000Z"
}

Erreurs

Code HTTP	Code erreur	Description
403	HTTP_ERROR	X-API-KEY manquant
404	NOT_FOUND	Job introuvable (mauvais jobId ou tenant)

Exemple curl

curl -H "X-API-KEY: votre-cle" \
  "https://api.opcovia.com/opco-ep/jobs/550e8400-e29b-41d4-a716-446655440000"

Cycle de vie d'un job

Strategie de polling

Nous recommandons un polling progressif :

1. Premiere requete apres 2 secondes
2. Puis toutes les 5 secondes pendant 1 minute
3. Puis toutes les 30 secondes

Alternativement, utilisez les webhooks pour etre notifie automatiquement (job.completed, job.failed).