1 — Aperçu du flux OAuth (haut niveau) #

2 — Configuration requise #

• En frontend (nuxt runtimeConfig), exposez uniquement l’URL d’autorisation si vous choisissez de rendre celle-ci côté client ; préférable : exposez un endpoint backend (/api/qonto/authorize) que le client appelle pour initier le flux (ne jamais exposer client_secret ni la clé de registration).

• Mettez à jour config/services.php pour exposer une entrée ‘qonto’ sous le nœud third_party_apis mappant ces variables d’environnement. Le mapping attendu ressemble à :

  • ‘third_party_apis’ => [ ‘qonto’ => [ ‘client_id’ => env(‘QONTO_CLIENT_ID’), ‘client_secret’ => env(‘QONTO_CLIENT_SECRET’), ‘redirect’ => env(‘QONTO_REDIRECT_URI’), ‘authorize_url’ => env(‘QONTO_AUTHORIZE_URL’), ‘token_url’ => env(‘QONTO_TOKEN_URL’), ‘api_base’ => env(‘QONTO_API_BASE’), ‘registration’ => [ ‘api_key’ => env(‘QONTO_REGISTRATION_API_KEY’), ‘api_base’ => env(‘QONTO_REGISTRATION_API_BASE’), ], ‘webhook_secret’ => env(‘QONTO_WEBHOOK_SECRET’), ], ]

Le contrôleur et les clients côté backend lisent désormais ces clés via config(‘services.third_party_apis.qonto’) et config(‘services.third_party_apis.qonto.registration’). Un provider (ThirdPartyApiServiceProvider) enregistre également les objets de configuration/clients (QontoConfig, QontoRegistrationClient) dans le container à partir de ce même nœud de configuration — vous pouvez donc les récupérer via injection de dépendances dans vos contrôleurs/services. QontoConfig encapsule la configuration centrale (endpoints, clés, options) et est l’objet à injecter lorsque vous avez besoin d’accéder à ces valeurs dans vos services.

Exemples de valeurs à vérifier:

• redirect_uri → https://app.example.com/auth/qonto/callback (doit être identique à la valeur enregistrée chez Qonto)
• Scopes → inclure uniquement les scopes nécessaires ; pour activer les fonctionnalités e‑invoicing, incluez explicitement le scope “invoice” (en plus des scopes de lecture des comptes/opérations). Note: l’utilisateur devra accepter ce scope lors du consentement ; sans acceptation, les fonctions e‑invoicing resteront inactives. Note: le QontoOAuthFlowClient (côté serveur) inclut désormais par défaut le scope “invoice” dans l’URL d’autorisation envoyée à Qonto — ajustez la liste des scopes dans votre configuration si vous ne souhaitez pas demander cet accès automatiquement.

3 — Endpoints back-end attendus (recommandés) #

• GET /api/qonto/authorize (ou POST /api/qonto/authorize)
  • Action: initie le flux d’autorisation OAuth. Le backend (QontoOauthController) construit l’URL d’autorisation (incluant client_id, redirect_uri, state et scopes — le QontoOAuthFlowClient inclut désormais par défaut le scope “invoice” pour l’e‑invoicing ; pensez à le retirer si vous ne souhaitez pas demander cet accès) , conserve le state côté serveur et renvoie l’URL au client ou effectue une redirection serveur-side.
  • Remarque: centraliser l’initiation côté serveur permet de ne pas exposer d’informations sensibles et de valider le state/PKCE correctement.
• POST /api/qonto/exchange
  • Reçoit: { code, state, [pkce_verifier?] } (provenant du client)
  • Action: échange code contre access_token et refresh_token auprès de Qonto (utilise QONTO_CLIENT_ID + QONTO_CLIENT_SECRET). Le contrôleur QontoOauthController valide le state et gère le stockage chiffré des tokens.
  • Retour: status + métadonnées (liste des comptes ou identifiant de connexion)
  • Remarque additionnelle: lors de l’échange, le backend persiste systématiquement l’organization_id renvoyé par Qonto en tant que métadonnée de la liaison (à stocker dans le modèle de connexion/compte). Des entrées de log opérationnelles décrivent la réception du code, la réponse d’échange (succès/erreur) et la persistance de l’organization_id pour faciliter le diagnostic côté opérateur.
• POST /api/qonto/register
  • Reçoit: { return_url? } ou contexte d’onboarding
  • Action: utilise la configuration de registration (QONTO_REGISTRATION_API_KEY et QONTO_REGISTRATION_API_BASE) via QontoRegistrationClient (fournie par le container) pour créer un lien/ressource d’onboarding (registration) côté Qonto. Ce flux est utilisé si vous devez initier un parcours d’enregistrement spécifique côté Qonto avant d’obtenir l’autorisation OAuth ou pour des étapes d’activation.
  • Retour: { registration_url } (URL à ouvrir côté client ou redirection serveur)
• GET /api/qonto/accounts
  • Reçoit: session / token côté serveur
  • Retour: liste des comptes Qonto pour l’utilisateur (numéro, nom, type, currency)
• POST /api/qonto/webhook
  • Reçoit: webhook émis par Qonto (vérifié via signature/HMAC). Le contrôleur QontoWebhookController valide la requête (QontoWebhookRequest), poste un job asynchrone (HandleQontoWebhookJob) et délègue le traitement à QontoWebhookHandler. Des events internes peuvent être dispatchés (ex: opérations sur comptes, notifications).
  • Remarque: une commande console (SyncWebhook) est fournie pour créer / synchroniser les webhooks côté Qonto depuis l’application (exécution via artisan). Vérifiez et exécutez cette commande lors du déploiement si nécessaire.
• POST /api/qonto/disconnect (optionnel)
  • Supprime l’association / révoque token côté serveur
• Console: php artisan qonto:sync-einvoicing-status (SyncEInvoicingStatusCommand)
  • Action: synchronise les statuts e‑invoicing des comptes Qonto liés en batch via QontoEInvoicingClient et QontoEInvoicingStatusSynchronizer. Peut être exécutée manuellement ou planifiée via le scheduler pour maintenir les statuts à jour.

Note: la partie backend n’est pas fournie par ces changements front-end. Il faut implémenter ces endpoints si non existants. Vérifiez que config/services.php et .env contiennent bien les nouvelles variables (notamment QONTO_REGISTRATION_API_KEY, QONTO_REGISTRATION_API_BASE et QONTO_WEBHOOK_SECRET) que QontoRegistrationClient, QontoWebhookClient et QontoConfig attendent. Les routes/services/Qonto.php ajoutées exposent les routes liées à ces contrôleurs.

4 — Composants UI et parcours utilisateur #

• EInvoicingOAuthModal.vue
  • Gère l’ouverture de la page d’autorisation Qonto et le traitement du retour (code/state). Le composant appelle maintenant l’endpoint backend d’initiation (/api/qonto/authorize) et peut afficher un écran d’attente pendant l’échange de code.
• EInvoicingQontoAccountModal.vue
  • Affiche les comptes disponibles récupérés depuis le backend et permet la sélection du compte à associer.
• EInvoicingLogoCard.vue, EInvoicingChoiceCard.vue, EInvoicingChecklist.vue, EInvoicingStep.vue, EInvoicingSuccessModal.vue
  • Contribuent au parcours e-invoicing (opt-in, collecte d’information, confirmation).
• pages/[name]/accounting/e-invoicing/index.vue
  • Point d’entrée produit : intègre les composants ci-dessus dans un parcours guidé.

Impact UX:

• Nouvelle option “Se connecter à Qonto” disponible dans la page e-invoicing.
• Après connexion, l’utilisateur sélectionne un compte Qonto à utiliser pour le rapprochement et le flux e-invoicing.
• Modal de succès et checklist guident l’utilisateur après la connexion.
• Si votre installation active le flow de registration/onboarding, l’utilisateur peut être redirigé vers un lien d’onboarding Qonto généré côté serveur (POST /api/qonto/register).
• Les webhooks Qonto peuvent déclencher des mises à jour côté application (transactions, statut d’activation, etc.) — prévoir des messages/indicateurs UI si nécessaire.

5 — Flux côté client : points d’implémentation #

• Protection routes & feature flags
  • Le composable useFeatureFlagGuard a été ajouté afin de conditionner l’accès au parcours e-invoicing selon les flags produit.
• Responsivité / design
  • Nouveaux assets et ajustements Tailwind (tailwind.config.ts, tailwindBreakpoints, CSS) pour que les modals et cartes s’affichent correctement sur mobile & desktop.
• Gestion du state
  • stores/app.js modifié : vérifiez les getters/actions liés à l’ouverture de modals et à la synchronisation de connexion Qonto.
• Interactions asynchrones
  • Les webhooks entrants sont traités de manière asynchrone côté backend (job queue). Le frontend ne doit pas attendre des traitements synchrones lors de la réception d’un webhook.

6 — Tests & validation #

• Tests manuels recommandés
  1. Vérifier que le frontend appelle l’endpoint d’initiation (/api/qonto/authorize) et que le serveur renvoie/redirect correctement vers l’URL d’autorisation Qonto. Vérifier explicitement que l’URL contient les scopes attendus, dont “invoice” si vous activez l’e‑invoicing. Note: par défaut le QontoOAuthFlowClient côté serveur inclut ce scope dans l’URL d’autorisation ; ajustez la configuration des scopes si nécessaire.
  2. S’assurer que le redirect_uri enregistré chez Qonto correspond exactement au runtime config.
  3. Simuler l’échange sur le backend (POST /api/qonto/exchange) et vérifier la liste de comptes renvoyée.
  4. S’assurer que l’organization_id renvoyé par Qonto est bien persisté avec la liaison (vérifier le modèle/DB utilisé pour stocker la connexion).
  5. Tester la sélection d’un compte via EInvoicingQontoAccountModal et vérifier la persistance côté serveur.
  6. Tester l’endpoint de registration (POST /api/qonto/register) si vous utilisez le flux d’onboarding — vérifier que la clé QONTO_REGISTRATION_API_KEY et QONTO_REGISTRATION_API_BASE sont lues par QontoRegistrationClient et que le lien renvoyé est valide. Vérifier l’envoi de la notification/email QontoRegistrationCompleted et le rendu de la vue mail (resources/views/mail/qonto_registration_completed.blade.php).
  7. Vérifier le traitement des webhooks :
     • Assurez-vous que QONTO_WEBHOOK_SECRET est configuré et que les webhooks entrants sont signés correctement.
     • Envoyer des webhooks de test et vérifier que QontoWebhookController valide la signature, poste le job HandleQontoWebhookJob et que QontoWebhookHandler traite les événements attendus.
  8. Vérifier le comportement en cas de token expiré.
  9. Synchronisation e-invoicing :
     • Déclencher manuellement l’event QontoOAuthLinkedEvent (ou effectuer une liaison complète) et vérifier que le listener SyncQontoEInvoicingStatusListener lance la synchronisation et met à jour les statuts e‑invoicing.
     • Exécuter la commande artisan php artisan qonto:sync-einvoicing-status (SyncEInvoicingStatusCommand) et vérifier que les statuts sont mis à jour en batch.
• Logging
  • Loggez clairement les étapes serveur : réception du code, réponse d’échange token, persistance (incluant l’organization_id), erreurs d’API Qonto, appels de registration, réception et traitement des webhooks. Vérifiez les messages de log associés à QontoOauthController, QontoRegistrationController et HandleQontoWebhookJob dans vos fichiers de logs (laravel.log ou channels configurés). Ces logs sont des points d’observation essentiels pour les opérateurs lors d’incidents.
• Environnements
  • Utiliser un environnement sandbox/test si Qonto le propose. Vérifier les différences d’URL API entre sandbox/production.

7 — Impact produit & opérations #

• Menu & navigation
  • sidebar_menu.json et AppsMenu/SidebarMenu ont été modifiés pour intégrer le point d’entrée e-invoicing.
• Labels & i18n
  • locales/fr.json et locales/en.json mis à jour pour les nouveaux textes UI. Vérifiez traduction et ton avant release.
• Assets
  • Ajout de logos et images (logo-qonto.svg, qonto-icon.jpeg) : vérifier licence usage et résolution pour affichage retina.
• Règles d’éligibilité
  • EInvoicingEligibility.ts implémente les règles d’éligibilité : contrôler les critères d’affichage du parcours (ex: type d’entreprise, statut abonnement).
• Opérations & runbook
  • Ajouter la configuration QONTO_WEBHOOK_SECRET sur les environnements et prévoir la surveillance des jobs liés aux webhooks.
  • Utiliser la commande de synchronisation des webhooks (SyncWebhook via artisan) fournie pour enregistrer / mettre à jour les webhooks côté Qonto lors du déploiement.
  • Planifier/exécuter la commande de synchronisation des statuts e‑invoicing (SyncEInvoicingStatusCommand) via le scheduler si vous souhaitez maintenir régulièrement les statuts à jour.
  • Opérations: surveillez aussi les logs d’échange de tokens et la persistance de l’organization_id (champ désormais présent dans le modèle de liaison) pour faciliter le diagnostic et l’alignement avec les informations côté Qonto.

FAQ #