Intégrer Convergence Plus, pas à pas

Ce guide décrit la démarche que nous avons suivie pour intégrer Convergence Plus dans Easy-FORMA, du premier appel en recette jusqu'à la mise en production. Il s'adresse aux équipes produit et techniques des éditeurs logiciels — mais les étapes sont identiques pour un CFA qui intègre son SI maison.

Étape 1 — Obtenir vos accès

• Demandez votre clé API (header X-API-Key) et l'accès à l'environnement RECETTE. La recette est un sandbox complet : aucun dossier n'atteint un vrai OPCO.
• La documentation interactive est disponible sur api.convergence-plus.fr/docs (Swagger) : chaque endpoint y est testable directement.
• Prévoyez un SIRET de test par OPCO cible — le routage dépend du SIRET employeur.

Étape 2 — Comprendre le modèle de données

Un dossier = deux objets : cerfa (le contrat 10103 : employeur, apprenti, maître d'apprentissage, formation) et convention (le volet financier : coûts, NPEC, dates). Votre source de vérité reste votre base ; l'API attend une projection JSON de ces deux objets.

Étape 3 — Le routage OPCO : n'implémentez rien

C'est le point qui divise le temps d'intégration par 10 : vous n'avez pas à résoudre SIRET → OPCO. Envoyez le SIRET employeur, Convergence Plus détermine l'OPCO propriétaire et ajoute lui-même les headers réglementaires (EDITEUR, LOGICIEL, VERSION) exigés par chaque OPCO.

Étape 4 — Respecter les règles de payload

Quelques règles vérifiées côté plateforme — les connaître dès le départ évite des jours de debug :

• NIR : 13 chiffres exactement (clé de contrôle tronquée, alignement DECA) ;
• À la création, ne jamais envoyer : noContrat, dateRupture, numeroInterne, numeroExterne, numeroDeca — ces champs sont valorisés par le SI de l'OPCO ; les envoyer, même à null, provoque un rejet ;
• Dates : ISO 8601 avec suffixe Z ;
• remunerationsAnnuelles[].ordre : chaîne au format "1.1", "2.1"…
• Certains champs des specs CFA Dock ne sont pas du schéma Convergence et sont rejetés — le validateur serveur vous le dira avant l'envoi.

Étape 5 — Envoyer le dossier (multipart)

Un seul appel : POST /dossiers/RECETTE en multipart/form-data avec une partie payload (JSON) et une partie fichier (PDF de la convention signée).

curl -X POST https://api.convergence-plus.fr/dossiers/RECETTE   -H "X-API-Key: votre-clé"   -F 'payload={"cerfa": {...}, "convention": {...}};type=application/json'   -F "fichier=@convention.pdf;type=application/pdf"

Étape 6 — Gérer le cycle de vie

• Après dépôt, interrogez GET /dossiers/etats/... et GET /dossiers/{id} pour suivre l'avancement et récupérer le numéro attribué par l'OPCO.
• Les erreurs métier (400, 436…) remontent avec un message exploitables : traduisez-les en actions correctives pour vos utilisateurs (ex. « date de rupture » → champ mal mappé).
• Persistez l'ID dossier et le dernier statut connu pour pouvoir rejouer ou auditer.

Étape 7 — Échéancier et facturation

Une fois le dossier accepté, récupérez l'échéancier officiel (dates + montants NPEC) puis programmez l'envoi des attestations de présence et factures aux dates prévues. C'est l'étape qui transforme l'API en outil de trésorerie : les paiements OPCO suivent l'échéancier, pas vos relances.

Étape 8 — Passer en production

• Rejouez vos scénarios de recette sur /dossiers/PRODUCTION avec un dossier réel pilote ;
• Vérifiez la lecture du statut sur un dossier déposé avant de généraliser ;
• Ouvrez progressivement à vos clients (feature flag par compte si vous êtes éditeur).