Module Stancer: Difference between revisions

Jump to navigation Jump to search

Module Stancer (view source)

Revision as of 21:51, 19 October 2026

36,886 bytes added ,  13 days ago
restore stancer page
VisualWikitext
(module mollie)
Tags: Replaced 2017 source edit
(restore stancer page)
 
Line 1: Line 1:
{{TemplateDocDevFr}}{{TemplateDocUtil}}
{{TemplateDocDevFr}}{{TemplateDocUtil}}
[[Category:Complementary modules]]
[[Category:Complementary modules]]
[[Category:Mollie]]
[[Category:Stancer]]
[[Category:caprel]]
[[Category:caprel]]


=Informations=
=Informations=
{{TemplateModuleInfo
{{TemplateModuleInfo
|modulename=Mollie
|modulename=Stancer
|editor=CAP-REL
|editor=CAP-REL
|web=[https://cap-rel.fr cap-rel.fr]
|web=[https://cap-rel.fr cap-rel.fr]
|webbuy={{LinkToPluginDownloadDoliStore|keyword=mollie}}
|webbuy={{LinkToPluginDownloadDoliStore|keyword=stancer}}
|status=stable
|status=stable
|prerequisites=PHP 7.4 minimum
|prerequisites=PHP 7.4 minimum
|minversion=18.0.0
|minversion=15.0.0
|note= Utilisez Mollie comme prestataire de paiement
|note= Utilisez Stancer comme prestataire de paiement
}}
}}




=Qu'est-ce que le module Mollie pour Dolibarr ?=
=Qu'est-ce que le module Stancer pour Dolibarr ?=


Plus de documentation sur le site de l'éditeur : https://doc.cap-rel.fr/mollie
Plus de documentation sur le site de l'éditeur<span> </span>: https://doc.cap-rel.fr/projet_stancer/accueil


Le module '''Mollie''' est un module d'intégration de la passerelle de paiement Mollie dans l'ERP [https://www.dolibarr.org Dolibarr]. Il permet d'encaisser des paiements par '''carte bancaire''' (avec 3D Secure) et par '''prélèvement SEPA''', et tous les autres moyens de paiements proposés par Mollie directement depuis les objets métier de Dolibarr (factures, commandes, devis, dons, cotisations d'adhérents).
Le module '''Stancer''' est un module d'intégration de la passerelle de paiement [https://stancer.com/fr/paiement-en-ligne?mtm_campaign=Dolibarr&mtm_source=Dolibarr Stancer] dans l'ERP [https://www.dolibarr.org Dolibarr]. Il permet d'encaisser des paiements par '''carte bancaire''' (avec 3D Secure) et par '''prélèvement SEPA''', directement depuis les objets métier de Dolibarr (factures, commandes, devis, dons, cotisations d'adhérents).


'''Langues supportées :''' Français, Anglais, Allemand, Espagnol, Italien, Néerlandais
'''Langues supportées<span> </span>:''' Français, Anglais, Allemand, Espagnol, Italien, Néerlandais
 
==Architecture technique==
 
 
===Tables de base de données===
 
Le module crée trois tables principales dans la base de données Dolibarr<span> </span>:
 
====llx_stancer_stancer_payments====
 
Stocke l'historique de tous les paiements (CB et SEPA).
 
{| class="wikitable"
!Champ!!Type!!Description
|-
|<code>rowid</code>||INTEGER (PK)||Identifiant interne auto-incrémenté
|-
|<code>stancer_id</code>||VARCHAR(30) NOT NULL||Identifiant unique du paiement chez Stancer
|-
|<code>amount</code>||INTEGER||Montant en centimes
|-
|<code>fee</code>||INTEGER||Frais de transaction en centimes
|-
|<code>currency</code>||VARCHAR(4)||Code devise (EUR, USD, etc.)
|-
|<code>description</code>||VARCHAR(64)||Description du paiement
|-
|<code>order_id</code>||VARCHAR(36)||Référence de commande du marchand
|-
|<code>unique_id</code>||VARCHAR(36) UNIQUE||Identifiant unique / clé d'idempotence (TAG)
|-
|<code>method</code>||VARCHAR(4)||Méthode de paiement (<code>card</code> ou <code>sepa</code>)
|-
|<code>card</code>||VARCHAR(30)||Identifiant de la carte si paiement CB
|-
|<code>sepa</code>||VARCHAR(30)||Identifiant SEPA si prélèvement
|-
|<code>customer</code>||VARCHAR(30)||Identifiant client Stancer
|-
|<code>refunds</code>||TEXT||Tableau JSON des remboursements associés
|-
|<code>response</code>||VARCHAR(4)||Code de réponse bancaire
|-
|<code>capture</code>||BOOLEAN||Capture immédiate (oui/non)
|-
|<code>created</code>||DATETIME||Date de création chez Stancer
|-
|<code>date_bank</code>||TIMESTAMP||Date de traitement bancaire
|-
|<code>live_mode</code>||BOOLEAN||Mode production (1) ou test (0)
|-
|<code>fk_soc</code>||INTEGER||Clé étrangère vers le tiers Dolibarr
|-
|<code>status</code>||INTEGER NOT NULL||Code de statut du paiement
|-
|<code>entity</code>||INTEGER||Support multi-entité
|-
|<code>date_creation</code>||DATETIME NOT NULL||Date de création locale
|-
|<code>tms</code>||TIMESTAMP||Date de dernière modification
|-
|<code>fk_user_creat</code>||INTEGER (FK → llx_user)||Utilisateur créateur
|-
|<code>fk_user_modif</code>||INTEGER||Utilisateur modificateur
|}
 
'''Index<span> </span>:''' stancer_id, fk_soc, status
 
====llx_stancer_stancer_payouts====
 
Stocke les reversements (virements de Stancer vers le compte bancaire du marchand).
 
{| class="wikitable"
!Champ!!Type!!Description
|-
|<code>rowid</code>||INTEGER (PK)||Identifiant interne
|-
|<code>payout_id</code>||VARCHAR(30) NOT NULL||Identifiant unique du reversement chez Stancer
|-
|<code>amount</code>||INTEGER||Montant total en centimes
|-
|<code>fees</code>||INTEGER||Frais de traitement en centimes
|-
|<code>amount_net</code>||INTEGER||Montant net (montant - frais)
|-
|<code>currency</code>||VARCHAR(4)||Code devise
|-
|<code>date_paym</code>||DATETIME||Date des transactions incluses
|-
|<code>date_bank</code>||DATETIME||Date de virement effectif
|-
|<code>details</code>||TEXT||Détails complémentaires (JSON)
|-
|<code>payments</code>||TEXT||JSON des paiements inclus dans ce reversement
|-
|<code>refunds</code>||TEXT||JSON des remboursements inclus
|-
|<code>disputes</code>||TEXT||JSON des litiges inclus
|-
|<code>statement_description</code>||TEXT||Libellé du relevé bancaire
|-
|<code>status</code>||INTEGER NOT NULL||Statut du reversement
|-
|<code>entity</code>||INTEGER||Support multi-entité
|-
|<code>tms</code>||TIMESTAMP||Date de dernière modification
|}
 
'''Index<span> </span>:''' payout_id, status
 
====llx_stancer_stancer_refunds====
 
Stocke les remboursements émis vers les clients.
 
{| class="wikitable"
!Champ!!Type!!Description
|-
|<code>rowid</code>||INTEGER (PK)||Identifiant interne
|-
|<code>refund_id</code>||VARCHAR(30) NOT NULL||Identifiant unique du remboursement chez Stancer
|-
|<code>payment_id</code>||VARCHAR(30) NOT NULL||Identifiant du paiement d'origine
|-
|<code>amount</code>||INTEGER||Montant remboursé en centimes
|-
|<code>currency</code>||VARCHAR(4)||Code devise
|-
|<code>status</code>||INTEGER NOT NULL||Statut du remboursement
|-
|<code>created</code>||DATETIME||Date de création chez Stancer
|-
|<code>date_refund</code>||TIMESTAMP||Date de traitement du remboursement
|-
|<code>date_bank</code>||TIMESTAMP||Date de crédit bancaire
|-
|<code>live_mode</code>||BOOLEAN||Mode production ou test
|-
|<code>fk_soc</code>||INTEGER||Clé étrangère vers le tiers
|-
|<code>entity</code>||INTEGER||Support multi-entité
|-
|<code>date_creation</code>||DATETIME NOT NULL||Date de création locale
|-
|<code>tms</code>||TIMESTAMP||Date de dernière modification
|-
|<code>fk_user_creat</code>||INTEGER (FK → llx_user)||Utilisateur créateur
|-
|<code>fk_user_modif</code>||INTEGER||Utilisateur modificateur
|}
 
'''Index<span> </span>:''' refund_id, payment_id, status, fk_soc
 
==Fonctionnalités==
 
===1. Paiement par carte bancaire (CB)===
 
====1.1 Flux de paiement CB====
 
Le paiement par carte bancaire suit le flux suivant<span> </span>:
 
#L'utilisateur Dolibarr clique sur le bouton "Payer avec Stancer" depuis la fiche d'une facture, commande, devis, don ou cotisation
#Le module valide l'objet (statut, montant restant dû, etc.)
#Un paiement est créé via l'API Stancer (<code>POST /checkout/</code>)
#L'enregistrement est sauvegardé dans <code>llx_stancer_stancer_payments</code>
#Le client est redirigé vers la page hébergée Stancer<span> </span>: <code>https://payment.stancer.com/{pubkey}/{paymentId}</code>
#Le client saisit ses informations de carte et confirme (avec 3D Secure si nécessaire)
#Stancer rappelle la page de retour<span> </span>: <code>/public/paymentback.php</code>
#La page de retour vérifie le statut du paiement via l'API
#Si le paiement est confirmé<span> </span>: enregistrement du paiement dans Dolibarr, mise à jour de la facture, envoi d'email de confirmation
 
====1.2 Page publique CB====
 
La page <code>public/cb.php</code> permet aux clients d'enregistrer une carte bancaire pour des paiements ultérieurs (sans effectuer de transaction immédiate).
 
'''Champs du formulaire<span> </span>:'''
 
*Nom de la société (lecture seule)
*Nom du titulaire de la carte
*Numéro de carte (masqué avec auto-formatage)
*Date d'expiration (format MM/AAAA)
*CVC/CVV
 
'''Sécurité<span> </span>:'''
 
*Protection CSRF via jeton
*Clé sécurisée<span> </span>: <code>hash("CB-{socid}-{nom_société}-{PAYMENT_SECURITY_TOKEN}")</code>
*Détection de rechargement de page pour prévenir les doublons
*Support de la pré-autorisation 3DS (<code>action=preauth</code>)
 
====1.3 Configuration CB====
 
{| class="wikitable"
!Paramètre!!Description
|-
|<code>STANCER_ENABLE_CB</code>||Activer/désactiver les paiements CB
|-
|<code>STANCER_PUBLIC_CB_PAGE</code>||Activer la page publique d'enregistrement de carte
|-
|<code>STANCER_CB_ORDER_PARTIAL_PAY</code>||Pourcentage d'acompte pour les commandes (0 = totalité)
|-
|<code>STANCER_CB_PROPAL_PARTIAL_PAY</code>||Pourcentage d'acompte pour les devis
|-
|<code>STANCER_AUTO_MAIL_ORDER_CB</code>||Envoi automatique d'email lors de l'initiation d'un paiement CB
|-
|<code>STANCER_AUTO_MAIL_INVOICES_CB</code>||Envoi automatique d'email CB pour les factures
|-
|<code>STANCER_AUTO_MAIL_INVOICES_CB_MAILTYPE</code>||Modèle d'email à utiliser pour les notifications CB
|}
 
====1.4 Acomptes et paiements partiels====
 
Le module supporte les acomptes sur les commandes et les devis<span> </span>:
 
*Configurable via <code>STANCER_CB_ORDER_PARTIAL_PAY</code> (pourcentage de 1 à 100)
*Configurable via <code>STANCER_CB_PROPAL_PARTIAL_PAY</code> pour les devis
*Le montant de l'acompte est calculé automatiquement<span> </span>: <code>total_ttc × pourcentage / 100</code>
*Les paiements partiels sont marqués avec un flag <code>partialPayment=1</code>
*Suivi des paiements multiples via un séquenceur (<code>SEQ={compteur}</code> dans le TAG)
 
===2. Paiement par prélèvement SEPA===
 
====2.1 Création de mandat SEPA====
 
La page publique <code>public/sepa-iban.php</code> permet aux clients de saisir leur IBAN pour créer un mandat SEPA.
 
'''Champs du formulaire<span> </span>:'''
 
*Nom de la société (lecture seule)
*Nom du titulaire du compte
*Nom de la banque
*IBAN (avec auto-espacement)
*BIC (optionnel, récupéré automatiquement depuis Stancer si absent)
 
'''Processus de création<span> </span>:'''
 
#Validation de l'IBAN via la bibliothèque <code>PHP_IBAN</code>
#Création du compte client Stancer si nécessaire
#Création/mise à jour de l'enregistrement <code>societe_rib</code> dans Dolibarr<span> </span>:
#*Label<span> </span>: <code>stancer-sepa-tst</code> (test) ou <code>stancer-sepa</code> (production)
#*RUM auto-généré via <code>BonPrelevement::buildRumNumber()</code>
#*Type FRST/RECUR (premier/récurrent)
#Enregistrement de l'IBAN chez Stancer via <code>stancerAddSEPAIfNeeded()</code>
#Génération optionnelle du PDF de mandat SEPA (si <code>STANCER_MANDATE_AUTO</code> activé)
#Signature électronique optionnelle via UpToSign (si <code>STANCER_MANDATE_AUTO_UPTOSIGN</code> activé)
 
====2.2 Flux de paiement SEPA====
 
#Le système (ou l'utilisateur) déclenche un prélèvement SEPA via <code>stancerSEPAstartPay()</code>
#Validation du délai SEPA (configurable, par défaut 5 jours avant l'échéance)
#Vérification du montant maximum autorisé (<code>STANCER_SWITCH_SEPA_AMOUNT_MAX</code>)
#Validation de la date de paiement de la facture
#Création du paiement via l'API Stancer
#Sauvegarde dans <code>llx_stancer_stancer_payments</code>
 
====2.3 Configuration SEPA====
 
{| class="wikitable"
!Paramètre!!Description
|-
|<code>STANCER_PUBLIC_IBAN_PAGE</code>||Activer la page publique de saisie IBAN
|-
|<code>STANCER_PUBLIC_IBAN_PAGE_FORCE</code>||Forcer l'affichage de la page IBAN
|-
|<code>STANCER_MANDATE_AUTO</code>||Générer automatiquement le PDF du mandat SEPA
|-
|<code>STANCER_MANDATE_AUTO_UPTOSIGN</code>||Intégration signature électronique UpToSign
|-
|<code>STANCER_MANDATE_AUTO_UPTOSIGN_NOCLICK</code>||Redirection automatique vers la signature
|-
|<code>STANCER_DELAY_SEPA</code>||Délai en jours avant prélèvement (défaut<span> </span>: 5)
|-
|<code>STANCER_DELAY_SEPA_UPDATE_INVOICES</code>||Mettre à jour les dates de factures selon le délai
|-
|<code>STANCER_SWITCH_SEPA_AMOUNT_MAX</code>||Montant maximum pour un prélèvement SEPA
|-
|<code>STANCER_SWITCH_SEPA_TO_OTHER_BANK</code>||Basculer vers un autre compte bancaire au-delà du seuil
|-
|<code>STANCER_AUTO_MAIL_INVOICES_SEPA</code>||Email automatique pour les prélèvements SEPA
|-
|<code>STANCER_AUTO_MAIL_INVOICES_SEPA_MAILTYPE</code>||Modèle d'email SEPA
|-
|<code>STANCER_EMAIL_DPO</code>||Email du Délégué à la Protection des Données (RGPD)
|-
|<code>PRELEVEMENT_ICS</code>||Identifiant Créancier SEPA (ICS)
|}
 
====2.4 Génération de mandat PDF====
 
Le module inclut un générateur PDF spécifique (<code>pdf_sepamandate_stancer</code>) qui produit<span> </span>:
 
*La Référence Unique de Mandat (RUM)
*L'Identifiant Créancier SEPA (ICS)
*Les coordonnées du créancier (nom, adresse complète)
*Le formulaire débiteur (nom, adresse, IBAN, BIC)
*La case à cocher FRST/RECUR
*Les textes légaux SEPA relatifs au traitement des données et aux droits
*Les informations du DPO (Délégué à la Protection des Données)
*L'espace de signature (avec support UpToSign pour signature électronique)
 
===3. Gestion des remboursements===
 
====3.1 Fonctionnalités====
 
*Création de remboursements via l'API Stancer (<code>POST /refunds/</code>)
*Suivi des remboursements dans la table <code>llx_stancer_stancer_refunds</code>
*Liaison avec le paiement d'origine via <code>payment_id</code>
*Statuts<span> </span>: Brouillon (0), Validé (1), Annulé (9)
*Page de liste dédiée avec filtres et recherche (<code>stancer_refunds_list.php</code>)
*Détection des remboursements déjà effectués pour éviter les doublons
 
====3.2 Statuts de remboursement====
 
{| class="wikitable"
!Code!!Statut!!Description
|-
|0||Brouillon||Remboursement en attente de traitement
|-
|1||Validé||Remboursement effectué
|-
|9||Annulé||Remboursement annulé
|}
 
===4. Gestion des reversements (Payouts)===
 
====4.1 Fonctionnalités====
 
Les reversements représentent les virements effectués par Stancer vers le compte bancaire du marchand.
 
*Synchronisation des reversements depuis l'API Stancer (<code>GET /payouts/</code>)
*Détail des reversements<span> </span>: paiements inclus, remboursements, litiges
*Calcul du montant net (montant brut - frais)
*'''Disponible uniquement en mode production''' (les reversements n'existent pas en mode test)
 
====4.2 Statuts des reversements====
 
{| class="wikitable"
!Code!!Statut!!Description
|-
| -10||Erreur||Erreur de traitement
|-
|0||Brouillon||En attente
|-
|1||En attente||Traitement en cours
|-
|2||À payer||Programmé pour paiement
|-
|3||Envoyé||Envoyé à la banque
|-
|4||Payé||Crédité sur le compte
|-
|5||Échoué||Échec du virement
|-
|9||Annulé||Reversement annulé
|-
|10||Validé||Validé dans le système
|}
 
====4.3 Import de relevés de reversement====
 
La page <code>stancer_import_check_reversements.php</code> permet d'importer et vérifier les relevés mensuels de Stancer au format CSV.
 
'''Processus d'import<span> </span>:'''
 
#Téléversement du fichier CSV avec le numéro de relevé
#Analyse automatique des en-têtes et mapping des colonnes
#Pour chaque opération (paiement, remboursement, litige)<span> </span>:
#*Vérification de l'existence de l'opération en banque (champ <code>num_chq</code>)
#*Validation des montants
#*Mise à jour du <code>num_releve</code>
#Pour chaque reversement<span> </span>:
#*Création d'une écriture VIR (virement) vers le compte principal
#*Création d'une écriture PRE (prélèvement) pour les frais
#Vérification croisée<span> </span>: détection des écritures bancaires absentes du fichier d'import
#Totalisation des crédits et débits avec comparaison
 
===5. Statuts des paiements===
 
{| class="wikitable"
!Code!!Statut!!Description
|-
| -10||Erreur||Erreur technique lors du paiement
|-
| -1||Masqué||Paiement masqué dans l'interface
|-
|0||Brouillon||Paiement initialisé, en attente
|-
|1||Autorisé||Autorisé par la banque, pas encore capturé
|-
|2||Capturé||Montant crédité sur le compte
|-
|3||Capture envoyée||Capture en cours de traitement
|-
|4||Contesté||Le client a contesté le paiement (litige)
|-
|5||Expiré||Paiement expiré
|-
|6||Échoué||Paiement échoué
|-
|7||Refusé||Paiement refusé par la banque
|-
|8||À capturer||Sera traité dans la journée
|-
|9||Annulé||Paiement annulé
|-
|10||Validé||Paiement validé dans le système
|}
 
===6. Pages de liste et de gestion===
 
====6.1 Liste des paiements (<code>stancer_payments_list.php</code>)====
 
'''Colonnes affichées<span> </span>:'''
 
*Identifiant interne (rowid)
*Identifiant Stancer (stancer_id) — lien cliquable vers le dashboard Stancer
*Montant (converti de centimes en devise)
*Devise
*Description
*Référence commande (order_id) — lien vers la facture/commande Dolibarr
*Identifiant unique (TAG)
*Méthode (card/sepa)
*Identifiant carte / SEPA
*Identifiant client Stancer
*Remboursements associés
*Statut (avec badge coloré)
*Code réponse bancaire
*Statut de capture
*Date de création
*Mode (test/production)
*Tiers (avec résolution automatique depuis le TAG si absent)
 
'''Fonctionnalités<span> </span>:'''
 
*Filtres individuels par colonne
*Recherche globale
*Tri par colonne
*Pagination configurable
*'''Bouton Rafraîchir'''<span> </span>: synchronisation manuelle avec l'API Stancer (déclenche <code>stancerRefreshAllPayments()</code>, <code>stancerRefreshAllPaymentsFromDolibarr()</code> et <code>stancerRemoveOldDraftPayments()</code>)
*Basculement vue liste / vue Kanban
*Suppression en masse (si permissions)
*Champs supplémentaires (extrafields) dynamiques
*Résolution automatique du tiers (fk_soc) depuis le TAG si absent
 
====6.2 Liste des reversements (<code>stancer_payouts_list.php</code>)====
 
'''Colonnes affichées<span> </span>:'''
 
*Identifiant interne et Stancer
*Montant brut, frais, montant net (calculé automatiquement)
*Devise
*Description et libellé relevé
*Dates (paiement et virement bancaire)
*Nombre de paiements, remboursements, litiges inclus
*Statut
*Mode (test/production)
 
'''Particularités<span> </span>:'''
 
*'''Le rafraîchissement n'est disponible qu'en mode production''' (message d'avertissement en mode test)
*Bouton "Nouveau" pour créer un enregistrement manuellement (tests)
 
====6.3 Liste des remboursements (<code>stancer_refunds_list.php</code>)====
 
Interface standard de liste Dolibarr avec<span> </span>:
 
*Colonnes triables et filtrables
*Vue liste et Kanban
*Actions en masse (suppression, email)
*Support des champs supplémentaires (extrafields)
 
===7. Page de retour de paiement (<code>public/paymentback.php</code>)===
 
Page publique appelée par Stancer après que le client a complété son paiement. Aucune authentification requise.
 
====7.1 Flux de traitement====
 
#'''Décodage des paramètres'''<span> </span>: déchiffrement Base64 du paramètre <code>s</code> contenant tag, source, ref, securekey, entity
#'''Récupération du paiement''' depuis la table Stancer par UUID ou session
#'''Vérification du statut''' via l'API Stancer (<code>GET /checkout/{id}</code>)
#'''Traitement carte bancaire'''<span> </span>: extraction des données de carte (marque, 4 derniers chiffres, nom, pays), création/mise à jour du mode de paiement
#'''Détection de doublons'''<span> </span>: recherche dans <code>llx_paiement</code> par <code>ext_payment_id</code> — affiche "Rechargement détecté" si doublon
#'''Mise à jour de l'enregistrement''' local via <code>fillDataFromApi()</code>
#'''Actions post-paiement'''<span> </span>: attribution de permissions temporaires, enregistrement du paiement sur l'objet Dolibarr
 
====7.2 Sécurité====
 
*Pas d'authentification requise (page publique)
*CSRF désactivé (callback externe)
*Paramètres encodés en Base64 dans l'URL
*Support multi-entité via le paramètre entity
 
===8. Onglet Tiers (<code>stancer_thirdparty.php</code>)===
 
Ajoute un onglet "Stancer" sur la fiche des tiers dans Dolibarr.
 
'''Sections affichées<span> </span>:'''
 
*'''Compte Stancer'''<span> </span>: nom, date de création, identifiant (lien vers manage.stancer.com), action de suppression
*'''Mandats SEPA''' (si compte existant)<span> </span>: tableau avec label, banque, IBAN, BIC, identifiant Stancer, RUM, date RUM, mode de prélèvement, actions (créer/supprimer sur Stancer)
*'''Cartes bancaires''' (si carte existante)<span> </span>: tableau avec label, type, numéro masqué, titulaire, expiration, type de carte, pays, actions
*'''Lien de paiement du solde'''<span> </span>: bouton "Payer le solde [€X.XX]" pour encaisser directement les factures impayées du tiers
*'''Liens publics'''<span> </span>: vers les pages de saisie IBAN et CB si activées
*'''Intégration UpToSign'''<span> </span>: avertissement si activé mais aucun signataire configuré
 
===9. Comptabilité et rapprochement===
 
====9.1 Gestion des frais====
 
Trois modes de gestion des frais Stancer<span> </span>:
 
{| class="wikitable"
!Mode!!Paramètre!!Description
|-
|Aucun||<code>STANCER_ADD_FEES = NONE</code>||Pas d'enregistrement automatique des frais
|-
|Par reversement||<code>STANCER_ADD_FEES = PAYOUT</code>||Frais enregistrés au niveau de chaque reversement
|-
|Par paiement||<code>STANCER_ADD_FEES = PAYMENT</code>||Frais enregistrés individuellement pour chaque paiement
|}
 
====9.2 Régularisation des écarts comptables (<code>admin/compta.php</code>)====
 
Page dédiée au rapprochement entre les factures fournisseur Stancer et les écritures comptables.
 
'''Fonctionnalités<span> </span>:'''
 
*Détection automatique des écarts entre débits et crédits
*Seuil configurable (<code>STANCER_COMPTA_SEUIL_ECART</code>, ex. 0.05 EUR)
*Création d'écritures OD (Opérations Diverses) pour régulariser
*Deux lignes par écart<span> </span>:
*#Ligne compte fournisseur<span> </span>: débit/crédit du solde d'écart
*#Ligne compte d'écart (658xxx)<span> </span>: contrepartie
 
'''Configuration<span> </span>:'''
 
{| class="wikitable"
!Paramètre!!Description
|-
|<code>STANCER_COMPTA_JOURNAL_OD</code>||Journal pour les écritures OD
|-
|<code>STANCER_COMPTA_ACCOUNT_ECART</code>||Compte comptable pour les écarts (ex. 658xxx)
|-
|<code>STANCER_COMPTA_SEUIL_ECART</code>||Seuil de régularisation (ex. 0.05 EUR)
|-
|<code>STANCER_COMPTA_SUPPLIER_ID</code>||Identifiant du fournisseur Stancer dans Dolibarr
|}
 
====9.3 Enregistrement bancaire====
 
Les paiements sont enregistrés dans le module bancaire de Dolibarr<span> </span>:
 
*Création d'écritures <code>llx_bank</code> pour chaque paiement confirmé
*Enregistrement des frais en écriture séparée si configuré
*Support des virements inter-comptes pour les reversements
*Détection des doublons bancaires (<code>stancerBankLineDoesNotExists()</code>)
 
===10. Automatisation et tâches planifiées===
 
Le module définit trois tâches cron dans Dolibarr<span> </span>:
 
====10.1 StancerCheckPay====
 
'''Fréquence<span> </span>:''' quotidienne
 
'''Action<span> </span>:''' Vérifie le statut des paiements et reversements
 
*Synchronise les paiements depuis l'API Stancer
*Synchronise les paiements locaux non finalisés
*Vérifie les reversements
*Envoie des notifications email si configuré
 
====10.2 StancerCheckTakePayments====
 
'''Fréquence<span> </span>:''' quotidienne
 
'''Action<span> </span>:''' Collecte automatique des paiements SEPA
 
*Recherche les factures avec un mode de paiement SEPA actif
*Vérifie l'existence d'un compte Stancer et d'un mandat SEPA valide
*Initie les prélèvements SEPA pour les factures éligibles
*Gère les acomptes et les échecs de relance
*Génère un rapport HTML/email des actions effectuées
 
====10.3 StancerCheckInvoicesPaid====
 
'''Fréquence<span> </span>:''' quotidienne
 
'''Action<span> </span>:''' Vérification du statut "payé" des factures
 
*Recherche les factures non marquées comme payées
*Vérifie si le montant payé correspond au total TTC
*Marque automatiquement les factures comme payées si le paiement est complet
 
===11. Hooks et intégration Dolibarr===
 
Le module s'intègre dans 14 points d'accroche (hooks) de Dolibarr<span> </span>:
 
{| class="wikitable"
!Hook!!Contexte d'intégration
|-
|<code>newpayment</code>||Création de paiement
|-
|<code>paymentlib</code>||Fonctions de la bibliothèque paiement
|-
|<code>invoicecard</code>||Fiche facture client
|-
|<code>invoicesuppliercard</code>||Fiche facture fournisseur
|-
|<code>ordercard</code>||Fiche commande
|-
|<code>propalcard</code>||Fiche devis / proposition commerciale
|-
|<code>formObjectOptions</code>||Options de formulaire
|-
|<code>thirdpartybancard</code>||Onglet compte bancaire du tiers
|-
|<code>printFieldListTitle</code>||En-têtes de colonnes dans les listes
|-
|<code>printFieldListValue</code>||Valeurs de colonnes dans les listes
|-
|<code>subscription</code>||Cotisations d'adhérents
|-
|<code>doncard</code>||Fiche don
|-
|<code>membercard</code>||Fiche adhérent
|-
|<code>bankline</code>||Ligne d'écriture bancaire
|}
 
'''Actions principales du hook <code>formConfirm</code><span> </span>:'''
 
*<code>stancerCard</code><span> </span>: affiche une popup de paiement CB avec QR code et lien de paiement
*<code>stancerSEPA</code><span> </span>: valide qu'un prélèvement SEPA n'est pas déjà en cours (temporisation de 10 minutes)
 
===12. Variables de substitution===
 
Le module fournit des variables de substitution pour les emails et documents<span> </span>:
 
{| class="wikitable"
!Variable!!Description
|-
|<code>__STANCER_SEPA_RUM__</code>||Référence Unique de Mandat SEPA
|-
|<code>__STANCER_SEPA_DELAIS__</code>||Délai de prélèvement SEPA (en jours)
|-
|<code>__STANCER_SEPA_URL__</code>||Lien public vers la page de saisie IBAN
|}
 
===13. Modèles d'emails===
 
Six modèles d'emails sont préconfigurés à l'installation<span> </span>:
 
{| class="wikitable"
!Modèle!!Utilisation
|-
|'''Stancer Facture (SEPA)'''||Notification de prélèvement SEPA classique
|-
|'''Stancer Facture (SEPA information initiale)'''||Email d'information initial SEPA (obligation réglementaire)
|-
|'''Stancer Facture (SEPA Succès)'''||Confirmation de prélèvement SEPA réussi
|-
|'''Stancer Facture (ERREUR)'''||Notification d'erreur de paiement avec options de récupération
|-
|'''Stancer Facture (CB)'''||Notification de paiement par carte bancaire
|-
|'''Stancer Commande'''||Rappel de paiement pour commande
|}
 
'''Variables disponibles dans les modèles<span> </span>:'''
<code>__REF__</code>, <code>__MYCOMPANY_NAME__</code>, <code>__MYCOMPANY_ADDRESS__</code>, <code>__MYCOMPANY_ZIP__</code>, <code>__MYCOMPANY_TOWN__</code>, <code>__DAY_TEXT__</code>, <code>__DAY__</code>, <code>__MONTH_TEXT__</code>, <code>__YEAR__</code>, <code>__AMOUNT_EXCL_TAX_FORMATED__</code>, <code>__STANCER_SEPA_DELAIS__</code>, <code>__USER_SIGNATURE__</code>, <code>__ONLINE_PAYMENT_URL__</code>
 
===14. Notifications automatiques===
 
{| class="wikitable"
!Paramètre!!Description
|-
|<code>STANCER_AUTO_MAIL_NOTIFICATIONS</code>||Activer les notifications email globales
|-
|<code>STANCER_AUTO_MAIL_NOTIFICATIONS_PAYMENT</code>||Notification à chaque paiement reçu
|-
|<code>STANCER_AUTO_MAIL_NOTIFICATIONS_PAYOUT</code>||Notification à chaque reversement reçu
|-
|<code>STANCER_AUTO_MAIL_NOTIFICATIONS_ON_NEW_CB_AND_SEPA</code>||Notification lors de l'enregistrement d'une nouvelle carte ou d'un nouveau mandat SEPA
|-
|<code>STANCER_AUTO_MAIL_INVOICES_ERROR</code>||Notification en cas d'erreur de paiement
|}
 
==Administration==
 
===Pages d'administration===
 
Le module fournit 12 pages d'administration accessibles depuis le menu Stancer<span> </span>:
 
{| class="wikitable"
!Page!!Fichier!!Description
|-
|Configuration||<code>admin/setup.php</code>||Paramètres généraux, clés API, comptes bancaires, synchronisation
|-
|Carte bancaire||<code>admin/cb.php</code>||Configuration des paiements CB, 3DS, emails
|-
|SEPA||<code>admin/sepa.php</code>||Configuration des prélèvements SEPA, délais, montants max
|-
|Email||<code>admin/mail.php</code>||Configuration des modèles d'emails
|-
|Association||<code>admin/asso.php</code>||Activation pour les associations et adhérents
|-
|Comptabilité||<code>admin/compta.php</code>||Rapprochement comptable et régularisation des écarts
|-
|Test||<code>admin/test.php</code>||Interface de test de l'API (client, paiements, reversements)
|-
|À propos||<code>admin/about.php</code>||Informations sur le module
|-
|Logs||<code>admin/logs.php</code>||Visualisation des journaux de transactions
|-
|Extrafields Paiements||<code>admin/stancer_payments_extrafields.php</code>||Champs personnalisés pour les paiements
|-
|Extrafields Reversements||<code>admin/stancer_payouts_extrafields.php</code>||Champs personnalisés pour les reversements
|-
|Extrafields Remboursements||<code>admin/stancer_refunds_extrafields.php</code>||Champs personnalisés pour les remboursements
|}
 
===Configuration générale===
 
====Clés API====
 
{| class="wikitable"
!Paramètre!!Description
|-
|<code>STANCER_IS_PROD</code>||Mode production (1) ou test (0)
|-
|<code>STANCER_TEST_PUBLIC_KEY</code>||Clé publique de test
|-
|<code>STANCER_TEST_PRIVATE_KEY</code>||Clé privée de test (masquée)
|-
|<code>STANCER_PROD_PUBLIC_KEY</code>||Clé publique de production
|-
|<code>STANCER_PROD_PRIVATE_KEY</code>||Clé privée de production (masquée)
|}
 
====Comptes et utilisateurs====
 
{| class="wikitable"
!Paramètre!!Description
|-
|<code>STANCER_USER_ACCOUNT_FOR_ACTIONS</code>||Utilisateur Dolibarr pour les actions automatisées
|-
|<code>STANCER_BANK_ACCOUNT_FOR_PAYMENTS</code>||Compte bancaire pour l'enregistrement des paiements
|-
|<code>STANCER_BANK_MAIN_ACCOUNT_FOR_PAYOUTS</code>||Compte bancaire principal pour les reversements
|}
 
====Synchronisation====
 
{| class="wikitable"
!Paramètre!!Description!!Défaut
|-
|<code>STANCER_NUMBER_OF_ITEMS_TO_SYNC</code>||Nombre d'éléments par appel API||200 (plage<span> </span>: 10-1000)
|-
|<code>STANCER_NB_DAYS_TO_SYNC</code>||Nombre de jours d'historique à récupérer||31 (plage<span> </span>: 10-730)
|}
 
====Divers====
 
{| class="wikitable"
!Paramètre!!Description
|-
|<code>STANCER_MONTHLY_SUBSCRIPTION_FEE</code>||Abonnement mensuel (frais de TPE, défaut<span> </span>: 18 EUR)
|-
|<code>STANCER_AUTO_INVOICE_ON_PROPAL_PAID</code>||Créer automatiquement une facture quand un devis est payé
|}
 
===Interface de test (<code>admin/test.php</code>)===
 
Permet de vérifier le bon fonctionnement de l'API directement depuis Dolibarr<span> </span>:
 
#'''Vérification de la configuration'''<span> </span>: affiche le mode (PRODUCTION / TEST) et un aperçu de la clé publique
#'''Création de client'''<span> </span>: crée ou récupère un client de test, affiche le lien vers le dashboard Stancer
#'''Lecture de client'''<span> </span>: affiche les détails (identifiant, email, nom, mobile)
#'''Liste des paiements récents'''<span> </span>: affiche les 5 derniers paiements (identifiant, montant, statut, date)
#'''Liste des reversements récents'''<span> </span>: affiche les 5 derniers reversements
#'''Détail d'un paiement'''<span> </span>: informations détaillées incluant le masquage de carte (**** + 4 derniers chiffres)
 
===Support des associations (<code>admin/asso.php</code>)===
 
L'activation de Stancer pour les associations crée automatiquement trois champs supplémentaires sur les adhérents<span> </span>:
 
{| class="wikitable"
!Champ!!Type!!Description
|-
|<code>stancer_sepa_ref</code>||VARCHAR(32)||Référence du mandat SEPA de l'adhérent
|-
|<code>stancer_cb_ref</code>||VARCHAR(32)||Référence de la carte bancaire de l'adhérent
|-
|<code>stancer_account</code>||VARCHAR(32)||Identifiant du compte client Stancer (obligatoire)
|}
 
==API REST Stancer==
 
Le module utilise un client REST intégré (<code>StancerApi</code>) qui communique directement avec l'API Stancer sans dépendance externe.
 
 
==Synchronisation==
 
===Principes===
 
*La synchronisation est '''exclusivement manuelle''' (bouton Rafraîchir dans les listes)
*Jamais de rafraîchissement automatique lors de la recherche ou du filtrage
*Les fonctions de synchronisation sont chaînées conditionnellement<span> </span>: si l'une échoue, les suivantes sont ignorées
 
===Flux de synchronisation des paiements===
 
#<code>stancerRefreshAllPayments()</code><span> </span>: récupère les '''nouveaux''' paiements depuis l'API Stancer depuis la dernière synchronisation
#<code>stancerRefreshAllPaymentsFromDolibarr()</code><span> </span>: vérifie le statut des paiements locaux '''non finalisés''' via l'API
#<code>stancerRemoveOldDraftPayments()</code><span> </span>: supprime les paiements brouillon anciens (> 30 jours), sans appel API
 
===Flux de synchronisation des reversements===
 
#<code>stancerRefreshAllPayoutsFromStancer()</code><span> </span>: récupère les reversements depuis l'API (mode production uniquement)
#Enchaîne avec la vérification locale si la première étape réussit
#Arrêt immédiat en cas d'erreur
 
==Objets métier supportés==
 
Le module s'intègre avec les objets Dolibarr suivants<span> </span>:
 
{| class="wikitable"
!Objet Dolibarr!!Paiement CB!!Prélèvement SEPA!!Remarques
|-
|'''Facture client'''||Oui||Oui||Calcul automatique du solde restant dû
|-
|'''Commande'''||Oui||—||Support des acomptes (pourcentage configurable)
|-
|'''Devis / Proposition commerciale'''||Oui||—||Support des acomptes, page dédiée
|-
|'''Don'''||Oui||—||Via la page publique de paiement
|-
|'''Cotisation d'adhérent'''||Oui||Oui||Nécessite l'activation du mode association
|}
 
==Codes de réponse bancaire==
 
Le module interprète les codes de réponse bancaire standards<span> </span>:
 
{| class="wikitable"
!Code!!Signification
|-
|00||Transaction approuvée
|-
|02||Contacter l'émetteur de la carte
|-
|03||Accepteur invalide
|-
|04||Conserver la carte
|-
|05||Ne pas honorer
|-
|07||Conserver la carte (conditions spéciales)
|-
|08||Approuver après identification
|-
|12||Transaction invalide
|-
|13||Montant invalide
|-
|14||Numéro de porteur invalide
|-
|15||Émetteur de carte inconnu
|-
|30||Erreur de format
|-
|31||Identifiant de l'acquéreur inconnu
|-
|33||Carte expirée
|-
|34||Suspicion de fraude
|-
|41||Carte perdue
|-
|43||Carte volée
|-
|51||Provision insuffisante ou crédit dépassé
|-
|54||Carte expirée
|-
|56||Carte absente du fichier
|-
|57||Transaction non autorisée pour ce porteur
|-
|58||Transaction non autorisée pour ce terminal
|-
|59||Suspicion de fraude
|-
|60||L'accepteur doit contacter l'acquéreur
|-
|61||Montant maximal de retrait dépassé
|-
|63||Règles de sécurité non respectées
|-
|68||Réponse non parvenue ou reçue trop tard
|-
|75||Nombre maximal d'essais PIN dépassé
|-
|76||Porteur déjà en opposition
|-
|90||Arrêt momentané du système
|-
|91||Émetteur de carte inaccessible
|-
|92||Transaction non trouvée par le réseau
|-
|94||Transaction dupliquée
|-
|96||Mauvais fonctionnement du système
|-
|97||Échéance de la temporisation
|-
|98||Serveur indisponible
|-
|99||Incident domaine initiateur
|-
|7840||Fraude détectée par le réseau CB
|}
 
==Tests==
 
Le module dispose d'une suite complète de tests<span> </span>:
 
===Tests unitaires===
 
{| class="wikitable"
!Fichier!!Couverture
|-
|<code>StancerApiTest.php</code>||Client HTTP StancerApi
|-
|<code>StancerClassTest.php</code>||Classe principale Stancer
|-
|<code>StancerLibTest.php</code>||Fonctions de la bibliothèque partagée
|-
|<code>StancerPaymentsTest.php</code>||Modèle Stancer_payments
|-
|<code>StancerPayoutsTest.php</code>||Modèle Stancer_payouts
|-
|<code>StancerRefundsTest.php</code>||Modèle Stancer_refunds
|}
 
===Tests d'intégration===
 
{| class="wikitable"
!Fichier!!Couverture
|-
|<code>StancerClassIntegrationTest.php</code>||Intégration classe principale avec Dolibarr
|-
|<code>StancerLibIntegrationTest.php</code>||Intégration fonctions bibliothèque
|-
|<code>StancerPaymentsIntegrationTest.php</code>||Intégration paiements
|-
|<code>StancerPayoutsIntegrationTest.php</code>||Intégration reversements
|-
|<code>StancerRefundsIntegrationTest.php</code>||Intégration remboursements
|-
|<code>StancerTriggersIntegrationTest.php</code>||Intégration déclencheurs
|}
 
===Infrastructure de test===
 
*'''Framework<span> </span>:''' PHPUnit 9.6+
*'''Mocks<span> </span>:''' HttpMock (simulation HTTP), DolibarrMocks (simulation Dolibarr)
*'''Fixtures<span> </span>:''' StancerApiFixtures (réponses API pré-enregistrées)
*'''Base de données<span> </span>:''' SQLite via <code>cap-rel/dolibarr-integration-sqlite</code>
*'''Couverture<span> </span>:''' PCOV avec rapport HTML
 
==Conformité et sécurité==
 
===RGPD / Protection des données===
 
*Configuration du DPO (Délégué à la Protection des Données) via <code>STANCER_EMAIL_DPO</code>
*Textes légaux SEPA intégrés dans les mandats PDF
*Informations sur le traitement des données dans les formulaires publics
 
===Sécurité des paiements===
 
*Support 3D Secure pour les paiements par carte
*Clés sécurisées (hachage) pour les pages publiques
*Détection de rechargement de page pour prévenir les paiements en double
*Protection CSRF sur les formulaires (désactivée uniquement sur les callbacks externes)
*Arrêt immédiat sur erreur 401 (authentification) pour éviter les requêtes en boucle
*Masquage des numéros de carte (affichage des 4 derniers chiffres uniquement)
 
===Multi-entité===
 
*Toutes les tables supportent le champ <code>entity</code> pour la gestion multi-société
*Les clés API sont configurables par entité
*Le contexte multi-entité est propagé dans les callbacks publics
 
==Historique des versions==
 
{| class="wikitable"
!Version!!Date!!Changements majeurs
|-
|1.2.136||2026-01-19||Paiement partiel (acompte) sur les devis
|-
|1.2.130||—||Corrections SQL des tâches cron
|-
|1.2.124||—||Migration vers getDolGlobalString(), support multi-entité, options d'automatisation SEPA
|-
|1.2.117||—||Nettoyage PHPStan, restauration gestion des frais
|-
|1.2.109||—||Second mandat SEPA, import de relevés, compatibilité Dolibarr 20
|-
|1.2.108||—||Support des remboursements, import CSV de relevés, helpers bancaires
|-
|1.2.100||—||Corrections de conditions de course, améliorations des popups
|-
|1.2.88||—||Retour bancaire anticipé CB, automatisation statut facture payée
|-
|1.2.80||—||Délai SEPA, gestion multi-entité
|-
|1.2.52||—||Rétro-portage PHP-IBAN, conformité CNIL/DPO
|-
|1.2.0||—||Configuration du délai SEPA, notifications email automatiques
|-
|1.0.0||2023-03-12||Publication initiale
|}
Eric.seigne
417

edits

Retrieved from "https://wiki.dolibarr.org/index.php/Special:MobileDiff/68230"

Navigation menu