Rapprochement bancaire — Types de pièces extensibles

Principe

Le dialogue « Créer une pièce » de l'outil de rapprochement bancaire listait jusqu'à présent deux types de documents en dur : Saisie de paiement et Écriture au journal. Une application tierce (Lending pour le remboursement d'un prêt, par exemple) pouvait reconnaître ses propres écritures dans les correspondances, mais ne pouvait pas les créer directement depuis le rapprochement.

Désormais, ce dialogue est extensible via un registre : erpnext.accounts.bank_reconciliation.voucher_types. Chaque application peut y inscrire ses propres types de pièces, avec leurs champs de dialogue, leurs conditions d'affichage et leur logique de création côté serveur.

Enregistrer un type de pièce

Inscrivez votre type dans le registre avant le chargement du bundle de l'outil de rapprochement (typiquement via un hook boot ou un script global de votre application) :

frappe.provide("erpnext.accounts.bank_reconciliation.voucher_types");

erpnext.accounts.bank_reconciliation.voucher_types["Loan Repayment"] = {
  is_applicable: (bank_transaction) => bank_transaction.deposit > 0,
  get_fields: (dialog_manager) => [
    // champs de dialogue affichés pour ce type
  ],
  create: (dialog_manager, values, allow_edit) =>
    frappe.xcall("lending.api.create_loan_repayment", { ... }),
};

Contrat de chaque entrée

Une entrée du registre peut définir trois fonctions :

• get_fields(dialog_manager) — renvoie un tableau de champs de dialogue supplémentaires affichés sous le sélecteur « Type de document ». Utilisez dialog_manager pour accéder au contexte (compte bancaire, transaction sélectionnée) si nécessaire.
• is_applicable(bank_transaction) — renvoie true/false pour masquer ou afficher ce type selon la transaction. Par exemple, ne proposer « Remboursement de prêt » que pour les dépôts (bank_transaction.deposit > 0).
• create(dialog_manager, values, allow_edit) — effectue l'appel serveur et renvoie la transaction bancaire réconciliée. Si allow_edit est vrai (chemin « Éditer en pleine page »), renvoyez le brouillon pour que l'utilisateur puisse le compléter avant soumission ; la réconciliation est alors déclenchée automatiquement après soumission.

Comportement de l'interface

• Le menu déroulant Type de document est rafraîchi pour chaque transaction : les types non applicables via is_applicable sont masqués.
• Les types enregistrés par d'autres applications avant le chargement de l'outil sont conservés, et les types natifs (Saisie de paiement, Écriture au journal) restent toujours en premier dans la liste.
• Les champs supplémentaires définis par get_fields sont injectés avant le bloc « Détails de la transaction ».
• Le bouton Soumettre et l'action Éditer en pleine page utilisent la même fonction create_voucher(values, allow_edit), qui appelle create du type sélectionné.

Réconciliation après soumission (pleine page)

Si un type de pièce propose l'édition en pleine page, l'utilisateur peut corriger le brouillon avant de le soumettre. À la soumission :

1. Le document est enregistré comme brouillon.
2. L'utilisateur est redirigé vers le formulaire complet.
3. À la soumission, la transaction bancaire est automatiquement réconciliée avec ce document — une seule fois.

Ce comportement s'applique aussi bien aux types natifs qu'aux types fournis par des applications tierces.

      
sequenceDiagram
  participant U as Comptable
  participant D as Dialogue de rapprochement
  participant S as Serveur
  U->>D: Sélectionne une transaction
  D->>D: Filtre les types via is_applicable
  U->>D: Choisit « Remboursement de prêt »
  D->>U: Affiche les champs spécifiques (get_fields)
  U->>D: Remplit les champs
  alt Soumission directe
    U->>D: Clique « Soumettre »
    D->>S: create(values, allow_edit=false)
    S-->>D: Transaction bancaire réconciliée
    D->>U: Mise à jour des cartes + fermeture
  else Édition pleine page
    U->>D: Clique « Éditer en pleine page »
    D->>S: create(values, allow_edit=true)
    S-->>D: Document brouillon
    D->>U: Ouvre le formulaire
    U->>S: Soumet le document
    S->>S: Réconcilie la transaction bancaire
  end

    

Cas d'usage — Remboursement de prêt

L'application Lending enregistre un type « Loan Repayment » :

• is_applicable : true uniquement pour les dépôts (remboursements reçus).
• get_fields : ajoute un champ « prêt » obligatoire pour rattacher le remboursement au contrat.
• create : appelle lending.api.create_loan_repayment qui crée l'écriture de remboursement et renvoie la transaction réconciliée.

Le comptable voit désormais « Loan Repayment » dans le sélecteur de type de pièce pour les transactions entrantes et peut créer le remboursement sans quitter le rapprochement bancaire.

Points de vigilance

• Le type doit être inscrit avant le chargement du bundle de l'outil de rapprochement. Privilégiez un hook déclenché tôt dans le cycle de vie de l'application cliente.
• Le nom du type dans le registre est la clé utilisée pour l'affichage dans le sélecteur. Évitez les doublons avec les types natifs.
• Si is_applicable n'est pas défini, le type est proposé pour toutes les transactions.
• La fonction create doit toujours renvoyer la transaction bancaire réconciliée (chemin direct) ou le brouillon (pleine page) pour que l'outil puisse mettre à jour l'interface.

Référence

• Merge request : !12077
• Fichier concerné : erpnext/public/js/bank_reconciliation_tool/dialog_manager.js
• Tests : erpnext/tests/js/bank_reconciliation_dialog_manager.test.mjs