Opcovia

Appearance

Demarrage rapide ​

Ce guide vous accompagne de l'installation au premier appel API.

Prerequisites ​

  • Node.js 20+
  • Docker (pour Redis et PostgreSQL)
  • pnpm (gestionnaire de paquets)

Installation ​

bash
git clone https://github.com/eduvia-technologies/opcovia.git
cd opcovia
pnpm install

Infrastructure locale ​

Lancez Redis et PostgreSQL via Docker Compose :

bash
docker compose up -d

Variables d'environnement ​

Copiez le fichier d'exemple et editez-le :

bash
cp .env.example .env

Les variables minimales a configurer :

env
# App
PORT=3000
NODE_ENV=development

# Base de donnees PostgreSQL
DATABASE_URL=postgresql://opcovia:opcovia@localhost:5432/opcovia

# Redis
REDIS_URL=redis://localhost:6379

# Identifiant editeur (headers API Convergence)
EDITEUR=mon-editeur
LOGICIEL=mon-logiciel
VERSION_LOGICIEL=1.0.0

# Cle de chiffrement (32 bytes = 64 caracteres hex)
DB_MASTER_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Pour connecter un OPCO (exemple OPCO EP) :

env
OPCO_EP_BASE_URL=https://api.opcoep.example.com
OPCO_EP_CLIENT_ID=votre-client-id
OPCO_EP_CLIENT_SECRET=votre-client-secret
OPCO_EP_TOKEN_URL=https://auth.opcoep.example.com/oauth/token

Voir la reference configuration pour la liste complete.

Migrations ​

Appliquez le schema de base de donnees :

bash
pnpm db:migrate   # applique les migrations versionnees (src/db/migrations)
# ou, en dev rapide : pnpm db:push (applique le schema sans fichier de migration)

En production, le conteneur applique automatiquement pnpm db:deploy (migrator programmatique, idempotent) au demarrage.

Lancement ​

bash
pnpm dev

Le serveur demarre sur http://localhost:3000. Verifiez qu'il fonctionne :

bash
curl http://localhost:3000/health
# {"status":"ok"}

Premier appel : lire un dossier ​

bash
curl -H "X-API-KEY: votre-cle-api" \
  "http://localhost:3000/opco-ep/dossiers?numeroInterne=12345"

Reponse :

json
{
  "employeur": { "siret": "12345678901234", "raisonSociale": "..." },
  "apprenti": { "nom": "Dupont", "prenom": "Jean", "..." : "..." },
  "contrat": { "..." : "..." },
  "formation": { "..." : "..." }
}

Premier appel : transmettre un dossier ​

Les POST sont asynchrones. Opcovia retourne immediatement un 202 Accepted avec un identifiant de job :

bash
curl -X POST \
  -H "X-API-KEY: votre-cle-api" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"cerfa": {"employeur": {"siret": "12345678901234"}, "apprenti": {"nom": "Dupont"}}}' \
  "http://localhost:3000/opco-ep/dossiers"

Reponse (202) :

json
{
  "jobId": "job_abc123",
  "statusUrl": "/opco-ep/jobs/job_abc123"
}

Suivre l'avancement du job ​

Pollez le statut du job jusqu'a sa completion :

bash
curl -H "X-API-KEY: votre-cle-api" \
  "http://localhost:3000/opco-ep/jobs/job_abc123"

Reponse en cours :

json
{
  "jobId": "job_abc123",
  "status": "processing"
}

Reponse terminee :

json
{
  "jobId": "job_abc123",
  "status": "completed",
  "result": { "numeroInterne": "67890", "..." : "..." }
}

En cas d'erreur :

json
{
  "jobId": "job_abc123",
  "status": "failed",
  "error": { "code": "VALIDATION_ERROR", "message": "SIRET invalide" }
}

Prochaines etapes ​