Dossiers

Endpoints de gestion des dossiers d'apprentissage.

GET /:opcoId/dossiers

Lecture d'un dossier par son identifiant. Un seul critere de recherche a la fois.

Auth : X-API-KEY obligatoire.

Parametres de requete

Deux modes exclusifs :

Parametre	Type	Description
numeroInterne	string	Identifiant technique attribue par l'OPCO
numeroExterne	string	Numero de dossier attribue par l'OPCO (avec numeroDeca)
numeroDeca	string	Numero DECA du dossier (avec numeroExterne)

Regles :

• numeroInterne seul, ou
• numeroExterne + numeroDeca ensemble
• Pas de combinaison mixte, pas de requete vide

Reponse 200

{
  "status": "success",
  "engagement": 12000,
  "cerfa": {
    "employeur": { "siret": "12345678901234", "denomination": "..." },
    "apprenti": { "nom": "Dupont", "prenom": "Jean", "dateNaissance": "2000-01-15" },
    "contrat": { "dateDebutContrat": "2024-09-01", "dateFinContrat": "2026-08-31" },
    "formation": { "rncp": "RNCP12345", "intituleQualification": "..." },
    "organismeFormation": { "siret": "98765432101234" }
  },
  "echeances": [...],
  "detailsFacturation": { ... },
  "engagementsFraisAnnexe": [...]
}

Erreurs

Code HTTP	Code erreur	Description
400	VALIDATION_ERROR	Parametres invalides (vide, partiel, combinaison mixte)
403	HTTP_ERROR	X-API-KEY manquant
404	NOT_FOUND	OPCO ou dossier introuvable
501	NOT_SUPPORTED	Endpoint non supporte par cet OPCO

Exemple curl

curl -H "X-API-KEY: votre-cle" \
  "https://api.opcovia.com/opco-ep/dossiers?numeroInterne=123456"

---

GET /:opcoId/dossiers/etats

Liste paginee des etats de tous les dossiers du CFA.

Auth : X-API-KEY obligatoire.

Parametres de requete (tous optionnels)

Parametre	Type	Description
anneeDossier	string	Annee du dossier (ex: 2024)
dateModification	string	Date a partir de laquelle restituer (YYYY-MM-DD)
numeroPage	string	Numero de page

Reponse 200

{
  "status": "success",
  "total": 150,
  "count": 50,
  "page": 1,
  "EtatDossierResult": [
    {
      "numeroExterne": "EXT-001",
      "numeroDeca": "DECA-001",
      "numeroInterne": "INT-001",
      "etat": "ENGAGE"
    }
  ]
}

Etats possibles : TRANSMIS, EN_COURS_INSTRUCTION, ENGAGE, ANNULE, REFUSE, RUPTURE, SOLDE.

Exemple curl

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

---

GET /:opcoId/dossiers/liste

Recuperation de plusieurs dossiers par leurs numeros internes (max 50).

Auth : X-API-KEY obligatoire.

Parametres de requete

Parametre	Type	Requis	Description
numerosInternes	string	Oui	Liste de numeros internes separes par des virgules

Reponse 200

{
  "status": "success",
  "dossiers": [ ... ],
  "numerosInternesIntrouvables": ["INT-999"]
}

Exemple curl

curl -H "X-API-KEY: votre-cle" \
  "https://api.opcovia.com/opco-ep/dossiers/liste?numerosInternes=INT-001,INT-002,INT-003"

---

POST /:opcoId/dossiers

Transmission d'un contrat d'apprentissage. Traitement asynchrone via file d'attente.

Auth : X-API-KEY obligatoire.

Body (JSON)

{
  "cerfa": {
    "employeur": { "siret": "12345678901234", ... },
    "apprenti": { "nom": "Dupont", "prenom": "Jean", ... },
    "contrat": { "dateDebutContrat": "2024-09-01", ... },
    "formation": { ... },
    "organismeFormation": { ... }
  },
  "_files": { "cerfa": "base64..." }
}

Le champ _files est optionnel et contient les fichiers joints en base64.

Headers optionnels

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

Reponse 202

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

Reponse 200 (doublon)

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

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: unique-key-123" \
  -d '{"cerfa": {...}}' \
  "https://api.opcovia.com/opco-ep/dossiers"