Clés et variables d'environnement
Pour celui qui héberge Hela. Les intégrations fonctionnent sans rien de plus que la base de données. Chaque partenaire OAuth demande qu'une application soit enregistrée chez lui : l'exploitant peut le faire une fois pour toutes les entreprises (clés ci-dessous), mais ce n'est pas obligatoire — une entreprise peut enregistrer la sienne depuis la page du connecteur, avec son propre identifiant et son propre secret.
Depuis le back-office
Depuis la 3.0, tout ce qui suit — sauf INTEGRATIONS_KEY — se règle aussi dans le back-office → Intégrations et clés, sans redéploiement : les clients OAuth, l'adresse publique de l'API et de l'application, les clés de connexion Apple. Une valeur enregistrée là l'emporte sur la variable d'environnement du même nom ; effacée, la variable reprend. Les secrets sont scellés avec INTEGRATIONS_KEY et ne sont jamais réaffichés. Les instances relisent les réglages toutes les trente secondes.
INTEGRATIONS_KEY reste volontairement dans l'environnement : c'est elle qui scelle tout le reste, et une serrure dont la clé est dans le même tiroir n'est pas une serrure.
Les variables de l'API
| Variable | Rôle |
|---|---|
INTEGRATIONS_KEY |
La clé qui chiffre les secrets des connexions (AES-256-GCM). Une chaîne aléatoire de 32 octets ou plus ; plusieurs clés séparées par des virgules, la plus récente en premier, pour tourner sans rien déchiffrer à la main. Sans elle, une clé est dérivée de JWT_SECRET et un avertissement est journalisé au démarrage. |
API_PUBLIC_URL |
L'adresse publique de l'API (https://api.example.com/v1), utilisée pour construire les adresses de retour OAuth et de notification des partenaires. Obligatoire pour OAuth et pour les webhooks entrants. |
MIGRATE_ON_BOOT |
false pour que l'API n'applique pas elle-même les migrations du schéma platform au démarrage (voir La base de données). Par défaut elle les applique. |
WEB_PUBLIC_URL |
L'adresse publique de l'application, où renvoyer le navigateur après une connexion Google, Microsoft ou Apple. Par défaut la première origine de WEB_ORIGIN. |
INTEGRATIONS_WORKER |
off pour ne pas exécuter la file des travaux dans ce processus (quand un autre processus la fait). Par défaut, chaque instance de l'API traite la file, avec verrou en base (SKIP LOCKED) : plusieurs instances ne se marchent pas dessus. |
NODE_ENV |
En production, les webhooks vers localhost et les adresses privées sont refusés ; dans tout autre mode ils sont permis, pour développer. |
Les clés OAuth
Un connecteur OAuth sans ses deux variables n'est pas indisponible : sa page demande à l'entreprise sa propre application (identifiant client et secret, adresse de retour affichée), et la connexion se fait avec elle. Les variables ci-dessous évitent simplement cette étape à chaque entreprise.
| Partenaire | Variables | Où les créer | Adresse de retour à déclarer |
|---|---|---|---|
| Google (Drive, Sheets) | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
Google Cloud Console → APIs & Services → Credentials → OAuth client (Web). Activer les APIs Drive et Sheets. Portées demandées : drive.file, spreadsheets. |
${WEB_PUBLIC_URL}/integrations/callback/google-drive et …/google-sheets |
| Microsoft (OneDrive, Excel) | MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET |
Entra admin center → App registrations. Type multitenant + personal accounts. Permissions Files.ReadWrite.AppFolder, offline_access. |
…/callback/onedrive, …/callback/excel-online |
| Dropbox | DROPBOX_CLIENT_ID, DROPBOX_CLIENT_SECRET |
Dropbox App Console, accès App folder. | …/callback/dropbox |
| QuickBooks | QUICKBOOKS_CLIENT_ID, QUICKBOOKS_CLIENT_SECRET |
Intuit Developer → app → Keys & credentials (production après revue). Portée com.intuit.quickbooks.accounting. |
…/callback/quickbooks |
| Xero | XERO_CLIENT_ID, XERO_CLIENT_SECRET |
developer.xero.com → My Apps → Web app. | …/callback/xero |
| Yuki | YUKI_CLIENT_ID, YUKI_CLIENT_SECRET |
Demande au support Yuki (API partenaires). | …/callback/yuki |
| Exact Online | EXACT_CLIENT_ID, EXACT_CLIENT_SECRET |
apps.exactonline.com → Register app. | …/callback/exact |
| Pennylane | PENNYLANE_CLIENT_ID, PENNYLANE_CLIENT_SECRET |
Pennylane → Développeurs → Applications. | …/callback/pennylane |
| DocuSign | DOCUSIGN_CLIENT_ID, DOCUSIGN_CLIENT_SECRET |
DocuSign Admin → Apps and Keys (compte demo pour commencer). | …/callback/docusign |
| Sage Business Cloud | SAGE_CLIENT_ID, SAGE_CLIENT_SECRET |
developerselfservice.sageone.com → Create app. | …/callback/sage |
| Zoho Books | ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET |
api-console.zoho.com → Server-based application. | …/callback/zoho-books |
| Google Calendar | les mêmes que Google, avec l'API Calendar activée | …/callback/google-calendar |
|
| Mollie Connect | MOLLIE_CLIENT_ID, MOLLIE_CLIENT_SECRET |
Tableau de bord Mollie → Développeurs → Applications. | …/callback/mollie |
| Square | SQUARE_CLIENT_ID, SQUARE_CLIENT_SECRET |
developer.squareup.com → application → OAuth (production). | …/callback/square |
| SumUp | SUMUP_CLIENT_ID, SUMUP_CLIENT_SECRET |
me.sumup.com → Développeurs → OAuth. | …/callback/sumup |
| Slack | SLACK_CLIENT_ID, SLACK_CLIENT_SECRET |
api.slack.com/apps → app → portées incoming-webhook, chat:write. |
…/callback/slack |
| Stripe Connect | STRIPE_CLIENT_ID, STRIPE_CLIENT_SECRET |
Tableau de bord Stripe → Connect → Paramètres : l'identifiant ca_… ; le secret est la clé secrète de la plateforme sk_live_…. Sans la paire, chaque entreprise colle sa propre clé Stripe. |
…/callback/stripe |
| Apple (connexion) | APPLE_CLIENT_ID, APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY |
developer.apple.com → Services ID + clé Sign in with Apple. | ${API_PUBLIC_URL}/auth/oauth/apple/callback |
| Google, Microsoft (connexion) | les mêmes paires que ci-dessus | …/auth/oauth/google/callback, …/auth/oauth/microsoft/callback |
L'adresse de retour est sur le domaine de l'application web (WEB_PUBLIC_URL, par défaut la première origine de WEB_ORIGIN), par exemple https://hela-web.vercel.app/integrations/callback/xero : c'est celle qu'une entreprise déclare dans la console du partenaire, et la page du connecteur l'affiche prête à copier. L'application la transmet à l'API, qui fait l'échange. GET /companies/{id}/integrations/meta/callback-url renvoie le gabarit, :provider à remplacer par la clé du connecteur.
Les connecteurs à clé (Odoo, Stripe, Mollie, PayPal, Square, SumUp, mobile money, Yousign, Clockify, Toggl, Shopify, WooCommerce, GoCardless, Ponto, Plaid, messagerie, taux) n'ont besoin d'aucune variable : chaque entreprise saisit ses propres identifiants.
L'application web
| Variable | Rôle |
|---|---|
NEXT_PUBLIC_API_URL |
L'adresse de l'API, la même que API_PUBLIC_URL. Sans elle, l'application est en démonstration et les pages Intégrations, Développeurs et Conformité montrent le catalogue sans rien connecter. |
La base de données
Les tables des intégrations vivent dans le schéma platform (domain_events, integration_connections, integration_jobs, integration_links, integration_logs, api_keys, webhook_endpoints, webhook_deliveries, fiscal_regimes, fiscal_submissions, platform_settings, user_identities, login_codes) et dans chaque schéma d'entreprise (fiscal_journal, time_entries, bank_transactions). Depuis la 3.0.1, l'API applique elle-même les migrations en attente du schéma platform au démarrage, sous un verrou consultatif Postgres (deux instances qui démarrent ensemble ne se gênent pas), avant d'accepter la première requête ; les schémas d'entreprise sont mis à jour juste après, comme avant. pnpm --filter api migration:run reste utilisable depuis un pipeline, et MIGRATE_ON_BOOT=false rend au processus son ancienne retenue. Toutes les migrations de la 3.0 sont additives : aucune table ni colonne existante n'est modifiée ou supprimée.
Rétention : les événements et les journaux de connexion sont gardés 90 jours, les envois de webhooks 30 jours, les travaux terminés 7 jours. Un nettoyage tourne toutes les cinq minutes.
Le réseau
L'API doit pouvoir sortir vers les partenaires (HTTPS) et les administrations — certaines (eTIMS, VFD) sur des adresses IP fixes qu'un pare-feu d'entreprise doit laisser passer. Les webhooks entrants et les retours OAuth exigent que API_PUBLIC_URL soit joignable depuis Internet.
Les webhooks sortants refusent les adresses privées, localhost, et les noms qui s'y résolvent, à la création et à chaque envoi ; les redirections ne sont pas suivies.
Vérifier
- Le journal de démarrage avertit si
INTEGRATIONS_KEYmanque (clé dérivée deJWT_SECRET). - La page Intégrations d'une entreprise montre À configurer sur chaque connecteur OAuth sans application — ni la plateforme ni l'entreprise n'en ont enregistré.
- Si cette page affiche Le serveur n'a pas répondu, l'API n'est pas joignable ou ses tables sont en retard : le journal de démarrage, ligne
[Migrations], dit ce qui a été appliqué. - Créer un webhook vers un
https://webhook.site/…et appuyer sur Tester vérifie la sortie réseau et la file des travaux.