Configuration

Toutes les variables d'environnement sont validees au demarrage via un schema Zod. Si une variable obligatoire manque ou a un format invalide, Opcovia refuse de demarrer avec un message d'erreur explicite.

Application

Variable	Type	Defaut	Description
PORT	number	3000	Port d'ecoute HTTP
NODE_ENV	enum	development	Environnement : development, test, production
LOG_LEVEL	enum	info	Niveau de log : debug, info, warn, error

Base de donnees

Variable	Type	Defaut	Description
DATABASE_URL	url	--	URL de connexion PostgreSQL. Obligatoire.

Redis

Variable	Type	Defaut	Description
REDIS_URL	url	--	URL de connexion Redis. Obligatoire.

HTTP upstream (API Convergence)

Ces headers sont envoyes a chaque appel vers les APIs OPCO. Ils identifient votre logiciel aupres de l'API Convergence.

Variable	Type	Defaut	Description
EDITEUR	string	--	Nom de l'editeur. Obligatoire.
LOGICIEL	string	--	Nom du logiciel. Obligatoire.
VERSION_LOGICIEL	string	--	Version du logiciel. Obligatoire.
HTTP_TIMEOUT_MS	number	30000	Timeout des appels HTTP vers les OPCOs (ms)

OAuth2 OPCO

Chaque OPCO se configure avec 4 variables. Le pattern est OPCO_{ID}_*.

OPCO EP

Variable	Type	Defaut	Description
OPCO_EP_BASE_URL	url	--	URL de base de l'API OPCO EP
OPCO_EP_CLIENT_ID	string	--	Client ID OAuth2
OPCO_EP_CLIENT_SECRET	string	--	Client secret OAuth2
OPCO_EP_TOKEN_URL	url	--	URL du endpoint token OAuth2

OPCO Mock (developpement local)

Variable	Type	Defaut	Description
OPCO_MOCK_BASE_URL	url	--	URL de base du mock OPCO
OPCO_MOCK_CLIENT_ID	string	--	Client ID du mock
OPCO_MOCK_CLIENT_SECRET	string	--	Client secret du mock
OPCO_MOCK_TOKEN_URL	url	--	URL token du mock

Toutes les variables OPCO sont optionnelles. Seuls les OPCOs configures sont disponibles.

Chiffrement

Variable	Type	Defaut	Description
DB_MASTER_KEY	string (64 chars)	--	Cle AES-256 en hexadecimal (32 bytes = 64 caracteres). Obligatoire. Utilisee pour chiffrer les donnees sensibles en base.

Cache

Variable	Type	Defaut	Description
CACHE_DEFAULT_TTL	number	300	Duree de vie du cache Redis en secondes (5 minutes par defaut)

Hub

Le Hub est optionnel. Sans Hub, Opcovia fonctionne en standalone avec un rate limiter local.

Variable	Type	Defaut	Description
HUB_URL	url	--	URL WebSocket du Hub (ex: ws://hub:8080)
HUB_API_KEY	string	--	Cle d'authentification pour le Hub

Auth proxy (optionnel)

Quand OPCOVIA_API_KEY est defini, l'acces au proxy exige Authorization: Bearer <cle>. La cle acceptee peut etre :

• la cle maitre OPCOVIA_API_KEY (pass-through : le CFA envoie son X-API-KEY OPCO directement) ;
• une cle client Opcovia geree (per-client) : le client n'envoie que sa cle, et le proxy resout la cle X-API-KEY OPCO depuis la base (opco_credentials, chiffree). Pour les routes sans opcoId (webhooks, sync, poller), le client precise l'OPCO via le header X-Opco-Id.

Variable	Type	Defaut	Description
OPCOVIA_API_KEY	string	--	Cle maitre Opcovia. Si absente, l'auth proxy est desactivee (dev/tests).

Gestion des clients geres via le CLI :

pnpm creds create-client "CFA Exemple"                      # genere et affiche la cle Opcovia (une seule fois)
pnpm creds set-credential <clientId> opco-ep <siren> <cle-opco>
pnpm creds list-clients

Record mode

Variable	Type	Defaut	Description
OPCOVIA_RECORD	boolean	false	Active le mode enregistrement pour les tests de contrat OPCO. Valeurs acceptees : true, 1.

Exemple complet

# Application
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

# Infrastructure
DATABASE_URL=postgresql://opcovia:secret@db:5432/opcovia
REDIS_URL=redis://redis:6379

# Identifiant editeur
EDITEUR=eduvia
LOGICIEL=eduvia-cfa
VERSION_LOGICIEL=2.1.0
HTTP_TIMEOUT_MS=15000

# Chiffrement
DB_MASTER_KEY=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

# OPCO EP
OPCO_EP_BASE_URL=https://api.opcoep.fr
OPCO_EP_CLIENT_ID=my-client-id
OPCO_EP_CLIENT_SECRET=my-client-secret
OPCO_EP_TOKEN_URL=https://auth.opcoep.fr/oauth/token

# Cache
CACHE_DEFAULT_TTL=600

# Hub (optionnel)
HUB_URL=ws://hub:8080
HUB_API_KEY=hub-secret-key