Documentation
Developper

Hooks de routage par unité économique

Intercepter et rediriger les e-invoices générées par E-transactions vers des points de traitement métier personnalisés.

Hooks de routage par unité économique

La fonctionnalité de routage des e-invoices par unité économique via des hooks est disponible à partir de la version de développement de E-transactions.

Principe

Lorsqu'une e-invoice est générée par l'application E-transactions, elle peut désormais être interceptée par d'autres applications installées sur le site. Le routage se fait par unité économique : chaque application peut déterminer, en fonction de l'unité économique d'origine, vers quel point de traitement (endpoint, service externe, configuration) l'e-invoice doit être dirigée.

Utilité

Ce mécanisme s'adresse aux situations suivantes :

  • Multi-sociétés avec configurations distinctes : une organisation gère plusieurs sociétés (unités économiques) et chacune doit transmettre ses e-invoices à un service ou un canal de traitement différent.
  • Routage conditionnel vers des services externes : une application tierce doit, selon l'unité économique, décider de l'URL d'envoi, des identifiants de connexion ou du format attendu par le destinataire.
  • Centralisation sans duplication : plutôt que de re-créer une logique de génération e-invoice par application, les modules tiers peuvent réutiliser la génération E-transactions puis rediriger le flux.

Mise en œuvre

Fichier hooks.py de votre application

Dans le fichier hooks.py de votre application (par exemple mon_app/hooks.py), déclarez un point d'extension pour le routage :

etransactions_einvoice_routing = "mon_app.utils.etransactions_routage.router_les_einvoices"

Signature de la fonction attendue

La fonction référencée par le hook doit accepter le doctype E-invoice en cours de génération et retourner le routage applicable. La fonction est appelée par le générateur E-transactions au moment de la construction de l'e-invoice.

def router_les_einvoices(doc, method=None):
    """Décide du point de traitement d'une e-invoice selon l'unité économique.

    Args:
        doc (Einvoice): Document E-invoice en cours de génération.
        method (str, optional): Nom de la méthode appelante.

    Returns:
        dict | None: Configuration de routage ou None pour conserver le comportement par défaut.
    """
    unite_economique = doc.company

    if unite_economique == "Maison Verte SARL":
        return {
            "endpoint": "https://facturation.maison-verte.example/api/etransactions",
            "config": "Paramètres de connexion Maison Verte",
        }

    if unite_economique == "Bureau Moderne":
        return {
            "endpoint": "https://compta.bureau-moderne.example/api/reception",
            "config": "Paramètres de connexion Bureau Moderne",
        }

    return None

Comportement par défaut

Le hook est volontairement non bloquant :

  • Si la fonction référencée est absente ou non définie dans une application, E-transactions conserve son comportement par défaut.
  • Si la fonction retourne None pour une e-invoice donnée, E-transactions continue avec le routage standard pour cette unité économique.
  • Les applications peuvent combiner plusieurs points d'extension : les hooks sont évalués dans l'ordre d'installation des applications sur le site.

Exemple : une application personnalisée pour le groupe Maison Verte

Le groupe Maison Verte SARL exploite deux sociétés distinctes dans Dokos : « Maison Verte SARL » (distribution) et « Bureau Moderne » (ensemblier). Chaque société doit transmettre ses e-invoices à un service de réception dédié.

Étapes de mise en place

  1. Déclaration du hook dans groupe_maison_verte/hooks.py :
etransactions_einvoice_routing = "groupe_maison_verte.etransactions.routage.router_par_unite"
  1. Implémentation du routage dans groupe_maison_verte/etransactions/routage.py :
def router_par_unite(doc, method=None):
    unite = doc.company

    mapping = {
        "Maison Verte SARL": {
            "endpoint": "https://facturation.maison-verte.example/api/etransactions",
            "config": "Config MV",
        },
        "Bureau Moderne": {
            "endpoint": "https://compta.bureau-moderne.example/api/reception",
            "config": "Config BM",
        },
    }

    return mapping.get(unite)
  1. Test du routage : lors de la soumission d'une facture dans « Maison Verte SARL », l'e-invoice est dirigée vers l'endpoint https://facturation.maison-verte.example/api/etransactions. Pour « Bureau Moderne », l'e-invoice est envoyée vers https://compta.bureau-moderne.example/api/reception.

Bonnes pratiques

  • Rendre le routage déterministe : évitez de dépendre d'états externes volatils. Pour une même e-invoice et une même unité économique, le hook doit retourner un résultat stable.
  • Ne pas modifier le document E-invoice dans le hook : le rôle du hook est de décider du routage, pas d'altérer la facture. Les modifications de contenu doivent se faire via d'autres mécanismes.
  • Journaliser les décisions de routage : conservez une trace de l'unité économique et de l'endpoint choisi afin de faciliter le débogage en production.
  • Tester chaque unité économique : assurez-vous que chaque société du site Dokos est couverte par un cas de test pour éviter les envois vers un mauvais canal.

Références