SILADEL - Contributions de l’utilisateur [fr]

README

2026-08-02T13:02:36Z

Goldron : Page créée avec « = STRIPEACCOUNTING FOR Dolibarr ERP CRM = '''StripeAccounting''' reconciles real Stripe movements — per-transaction and subscription/service fees, refunds, disputes... »

= STRIPEACCOUNTING FOR [[Dolibarr ERP CRM]] =

'''StripeAccounting''' reconciles real Stripe movements — per-transaction and subscription/service fees, refunds, disputes (chargebacks) and payouts — with Dolibarr's Stripe intermediary financial account, and automatically generates the missing entries or bank movements.

This module is complementary to the official Stripe module: it never creates payments, invoices, checkout sessions or payment webhooks. It only reads the Stripe API and posts the accounting entries the official module doesn't cover.

== How it works ==

# The module pulls Stripe's Balance Transactions, Charges, Refunds, Disputes and Payouts through the Stripe API, reusing the API key and mode (test/live) already configured by the official Stripe module.
# Every Stripe object is stored once in its own table (<code>llx_stripeaccounting_transaction</code>), keyed by its Stripe id, so a transaction is never processed twice even if the sync runs repeatedly.
# For each new object, the matching accounting treatment is triggered automatically:

* '''Per-transaction fees''' and '''subscription/service fees''' (Radar, Billing, Connect...):
*: The module creates the matching bank movement on the Stripe account (with its accounting counterpart already set), but '''does not post the ledger entry itself'''.
*: Dolibarr's own native "Transfer to accounting" button generates it afterwards, exactly like any other bank movement.
*: Exception: under French VAT mode, the full entry (fee + VAT) is still posted directly by the module, with no dedicated bank movement.

* '''Payouts''':
*: The module creates a real internal bank transfer between the Stripe account and the main bank account.
*: Dolibarr's native transfer-to-accounting step posts the entry on both sides.

* '''Refunds''':
*: Reverse the original charge's entry when the related invoice/payment can be traced back.
*: Otherwise the transaction is flagged for manual review instead of guessing an account.

* '''Disputes / chargebacks''':
*: The disputed amount is posted immediately to a dedicated loss account, plus the dispute's own Stripe fee.

* '''Stripe balance corrections''' (<code>adjustment</code>, an automatic refund after a payment ultimately failed):
*: Recorded so they stay visible, but never posted automatically — their sign and cause vary too much to be posted reliably without human review.

* '''Optional VAT handling on fees''':
*: No VAT, French VAT, or intracommunity reverse charge.
*: The reverse charge mode posts a symmetric, zero-net VAT pair immediately.

# A dashboard shows:
#* Stripe balance
#* unreconciled transactions
#* monthly fees
#* pending payouts
#* manual "Sync now" action

#: A cron job runs the same reconciliation on a schedule.

# For a Stripe account '''not connected through the API''' (for example another storefront with its own merchant account), a CSV import page processes Stripe's "Balance history" export (one file covering every movement type) under the same idempotency guarantees.
#: The import button stays disabled until the minimal configuration is complete, exactly like the sync button.

== Setup ==

'''Home > Setup > Modules > StripeAccounting'''

* '''Stripe financial account''' and '''Main bank account'''
*: Editable selectors that write directly to the official Stripe module's own constants (no local copy, so no risk of drift).

* '''Fees account'''
*: Accounting account for Stripe commissions (example: 627xxx).

* '''Disputes account'''
*: Accounting account for chargeback losses (example: 658xxx).

* '''Stripe supplier thirdparty'''
*: Used to post subscription/service fees (Radar, Billing...) against this thirdparty's own supplier accounting code.

* '''VAT mode'''
*: None, French VAT, or intracommunity reverse charge, with a configurable rate.

* '''Sync frequency'''
*: How often the scheduled job runs.

The module refuses to run any synchronization while the minimal configuration above is incomplete — it aborts up-front rather than posting partial or guessed entries.

<div style="border:1px solid #e00; background:#fee; padding:10px;">
'''⚠️ Warning'''

Do not enable '''"Enable the auto recording of Stripe payouts"''' on the official Stripe module's setup page (Setup > Modules > Stripe).

It makes the official module's own webhook create a bank movement for every Stripe payout — exactly what this module already does, but without any idempotency of its own.

Having both mechanisms enabled at once would each create their own bank movement for the same payout, resulting in a duplicate.
</div>

== Scheduled task (cron) ==

Activating the module registers a scheduled job (<code>StripeAccountingSync</code>) in:

'''Home > Setup > Modules > Scheduled jobs'''

However, two things are required for it to actually run unattended:

=== 1. Enable the job ===

Dolibarr creates it disabled by default.

Open it from the scheduled jobs list and tick '''Active'''.

=== 2. Trigger Dolibarr's scheduler periodically ===

Nothing calls it automatically.

You need an external cron hitting one of the following:

'''Module standalone CLI script:'''

<syntaxhighlight lang="bash">
*/15 * * * * php /path/to/htdocs/custom/stripeaccounting/cron/stripe_sync.php >> /var/log/stripeaccounting.log 2>&1
</syntaxhighlight>

'''Dolibarr generic URL-based job runner:'''

<syntaxhighlight lang="bash">
*/15 * * * * curl "https://your-dolibarr-url/public/cron/cron_run_jobs_by_url.php?securitykey=YOUR_KEY&userlogin=YOUR_LOGIN"
</syntaxhighlight>

Without one of these two crontab entries, synchronization only happens when someone clicks '''"Sync now"''' on the dashboard.

== Requirements ==

* Dolibarr 17+
* PHP 7.2 to 8.5 (no syntax specific to a recent PHP version is used, to stay compatible across that whole range)
* Official Stripe module enabled and configured:
** API keys
** financial account
* Double-entry Accounting module, for the <code>llx_accounting_bookkeeping</code> table

== Credits ==

StripeAccounting is developed and maintained by '''SILADEL'''.

=== License ===

GPL v3 or any later version.

=== SILADEL ===

'''SILADEL'''
7 ch des coquelicots
81990 Cambon France

E-mail: [mailto:info@siladel.fr info@siladel.fr]

Website: [https://www.siladel.fr www.siladel.fr]

== Documentation ==

* [[Documentation Wiki|WIKI Documentation]]

=== Support request ===

[mailto:info@siladel.fr Support request]

----

<center>
[[File:SILADELogo.svg|84px|SILADEL]]

<br />

Developed by [https://www.siladel.fr SILADEL] — Author: IGREJA David
</center>

Stripeaccounting

2026-08-02T12:41:12Z

Goldron :

{{DISPLAYTITLE:StripeAccounting — Documentation technique}}

[[Fichier:Us.png|32px|link=Stripeaccounting/en|English documentation]]

<div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;">
'''StripeAccounting''' est un module Dolibarr de '''rapprochement comptable Stripe'''.

Il lit l'API Stripe (ou un export CSV), repère les mouvements que le module Stripe officiel ne comptabilise pas — frais, remboursements, litiges, virements — et pose les écritures manquantes.

: '''Compatibilité''' — Dolibarr 17+, PHP 7.2 → 8.5
: '''Dépend de''' — modules Stripe, Banque, Comptabilité en partie double
: '''Voir aussi''' — [[README-fr|Installation et guide utilisateur]]
</div>

__TOC__

== 1. Principes de fonctionnement ==

Quatre règles gouvernent tout le module.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Principe !! Ce que ça veut dire
|-
| '''Complémentaire''' || Le module ne crée aucun paiement, aucune facture, aucun webhook. Il lit Stripe et complète la comptabilité, rien de plus.
|-
| '''Idempotent''' || Chaque objet Stripe n'est traité qu'une fois, quel que soit le nombre de relances de la synchronisation.
|-
| '''Jamais de devinette''' || Si une opération ne peut pas être rattachée avec certitude, rien n'est posté : la ligne passe en <code>error</code> pour revue manuelle.
|-
| '''Configuration bloquante''' || Tant que la configuration minimale est incomplète, aucune synchronisation ne démarre (ni bouton, ni cron, ni import).
|}

== 2. Prérequis ==

=== Modules Dolibarr requis ===

{| class="wikitable"
! Module !! Ce qu'il apporte
|-
| '''Stripe''' (<code>modStripe</code>) || Clé API, mode test/live, compte financier Stripe
|-
| '''Banque''' (<code>modBanque</code>) || Tables <code>llx_bank</code> et <code>llx_bank_account</code>
|-
| '''Comptabilité en partie double''' (<code>modAccounting</code>) || Table <code>llx_accounting_bookkeeping</code>
|}

=== Réglage Dolibarr indispensable ===

<code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code> doit être renseigné dans '''Comptabilité → Configuration → Comptes par défaut'''. Sans lui, le virement interne généré par les payouts ne peut pas être transféré en comptabilité (limite de Dolibarr, pas du module).

l’option s'appelle : '''Compte comptable par défaut pour les virements internes'''

=== Notes ===

* Le SDK PHP Stripe n'est pas dupliqué : le module réutilise la copie du cœur (<code>includes/stripe/stripe-php/</code>).
* Le code évite volontairement toute syntaxe PHP postérieure à 7.2 (pas de <code>match</code>, <code>?-></code>, enums, propriétés typées, <code>str_contains</code>…) pour couvrir toute la plage 7.2 → 8.5.

== 3. Arborescence ==

<pre>
custom/stripeaccounting/
├── core/modules/modStripeAccounting.class.php Descripteur (droits, menus, cron, constantes)
├── class/
│ ├── StripeApi.class.php Wrapper SDK Stripe (lecture seule)
│ ├── StripeRepository.class.php Accès SQL + idempotence
│ ├── StripeLogger.class.php Journalisation
│ ├── StripeAccounting.class.php Génération des écritures
│ ├── StripePayout.class.php Rapprochement des virements
│ ├── StripeSync.class.php Orchestrateur (point d'entrée du cron)
│ ├── StripeCsvImporter.class.php Import CSV
│ └── actions_stripeaccounting.class.php Hook 'bankcard'
├── admin/setup.php Configuration
├── import.php Import CSV
├── dashboard.php Tableau de bord
├── transaction_list.php Liste des transactions
├── cron/stripe_sync.php Point d'entrée CLI
├── lib/stripeaccounting.lib.php
├── sql/
├── langs/{fr_FR,en_US,es_ES,it_IT,de_DE}/
└── css/
</pre>

=== Sens des dépendances ===

: pages et hook → <code>StripeSync</code> → (<code>StripeApi</code>, <code>StripeRepository</code>, <code>StripeAccounting</code>, <code>StripePayout</code>) → <code>StripeLogger</code>

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Classe !! Rôle
|-
| <code>StripeApi</code> || Interroge le SDK Stripe (balance transactions, charges, remboursements, litiges, payouts) avec pagination automatique. Aucun accès base, aucune écriture.
|-
| <code>StripeRepository</code> || Tout le SQL des deux tables du module. <code>upsertTransaction()</code> est le point d'idempotence.
|-
| <code>StripeLogger</code> || Écrit dans <code>llx_stripeaccounting_log</code> et en miroir dans <code>dol_syslog()</code>.
|-
| <code>StripeAccounting</code> || Construit les écritures (remboursement, litige, TVA autoliquidation) ou les mouvements bancaires (frais). Expose <code>checkConfig()</code>.
|-
| <code>StripePayout</code> || Crée le virement bancaire interne entre le compte Stripe et la banque réelle.
|-
| <code>StripeSync</code> || Orchestrateur : une méthode par flux, plus <code>reconcileStripeAccount()</code> qui enchaîne tout.
|-
| <code>StripeCsvImporter</code> || Alimente le même pipeline depuis un export CSV Stripe.
|-
| <code>ActionsStripeAccounting</code> || Hook <code>bankcard</code> : lien vers le tableau de bord sur la fiche du compte Stripe.
|}

== 4. Synchronisation et idempotence ==

Chaque flux (<code>syncFees</code>, <code>syncRefunds</code>, <code>syncDisputes</code>, <code>syncPayouts</code>, <code>syncTransactions</code>) suit toujours les mêmes étapes :

# '''Vérifier la configuration''' — si elle est incomplète : log <code>ERROR</code>, arrêt immédiat, aucun appel API.
# '''Lister les objets Stripe''' sur une fenêtre glissante de '''35 jours'''.
# '''Filtrer''' — un objet est ignoré seulement s'il existe déjà ''et'' que son statut est <code>reconciled</code> ou <code>ignored</code>. Une ligne en <code>pending</code> ou <code>error</code> est '''retentée''' à ce run.
# '''Enregistrer''' en statut <code>pending</code>, puis générer l'écriture ou le mouvement bancaire.
# '''Conclure''' — succès : statut <code>reconciled</code>. Échec : statut <code>error</code> avec le message, et '''le lot continue''' sur l'objet suivant.

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Reprise automatique''' — une ligne en <code>error</code> redevient éligible au run suivant. Une fois la cause corrigée (par exemple un exercice comptable créé tardivement), aucune intervention manuelle n'est nécessaire.
</div>

=== Pourquoi les doublons sont impossibles ===

* '''Clé unique en base''' sur <code>(stripe_object_id, entity)</code> — protège même contre deux exécutions concurrentes du cron.
* '''Test explicite avant traitement''' — évite jusqu'à la tentative d'écriture pour un objet déjà finalisé.

=== Cas particuliers : <code>adjustment</code> et <code>payment_failure_refund</code> ===

Ce sont des corrections de solde effectuées par Stripe lui-même (réversion après litige, remboursement d'un paiement finalement échoué). Le module les '''enregistre''' — sinon elles resteraient invisibles — mais ne les comptabilise '''jamais''' automatiquement : le signe du montant et la cause varient trop. Elles sont créées directement en <code>error</code>, avec un message explicite, à traiter manuellement.

== 5. Écritures comptables ==

Toutes les lignes d'un même évènement partagent le triplet <code>doc_type='stripeaccounting'</code>, <code>fk_doc</code>, <code>doc_ref</code> : Dolibarr les regroupe automatiquement sous un même numéro de pièce, sans numérotation propre au module.

=== Vue d'ensemble ===

{| class="wikitable" style="width:100%;"
! Évènement !! Ce que fait le module !! Résultat comptable
|-
| Frais Stripe ''(TVA <code>none</code> ou <code>autoliquidation</code>)'' || Mouvement bancaire <code>PaymentVarious</code> || Écriture 627xxx / 517xxx générée plus tard par Dolibarr
|-
| Frais Stripe ''(mode <code>autoliquidation</code>)'' || En plus : paire TVA postée immédiatement || Débit TVA déductible, crédit TVA autoliquidation ''(impact net nul)''
|-
| Frais Stripe ''(mode <code>french</code>)'' || Écriture directe complète || Débit compte de frais HT + TVA déductible, crédit compte Stripe TTC
|-
| Frais d'abonnement / service ''(Radar, Billing, Connect…)'' || Mouvement bancaire <code>PaymentVarious</code> || Écriture générée plus tard par Dolibarr, sur le compte fournisseur Stripe
|-
| Virement (payout) || Virement bancaire interne entre les 2 comptes || Écriture générée plus tard par Dolibarr
|-
| Remboursement ''(facture retrouvée)'' || Écriture directe || Débit compte client 411xxx, crédit compte Stripe 517xxx
|-
| Remboursement ''(facture introuvable)'' || Rien || Statut <code>error</code>, à traiter manuellement
|-
| Litige / chargeback || Écriture directe || Débit perte sur litiges 658xxx, crédit compte Stripe 517xxx ''(+ compte de frais si frais associés)''
|}

=== Pourquoi frais et virements ne génèrent pas d'écriture directe ===

Le problème historique : quand une facture Stripe est transférée en comptabilité par le workflow standard de Dolibarr, le paiement est comptabilisé pour son montant '''brut''' — les frais sont ignorés à cette étape.

Si le module postait ''en plus'' sa propre écriture ''et'' sa propre ligne bancaire, cette ligne resterait invisible pour <code>bankjournal.php</code> — qui ne reconnaît que les lignes rattachées à <code>doc_type='bank'</code>. Un administrateur transférant « normalement » le compte bancaire en comptabilité créait alors une '''seconde''' écriture pour le même mouvement.

'''La solution retenue :''' pour les frais, les frais d'abonnement et les virements, le module ne crée plus que le '''mouvement bancaire réel''', avec les mécanismes natifs de Dolibarr. C'est ensuite le bouton natif ''« Transférer en comptabilité »'' qui produit l'écriture, comme pour n'importe quel autre mouvement bancaire. Le module ne touche donc plus du tout <code>llx_accounting_bookkeeping</code> dans ces trois cas.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Cas !! Mécanisme natif utilisé
|-
| Frais et frais d'abonnement || <code>PaymentVarious</code> (mouvement bancaire avec compte de contrepartie, sans tiers ni facture), avec son propre <code>accountancy_code</code> que <code>bankjournal.php</code> lit directement.
|-
| Virements (payouts) || Virement interne Dolibarr : <code>Account::addline()</code> des deux côtés, plus <code>add_url_line(…, 'banktransfert')</code>. La contrepartie est imputée sur <code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code>.
|}

Dans les deux cas, le statut passe à <code>reconciled</code> — le module a fini son travail — mais '''<code>piece_num</code> reste vide''' : l'écriture n'existe pas encore, seul <code>fk_bank</code> est renseigné. Après transfert manuel, on la retrouve avec <code>doc_type='bank'</code> et <code>fk_doc</code> égal au <code>fk_bank</code> de la ligne.

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''À savoir''' — l'écriture des virements ne s'équilibre à zéro sur le compte de transfert que lorsque '''les deux''' comptes bancaires (Stripe ''et'' la banque réelle) ont été transférés en comptabilité, pas seulement un des deux.
</div>

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ <code>STRIPE_AUTO_RECORD_PAYOUT</code> doit rester désactivé'''

Dès lors que ce module gère les virements, décochez « Activer l'enregistrement automatique des paiements Stripe » dans <code>stripe/admin/stripe.php</code> — malgré son libellé, cette case ne concerne que les virements.

Sinon, le webhook du module officiel et ce module créeraient chacun leur propre mouvement bancaire pour le même virement, sans le savoir l'un de l'autre.

Le webhook cœur ne conserve d'ailleurs '''aucune''' trace de l'id du virement traité : en cas de double livraison Stripe (garantie « au moins une fois »), rien ne l'empêche de doublonner tout seul. Ce module, lui, a une vraie idempotence et rattrape automatiquement tout virement manqué sur 35 jours.
</div>

=== Page « Transferts Stripe » masquée ===

À l'activation, <code>modStripeAccounting::init()</code> désactive l'entrée de menu <code>stripe/payout.php</code> : cette page interroge l'API en direct sans rien enregistrer, et sa coexistence avec ce module ne créerait qu'une confusion sur ce qui fait foi pour les virements. <code>remove()</code> restaure la condition d'origine. '''C'est la seule table du cœur que ce module modifie''' — délibéré, et documenté ici pour cette raison.

=== Frais par transaction ou frais d'abonnement ? ===

Stripe facture deux choses distinctes sous le mot « frais » :

{| class="wikitable" style="width:100%;"
! !! Frais par transaction !! Frais d'abonnement / service
|-
! Exemple
| Commission sur chaque encaissement || Radar, Billing, Connect
|-
! Où le trouver
| Champ <code>.fee</code> d'une balance transaction de type <code>charge</code> || Balance transaction dédiée, de type <code>stripe_fee</code> ou <code>application_fee</code> ''(le <code>.fee</code> y vaut toujours 0, le montant est dans <code>.amount</code>)''
|-
! Compte utilisé
| Compte de frais configuré (627xxx) || Code comptable fournisseur du tiers Stripe configuré
|-
! Type en base
| <code>fee</code> || <code>subscription_fee</code>
|}

=== Limite du mode TVA <code>french</code> ===

Ce mode doit scinder le montant TTC en HT + TVA, un découpage que <code>PaymentVarious</code> ne sait pas exprimer. Il reste donc sur l'ancien comportement : écriture directe complète, aucun mouvement bancaire créé. Pas de risque de doublon (puisque aucune ligne bancaire n'est produite), mais le solde <code>llx_bank</code> du compte Stripe ne reflétera jamais les frais tant que ce mode est actif.

== 6. Import CSV ==

L'import couvre le cas d'un compte Stripe '''différent''' de celui configuré dans le module officiel — par exemple une autre boutique PrestaShop avec son propre compte marchand. L'API n'y a pas accès : le contenu est exporté en CSV depuis le dashboard Stripe, puis importé.

=== Hypothèse de départ ===

Les factures et paiements de cette boutique sont '''déjà''' comptabilisés dans Dolibarr par un autre processus, et l'encaissement (débit 517, crédit 411) est déjà posé. Seuls manquent les '''frais''', les '''remboursements''' et les '''virements''' — c'est exactement ce que l'import traite.

=== Interface : un seul champ ===

<code>import.php</code> n'expose plus qu'un champ d'upload, '''Historique général''', câblé sur <code>importGeneralHistory()</code>. Ce fichier couvre à lui seul tous les types de mouvements.

Les méthodes <code>importPayments()</code> et <code>importPayouts()</code> restent implémentées et fonctionnelles, mais ne sont plus atteignables depuis l'interface ; elles sont documentées ci-dessous pour mémoire.

Comme le bouton « Synchroniser maintenant », l'import est bloqué — bandeau d'alerte, bouton désactivé, garde-fou côté serveur — tant que la configuration est incomplète.

=== Les trois méthodes ===

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Méthode !! Export Stripe lu !! Traitement
|-
| <code>importGeneralHistory()</code><br />''(seule exposée)'' || Balance history || Aiguillage par colonne <code>Type</code>, voir tableau ci-dessous
|-
| <code>importPayments()</code> || Payments || Frais → écriture de frais. Montant remboursé → ligne <code>refund</code> toujours en <code>error</code>.
|-
| <code>importPayouts()</code> || Payouts || Exactement le même traitement qu'un payout venu de l'API
|}

Aiguillage de l'historique général, par colonne <code>Type</code> :

{| class="wikitable" style="width:100%;"
! style="width:30%;" | Type Stripe !! Traitement
|-
| <code>payout</code> || Virement bancaire interne, comme via l'API
|-
| <code>charge</code> / <code>payment</code> avec frais || Mouvement de frais
|-
| <code>stripe_fee</code> / <code>application_fee</code> || Frais d'abonnement, sur le compte fournisseur Stripe
|-
| <code>refund</code> || Enregistré, '''toujours''' en <code>error</code>
|-
| <code>payout_minimum_balance_hold</code> / <code>…_release</code> || '''Ignorés''' — réserve glissante Stripe, impact net nul, rien à comptabiliser
|-
| tout autre type || Enregistré en <code>type='other'</code>, statut <code>error</code>, type brut conservé dans la description. Aucune écriture devinée.
|}

Les colonnes sont reconnues '''par leur nom''' : l'ordre importe peu, et les colonnes en plus non utilisées sont ignorées.

=== Idempotence de l'import ===

La clé unique protège contre tout double import : réimporter le même CSV, ou un CSV qui chevauche un import précédent, ne crée aucun doublon.

Point important : dans l'historique général, les lignes <code>payout</code> et <code>charge</code>/<code>payment</code> sont indexées par leur colonne '''<code>Source</code>''' (<code>po_…</code>, <code>ch_…</code>), pas par l'<code>id</code> de la ligne (<code>txn_…</code>) — soit exactement la même clé que les imports dédiés. Importer l'historique général '''en plus''' des exports spécifiques ne poste donc jamais deux fois la même écriture, quel que soit l'ordre.

Les identifiants Stripe étant uniques à l'échelle de la plateforme, mélanger dans la même table des lignes venant du compte API et de plusieurs comptes importés en CSV ne présente aucun risque de collision.

=== Détails pratiques ===

* '''Libellé source''' — un champ libre saisi à l'import (ex. « Boutique DRM ») est stocké sur chaque ligne créée et sert de colonne et de filtre dans la liste, pour distinguer plusieurs boutiques côte à côte.
* '''Format des montants''' — les CSV Stripe utilisent la virgule décimale française, convertie via <code>price2num()</code>. Les dates marquées <code>(UTC)</code> sont interprétées comme telles.

== 7. Configuration ==

La clé API et le mode test/live ne sont '''pas''' ressaisis ici : ils sont lus en lecture seule depuis le module Stripe officiel.

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Champ !! Constante !! Usage
|-
| Compte financier Stripe || <code>STRIPE_BANK_ACCOUNT_FOR_PAYMENTS</code> ''(constante du module officiel)'' || Sélecteur de compte bancaire. Aucune copie locale, donc aucun risque de divergence.
|-
| Compte bancaire principal || <code>STRIPE_BANK_ACCOUNT_FOR_BANKTRANSFERS</code> ''(constante du module officiel)'' || Même sélecteur. Voir l'encadré ci-dessous.
|-
| Compte de frais || <code>STRIPEACCOUNTING_COMPTE_FRAIS</code> || Numéro de compte, ex. 627xxx
|-
| Compte de litiges || <code>STRIPEACCOUNTING_COMPTE_LITIGES</code> || Numéro de compte, ex. 658xxx. '''Requis''' — utilisé dès qu'un litige survient, quel que soit le mode TVA.
|-
| Tiers fournisseur Stripe || <code>STRIPEACCOUNTING_FOURNISSEUR_STRIPE_ID</code> || Tiers marqué fournisseur ; c'est son code comptable fournisseur qui est utilisé. Optionnel, sauf s'il existe des frais d'abonnement.
|-
| Mode TVA || <code>STRIPEACCOUNTING_VAT_MODE</code> || <code>none</code>, <code>french</code> ou <code>autoliquidation</code>
|-
| Compte TVA déductible (intracommunautaire) || <code>STRIPEACCOUNTING_COMPTE_TVA_DEDUCTIBLE</code> || Requis si mode TVA ≠ <code>none</code>. Stripe facturant toujours depuis une entité UE non française, la TVA déductible est intracommunautaire dans tous les cas.
|-
| Compte de TVA due (intracommunautaire) || <code>STRIPEACCOUNTING_COMPTE_TVA_AUTOLIQUIDATION</code> || Requis en mode <code>autoliquidation</code> uniquement — jamais utilisé en mode <code>french</code>.
|-
| Taux de TVA || <code>STRIPEACCOUNTING_VAT_RATE</code> || Pourcentage, 20 par défaut
|-
| Fréquence de synchronisation || <code>STRIPEACCOUNTING_SYNC_UNITFREQUENCY</code> || Répercutée sur la tâche planifiée (en secondes)
|}

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Pourquoi redéfinir le compte bancaire principal ici ?'''

La page de configuration du module Stripe officiel n'affiche ce champ que si <code>STRIPE_AUTO_RECORD_PAYOUT</code> est activé — et son handler de sauvegarde remet la valeur à 0 à chaque enregistrement tant que le champ n'est pas rendu. Or ce réglage doit justement rester désactivé quand ce module gère les virements. Le champ est donc réexposé ici, en écrivant directement la constante du cœur, pour que la valeur reste configurable et stable.

Les deux sélecteurs de compte n'écrivent leur constante que si un compte réel a été soumis : enregistrer la page pour un tout autre champ n'écrase jamais une valeur correcte.
</div>

=== Vérification de la configuration ===

<code>StripeAccounting::checkConfig()</code> renvoie la liste des constantes manquantes. Elle est appelée à la fois par la page de configuration (bandeau d'information) et par chaque point d'entrée de synchronisation (garde-fou réel qui bloque tout traitement).

=== Piège des sélecteurs de compte comptable ===

Les quatre champs utilisant <code>FormAccounting::select_account()</code> (frais, litiges, les deux comptes TVA) ont une option « rien sélectionné » dont la valeur est '''<code>-1</code>''' — une chaîne non vide, donc vraie en PHP. Un champ laissé vide et enregistré stocke littéralement <code>-1</code>.

<code>StripeAccounting::getAccountConst()</code> normalise cette valeur en chaîne vide à la lecture, partout où ces constantes sont lues. Aucune écriture ne peut donc atterrir sur le compte inexistant <code>-1</code>.

== 8. Interface ==

=== Tableau de bord ===

Solde Stripe (appel API en direct), nombre de transactions non rapprochées, total des frais du mois, payouts en attente, et bouton '''Synchroniser maintenant''' — désactivé, avec bandeau listant les constantes manquantes, tant que la configuration est incomplète.

=== Liste des transactions ===

Liste paginée, triable et filtrable, construite avec le même mécanisme que les listes natives Dolibarr : l'icône en haut à droite du tableau permet à chaque utilisateur de choisir ses colonnes, et la préférence est mémorisée par utilisateur.

{| class="wikitable" style="width:100%;"
! style="width:20%;" | Colonne !! Contenu
|-
| Montant, Frais, Total || Le popup sur les frais indique la TVA sur frais quand une paire d'autoliquidation ou une TVA française a été postée
|-
| Type, Description || Popup avec l'ID Stripe, l'ID d'évènement ou de source, et la description complète non tronquée
|-
| Tiers || Le client résolu via la facture, ou via la charge source pour son frais associé, ou le tiers fournisseur Stripe pour un frais d'abonnement
|-
| Écriture || Lien « Pièce n°X » vers l'écriture, et/ou lien vers le mouvement bancaire associé — voir la nuance ci-dessous
|-
| Source, Statut || Le badge <code>error</code> ouvre un popup avec le message d'erreur complet : plus besoin d'aller en base pour comprendre un échec
|}

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''Lire la colonne « Écriture »''' — sur une ligne <code>fee</code>, <code>subscription_fee</code> ou <code>payout</code>, le lien pointe vers le '''mouvement bancaire''', pas vers une pièce comptable. Le <code>piece_num</code> du module, lui, n'est jamais l'écriture 627/517 du frais : c'est uniquement la paire TVA d'autoliquidation. L'écriture du frais est générée plus tard, par le bouton natif de Dolibarr, et n'est jamais reportée sur cette ligne.
</div>

La page est '''purement consultative''' : aucune comptabilisation manuelle n'y est proposée. Le module comptabilise automatiquement, et le transfert en comptabilité des frais et virements se fait depuis le bouton natif « Transférer en comptabilité ».

=== Lignes <code>charge</code> et <code>fee</code> ===

Chaque paiement produit '''deux lignes''' en base :

* une ligne <code>charge</code>, toujours en statut <code>ignored</code>, frais à 0, jamais traitée — présente uniquement pour l'idempotence ;
* une ligne <code>fee</code> pour le même paiement, liée à la première.

Les deux apparaissent séparément dans la liste, mais la ligne <code>fee</code> porte elle aussi le lien vers le paiement et la facture, résolu par jointure.

=== Bandeau mode test ===

Tant que le mode live n'est pas activé, le tableau de bord, la page de configuration et la liste des transactions affichent tous les trois le même avertissement que le module Stripe officiel. Impossible d'oublier qu'on travaille en mode test.

=== Menus ===

Tout est regroupé sous '''Banques et caisses → Compte Stripe''' (menu du module officiel), à plat, en trois entrées de même niveau :

# Tableau de bord Stripe
# Transactions Stripe
# Import CSV ''(réservé aux administrateurs)''

Un lien vers le tableau de bord est aussi ajouté automatiquement sur la fiche du compte bancaire configuré comme compte Stripe.

== 9. Tâche planifiée ==

Deux façons d'exécuter la synchronisation, toutes deux idempotentes et sans risque à relancer. Dans les deux cas le code exécuté est strictement le même : aucune divergence de comportement.

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ Aucune des deux ne démarre toute seule.'''

L'activation du module crée la tâche <code>StripeAccountingSync</code>, mais '''désactivée par défaut'''. Et même activée, l'ordonnanceur Dolibarr n'est déclenché par rien tant qu'aucune crontab système ne l'appelle. Sans ces deux étapes, la synchro n'a lieu qu'au clic manuel sur « Synchroniser maintenant ».
</div>

=== Étape 1 — activer la tâche ===

Dans '''Accueil → Configuration → Modules → Tâches planifiées'''. <code>llx_cronjob</code> étant une table du cœur, ce réglage se fait uniquement par l'interface, jamais en SQL direct depuis le module.

=== Étape 2 — un déclencheur système ===

Au choix, l'une des deux options.

'''Option A — ordonnanceur Dolibarr''' ''(recommandé si plusieurs tâches planifiées coexistent)''. Lance toutes les tâches dues, pas seulement celle-ci. Nécessite l'étape 1.

<syntaxhighlight lang="bash">
*/15 * * * * curl "https://votre-dolibarr/public/cron/cron_run_jobs_by_url.php?securitykey=VOTRE_CLE&userlogin=VOTRE_LOGIN"
</syntaxhighlight>

La clé de sécurité se génère sur la page des tâches planifiées, bouton « Sécurité de l'exécution des tâches par URL ».

'''Option B — script CLI du module.''' Autonome, refuse l'exécution depuis un navigateur, et indépendant de l'état activé ou non de la tâche Dolibarr.

<syntaxhighlight lang="bash">
*/15 * * * * php /chemin/vers/htdocs/custom/stripeaccounting/cron/stripe_sync.php >> /var/log/stripeaccounting.log 2>&1
</syntaxhighlight>

== 10. Journalisation et permissions ==

=== Journalisation ===

Chaque appel API, écriture générée, avertissement ou erreur est tracé dans <code>llx_stripeaccounting_log</code>, consultable en base ou via le fichier de log standard Dolibarr. Niveaux : <code>DEBUG</code> < <code>INFO</code> < <code>WARNING</code> < <code>ERROR</code>. La colonne <code>context</code> contient le détail structuré en JSON (payload API, montants calculés…).

=== Permissions ===

{| class="wikitable"
! Droit !! Contrôle
|-
| <code>read</code> || Consultation du tableau de bord et de la liste
|-
| <code>write</code> || Déclarée pour la configuration, mais non vérifiée dans le code aujourd'hui
|-
| <code>reconcile</code> || Déclenchement manuel de la synchronisation
|}

En pratique, <code>admin/setup.php</code> et <code>import.php</code> ne contrôlent que le statut '''administrateur Dolibarr''', pas le droit <code>write</code> : seuls les administrateurs peuvent configurer le module ou importer un CSV, quoi qu'il soit coché dans les permissions.

== 11. Base de données ==

=== <code>llx_stripeaccounting_transaction</code> ===

Une ligne par objet Stripe traité — charge, frais, remboursement, litige ou virement — tous dans la même table, distingués par la colonne <code>type</code>.

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Colonne !! style="width:16%;" | Type !! Rôle
|-
| <code>rowid</code> || int AI || Clé primaire
|-
| <code>entity</code> || int || Multi-société Dolibarr
|-
| <code>stripe_object_id</code> || varchar(80) || Identifiant Stripe — '''ancre d'idempotence'''
|-
| <code>stripe_event_id</code> || varchar(80) || Identifiant d'évènement, informatif seulement
|-
| <code>type</code> || varchar(20) || <code>charge</code>, <code>fee</code>, <code>subscription_fee</code>, <code>refund</code>, <code>dispute</code>, <code>payout</code>, <code>other</code>
|-
| <code>stripe_source_id</code> || varchar(80) || Objet Stripe source (ex. la charge liée à un remboursement)
|-
| <code>source_label</code> || varchar(80) || Libellé libre saisi à l'import CSV ; vide pour les lignes venues de l'API
|-
| <code>description</code> || varchar(255) || Libellé Stripe
|-
| <code>amount</code>, <code>fee</code>, <code>net</code> || decimal(24,8) || Montants déjà convertis depuis les centimes Stripe
|-
| <code>currency</code> || varchar(3) || Code devise ISO
|-
| <code>date_created</code>, <code>date_available_on</code> || datetime || Dates côté Stripe
|-
| <code>fk_facture</code>, <code>fk_paiement</code> || int || Facture et paiement Dolibarr résolus, si trouvés
|-
| <code>fk_bank</code> || int || Ligne <code>llx_bank</code> générée ''(vide pour un frais en mode TVA <code>french</code>)''
|-
| <code>piece_num</code> || varchar(20) || Numéro de pièce comptable généré, quand il y en a un
|-
| <code>status</code> || varchar(16) || <code>pending</code>, <code>reconciled</code>, <code>error</code>, <code>ignored</code>
|-
| <code>error_message</code> || text || Détail en cas d'erreur
|-
| <code>date_creation</code>, <code>date_processed</code> || datetime || Horodatage technique
|-
| <code>fk_user_creat</code> || int || Utilisateur ayant déclenché le traitement
|}

'''Clé unique''' sur <code>(stripe_object_id, entity)</code> — c'est elle qui garantit qu'un même objet Stripe ne peut jamais être inséré deux fois, même en cas d'exécutions concurrentes.

=== <code>llx_stripeaccounting_log</code> ===

{| class="wikitable"
! Colonne !! Rôle
|-
| <code>level</code> || <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>
|-
| <code>message</code> || Message court
|-
| <code>context</code> || Contexte structuré en JSON
|-
| <code>fk_stripeaccounting_transaction</code> || Transaction liée, si applicable
|-
| <code>datec</code> || Horodatage
|}

== 12. Dépannage ==

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Symptôme !! Cause probable !! Action
|-
| Le bouton « Synchroniser maintenant » est désactivé || Configuration minimale incomplète || Compléter les champs listés dans le bandeau d'alerte de la page de configuration
|-
| Une transaction reste en <code>error</code> || Écriture refusée par Dolibarr (compte inexistant, période clôturée), ou remboursement non rattaché || Lire <code>error_message</code> sur la ligne, puis le détail dans la table de logs
|-
| Le solde Stripe ne s'affiche pas || Clé API manquante ou invalide dans le module Stripe officiel || Vérifier <code>stripe/admin/stripe.php</code>
|-
| Un remboursement n'est jamais rapproché || Le paiement d'origine n'a pas été retrouvé via <code>ext_payment_id</code> || Vérifier que le paiement Stripe a bien été enregistré par le module officiel avec cet identifiant
|-
| Un <code>subscription_fee</code> reste en <code>error</code> || Tiers fournisseur Stripe non renseigné, ou sans code comptable fournisseur || Renseigner le champ en configuration, et compléter la fiche du tiers
|-
| Un remboursement importé en CSV reste en <code>error</code> || '''Normal et attendu''' — ce compte n'est pas relié à <code>ext_payment_id</code> || Traiter la facture et le remboursement manuellement en comptabilité
|}

== 13. Pièges rencontrés ==

Notes de développement, conservées pour éviter de retomber dedans.

* '''<code>PaymentVarious::create()</code>''' ne met à jour <code>fk_bank</code> qu'en base, jamais sur l'objet PHP. Un <code>fetch()</code> après <code>create()</code> est indispensable pour récupérer la vraie valeur.
* '''<code>select_comptes()</code>''' affiche son propre HTML ''et'' retourne le nombre de comptes. L'appeler en instruction nue : l'envelopper dans <code>print</code> réafficherait ce nombre juste après la balise select.
* '''<code>master.inc.php</code>, pas <code>main.inc.php</code>''' pour le script CLI. Le second attend une session HTTP et, en pur CLI, se termine silencieusement — aucune sortie, aucun log, code retour 0 — dans sa redirection vers la page de connexion. L'impression trompeuse que le script « ne fait rien » plutôt qu'une vraie erreur.
* '''Bibliothèques du cœur''' — <code>master.inc.php</code> ne charge pas tout ce que <code>main.inc.php</code> charge pour le web (par exemple <code>core/lib/date.lib.php</code>, requis par <code>BookKeeping</code>). À inclure explicitement si le script CLI évolue.
* '''Option « rien sélectionné » à <code>-1</code>''' dans les sélecteurs de compte comptable — voir la section Configuration.

== 14. Limites connues ==

* '''Devises « zéro décimale »''' (JPY, KRW…) non gérées : les montants sont divisés par 100 en supposant deux décimales. Usage prévu : EUR.
* '''Fenêtre de 35 jours''' non configurable. Une synchronisation interrompue plus longtemps devra être rattrapée manuellement.
* '''Rattachement des remboursements''' — dépend de <code>ext_payment_id</code> et <code>ext_payment_site</code> sur <code>llx_paiement</code>, renseignés par le flux de paiement Stripe standard. Un paiement enregistré autrement ne pourra pas être rattaché automatiquement. Le rattachement se fait via le '''PaymentIntent id''', jamais via l'id de charge : le module Stripe du cœur ne stocke jamais ce dernier ''(il y met soit le PaymentIntent brut, soit un composite, selon le chemin de paiement emprunté)''.
* '''Import CSV en notation française''' uniquement : un export à point décimal ne serait pas interprété correctement.
* '''Colonne « Transfer » du CSV Paiements''' stockée à titre informatif seulement : elle ne sert pas à vérifier que le total des paiements correspond au montant du virement importé.
* '''Remboursements importés en CSV toujours en <code>error</code>''' — comportement voulu, pas un bug.
* '''Mode TVA <code>french</code>''' — le solde bancaire du compte Stripe ne reflète pas les frais, voir section 5.

[[Catégorie:Dolibarr]]
[[Catégorie:Modules]]
[[Catégorie:Comptabilité]]

Stripeaccounting/en

2026-08-02T12:41:00Z

Goldron :

{{DISPLAYTITLE:StripeAccounting — Technical documentation}}

[[Fichier:Fr.png|32px|link=Stripeaccounting|Doc en Français]]

<div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;">
'''StripeAccounting''' is a Dolibarr module for '''Stripe accounting reconciliation'''.

It reads the Stripe API (or a CSV export), identifies the movements the official Stripe module does not post — fees, refunds, disputes, payouts — and creates the missing accounting entries.

: '''Compatibility''' — Dolibarr 17+, PHP 7.2 → 8.5
: '''Depends on''' — Stripe, Bank and Double-entry Accounting modules
: '''See also''' — [[README|Installation and user guide]]
</div>

__TOC__

== 1. Design principles ==

Four rules govern the whole module.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Principle !! What it means
|-
| '''Complementary''' || The module creates no payment, no invoice, no webhook. It reads Stripe and completes the books, nothing more.
|-
| '''Idempotent''' || Each Stripe object is processed once only, no matter how many times the sync is re-run.
|-
| '''Never guess''' || If an operation cannot be matched with certainty, nothing is posted: the row goes to <code>error</code> for manual review.
|-
| '''Configuration is blocking''' || As long as the minimum configuration is incomplete, no sync runs at all (no button, no cron, no import).
|}

== 2. Requirements ==

=== Required Dolibarr modules ===

{| class="wikitable"
! Module !! What it provides
|-
| '''Stripe''' (<code>modStripe</code>) || API key, test/live mode, Stripe financial account
|-
| '''Bank''' (<code>modBanque</code>) || <code>llx_bank</code> and <code>llx_bank_account</code> tables
|-
| '''Double-entry accounting''' (<code>modAccounting</code>) || <code>llx_accounting_bookkeeping</code> table
|}

=== Mandatory Dolibarr setting ===

<code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code> must be set under '''Accounting → Setup → Miscellaneous accounts'''. Without it, the internal transfer generated by payouts cannot be transferred to accounting (a Dolibarr limitation, not a module one).

=== Notes ===

* The Stripe PHP SDK is not re-vendored: the module reuses the core copy (<code>includes/stripe/stripe-php/</code>).
* The code deliberately avoids any PHP syntax newer than 7.2 (no <code>match</code>, <code>?-></code>, enums, typed properties, <code>str_contains</code>…) so it runs across the whole 7.2 → 8.5 range.

== 3. File tree ==

<pre>
custom/stripeaccounting/
├── core/modules/modStripeAccounting.class.php Module descriptor (permissions, menus, cron, constants)
├── class/
│ ├── StripeApi.class.php Stripe SDK wrapper (read-only)
│ ├── StripeRepository.class.php SQL access + idempotency
│ ├── StripeLogger.class.php Logging
│ ├── StripeAccounting.class.php Accounting entry generation
│ ├── StripePayout.class.php Payout reconciliation
│ ├── StripeSync.class.php Orchestrator (cron entry point)
│ ├── StripeCsvImporter.class.php CSV import
│ └── actions_stripeaccounting.class.php 'bankcard' hook
├── admin/setup.php Configuration
├── import.php CSV import
├── dashboard.php Dashboard
├── transaction_list.php Transaction list
├── cron/stripe_sync.php CLI entry point
├── lib/stripeaccounting.lib.php
├── sql/
├── langs/{fr_FR,en_US,es_ES,it_IT,de_DE}/
└── css/
</pre>

=== Dependency direction ===

: pages and hook → <code>StripeSync</code> → (<code>StripeApi</code>, <code>StripeRepository</code>, <code>StripeAccounting</code>, <code>StripePayout</code>) → <code>StripeLogger</code>

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Class !! Role
|-
| <code>StripeApi</code> || Queries the Stripe SDK (balance transactions, charges, refunds, disputes, payouts) with automatic pagination. No database access, no accounting entries.
|-
| <code>StripeRepository</code> || All SQL for the module's two tables. <code>upsertTransaction()</code> is the idempotency anchor.
|-
| <code>StripeLogger</code> || Writes to <code>llx_stripeaccounting_log</code> and mirrors to <code>dol_syslog()</code>.
|-
| <code>StripeAccounting</code> || Builds accounting entries (refund, dispute, reverse-charge VAT) or bank movements (fees). Exposes <code>checkConfig()</code>.
|-
| <code>StripePayout</code> || Creates the internal bank transfer between the Stripe account and the real bank account.
|-
| <code>StripeSync</code> || Orchestrator: one method per flow, plus <code>reconcileStripeAccount()</code> which chains them all.
|-
| <code>StripeCsvImporter</code> || Feeds the same pipeline from a Stripe CSV export.
|-
| <code>ActionsStripeAccounting</code> || <code>bankcard</code> hook: dashboard link on the Stripe account record.
|}

== 4. Synchronisation and idempotency ==

Every flow (<code>syncFees</code>, <code>syncRefunds</code>, <code>syncDisputes</code>, <code>syncPayouts</code>, <code>syncTransactions</code>) always follows the same steps:

# '''Check the configuration''' — if incomplete: <code>ERROR</code> log, immediate stop, no API call at all.
# '''List Stripe objects''' over a rolling window of '''35 days'''.
# '''Filter''' — an object is skipped only if it already exists ''and'' its status is <code>reconciled</code> or <code>ignored</code>. A row in <code>pending</code> or <code>error</code> is '''retried''' on this run.
# '''Record''' it as <code>pending</code>, then generate the accounting entry or bank movement.
# '''Conclude''' — success: status <code>reconciled</code>. Failure: status <code>error</code> with the message, and '''the batch carries on''' with the next object.

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Automatic retry''' — a row in <code>error</code> becomes eligible again on the next run. Once the cause is fixed (a fiscal year created late, for instance), no manual action is needed.
</div>

=== Why duplicates are impossible ===

* '''Unique database key''' on <code>(stripe_object_id, entity)</code> — protects even against two concurrent cron executions.
* '''Explicit check before processing''' — avoids even attempting to post an entry for an already-finalised object.

=== Special cases: <code>adjustment</code> and <code>payment_failure_refund</code> ===

These are balance corrections Stripe makes on its own (reversal after a dispute is resolved, automatic refund of a payment that ultimately failed). The module '''records''' them — otherwise they would stay invisible — but '''never''' posts them automatically: the sign of the amount and the underlying cause vary too much. They are created directly in <code>error</code>, with an explicit message, to be handled manually.

== 5. Accounting entries ==

All lines of a single Stripe event share the same <code>doc_type='stripeaccounting'</code>, <code>fk_doc</code> and <code>doc_ref</code> triplet: Dolibarr automatically groups them under one piece number, so the module needs no numbering scheme of its own.

=== Overview ===

{| class="wikitable" style="width:100%;"
! Event !! What the module does !! Resulting entry
|-
| Stripe fee ''(VAT mode <code>none</code> or <code>autoliquidation</code>)'' || <code>PaymentVarious</code> bank movement || 627xxx / 517xxx entry generated later by Dolibarr
|-
| Stripe fee ''(<code>autoliquidation</code> mode)'' || Plus: VAT pair posted immediately || Debit deductible VAT, credit reverse-charge VAT ''(net impact nil)''
|-
| Stripe fee ''(<code>french</code> mode)'' || Full direct entry || Debit fee account excl. VAT + deductible VAT, credit Stripe account incl. VAT
|-
| Subscription / service fees ''(Radar, Billing, Connect…)'' || <code>PaymentVarious</code> bank movement || Entry generated later by Dolibarr, on the Stripe supplier account
|-
| Payout || Internal bank transfer between the two accounts || Entry generated later by Dolibarr
|-
| Refund ''(invoice found)'' || Direct entry || Debit customer account 411xxx, credit Stripe account 517xxx
|-
| Refund ''(invoice not found)'' || Nothing || Status <code>error</code>, handle manually
|-
| Dispute / chargeback || Direct entry || Debit dispute loss 658xxx, credit Stripe account 517xxx ''(+ fee account if fees apply)''
|}

=== Why fees and payouts produce no direct entry ===

The historical problem: when a Stripe-paid invoice is transferred to accounting through Dolibarr's standard workflow, the payment is posted at its '''gross''' amount — fees are ignored at that stage.

If the module posted its own entry ''and'' its own bank line on top of that, this line would stay invisible to <code>bankjournal.php</code> — which only recognises lines attached to <code>doc_type='bank'</code>. An administrator transferring the bank account to accounting "normally" would then create a '''second''' entry for the very same movement.

'''The chosen solution:''' for fees, subscription fees and payouts, the module now creates only the '''real bank movement''', using Dolibarr's native mechanisms. The native ''"Transfer to accounting"'' button then produces the entry, exactly as for any other bank movement. In those three cases, the module no longer touches <code>llx_accounting_bookkeeping</code> at all.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Case !! Native mechanism used
|-
| Fees and subscription fees || <code>PaymentVarious</code> (bank movement with an explicit counterpart account, no third party or invoice), carrying its own <code>accountancy_code</code>, which <code>bankjournal.php</code> reads directly.
|-
| Payouts || Dolibarr internal transfer: <code>Account::addline()</code> on both sides, plus <code>add_url_line(…, 'banktransfert')</code>. The counterpart is posted to <code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code>.
|}

In both cases the status becomes <code>reconciled</code> — the module's job is done — but '''<code>piece_num</code> stays empty''': the entry does not exist yet, only <code>fk_bank</code> is set. After the manual transfer, it can be found with <code>doc_type='bank'</code> and <code>fk_doc</code> equal to the row's <code>fk_bank</code>.

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''Worth knowing''' — the payout entry only balances to zero on the transfer account once '''both''' bank accounts (Stripe ''and'' the real bank) have been transferred to accounting, not just one of them.
</div>

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ <code>STRIPE_AUTO_RECORD_PAYOUT</code> must stay disabled'''

Once this module handles payouts, untick "Enable automatic recording of Stripe payments" in <code>stripe/admin/stripe.php</code> — despite its wording, that checkbox only concerns payouts.

Otherwise the official module's webhook and this module would each create their own bank movement for the same payout, unaware of each other.

The core webhook keeps '''no''' trace of the payout id it has processed: should Stripe deliver the event twice (delivery is guaranteed "at least once"), nothing stops it from duplicating on its own either. This module has real idempotency and automatically catches up any missed payout within 35 days.
</div>

=== The "Stripe transfers" page is hidden ===

On activation, <code>modStripeAccounting::init()</code> disables the <code>stripe/payout.php</code> menu entry: that page queries the API live without recording anything, and having it alongside this module would only create confusion about which one is authoritative for payouts. <code>remove()</code> restores the original condition. '''This is the only core table the module modifies''' — deliberate, and documented here for that reason.

=== Per-transaction fees or subscription fees? ===

Stripe bills two distinct things under the generic word "fees":

{| class="wikitable" style="width:100%;"
! !! Per-transaction fees !! Subscription / service fees
|-
! Example
| Commission on each payment || Radar, Billing, Connect
|-
! Where to find it
| The <code>.fee</code> field of a <code>charge</code> balance transaction || A dedicated balance transaction, type <code>stripe_fee</code> or <code>application_fee</code> ''(its <code>.fee</code> is always 0, the amount sits in <code>.amount</code>)''
|-
! Account used
| The configured fee account (627xxx) || The supplier accounting code of the configured Stripe third party
|-
! Type in database
| <code>fee</code> || <code>subscription_fee</code>
|}

=== Limitation of the <code>french</code> VAT mode ===

This mode has to split the gross amount into net + VAT, something <code>PaymentVarious</code> cannot express. It therefore keeps the previous behaviour: a full direct entry, with no bank movement created. No duplicate risk (precisely because no bank line is produced), but the <code>llx_bank</code> balance of the Stripe account will never reflect the fees while this mode is active.

== 6. CSV import ==

The import covers the case of a Stripe account '''different''' from the one configured in the official module — another PrestaShop shop with its own merchant account, for example. The API has no access to it: its contents are exported to CSV from the Stripe dashboard, then imported.

=== Starting assumption ===

The invoices and payments of that shop are '''already''' posted in Dolibarr through some other process, and the collection (debit 517, credit 411) is already booked. Only the '''fees''', '''refunds''' and '''payouts''' are missing — which is exactly what the import handles.

=== Interface: a single field ===

<code>import.php</code> now exposes only one upload field, '''General history''', wired to <code>importGeneralHistory()</code>. That file alone covers every movement type.

<code>importPayments()</code> and <code>importPayouts()</code> are still implemented and functional, but no longer reachable from the interface; they are documented below for reference.

Like the "Sync now" button, the import is blocked — warning banner, disabled button, server-side guard — while the configuration is incomplete.

=== The three methods ===

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Method !! Stripe export read !! Processing
|-
| <code>importGeneralHistory()</code><br />''(the only one exposed)'' || Balance history || Dispatch on the <code>Type</code> column, see table below
|-
| <code>importPayments()</code> || Payments || Fee → fee movement. Amount refunded → <code>refund</code> row, always in <code>error</code>.
|-
| <code>importPayouts()</code> || Payouts || Exactly the same processing as a payout coming from the API
|}

General history dispatch, by <code>Type</code> column:

{| class="wikitable" style="width:100%;"
! style="width:30%;" | Stripe type !! Processing
|-
| <code>payout</code> || Internal bank transfer, as via the API
|-
| <code>charge</code> / <code>payment</code> with a fee || Fee movement
|-
| <code>stripe_fee</code> / <code>application_fee</code> || Subscription fee, on the Stripe supplier account
|-
| <code>refund</code> || Recorded, '''always''' in <code>error</code>
|-
| <code>payout_minimum_balance_hold</code> / <code>…_release</code> || '''Ignored''' — Stripe rolling reserve, no real cash movement, nothing to post
|-
| any other type || Recorded as <code>type='other'</code>, status <code>error</code>, raw Stripe type kept in the description. No guessed entry.
|}

Columns are matched '''by name''': their order does not matter, and extra unused columns are ignored.

=== Import idempotency ===

The unique key protects against any double import: re-importing the same CSV, or one overlapping a previous import, creates no duplicate.

An important detail: in the general history, <code>payout</code> and <code>charge</code>/<code>payment</code> rows are indexed by their '''<code>Source</code>''' column (<code>po_…</code>, <code>ch_…</code>), not by the row's own <code>id</code> (<code>txn_…</code>) — the very same key the dedicated imports use. Importing the general history '''on top of''' the specific exports therefore never posts the same entry twice, in any order.

Since Stripe identifiers are unique platform-wide, mixing rows from the API account and from several CSV-imported accounts in the same table carries no collision risk.

=== Practical details ===

* '''Source label''' — a free-text field entered at import time (e.g. "DRM shop") is stored on every created row and serves as a column and filter in the list, to tell several shops apart side by side.
* '''Amount format''' — Stripe CSVs use the French decimal comma, converted through <code>price2num()</code>. Dates marked <code>(UTC)</code> are interpreted as such.

== 7. Configuration ==

The API key and test/live mode are '''not''' re-entered here: they are read, read-only, from the official Stripe module.

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Field !! Constant !! Purpose
|-
| Stripe financial account || <code>STRIPE_BANK_ACCOUNT_FOR_PAYMENTS</code> ''(official module constant)'' || Bank account selector. No local copy, hence no risk of divergence.
|-
| Main bank account || <code>STRIPE_BANK_ACCOUNT_FOR_BANKTRANSFERS</code> ''(official module constant)'' || Same selector. See the box below.
|-
| Fee account || <code>STRIPEACCOUNTING_COMPTE_FRAIS</code> || Account number, e.g. 627xxx
|-
| Dispute account || <code>STRIPEACCOUNTING_COMPTE_LITIGES</code> || Account number, e.g. 658xxx. '''Required''' — used as soon as a dispute occurs, whatever the VAT mode.
|-
| Stripe supplier third party || <code>STRIPEACCOUNTING_FOURNISSEUR_STRIPE_ID</code> || A third party flagged as supplier; its supplier accounting code is what gets used. Optional, unless subscription fees exist.
|-
| VAT mode || <code>STRIPEACCOUNTING_VAT_MODE</code> || <code>none</code>, <code>french</code> or <code>autoliquidation</code>
|-
| Deductible VAT account (intra-EU) || <code>STRIPEACCOUNTING_COMPTE_TVA_DEDUCTIBLE</code> || Required when the VAT mode is not <code>none</code>. Stripe always invoices from a non-French EU entity, so the deductible VAT is intra-EU in every case.
|-
| VAT due account (intra-EU) || <code>STRIPEACCOUNTING_COMPTE_TVA_AUTOLIQUIDATION</code> || Required in <code>autoliquidation</code> mode only — never used in <code>french</code> mode.
|-
| VAT rate || <code>STRIPEACCOUNTING_VAT_RATE</code> || Percentage, 20 by default
|-
| Sync frequency || <code>STRIPEACCOUNTING_SYNC_UNITFREQUENCY</code> || Applied to the scheduled job (in seconds)
|}

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Why redefine the main bank account here?'''

The official Stripe module's setup page only renders that field when <code>STRIPE_AUTO_RECORD_PAYOUT</code> is enabled — and its own save handler resets the value to 0 on every save while the field is not rendered. Yet that setting must stay disabled once this module handles payouts. The field is therefore re-exposed here, writing the core constant directly, so the value stays configurable and stable.

Both account selectors only write their constant when a real account was submitted: saving the page for some unrelated field never overwrites a correct value.
</div>

=== Configuration check ===

<code>StripeAccounting::checkConfig()</code> returns the list of missing constants. It is called both by the setup page (information banner) and by every sync entry point (the real guard that blocks all processing).

=== Pitfall with accounting account selectors ===

The four fields using <code>FormAccounting::select_account()</code> (fees, disputes, both VAT accounts) have a "nothing selected" option whose value is '''<code>-1</code>''' — a non-empty string, therefore truthy in PHP. A field left blank and saved literally stores <code>-1</code>.

<code>StripeAccounting::getAccountConst()</code> normalises that value to an empty string on read, everywhere these constants are read. No entry can therefore land on the non-existent account <code>-1</code>.

== 8. User interface ==

=== Dashboard ===

Stripe balance (live API call), number of unreconciled transactions, total fees for the month, pending payouts, and a '''Sync now''' button — disabled, with a banner listing the missing constants, while the configuration is incomplete.

=== Transaction list ===

A paginated, sortable, filterable list built with the same mechanism as native Dolibarr lists: the icon at the top right of the table lets each user pick their columns, and the preference is stored per user.

{| class="wikitable" style="width:100%;"
! style="width:20%;" | Column !! Content
|-
| Amount, Fee, Total || The fee popup shows the VAT on the fee whenever a reverse-charge pair or French VAT was posted
|-
| Type, Description || Popup with the Stripe ID, the event or source ID, and the full untruncated description
|-
| Third party || The customer resolved through the invoice, or through the source charge for its related fee, or the configured Stripe supplier for a subscription fee
|-
| Entry || A "Piece no. X" link to the accounting entry, and/or a link to the related bank movement — see the caveat below
|-
| Source, Status || The <code>error</code> badge opens a popup with the full error message: no need to query the database to understand a failure
|}

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''Reading the "Entry" column''' — on a <code>fee</code>, <code>subscription_fee</code> or <code>payout</code> row, the link points to the '''bank movement''', not to an accounting piece. The module's <code>piece_num</code> is never the 627/517 entry for the fee: it is only the reverse-charge VAT pair. The fee entry itself is generated later, by Dolibarr's native button, and is never reported back onto this row.
</div>

The page is '''purely informational''': no manual posting is offered there. The module posts automatically, and the actual transfer to accounting for fees and payouts happens through the native "Transfer to accounting" button.

=== <code>charge</code> and <code>fee</code> rows ===

Each payment produces '''two rows''' in the database:

* a <code>charge</code> row, always in status <code>ignored</code>, fee 0, never processed — present solely for idempotency;
* a <code>fee</code> row for the same payment, linked to the first one.

Both appear separately in the list, but the <code>fee</code> row also carries the link to the payment and the invoice, resolved through a join.

=== Test mode banner ===

While live mode is off, the dashboard, the setup page and the transaction list all display the same warning as the official Stripe module. It is impossible to forget you are working in test mode.

=== Menus ===

Everything sits under '''Banks and cash → Stripe account''' (the official module's menu), flat, as three entries at the same level:

# Stripe dashboard
# Stripe transactions
# CSV import ''(administrators only)''

A dashboard link is also added automatically on the bank account record configured as the Stripe account.

== 9. Scheduled job ==

There are two ways to run the sync, both idempotent and safe to re-run. In both cases the code executed is strictly the same: no behavioural difference between the two triggers.

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ Neither of them starts on its own.'''

Activating the module creates the <code>StripeAccountingSync</code> job, but '''disabled by default'''. And even once enabled, the Dolibarr scheduler is triggered by nothing until a system crontab calls it. Without both steps, the sync only happens when "Sync now" is clicked manually.
</div>

=== Step 1 — enable the job ===

Under '''Home → Setup → Modules → Scheduled jobs'''. Since <code>llx_cronjob</code> is a core table, this setting is made through the interface only, never by direct SQL from the module.

=== Step 2 — a system trigger ===

Pick either option.

'''Option A — Dolibarr scheduler''' ''(recommended when several Dolibarr scheduled jobs coexist)''. Runs every due job, not just this one. Requires step 1.

<syntaxhighlight lang="bash">
*/15 * * * * curl "https://your-dolibarr/public/cron/cron_run_jobs_by_url.php?securitykey=YOUR_KEY&userlogin=YOUR_LOGIN"
</syntaxhighlight>

The security key is generated on the scheduled jobs page, "Security of job execution by URL" button.

'''Option B — the module's CLI script.''' Standalone, refuses to run from a browser, and independent of whether the Dolibarr job is enabled.

<syntaxhighlight lang="bash">
*/15 * * * * php /path/to/htdocs/custom/stripeaccounting/cron/stripe_sync.php >> /var/log/stripeaccounting.log 2>&1
</syntaxhighlight>

== 10. Logging and permissions ==

=== Logging ===

Every API call, generated entry, warning or error is traced in <code>llx_stripeaccounting_log</code>, readable in the database or through the standard Dolibarr log file. Levels: <code>DEBUG</code> < <code>INFO</code> < <code>WARNING</code> < <code>ERROR</code>. The <code>context</code> column holds the structured detail as JSON (API payload, computed amounts…).

=== Permissions ===

{| class="wikitable"
! Right !! Controls
|-
| <code>read</code> || Access to the dashboard and the transaction list
|-
| <code>write</code> || Declared for configuration, but not checked in the code today
|-
| <code>reconcile</code> || Manual sync triggering
|}

In practice, <code>admin/setup.php</code> and <code>import.php</code> only check '''Dolibarr administrator''' status, not the <code>write</code> right: only administrators can configure the module or import a CSV, whatever is ticked in the module permissions.

== 11. Database schema ==

=== <code>llx_stripeaccounting_transaction</code> ===

One row per processed Stripe object — charge, fee, refund, dispute or payout — all in the same table, distinguished by the <code>type</code> column.

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Column !! style="width:16%;" | Type !! Role
|-
| <code>rowid</code> || int AI || Primary key
|-
| <code>entity</code> || int || Dolibarr multi-company
|-
| <code>stripe_object_id</code> || varchar(80) || Stripe identifier — '''idempotency anchor'''
|-
| <code>stripe_event_id</code> || varchar(80) || Event identifier, informational only
|-
| <code>type</code> || varchar(20) || <code>charge</code>, <code>fee</code>, <code>subscription_fee</code>, <code>refund</code>, <code>dispute</code>, <code>payout</code>, <code>other</code>
|-
| <code>stripe_source_id</code> || varchar(80) || Source Stripe object (e.g. the charge behind a refund)
|-
| <code>source_label</code> || varchar(80) || Free-text label entered at CSV import; empty for API rows
|-
| <code>description</code> || varchar(255) || Stripe label
|-
| <code>amount</code>, <code>fee</code>, <code>net</code> || decimal(24,8) || Amounts already converted from Stripe cents
|-
| <code>currency</code> || varchar(3) || ISO currency code
|-
| <code>date_created</code>, <code>date_available_on</code> || datetime || Stripe-side dates
|-
| <code>fk_facture</code>, <code>fk_paiement</code> || int || Resolved Dolibarr invoice and payment, if found
|-
| <code>fk_bank</code> || int || Generated <code>llx_bank</code> line ''(empty for a fee in <code>french</code> VAT mode)''
|-
| <code>piece_num</code> || varchar(20) || Generated accounting piece number, where there is one
|-
| <code>status</code> || varchar(16) || <code>pending</code>, <code>reconciled</code>, <code>error</code>, <code>ignored</code>
|-
| <code>error_message</code> || text || Detail on failure
|-
| <code>date_creation</code>, <code>date_processed</code> || datetime || Technical timestamps
|-
| <code>fk_user_creat</code> || int || User who triggered the processing
|}

'''Unique key''' on <code>(stripe_object_id, entity)</code> — this is what guarantees the same Stripe object can never be inserted twice, even with concurrent executions.

=== <code>llx_stripeaccounting_log</code> ===

{| class="wikitable"
! Column !! Role
|-
| <code>level</code> || <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>
|-
| <code>message</code> || Short message
|-
| <code>context</code> || Structured context as JSON
|-
| <code>fk_stripeaccounting_transaction</code> || Related transaction, where applicable
|-
| <code>datec</code> || Timestamp
|}

== 12. Troubleshooting ==

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Symptom !! Likely cause !! Action
|-
| The "Sync now" button is disabled || Minimum configuration incomplete || Fill in the fields listed in the setup page banner
|-
| A transaction stays in <code>error</code> || Entry rejected by Dolibarr (non-existent account, closed period), or refund not matched || Read <code>error_message</code> on the row, then the detail in the log table
|-
| The Stripe balance is not displayed || API key missing or invalid in the official Stripe module || Check <code>stripe/admin/stripe.php</code>
|-
| A refund is never reconciled || The original payment was not found through <code>ext_payment_id</code> || Check that the Stripe payment was recorded by the official module with that identifier
|-
| A <code>subscription_fee</code> stays in <code>error</code> || Stripe supplier third party not set, or has no supplier accounting code || Fill the field in setup, and complete the third party record
|-
| A CSV-imported refund stays in <code>error</code> || '''Normal and expected''' — that account is not linked to <code>ext_payment_id</code> || Handle the invoice and refund manually in accounting
|}

== 13. Pitfalls encountered ==

Development notes, kept so nobody falls into them again.

* '''<code>PaymentVarious::create()</code>''' only updates <code>fk_bank</code> in the database, never on the PHP object. A <code>fetch()</code> after <code>create()</code> is required to get the real value.
* '''<code>select_comptes()</code>''' prints its own HTML ''and'' returns the number of accounts. Call it as a bare statement: wrapping it in <code>print</code> would display that number right after the select tag.
* '''<code>master.inc.php</code>, not <code>main.inc.php</code>''' for the CLI script. The latter expects an HTTP session and, in pure CLI, exits silently — no output, no log, return code 0 — inside its redirect to the login page. This gives the misleading impression that the script "does nothing" rather than a real error.
* '''Core libraries''' — <code>master.inc.php</code> does not load everything <code>main.inc.php</code> loads for the web (e.g. <code>core/lib/date.lib.php</code>, required by <code>BookKeeping</code>). Include them explicitly if the CLI script evolves.
* '''The "nothing selected" option is <code>-1</code>''' in accounting account selectors — see the Configuration section.

== 14. Known limitations ==

* '''Zero-decimal currencies''' (JPY, KRW…) are not handled: amounts are divided by 100 assuming two decimals. Intended use: EUR.
* '''The 35-day window''' is not configurable. A sync interrupted for longer must be caught up manually.
* '''Refund matching''' — relies on <code>ext_payment_id</code> and <code>ext_payment_site</code> in <code>llx_paiement</code>, filled in by the standard Stripe payment flow. A payment recorded any other way cannot be matched automatically. Matching goes through the '''PaymentIntent id''', never the charge id: the core Stripe module never stores the latter ''(it stores either the raw PaymentIntent, or a composite value, depending on the payment path taken)''.
* '''CSV import assumes French notation''': an export with a decimal point would not be parsed correctly.
* '''The "Transfer" column of the Payments CSV''' is stored for information only: it is not used to check that the sum of payments matches the imported payout amount.
* '''CSV-imported refunds always land in <code>error</code>''' — intended behaviour, not a bug.
* '''<code>french</code> VAT mode''' — the Stripe account's bank balance does not reflect the fees, see section 5.

[[Category:Dolibarr]]
[[Category:Modules]]
[[Category:Accounting]]

Stripeaccounting

2026-08-02T12:40:16Z

Goldron :

Stripeaccounting

2026-08-02T12:39:06Z

Goldron :

{{DISPLAYTITLE:StripeAccounting — Documentation technique}}

[[Fichier:Us.png|64px|link=Stripeaccounting/en|Doc en anglais]]

<div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;">
'''StripeAccounting''' est un module Dolibarr de '''rapprochement comptable Stripe'''.

Il lit l'API Stripe (ou un export CSV), repère les mouvements que le module Stripe officiel ne comptabilise pas — frais, remboursements, litiges, virements — et pose les écritures manquantes.

: '''Compatibilité''' — Dolibarr 17+, PHP 7.2 → 8.5
: '''Dépend de''' — modules Stripe, Banque, Comptabilité en partie double
: '''Voir aussi''' — [[README-fr|Installation et guide utilisateur]]
</div>

__TOC__

== 1. Principes de fonctionnement ==

Quatre règles gouvernent tout le module.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Principe !! Ce que ça veut dire
|-
| '''Complémentaire''' || Le module ne crée aucun paiement, aucune facture, aucun webhook. Il lit Stripe et complète la comptabilité, rien de plus.
|-
| '''Idempotent''' || Chaque objet Stripe n'est traité qu'une fois, quel que soit le nombre de relances de la synchronisation.
|-
| '''Jamais de devinette''' || Si une opération ne peut pas être rattachée avec certitude, rien n'est posté : la ligne passe en <code>error</code> pour revue manuelle.
|-
| '''Configuration bloquante''' || Tant que la configuration minimale est incomplète, aucune synchronisation ne démarre (ni bouton, ni cron, ni import).
|}

== 2. Prérequis ==

=== Modules Dolibarr requis ===

{| class="wikitable"
! Module !! Ce qu'il apporte
|-
| '''Stripe''' (<code>modStripe</code>) || Clé API, mode test/live, compte financier Stripe
|-
| '''Banque''' (<code>modBanque</code>) || Tables <code>llx_bank</code> et <code>llx_bank_account</code>
|-
| '''Comptabilité en partie double''' (<code>modAccounting</code>) || Table <code>llx_accounting_bookkeeping</code>
|}

=== Réglage Dolibarr indispensable ===

<code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code> doit être renseigné dans '''Comptabilité → Configuration → Comptes par défaut'''. Sans lui, le virement interne généré par les payouts ne peut pas être transféré en comptabilité (limite de Dolibarr, pas du module).

l’option s'appelle : '''Compte comptable par défaut pour les virements internes'''

=== Notes ===

* Le SDK PHP Stripe n'est pas dupliqué : le module réutilise la copie du cœur (<code>includes/stripe/stripe-php/</code>).
* Le code évite volontairement toute syntaxe PHP postérieure à 7.2 (pas de <code>match</code>, <code>?-></code>, enums, propriétés typées, <code>str_contains</code>…) pour couvrir toute la plage 7.2 → 8.5.

== 3. Arborescence ==

<pre>
custom/stripeaccounting/
├── core/modules/modStripeAccounting.class.php Descripteur (droits, menus, cron, constantes)
├── class/
│ ├── StripeApi.class.php Wrapper SDK Stripe (lecture seule)
│ ├── StripeRepository.class.php Accès SQL + idempotence
│ ├── StripeLogger.class.php Journalisation
│ ├── StripeAccounting.class.php Génération des écritures
│ ├── StripePayout.class.php Rapprochement des virements
│ ├── StripeSync.class.php Orchestrateur (point d'entrée du cron)
│ ├── StripeCsvImporter.class.php Import CSV
│ └── actions_stripeaccounting.class.php Hook 'bankcard'
├── admin/setup.php Configuration
├── import.php Import CSV
├── dashboard.php Tableau de bord
├── transaction_list.php Liste des transactions
├── cron/stripe_sync.php Point d'entrée CLI
├── lib/stripeaccounting.lib.php
├── sql/
├── langs/{fr_FR,en_US,es_ES,it_IT,de_DE}/
└── css/
</pre>

=== Sens des dépendances ===

: pages et hook → <code>StripeSync</code> → (<code>StripeApi</code>, <code>StripeRepository</code>, <code>StripeAccounting</code>, <code>StripePayout</code>) → <code>StripeLogger</code>

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Classe !! Rôle
|-
| <code>StripeApi</code> || Interroge le SDK Stripe (balance transactions, charges, remboursements, litiges, payouts) avec pagination automatique. Aucun accès base, aucune écriture.
|-
| <code>StripeRepository</code> || Tout le SQL des deux tables du module. <code>upsertTransaction()</code> est le point d'idempotence.
|-
| <code>StripeLogger</code> || Écrit dans <code>llx_stripeaccounting_log</code> et en miroir dans <code>dol_syslog()</code>.
|-
| <code>StripeAccounting</code> || Construit les écritures (remboursement, litige, TVA autoliquidation) ou les mouvements bancaires (frais). Expose <code>checkConfig()</code>.
|-
| <code>StripePayout</code> || Crée le virement bancaire interne entre le compte Stripe et la banque réelle.
|-
| <code>StripeSync</code> || Orchestrateur : une méthode par flux, plus <code>reconcileStripeAccount()</code> qui enchaîne tout.
|-
| <code>StripeCsvImporter</code> || Alimente le même pipeline depuis un export CSV Stripe.
|-
| <code>ActionsStripeAccounting</code> || Hook <code>bankcard</code> : lien vers le tableau de bord sur la fiche du compte Stripe.
|}

== 4. Synchronisation et idempotence ==

Chaque flux (<code>syncFees</code>, <code>syncRefunds</code>, <code>syncDisputes</code>, <code>syncPayouts</code>, <code>syncTransactions</code>) suit toujours les mêmes étapes :

# '''Vérifier la configuration''' — si elle est incomplète : log <code>ERROR</code>, arrêt immédiat, aucun appel API.
# '''Lister les objets Stripe''' sur une fenêtre glissante de '''35 jours'''.
# '''Filtrer''' — un objet est ignoré seulement s'il existe déjà ''et'' que son statut est <code>reconciled</code> ou <code>ignored</code>. Une ligne en <code>pending</code> ou <code>error</code> est '''retentée''' à ce run.
# '''Enregistrer''' en statut <code>pending</code>, puis générer l'écriture ou le mouvement bancaire.
# '''Conclure''' — succès : statut <code>reconciled</code>. Échec : statut <code>error</code> avec le message, et '''le lot continue''' sur l'objet suivant.

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Reprise automatique''' — une ligne en <code>error</code> redevient éligible au run suivant. Une fois la cause corrigée (par exemple un exercice comptable créé tardivement), aucune intervention manuelle n'est nécessaire.
</div>

=== Pourquoi les doublons sont impossibles ===

* '''Clé unique en base''' sur <code>(stripe_object_id, entity)</code> — protège même contre deux exécutions concurrentes du cron.
* '''Test explicite avant traitement''' — évite jusqu'à la tentative d'écriture pour un objet déjà finalisé.

=== Cas particuliers : <code>adjustment</code> et <code>payment_failure_refund</code> ===

Ce sont des corrections de solde effectuées par Stripe lui-même (réversion après litige, remboursement d'un paiement finalement échoué). Le module les '''enregistre''' — sinon elles resteraient invisibles — mais ne les comptabilise '''jamais''' automatiquement : le signe du montant et la cause varient trop. Elles sont créées directement en <code>error</code>, avec un message explicite, à traiter manuellement.

== 5. Écritures comptables ==

Toutes les lignes d'un même évènement partagent le triplet <code>doc_type='stripeaccounting'</code>, <code>fk_doc</code>, <code>doc_ref</code> : Dolibarr les regroupe automatiquement sous un même numéro de pièce, sans numérotation propre au module.

=== Vue d'ensemble ===

{| class="wikitable" style="width:100%;"
! Évènement !! Ce que fait le module !! Résultat comptable
|-
| Frais Stripe ''(TVA <code>none</code> ou <code>autoliquidation</code>)'' || Mouvement bancaire <code>PaymentVarious</code> || Écriture 627xxx / 517xxx générée plus tard par Dolibarr
|-
| Frais Stripe ''(mode <code>autoliquidation</code>)'' || En plus : paire TVA postée immédiatement || Débit TVA déductible, crédit TVA autoliquidation ''(impact net nul)''
|-
| Frais Stripe ''(mode <code>french</code>)'' || Écriture directe complète || Débit compte de frais HT + TVA déductible, crédit compte Stripe TTC
|-
| Frais d'abonnement / service ''(Radar, Billing, Connect…)'' || Mouvement bancaire <code>PaymentVarious</code> || Écriture générée plus tard par Dolibarr, sur le compte fournisseur Stripe
|-
| Virement (payout) || Virement bancaire interne entre les 2 comptes || Écriture générée plus tard par Dolibarr
|-
| Remboursement ''(facture retrouvée)'' || Écriture directe || Débit compte client 411xxx, crédit compte Stripe 517xxx
|-
| Remboursement ''(facture introuvable)'' || Rien || Statut <code>error</code>, à traiter manuellement
|-
| Litige / chargeback || Écriture directe || Débit perte sur litiges 658xxx, crédit compte Stripe 517xxx ''(+ compte de frais si frais associés)''
|}

=== Pourquoi frais et virements ne génèrent pas d'écriture directe ===

Le problème historique : quand une facture Stripe est transférée en comptabilité par le workflow standard de Dolibarr, le paiement est comptabilisé pour son montant '''brut''' — les frais sont ignorés à cette étape.

Si le module postait ''en plus'' sa propre écriture ''et'' sa propre ligne bancaire, cette ligne resterait invisible pour <code>bankjournal.php</code> — qui ne reconnaît que les lignes rattachées à <code>doc_type='bank'</code>. Un administrateur transférant « normalement » le compte bancaire en comptabilité créait alors une '''seconde''' écriture pour le même mouvement.

'''La solution retenue :''' pour les frais, les frais d'abonnement et les virements, le module ne crée plus que le '''mouvement bancaire réel''', avec les mécanismes natifs de Dolibarr. C'est ensuite le bouton natif ''« Transférer en comptabilité »'' qui produit l'écriture, comme pour n'importe quel autre mouvement bancaire. Le module ne touche donc plus du tout <code>llx_accounting_bookkeeping</code> dans ces trois cas.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Cas !! Mécanisme natif utilisé
|-
| Frais et frais d'abonnement || <code>PaymentVarious</code> (mouvement bancaire avec compte de contrepartie, sans tiers ni facture), avec son propre <code>accountancy_code</code> que <code>bankjournal.php</code> lit directement.
|-
| Virements (payouts) || Virement interne Dolibarr : <code>Account::addline()</code> des deux côtés, plus <code>add_url_line(…, 'banktransfert')</code>. La contrepartie est imputée sur <code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code>.
|}

Dans les deux cas, le statut passe à <code>reconciled</code> — le module a fini son travail — mais '''<code>piece_num</code> reste vide''' : l'écriture n'existe pas encore, seul <code>fk_bank</code> est renseigné. Après transfert manuel, on la retrouve avec <code>doc_type='bank'</code> et <code>fk_doc</code> égal au <code>fk_bank</code> de la ligne.

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''À savoir''' — l'écriture des virements ne s'équilibre à zéro sur le compte de transfert que lorsque '''les deux''' comptes bancaires (Stripe ''et'' la banque réelle) ont été transférés en comptabilité, pas seulement un des deux.
</div>

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ <code>STRIPE_AUTO_RECORD_PAYOUT</code> doit rester désactivé'''

Dès lors que ce module gère les virements, décochez « Activer l'enregistrement automatique des paiements Stripe » dans <code>stripe/admin/stripe.php</code> — malgré son libellé, cette case ne concerne que les virements.

Sinon, le webhook du module officiel et ce module créeraient chacun leur propre mouvement bancaire pour le même virement, sans le savoir l'un de l'autre.

Le webhook cœur ne conserve d'ailleurs '''aucune''' trace de l'id du virement traité : en cas de double livraison Stripe (garantie « au moins une fois »), rien ne l'empêche de doublonner tout seul. Ce module, lui, a une vraie idempotence et rattrape automatiquement tout virement manqué sur 35 jours.
</div>

=== Page « Transferts Stripe » masquée ===

À l'activation, <code>modStripeAccounting::init()</code> désactive l'entrée de menu <code>stripe/payout.php</code> : cette page interroge l'API en direct sans rien enregistrer, et sa coexistence avec ce module ne créerait qu'une confusion sur ce qui fait foi pour les virements. <code>remove()</code> restaure la condition d'origine. '''C'est la seule table du cœur que ce module modifie''' — délibéré, et documenté ici pour cette raison.

=== Frais par transaction ou frais d'abonnement ? ===

Stripe facture deux choses distinctes sous le mot « frais » :

{| class="wikitable" style="width:100%;"
! !! Frais par transaction !! Frais d'abonnement / service
|-
! Exemple
| Commission sur chaque encaissement || Radar, Billing, Connect
|-
! Où le trouver
| Champ <code>.fee</code> d'une balance transaction de type <code>charge</code> || Balance transaction dédiée, de type <code>stripe_fee</code> ou <code>application_fee</code> ''(le <code>.fee</code> y vaut toujours 0, le montant est dans <code>.amount</code>)''
|-
! Compte utilisé
| Compte de frais configuré (627xxx) || Code comptable fournisseur du tiers Stripe configuré
|-
! Type en base
| <code>fee</code> || <code>subscription_fee</code>
|}

=== Limite du mode TVA <code>french</code> ===

Ce mode doit scinder le montant TTC en HT + TVA, un découpage que <code>PaymentVarious</code> ne sait pas exprimer. Il reste donc sur l'ancien comportement : écriture directe complète, aucun mouvement bancaire créé. Pas de risque de doublon (puisque aucune ligne bancaire n'est produite), mais le solde <code>llx_bank</code> du compte Stripe ne reflétera jamais les frais tant que ce mode est actif.

== 6. Import CSV ==

L'import couvre le cas d'un compte Stripe '''différent''' de celui configuré dans le module officiel — par exemple une autre boutique PrestaShop avec son propre compte marchand. L'API n'y a pas accès : le contenu est exporté en CSV depuis le dashboard Stripe, puis importé.

=== Hypothèse de départ ===

Les factures et paiements de cette boutique sont '''déjà''' comptabilisés dans Dolibarr par un autre processus, et l'encaissement (débit 517, crédit 411) est déjà posé. Seuls manquent les '''frais''', les '''remboursements''' et les '''virements''' — c'est exactement ce que l'import traite.

=== Interface : un seul champ ===

<code>import.php</code> n'expose plus qu'un champ d'upload, '''Historique général''', câblé sur <code>importGeneralHistory()</code>. Ce fichier couvre à lui seul tous les types de mouvements.

Les méthodes <code>importPayments()</code> et <code>importPayouts()</code> restent implémentées et fonctionnelles, mais ne sont plus atteignables depuis l'interface ; elles sont documentées ci-dessous pour mémoire.

Comme le bouton « Synchroniser maintenant », l'import est bloqué — bandeau d'alerte, bouton désactivé, garde-fou côté serveur — tant que la configuration est incomplète.

=== Les trois méthodes ===

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Méthode !! Export Stripe lu !! Traitement
|-
| <code>importGeneralHistory()</code><br />''(seule exposée)'' || Balance history || Aiguillage par colonne <code>Type</code>, voir tableau ci-dessous
|-
| <code>importPayments()</code> || Payments || Frais → écriture de frais. Montant remboursé → ligne <code>refund</code> toujours en <code>error</code>.
|-
| <code>importPayouts()</code> || Payouts || Exactement le même traitement qu'un payout venu de l'API
|}

Aiguillage de l'historique général, par colonne <code>Type</code> :

{| class="wikitable" style="width:100%;"
! style="width:30%;" | Type Stripe !! Traitement
|-
| <code>payout</code> || Virement bancaire interne, comme via l'API
|-
| <code>charge</code> / <code>payment</code> avec frais || Mouvement de frais
|-
| <code>stripe_fee</code> / <code>application_fee</code> || Frais d'abonnement, sur le compte fournisseur Stripe
|-
| <code>refund</code> || Enregistré, '''toujours''' en <code>error</code>
|-
| <code>payout_minimum_balance_hold</code> / <code>…_release</code> || '''Ignorés''' — réserve glissante Stripe, impact net nul, rien à comptabiliser
|-
| tout autre type || Enregistré en <code>type='other'</code>, statut <code>error</code>, type brut conservé dans la description. Aucune écriture devinée.
|}

Les colonnes sont reconnues '''par leur nom''' : l'ordre importe peu, et les colonnes en plus non utilisées sont ignorées.

=== Idempotence de l'import ===

La clé unique protège contre tout double import : réimporter le même CSV, ou un CSV qui chevauche un import précédent, ne crée aucun doublon.

Point important : dans l'historique général, les lignes <code>payout</code> et <code>charge</code>/<code>payment</code> sont indexées par leur colonne '''<code>Source</code>''' (<code>po_…</code>, <code>ch_…</code>), pas par l'<code>id</code> de la ligne (<code>txn_…</code>) — soit exactement la même clé que les imports dédiés. Importer l'historique général '''en plus''' des exports spécifiques ne poste donc jamais deux fois la même écriture, quel que soit l'ordre.

Les identifiants Stripe étant uniques à l'échelle de la plateforme, mélanger dans la même table des lignes venant du compte API et de plusieurs comptes importés en CSV ne présente aucun risque de collision.

=== Détails pratiques ===

* '''Libellé source''' — un champ libre saisi à l'import (ex. « Boutique DRM ») est stocké sur chaque ligne créée et sert de colonne et de filtre dans la liste, pour distinguer plusieurs boutiques côte à côte.
* '''Format des montants''' — les CSV Stripe utilisent la virgule décimale française, convertie via <code>price2num()</code>. Les dates marquées <code>(UTC)</code> sont interprétées comme telles.

== 7. Configuration ==

La clé API et le mode test/live ne sont '''pas''' ressaisis ici : ils sont lus en lecture seule depuis le module Stripe officiel.

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Champ !! Constante !! Usage
|-
| Compte financier Stripe || <code>STRIPE_BANK_ACCOUNT_FOR_PAYMENTS</code> ''(constante du module officiel)'' || Sélecteur de compte bancaire. Aucune copie locale, donc aucun risque de divergence.
|-
| Compte bancaire principal || <code>STRIPE_BANK_ACCOUNT_FOR_BANKTRANSFERS</code> ''(constante du module officiel)'' || Même sélecteur. Voir l'encadré ci-dessous.
|-
| Compte de frais || <code>STRIPEACCOUNTING_COMPTE_FRAIS</code> || Numéro de compte, ex. 627xxx
|-
| Compte de litiges || <code>STRIPEACCOUNTING_COMPTE_LITIGES</code> || Numéro de compte, ex. 658xxx. '''Requis''' — utilisé dès qu'un litige survient, quel que soit le mode TVA.
|-
| Tiers fournisseur Stripe || <code>STRIPEACCOUNTING_FOURNISSEUR_STRIPE_ID</code> || Tiers marqué fournisseur ; c'est son code comptable fournisseur qui est utilisé. Optionnel, sauf s'il existe des frais d'abonnement.
|-
| Mode TVA || <code>STRIPEACCOUNTING_VAT_MODE</code> || <code>none</code>, <code>french</code> ou <code>autoliquidation</code>
|-
| Compte TVA déductible (intracommunautaire) || <code>STRIPEACCOUNTING_COMPTE_TVA_DEDUCTIBLE</code> || Requis si mode TVA ≠ <code>none</code>. Stripe facturant toujours depuis une entité UE non française, la TVA déductible est intracommunautaire dans tous les cas.
|-
| Compte de TVA due (intracommunautaire) || <code>STRIPEACCOUNTING_COMPTE_TVA_AUTOLIQUIDATION</code> || Requis en mode <code>autoliquidation</code> uniquement — jamais utilisé en mode <code>french</code>.
|-
| Taux de TVA || <code>STRIPEACCOUNTING_VAT_RATE</code> || Pourcentage, 20 par défaut
|-
| Fréquence de synchronisation || <code>STRIPEACCOUNTING_SYNC_UNITFREQUENCY</code> || Répercutée sur la tâche planifiée (en secondes)
|}

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Pourquoi redéfinir le compte bancaire principal ici ?'''

La page de configuration du module Stripe officiel n'affiche ce champ que si <code>STRIPE_AUTO_RECORD_PAYOUT</code> est activé — et son handler de sauvegarde remet la valeur à 0 à chaque enregistrement tant que le champ n'est pas rendu. Or ce réglage doit justement rester désactivé quand ce module gère les virements. Le champ est donc réexposé ici, en écrivant directement la constante du cœur, pour que la valeur reste configurable et stable.

Les deux sélecteurs de compte n'écrivent leur constante que si un compte réel a été soumis : enregistrer la page pour un tout autre champ n'écrase jamais une valeur correcte.
</div>

=== Vérification de la configuration ===

<code>StripeAccounting::checkConfig()</code> renvoie la liste des constantes manquantes. Elle est appelée à la fois par la page de configuration (bandeau d'information) et par chaque point d'entrée de synchronisation (garde-fou réel qui bloque tout traitement).

=== Piège des sélecteurs de compte comptable ===

Les quatre champs utilisant <code>FormAccounting::select_account()</code> (frais, litiges, les deux comptes TVA) ont une option « rien sélectionné » dont la valeur est '''<code>-1</code>''' — une chaîne non vide, donc vraie en PHP. Un champ laissé vide et enregistré stocke littéralement <code>-1</code>.

<code>StripeAccounting::getAccountConst()</code> normalise cette valeur en chaîne vide à la lecture, partout où ces constantes sont lues. Aucune écriture ne peut donc atterrir sur le compte inexistant <code>-1</code>.

== 8. Interface ==

=== Tableau de bord ===

Solde Stripe (appel API en direct), nombre de transactions non rapprochées, total des frais du mois, payouts en attente, et bouton '''Synchroniser maintenant''' — désactivé, avec bandeau listant les constantes manquantes, tant que la configuration est incomplète.

=== Liste des transactions ===

Liste paginée, triable et filtrable, construite avec le même mécanisme que les listes natives Dolibarr : l'icône en haut à droite du tableau permet à chaque utilisateur de choisir ses colonnes, et la préférence est mémorisée par utilisateur.

{| class="wikitable" style="width:100%;"
! style="width:20%;" | Colonne !! Contenu
|-
| Montant, Frais, Total || Le popup sur les frais indique la TVA sur frais quand une paire d'autoliquidation ou une TVA française a été postée
|-
| Type, Description || Popup avec l'ID Stripe, l'ID d'évènement ou de source, et la description complète non tronquée
|-
| Tiers || Le client résolu via la facture, ou via la charge source pour son frais associé, ou le tiers fournisseur Stripe pour un frais d'abonnement
|-
| Écriture || Lien « Pièce n°X » vers l'écriture, et/ou lien vers le mouvement bancaire associé — voir la nuance ci-dessous
|-
| Source, Statut || Le badge <code>error</code> ouvre un popup avec le message d'erreur complet : plus besoin d'aller en base pour comprendre un échec
|}

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''Lire la colonne « Écriture »''' — sur une ligne <code>fee</code>, <code>subscription_fee</code> ou <code>payout</code>, le lien pointe vers le '''mouvement bancaire''', pas vers une pièce comptable. Le <code>piece_num</code> du module, lui, n'est jamais l'écriture 627/517 du frais : c'est uniquement la paire TVA d'autoliquidation. L'écriture du frais est générée plus tard, par le bouton natif de Dolibarr, et n'est jamais reportée sur cette ligne.
</div>

La page est '''purement consultative''' : aucune comptabilisation manuelle n'y est proposée. Le module comptabilise automatiquement, et le transfert en comptabilité des frais et virements se fait depuis le bouton natif « Transférer en comptabilité ».

=== Lignes <code>charge</code> et <code>fee</code> ===

Chaque paiement produit '''deux lignes''' en base :

* une ligne <code>charge</code>, toujours en statut <code>ignored</code>, frais à 0, jamais traitée — présente uniquement pour l'idempotence ;
* une ligne <code>fee</code> pour le même paiement, liée à la première.

Les deux apparaissent séparément dans la liste, mais la ligne <code>fee</code> porte elle aussi le lien vers le paiement et la facture, résolu par jointure.

=== Bandeau mode test ===

Tant que le mode live n'est pas activé, le tableau de bord, la page de configuration et la liste des transactions affichent tous les trois le même avertissement que le module Stripe officiel. Impossible d'oublier qu'on travaille en mode test.

=== Menus ===

Tout est regroupé sous '''Banques et caisses → Compte Stripe''' (menu du module officiel), à plat, en trois entrées de même niveau :

# Tableau de bord Stripe
# Transactions Stripe
# Import CSV ''(réservé aux administrateurs)''

Un lien vers le tableau de bord est aussi ajouté automatiquement sur la fiche du compte bancaire configuré comme compte Stripe.

== 9. Tâche planifiée ==

Deux façons d'exécuter la synchronisation, toutes deux idempotentes et sans risque à relancer. Dans les deux cas le code exécuté est strictement le même : aucune divergence de comportement.

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ Aucune des deux ne démarre toute seule.'''

L'activation du module crée la tâche <code>StripeAccountingSync</code>, mais '''désactivée par défaut'''. Et même activée, l'ordonnanceur Dolibarr n'est déclenché par rien tant qu'aucune crontab système ne l'appelle. Sans ces deux étapes, la synchro n'a lieu qu'au clic manuel sur « Synchroniser maintenant ».
</div>

=== Étape 1 — activer la tâche ===

Dans '''Accueil → Configuration → Modules → Tâches planifiées'''. <code>llx_cronjob</code> étant une table du cœur, ce réglage se fait uniquement par l'interface, jamais en SQL direct depuis le module.

=== Étape 2 — un déclencheur système ===

Au choix, l'une des deux options.

'''Option A — ordonnanceur Dolibarr''' ''(recommandé si plusieurs tâches planifiées coexistent)''. Lance toutes les tâches dues, pas seulement celle-ci. Nécessite l'étape 1.

<syntaxhighlight lang="bash">
*/15 * * * * curl "https://votre-dolibarr/public/cron/cron_run_jobs_by_url.php?securitykey=VOTRE_CLE&userlogin=VOTRE_LOGIN"
</syntaxhighlight>

La clé de sécurité se génère sur la page des tâches planifiées, bouton « Sécurité de l'exécution des tâches par URL ».

'''Option B — script CLI du module.''' Autonome, refuse l'exécution depuis un navigateur, et indépendant de l'état activé ou non de la tâche Dolibarr.

<syntaxhighlight lang="bash">
*/15 * * * * php /chemin/vers/htdocs/custom/stripeaccounting/cron/stripe_sync.php >> /var/log/stripeaccounting.log 2>&1
</syntaxhighlight>

== 10. Journalisation et permissions ==

=== Journalisation ===

Chaque appel API, écriture générée, avertissement ou erreur est tracé dans <code>llx_stripeaccounting_log</code>, consultable en base ou via le fichier de log standard Dolibarr. Niveaux : <code>DEBUG</code> < <code>INFO</code> < <code>WARNING</code> < <code>ERROR</code>. La colonne <code>context</code> contient le détail structuré en JSON (payload API, montants calculés…).

=== Permissions ===

{| class="wikitable"
! Droit !! Contrôle
|-
| <code>read</code> || Consultation du tableau de bord et de la liste
|-
| <code>write</code> || Déclarée pour la configuration, mais non vérifiée dans le code aujourd'hui
|-
| <code>reconcile</code> || Déclenchement manuel de la synchronisation
|}

En pratique, <code>admin/setup.php</code> et <code>import.php</code> ne contrôlent que le statut '''administrateur Dolibarr''', pas le droit <code>write</code> : seuls les administrateurs peuvent configurer le module ou importer un CSV, quoi qu'il soit coché dans les permissions.

== 11. Base de données ==

=== <code>llx_stripeaccounting_transaction</code> ===

Une ligne par objet Stripe traité — charge, frais, remboursement, litige ou virement — tous dans la même table, distingués par la colonne <code>type</code>.

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Colonne !! style="width:16%;" | Type !! Rôle
|-
| <code>rowid</code> || int AI || Clé primaire
|-
| <code>entity</code> || int || Multi-société Dolibarr
|-
| <code>stripe_object_id</code> || varchar(80) || Identifiant Stripe — '''ancre d'idempotence'''
|-
| <code>stripe_event_id</code> || varchar(80) || Identifiant d'évènement, informatif seulement
|-
| <code>type</code> || varchar(20) || <code>charge</code>, <code>fee</code>, <code>subscription_fee</code>, <code>refund</code>, <code>dispute</code>, <code>payout</code>, <code>other</code>
|-
| <code>stripe_source_id</code> || varchar(80) || Objet Stripe source (ex. la charge liée à un remboursement)
|-
| <code>source_label</code> || varchar(80) || Libellé libre saisi à l'import CSV ; vide pour les lignes venues de l'API
|-
| <code>description</code> || varchar(255) || Libellé Stripe
|-
| <code>amount</code>, <code>fee</code>, <code>net</code> || decimal(24,8) || Montants déjà convertis depuis les centimes Stripe
|-
| <code>currency</code> || varchar(3) || Code devise ISO
|-
| <code>date_created</code>, <code>date_available_on</code> || datetime || Dates côté Stripe
|-
| <code>fk_facture</code>, <code>fk_paiement</code> || int || Facture et paiement Dolibarr résolus, si trouvés
|-
| <code>fk_bank</code> || int || Ligne <code>llx_bank</code> générée ''(vide pour un frais en mode TVA <code>french</code>)''
|-
| <code>piece_num</code> || varchar(20) || Numéro de pièce comptable généré, quand il y en a un
|-
| <code>status</code> || varchar(16) || <code>pending</code>, <code>reconciled</code>, <code>error</code>, <code>ignored</code>
|-
| <code>error_message</code> || text || Détail en cas d'erreur
|-
| <code>date_creation</code>, <code>date_processed</code> || datetime || Horodatage technique
|-
| <code>fk_user_creat</code> || int || Utilisateur ayant déclenché le traitement
|}

'''Clé unique''' sur <code>(stripe_object_id, entity)</code> — c'est elle qui garantit qu'un même objet Stripe ne peut jamais être inséré deux fois, même en cas d'exécutions concurrentes.

=== <code>llx_stripeaccounting_log</code> ===

{| class="wikitable"
! Colonne !! Rôle
|-
| <code>level</code> || <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>
|-
| <code>message</code> || Message court
|-
| <code>context</code> || Contexte structuré en JSON
|-
| <code>fk_stripeaccounting_transaction</code> || Transaction liée, si applicable
|-
| <code>datec</code> || Horodatage
|}

== 12. Dépannage ==

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Symptôme !! Cause probable !! Action
|-
| Le bouton « Synchroniser maintenant » est désactivé || Configuration minimale incomplète || Compléter les champs listés dans le bandeau d'alerte de la page de configuration
|-
| Une transaction reste en <code>error</code> || Écriture refusée par Dolibarr (compte inexistant, période clôturée), ou remboursement non rattaché || Lire <code>error_message</code> sur la ligne, puis le détail dans la table de logs
|-
| Le solde Stripe ne s'affiche pas || Clé API manquante ou invalide dans le module Stripe officiel || Vérifier <code>stripe/admin/stripe.php</code>
|-
| Un remboursement n'est jamais rapproché || Le paiement d'origine n'a pas été retrouvé via <code>ext_payment_id</code> || Vérifier que le paiement Stripe a bien été enregistré par le module officiel avec cet identifiant
|-
| Un <code>subscription_fee</code> reste en <code>error</code> || Tiers fournisseur Stripe non renseigné, ou sans code comptable fournisseur || Renseigner le champ en configuration, et compléter la fiche du tiers
|-
| Un remboursement importé en CSV reste en <code>error</code> || '''Normal et attendu''' — ce compte n'est pas relié à <code>ext_payment_id</code> || Traiter la facture et le remboursement manuellement en comptabilité
|}

== 13. Pièges rencontrés ==

Notes de développement, conservées pour éviter de retomber dedans.

* '''<code>PaymentVarious::create()</code>''' ne met à jour <code>fk_bank</code> qu'en base, jamais sur l'objet PHP. Un <code>fetch()</code> après <code>create()</code> est indispensable pour récupérer la vraie valeur.
* '''<code>select_comptes()</code>''' affiche son propre HTML ''et'' retourne le nombre de comptes. L'appeler en instruction nue : l'envelopper dans <code>print</code> réafficherait ce nombre juste après la balise select.
* '''<code>master.inc.php</code>, pas <code>main.inc.php</code>''' pour le script CLI. Le second attend une session HTTP et, en pur CLI, se termine silencieusement — aucune sortie, aucun log, code retour 0 — dans sa redirection vers la page de connexion. L'impression trompeuse que le script « ne fait rien » plutôt qu'une vraie erreur.
* '''Bibliothèques du cœur''' — <code>master.inc.php</code> ne charge pas tout ce que <code>main.inc.php</code> charge pour le web (par exemple <code>core/lib/date.lib.php</code>, requis par <code>BookKeeping</code>). À inclure explicitement si le script CLI évolue.
* '''Option « rien sélectionné » à <code>-1</code>''' dans les sélecteurs de compte comptable — voir la section Configuration.

== 14. Limites connues ==

* '''Devises « zéro décimale »''' (JPY, KRW…) non gérées : les montants sont divisés par 100 en supposant deux décimales. Usage prévu : EUR.
* '''Fenêtre de 35 jours''' non configurable. Une synchronisation interrompue plus longtemps devra être rattrapée manuellement.
* '''Rattachement des remboursements''' — dépend de <code>ext_payment_id</code> et <code>ext_payment_site</code> sur <code>llx_paiement</code>, renseignés par le flux de paiement Stripe standard. Un paiement enregistré autrement ne pourra pas être rattaché automatiquement. Le rattachement se fait via le '''PaymentIntent id''', jamais via l'id de charge : le module Stripe du cœur ne stocke jamais ce dernier ''(il y met soit le PaymentIntent brut, soit un composite, selon le chemin de paiement emprunté)''.
* '''Import CSV en notation française''' uniquement : un export à point décimal ne serait pas interprété correctement.
* '''Colonne « Transfer » du CSV Paiements''' stockée à titre informatif seulement : elle ne sert pas à vérifier que le total des paiements correspond au montant du virement importé.
* '''Remboursements importés en CSV toujours en <code>error</code>''' — comportement voulu, pas un bug.
* '''Mode TVA <code>french</code>''' — le solde bancaire du compte Stripe ne reflète pas les frais, voir section 5.

[[Catégorie:Dolibarr]]
[[Catégorie:Modules]]
[[Catégorie:Comptabilité]]

Stripeaccounting/en

2026-08-02T12:36:37Z

Goldron :

{{DISPLAYTITLE:StripeAccounting — Technical documentation}}

[[Fichier:Fr.png|link=Stripeaccounting]]

<div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;">
'''StripeAccounting''' is a Dolibarr module for '''Stripe accounting reconciliation'''.

It reads the Stripe API (or a CSV export), identifies the movements the official Stripe module does not post — fees, refunds, disputes, payouts — and creates the missing accounting entries.

: '''Compatibility''' — Dolibarr 17+, PHP 7.2 → 8.5
: '''Depends on''' — Stripe, Bank and Double-entry Accounting modules
: '''See also''' — [[README|Installation and user guide]]
</div>

__TOC__

== 1. Design principles ==

Four rules govern the whole module.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Principle !! What it means
|-
| '''Complementary''' || The module creates no payment, no invoice, no webhook. It reads Stripe and completes the books, nothing more.
|-
| '''Idempotent''' || Each Stripe object is processed once only, no matter how many times the sync is re-run.
|-
| '''Never guess''' || If an operation cannot be matched with certainty, nothing is posted: the row goes to <code>error</code> for manual review.
|-
| '''Configuration is blocking''' || As long as the minimum configuration is incomplete, no sync runs at all (no button, no cron, no import).
|}

== 2. Requirements ==

=== Required Dolibarr modules ===

{| class="wikitable"
! Module !! What it provides
|-
| '''Stripe''' (<code>modStripe</code>) || API key, test/live mode, Stripe financial account
|-
| '''Bank''' (<code>modBanque</code>) || <code>llx_bank</code> and <code>llx_bank_account</code> tables
|-
| '''Double-entry accounting''' (<code>modAccounting</code>) || <code>llx_accounting_bookkeeping</code> table
|}

=== Mandatory Dolibarr setting ===

<code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code> must be set under '''Accounting → Setup → Miscellaneous accounts'''. Without it, the internal transfer generated by payouts cannot be transferred to accounting (a Dolibarr limitation, not a module one).

=== Notes ===

* The Stripe PHP SDK is not re-vendored: the module reuses the core copy (<code>includes/stripe/stripe-php/</code>).
* The code deliberately avoids any PHP syntax newer than 7.2 (no <code>match</code>, <code>?-></code>, enums, typed properties, <code>str_contains</code>…) so it runs across the whole 7.2 → 8.5 range.

== 3. File tree ==

<pre>
custom/stripeaccounting/
├── core/modules/modStripeAccounting.class.php Module descriptor (permissions, menus, cron, constants)
├── class/
│ ├── StripeApi.class.php Stripe SDK wrapper (read-only)
│ ├── StripeRepository.class.php SQL access + idempotency
│ ├── StripeLogger.class.php Logging
│ ├── StripeAccounting.class.php Accounting entry generation
│ ├── StripePayout.class.php Payout reconciliation
│ ├── StripeSync.class.php Orchestrator (cron entry point)
│ ├── StripeCsvImporter.class.php CSV import
│ └── actions_stripeaccounting.class.php 'bankcard' hook
├── admin/setup.php Configuration
├── import.php CSV import
├── dashboard.php Dashboard
├── transaction_list.php Transaction list
├── cron/stripe_sync.php CLI entry point
├── lib/stripeaccounting.lib.php
├── sql/
├── langs/{fr_FR,en_US,es_ES,it_IT,de_DE}/
└── css/
</pre>

=== Dependency direction ===

: pages and hook → <code>StripeSync</code> → (<code>StripeApi</code>, <code>StripeRepository</code>, <code>StripeAccounting</code>, <code>StripePayout</code>) → <code>StripeLogger</code>

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Class !! Role
|-
| <code>StripeApi</code> || Queries the Stripe SDK (balance transactions, charges, refunds, disputes, payouts) with automatic pagination. No database access, no accounting entries.
|-
| <code>StripeRepository</code> || All SQL for the module's two tables. <code>upsertTransaction()</code> is the idempotency anchor.
|-
| <code>StripeLogger</code> || Writes to <code>llx_stripeaccounting_log</code> and mirrors to <code>dol_syslog()</code>.
|-
| <code>StripeAccounting</code> || Builds accounting entries (refund, dispute, reverse-charge VAT) or bank movements (fees). Exposes <code>checkConfig()</code>.
|-
| <code>StripePayout</code> || Creates the internal bank transfer between the Stripe account and the real bank account.
|-
| <code>StripeSync</code> || Orchestrator: one method per flow, plus <code>reconcileStripeAccount()</code> which chains them all.
|-
| <code>StripeCsvImporter</code> || Feeds the same pipeline from a Stripe CSV export.
|-
| <code>ActionsStripeAccounting</code> || <code>bankcard</code> hook: dashboard link on the Stripe account record.
|}

== 4. Synchronisation and idempotency ==

Every flow (<code>syncFees</code>, <code>syncRefunds</code>, <code>syncDisputes</code>, <code>syncPayouts</code>, <code>syncTransactions</code>) always follows the same steps:

# '''Check the configuration''' — if incomplete: <code>ERROR</code> log, immediate stop, no API call at all.
# '''List Stripe objects''' over a rolling window of '''35 days'''.
# '''Filter''' — an object is skipped only if it already exists ''and'' its status is <code>reconciled</code> or <code>ignored</code>. A row in <code>pending</code> or <code>error</code> is '''retried''' on this run.
# '''Record''' it as <code>pending</code>, then generate the accounting entry or bank movement.
# '''Conclude''' — success: status <code>reconciled</code>. Failure: status <code>error</code> with the message, and '''the batch carries on''' with the next object.

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Automatic retry''' — a row in <code>error</code> becomes eligible again on the next run. Once the cause is fixed (a fiscal year created late, for instance), no manual action is needed.
</div>

=== Why duplicates are impossible ===

* '''Unique database key''' on <code>(stripe_object_id, entity)</code> — protects even against two concurrent cron executions.
* '''Explicit check before processing''' — avoids even attempting to post an entry for an already-finalised object.

=== Special cases: <code>adjustment</code> and <code>payment_failure_refund</code> ===

These are balance corrections Stripe makes on its own (reversal after a dispute is resolved, automatic refund of a payment that ultimately failed). The module '''records''' them — otherwise they would stay invisible — but '''never''' posts them automatically: the sign of the amount and the underlying cause vary too much. They are created directly in <code>error</code>, with an explicit message, to be handled manually.

== 5. Accounting entries ==

All lines of a single Stripe event share the same <code>doc_type='stripeaccounting'</code>, <code>fk_doc</code> and <code>doc_ref</code> triplet: Dolibarr automatically groups them under one piece number, so the module needs no numbering scheme of its own.

=== Overview ===

{| class="wikitable" style="width:100%;"
! Event !! What the module does !! Resulting entry
|-
| Stripe fee ''(VAT mode <code>none</code> or <code>autoliquidation</code>)'' || <code>PaymentVarious</code> bank movement || 627xxx / 517xxx entry generated later by Dolibarr
|-
| Stripe fee ''(<code>autoliquidation</code> mode)'' || Plus: VAT pair posted immediately || Debit deductible VAT, credit reverse-charge VAT ''(net impact nil)''
|-
| Stripe fee ''(<code>french</code> mode)'' || Full direct entry || Debit fee account excl. VAT + deductible VAT, credit Stripe account incl. VAT
|-
| Subscription / service fees ''(Radar, Billing, Connect…)'' || <code>PaymentVarious</code> bank movement || Entry generated later by Dolibarr, on the Stripe supplier account
|-
| Payout || Internal bank transfer between the two accounts || Entry generated later by Dolibarr
|-
| Refund ''(invoice found)'' || Direct entry || Debit customer account 411xxx, credit Stripe account 517xxx
|-
| Refund ''(invoice not found)'' || Nothing || Status <code>error</code>, handle manually
|-
| Dispute / chargeback || Direct entry || Debit dispute loss 658xxx, credit Stripe account 517xxx ''(+ fee account if fees apply)''
|}

=== Why fees and payouts produce no direct entry ===

The historical problem: when a Stripe-paid invoice is transferred to accounting through Dolibarr's standard workflow, the payment is posted at its '''gross''' amount — fees are ignored at that stage.

If the module posted its own entry ''and'' its own bank line on top of that, this line would stay invisible to <code>bankjournal.php</code> — which only recognises lines attached to <code>doc_type='bank'</code>. An administrator transferring the bank account to accounting "normally" would then create a '''second''' entry for the very same movement.

'''The chosen solution:''' for fees, subscription fees and payouts, the module now creates only the '''real bank movement''', using Dolibarr's native mechanisms. The native ''"Transfer to accounting"'' button then produces the entry, exactly as for any other bank movement. In those three cases, the module no longer touches <code>llx_accounting_bookkeeping</code> at all.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Case !! Native mechanism used
|-
| Fees and subscription fees || <code>PaymentVarious</code> (bank movement with an explicit counterpart account, no third party or invoice), carrying its own <code>accountancy_code</code>, which <code>bankjournal.php</code> reads directly.
|-
| Payouts || Dolibarr internal transfer: <code>Account::addline()</code> on both sides, plus <code>add_url_line(…, 'banktransfert')</code>. The counterpart is posted to <code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code>.
|}

In both cases the status becomes <code>reconciled</code> — the module's job is done — but '''<code>piece_num</code> stays empty''': the entry does not exist yet, only <code>fk_bank</code> is set. After the manual transfer, it can be found with <code>doc_type='bank'</code> and <code>fk_doc</code> equal to the row's <code>fk_bank</code>.

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''Worth knowing''' — the payout entry only balances to zero on the transfer account once '''both''' bank accounts (Stripe ''and'' the real bank) have been transferred to accounting, not just one of them.
</div>

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ <code>STRIPE_AUTO_RECORD_PAYOUT</code> must stay disabled'''

Once this module handles payouts, untick "Enable automatic recording of Stripe payments" in <code>stripe/admin/stripe.php</code> — despite its wording, that checkbox only concerns payouts.

Otherwise the official module's webhook and this module would each create their own bank movement for the same payout, unaware of each other.

The core webhook keeps '''no''' trace of the payout id it has processed: should Stripe deliver the event twice (delivery is guaranteed "at least once"), nothing stops it from duplicating on its own either. This module has real idempotency and automatically catches up any missed payout within 35 days.
</div>

=== The "Stripe transfers" page is hidden ===

On activation, <code>modStripeAccounting::init()</code> disables the <code>stripe/payout.php</code> menu entry: that page queries the API live without recording anything, and having it alongside this module would only create confusion about which one is authoritative for payouts. <code>remove()</code> restores the original condition. '''This is the only core table the module modifies''' — deliberate, and documented here for that reason.

=== Per-transaction fees or subscription fees? ===

Stripe bills two distinct things under the generic word "fees":

{| class="wikitable" style="width:100%;"
! !! Per-transaction fees !! Subscription / service fees
|-
! Example
| Commission on each payment || Radar, Billing, Connect
|-
! Where to find it
| The <code>.fee</code> field of a <code>charge</code> balance transaction || A dedicated balance transaction, type <code>stripe_fee</code> or <code>application_fee</code> ''(its <code>.fee</code> is always 0, the amount sits in <code>.amount</code>)''
|-
! Account used
| The configured fee account (627xxx) || The supplier accounting code of the configured Stripe third party
|-
! Type in database
| <code>fee</code> || <code>subscription_fee</code>
|}

=== Limitation of the <code>french</code> VAT mode ===

This mode has to split the gross amount into net + VAT, something <code>PaymentVarious</code> cannot express. It therefore keeps the previous behaviour: a full direct entry, with no bank movement created. No duplicate risk (precisely because no bank line is produced), but the <code>llx_bank</code> balance of the Stripe account will never reflect the fees while this mode is active.

== 6. CSV import ==

The import covers the case of a Stripe account '''different''' from the one configured in the official module — another PrestaShop shop with its own merchant account, for example. The API has no access to it: its contents are exported to CSV from the Stripe dashboard, then imported.

=== Starting assumption ===

The invoices and payments of that shop are '''already''' posted in Dolibarr through some other process, and the collection (debit 517, credit 411) is already booked. Only the '''fees''', '''refunds''' and '''payouts''' are missing — which is exactly what the import handles.

=== Interface: a single field ===

<code>import.php</code> now exposes only one upload field, '''General history''', wired to <code>importGeneralHistory()</code>. That file alone covers every movement type.

<code>importPayments()</code> and <code>importPayouts()</code> are still implemented and functional, but no longer reachable from the interface; they are documented below for reference.

Like the "Sync now" button, the import is blocked — warning banner, disabled button, server-side guard — while the configuration is incomplete.

=== The three methods ===

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Method !! Stripe export read !! Processing
|-
| <code>importGeneralHistory()</code><br />''(the only one exposed)'' || Balance history || Dispatch on the <code>Type</code> column, see table below
|-
| <code>importPayments()</code> || Payments || Fee → fee movement. Amount refunded → <code>refund</code> row, always in <code>error</code>.
|-
| <code>importPayouts()</code> || Payouts || Exactly the same processing as a payout coming from the API
|}

General history dispatch, by <code>Type</code> column:

{| class="wikitable" style="width:100%;"
! style="width:30%;" | Stripe type !! Processing
|-
| <code>payout</code> || Internal bank transfer, as via the API
|-
| <code>charge</code> / <code>payment</code> with a fee || Fee movement
|-
| <code>stripe_fee</code> / <code>application_fee</code> || Subscription fee, on the Stripe supplier account
|-
| <code>refund</code> || Recorded, '''always''' in <code>error</code>
|-
| <code>payout_minimum_balance_hold</code> / <code>…_release</code> || '''Ignored''' — Stripe rolling reserve, no real cash movement, nothing to post
|-
| any other type || Recorded as <code>type='other'</code>, status <code>error</code>, raw Stripe type kept in the description. No guessed entry.
|}

Columns are matched '''by name''': their order does not matter, and extra unused columns are ignored.

=== Import idempotency ===

The unique key protects against any double import: re-importing the same CSV, or one overlapping a previous import, creates no duplicate.

An important detail: in the general history, <code>payout</code> and <code>charge</code>/<code>payment</code> rows are indexed by their '''<code>Source</code>''' column (<code>po_…</code>, <code>ch_…</code>), not by the row's own <code>id</code> (<code>txn_…</code>) — the very same key the dedicated imports use. Importing the general history '''on top of''' the specific exports therefore never posts the same entry twice, in any order.

Since Stripe identifiers are unique platform-wide, mixing rows from the API account and from several CSV-imported accounts in the same table carries no collision risk.

=== Practical details ===

* '''Source label''' — a free-text field entered at import time (e.g. "DRM shop") is stored on every created row and serves as a column and filter in the list, to tell several shops apart side by side.
* '''Amount format''' — Stripe CSVs use the French decimal comma, converted through <code>price2num()</code>. Dates marked <code>(UTC)</code> are interpreted as such.

== 7. Configuration ==

The API key and test/live mode are '''not''' re-entered here: they are read, read-only, from the official Stripe module.

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Field !! Constant !! Purpose
|-
| Stripe financial account || <code>STRIPE_BANK_ACCOUNT_FOR_PAYMENTS</code> ''(official module constant)'' || Bank account selector. No local copy, hence no risk of divergence.
|-
| Main bank account || <code>STRIPE_BANK_ACCOUNT_FOR_BANKTRANSFERS</code> ''(official module constant)'' || Same selector. See the box below.
|-
| Fee account || <code>STRIPEACCOUNTING_COMPTE_FRAIS</code> || Account number, e.g. 627xxx
|-
| Dispute account || <code>STRIPEACCOUNTING_COMPTE_LITIGES</code> || Account number, e.g. 658xxx. '''Required''' — used as soon as a dispute occurs, whatever the VAT mode.
|-
| Stripe supplier third party || <code>STRIPEACCOUNTING_FOURNISSEUR_STRIPE_ID</code> || A third party flagged as supplier; its supplier accounting code is what gets used. Optional, unless subscription fees exist.
|-
| VAT mode || <code>STRIPEACCOUNTING_VAT_MODE</code> || <code>none</code>, <code>french</code> or <code>autoliquidation</code>
|-
| Deductible VAT account (intra-EU) || <code>STRIPEACCOUNTING_COMPTE_TVA_DEDUCTIBLE</code> || Required when the VAT mode is not <code>none</code>. Stripe always invoices from a non-French EU entity, so the deductible VAT is intra-EU in every case.
|-
| VAT due account (intra-EU) || <code>STRIPEACCOUNTING_COMPTE_TVA_AUTOLIQUIDATION</code> || Required in <code>autoliquidation</code> mode only — never used in <code>french</code> mode.
|-
| VAT rate || <code>STRIPEACCOUNTING_VAT_RATE</code> || Percentage, 20 by default
|-
| Sync frequency || <code>STRIPEACCOUNTING_SYNC_UNITFREQUENCY</code> || Applied to the scheduled job (in seconds)
|}

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Why redefine the main bank account here?'''

The official Stripe module's setup page only renders that field when <code>STRIPE_AUTO_RECORD_PAYOUT</code> is enabled — and its own save handler resets the value to 0 on every save while the field is not rendered. Yet that setting must stay disabled once this module handles payouts. The field is therefore re-exposed here, writing the core constant directly, so the value stays configurable and stable.

Both account selectors only write their constant when a real account was submitted: saving the page for some unrelated field never overwrites a correct value.
</div>

=== Configuration check ===

<code>StripeAccounting::checkConfig()</code> returns the list of missing constants. It is called both by the setup page (information banner) and by every sync entry point (the real guard that blocks all processing).

=== Pitfall with accounting account selectors ===

The four fields using <code>FormAccounting::select_account()</code> (fees, disputes, both VAT accounts) have a "nothing selected" option whose value is '''<code>-1</code>''' — a non-empty string, therefore truthy in PHP. A field left blank and saved literally stores <code>-1</code>.

<code>StripeAccounting::getAccountConst()</code> normalises that value to an empty string on read, everywhere these constants are read. No entry can therefore land on the non-existent account <code>-1</code>.

== 8. User interface ==

=== Dashboard ===

Stripe balance (live API call), number of unreconciled transactions, total fees for the month, pending payouts, and a '''Sync now''' button — disabled, with a banner listing the missing constants, while the configuration is incomplete.

=== Transaction list ===

A paginated, sortable, filterable list built with the same mechanism as native Dolibarr lists: the icon at the top right of the table lets each user pick their columns, and the preference is stored per user.

{| class="wikitable" style="width:100%;"
! style="width:20%;" | Column !! Content
|-
| Amount, Fee, Total || The fee popup shows the VAT on the fee whenever a reverse-charge pair or French VAT was posted
|-
| Type, Description || Popup with the Stripe ID, the event or source ID, and the full untruncated description
|-
| Third party || The customer resolved through the invoice, or through the source charge for its related fee, or the configured Stripe supplier for a subscription fee
|-
| Entry || A "Piece no. X" link to the accounting entry, and/or a link to the related bank movement — see the caveat below
|-
| Source, Status || The <code>error</code> badge opens a popup with the full error message: no need to query the database to understand a failure
|}

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''Reading the "Entry" column''' — on a <code>fee</code>, <code>subscription_fee</code> or <code>payout</code> row, the link points to the '''bank movement''', not to an accounting piece. The module's <code>piece_num</code> is never the 627/517 entry for the fee: it is only the reverse-charge VAT pair. The fee entry itself is generated later, by Dolibarr's native button, and is never reported back onto this row.
</div>

The page is '''purely informational''': no manual posting is offered there. The module posts automatically, and the actual transfer to accounting for fees and payouts happens through the native "Transfer to accounting" button.

=== <code>charge</code> and <code>fee</code> rows ===

Each payment produces '''two rows''' in the database:

* a <code>charge</code> row, always in status <code>ignored</code>, fee 0, never processed — present solely for idempotency;
* a <code>fee</code> row for the same payment, linked to the first one.

Both appear separately in the list, but the <code>fee</code> row also carries the link to the payment and the invoice, resolved through a join.

=== Test mode banner ===

While live mode is off, the dashboard, the setup page and the transaction list all display the same warning as the official Stripe module. It is impossible to forget you are working in test mode.

=== Menus ===

Everything sits under '''Banks and cash → Stripe account''' (the official module's menu), flat, as three entries at the same level:

# Stripe dashboard
# Stripe transactions
# CSV import ''(administrators only)''

A dashboard link is also added automatically on the bank account record configured as the Stripe account.

== 9. Scheduled job ==

There are two ways to run the sync, both idempotent and safe to re-run. In both cases the code executed is strictly the same: no behavioural difference between the two triggers.

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ Neither of them starts on its own.'''

Activating the module creates the <code>StripeAccountingSync</code> job, but '''disabled by default'''. And even once enabled, the Dolibarr scheduler is triggered by nothing until a system crontab calls it. Without both steps, the sync only happens when "Sync now" is clicked manually.
</div>

=== Step 1 — enable the job ===

Under '''Home → Setup → Modules → Scheduled jobs'''. Since <code>llx_cronjob</code> is a core table, this setting is made through the interface only, never by direct SQL from the module.

=== Step 2 — a system trigger ===

Pick either option.

'''Option A — Dolibarr scheduler''' ''(recommended when several Dolibarr scheduled jobs coexist)''. Runs every due job, not just this one. Requires step 1.

<syntaxhighlight lang="bash">
*/15 * * * * curl "https://your-dolibarr/public/cron/cron_run_jobs_by_url.php?securitykey=YOUR_KEY&userlogin=YOUR_LOGIN"
</syntaxhighlight>

The security key is generated on the scheduled jobs page, "Security of job execution by URL" button.

'''Option B — the module's CLI script.''' Standalone, refuses to run from a browser, and independent of whether the Dolibarr job is enabled.

<syntaxhighlight lang="bash">
*/15 * * * * php /path/to/htdocs/custom/stripeaccounting/cron/stripe_sync.php >> /var/log/stripeaccounting.log 2>&1
</syntaxhighlight>

== 10. Logging and permissions ==

=== Logging ===

Every API call, generated entry, warning or error is traced in <code>llx_stripeaccounting_log</code>, readable in the database or through the standard Dolibarr log file. Levels: <code>DEBUG</code> < <code>INFO</code> < <code>WARNING</code> < <code>ERROR</code>. The <code>context</code> column holds the structured detail as JSON (API payload, computed amounts…).

=== Permissions ===

{| class="wikitable"
! Right !! Controls
|-
| <code>read</code> || Access to the dashboard and the transaction list
|-
| <code>write</code> || Declared for configuration, but not checked in the code today
|-
| <code>reconcile</code> || Manual sync triggering
|}

In practice, <code>admin/setup.php</code> and <code>import.php</code> only check '''Dolibarr administrator''' status, not the <code>write</code> right: only administrators can configure the module or import a CSV, whatever is ticked in the module permissions.

== 11. Database schema ==

=== <code>llx_stripeaccounting_transaction</code> ===

One row per processed Stripe object — charge, fee, refund, dispute or payout — all in the same table, distinguished by the <code>type</code> column.

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Column !! style="width:16%;" | Type !! Role
|-
| <code>rowid</code> || int AI || Primary key
|-
| <code>entity</code> || int || Dolibarr multi-company
|-
| <code>stripe_object_id</code> || varchar(80) || Stripe identifier — '''idempotency anchor'''
|-
| <code>stripe_event_id</code> || varchar(80) || Event identifier, informational only
|-
| <code>type</code> || varchar(20) || <code>charge</code>, <code>fee</code>, <code>subscription_fee</code>, <code>refund</code>, <code>dispute</code>, <code>payout</code>, <code>other</code>
|-
| <code>stripe_source_id</code> || varchar(80) || Source Stripe object (e.g. the charge behind a refund)
|-
| <code>source_label</code> || varchar(80) || Free-text label entered at CSV import; empty for API rows
|-
| <code>description</code> || varchar(255) || Stripe label
|-
| <code>amount</code>, <code>fee</code>, <code>net</code> || decimal(24,8) || Amounts already converted from Stripe cents
|-
| <code>currency</code> || varchar(3) || ISO currency code
|-
| <code>date_created</code>, <code>date_available_on</code> || datetime || Stripe-side dates
|-
| <code>fk_facture</code>, <code>fk_paiement</code> || int || Resolved Dolibarr invoice and payment, if found
|-
| <code>fk_bank</code> || int || Generated <code>llx_bank</code> line ''(empty for a fee in <code>french</code> VAT mode)''
|-
| <code>piece_num</code> || varchar(20) || Generated accounting piece number, where there is one
|-
| <code>status</code> || varchar(16) || <code>pending</code>, <code>reconciled</code>, <code>error</code>, <code>ignored</code>
|-
| <code>error_message</code> || text || Detail on failure
|-
| <code>date_creation</code>, <code>date_processed</code> || datetime || Technical timestamps
|-
| <code>fk_user_creat</code> || int || User who triggered the processing
|}

'''Unique key''' on <code>(stripe_object_id, entity)</code> — this is what guarantees the same Stripe object can never be inserted twice, even with concurrent executions.

=== <code>llx_stripeaccounting_log</code> ===

{| class="wikitable"
! Column !! Role
|-
| <code>level</code> || <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>
|-
| <code>message</code> || Short message
|-
| <code>context</code> || Structured context as JSON
|-
| <code>fk_stripeaccounting_transaction</code> || Related transaction, where applicable
|-
| <code>datec</code> || Timestamp
|}

== 12. Troubleshooting ==

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Symptom !! Likely cause !! Action
|-
| The "Sync now" button is disabled || Minimum configuration incomplete || Fill in the fields listed in the setup page banner
|-
| A transaction stays in <code>error</code> || Entry rejected by Dolibarr (non-existent account, closed period), or refund not matched || Read <code>error_message</code> on the row, then the detail in the log table
|-
| The Stripe balance is not displayed || API key missing or invalid in the official Stripe module || Check <code>stripe/admin/stripe.php</code>
|-
| A refund is never reconciled || The original payment was not found through <code>ext_payment_id</code> || Check that the Stripe payment was recorded by the official module with that identifier
|-
| A <code>subscription_fee</code> stays in <code>error</code> || Stripe supplier third party not set, or has no supplier accounting code || Fill the field in setup, and complete the third party record
|-
| A CSV-imported refund stays in <code>error</code> || '''Normal and expected''' — that account is not linked to <code>ext_payment_id</code> || Handle the invoice and refund manually in accounting
|}

== 13. Pitfalls encountered ==

Development notes, kept so nobody falls into them again.

* '''<code>PaymentVarious::create()</code>''' only updates <code>fk_bank</code> in the database, never on the PHP object. A <code>fetch()</code> after <code>create()</code> is required to get the real value.
* '''<code>select_comptes()</code>''' prints its own HTML ''and'' returns the number of accounts. Call it as a bare statement: wrapping it in <code>print</code> would display that number right after the select tag.
* '''<code>master.inc.php</code>, not <code>main.inc.php</code>''' for the CLI script. The latter expects an HTTP session and, in pure CLI, exits silently — no output, no log, return code 0 — inside its redirect to the login page. This gives the misleading impression that the script "does nothing" rather than a real error.
* '''Core libraries''' — <code>master.inc.php</code> does not load everything <code>main.inc.php</code> loads for the web (e.g. <code>core/lib/date.lib.php</code>, required by <code>BookKeeping</code>). Include them explicitly if the CLI script evolves.
* '''The "nothing selected" option is <code>-1</code>''' in accounting account selectors — see the Configuration section.

== 14. Known limitations ==

* '''Zero-decimal currencies''' (JPY, KRW…) are not handled: amounts are divided by 100 assuming two decimals. Intended use: EUR.
* '''The 35-day window''' is not configurable. A sync interrupted for longer must be caught up manually.
* '''Refund matching''' — relies on <code>ext_payment_id</code> and <code>ext_payment_site</code> in <code>llx_paiement</code>, filled in by the standard Stripe payment flow. A payment recorded any other way cannot be matched automatically. Matching goes through the '''PaymentIntent id''', never the charge id: the core Stripe module never stores the latter ''(it stores either the raw PaymentIntent, or a composite value, depending on the payment path taken)''.
* '''CSV import assumes French notation''': an export with a decimal point would not be parsed correctly.
* '''The "Transfer" column of the Payments CSV''' is stored for information only: it is not used to check that the sum of payments matches the imported payout amount.
* '''CSV-imported refunds always land in <code>error</code>''' — intended behaviour, not a bug.
* '''<code>french</code> VAT mode''' — the Stripe account's bank balance does not reflect the fees, see section 5.

[[Category:Dolibarr]]
[[Category:Modules]]
[[Category:Accounting]]

Stripeaccounting

2026-08-02T12:36:13Z

Goldron :

{{DISPLAYTITLE:StripeAccounting — Documentation technique}}

[[Fichier:Us.png|link=Stripeaccounting/en]]

<div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;">
'''StripeAccounting''' est un module Dolibarr de '''rapprochement comptable Stripe'''.

Il lit l'API Stripe (ou un export CSV), repère les mouvements que le module Stripe officiel ne comptabilise pas — frais, remboursements, litiges, virements — et pose les écritures manquantes.

: '''Compatibilité''' — Dolibarr 17+, PHP 7.2 → 8.5
: '''Dépend de''' — modules Stripe, Banque, Comptabilité en partie double
: '''Voir aussi''' — [[README-fr|Installation et guide utilisateur]]
</div>

__TOC__

== 1. Principes de fonctionnement ==

Quatre règles gouvernent tout le module.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Principe !! Ce que ça veut dire
|-
| '''Complémentaire''' || Le module ne crée aucun paiement, aucune facture, aucun webhook. Il lit Stripe et complète la comptabilité, rien de plus.
|-
| '''Idempotent''' || Chaque objet Stripe n'est traité qu'une fois, quel que soit le nombre de relances de la synchronisation.
|-
| '''Jamais de devinette''' || Si une opération ne peut pas être rattachée avec certitude, rien n'est posté : la ligne passe en <code>error</code> pour revue manuelle.
|-
| '''Configuration bloquante''' || Tant que la configuration minimale est incomplète, aucune synchronisation ne démarre (ni bouton, ni cron, ni import).
|}

== 2. Prérequis ==

=== Modules Dolibarr requis ===

{| class="wikitable"
! Module !! Ce qu'il apporte
|-
| '''Stripe''' (<code>modStripe</code>) || Clé API, mode test/live, compte financier Stripe
|-
| '''Banque''' (<code>modBanque</code>) || Tables <code>llx_bank</code> et <code>llx_bank_account</code>
|-
| '''Comptabilité en partie double''' (<code>modAccounting</code>) || Table <code>llx_accounting_bookkeeping</code>
|}

=== Réglage Dolibarr indispensable ===

<code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code> doit être renseigné dans '''Comptabilité → Configuration → Comptes par défaut'''. Sans lui, le virement interne généré par les payouts ne peut pas être transféré en comptabilité (limite de Dolibarr, pas du module).

l’option s'appelle : '''Compte comptable par défaut pour les virements internes'''

=== Notes ===

* Le SDK PHP Stripe n'est pas dupliqué : le module réutilise la copie du cœur (<code>includes/stripe/stripe-php/</code>).
* Le code évite volontairement toute syntaxe PHP postérieure à 7.2 (pas de <code>match</code>, <code>?-></code>, enums, propriétés typées, <code>str_contains</code>…) pour couvrir toute la plage 7.2 → 8.5.

== 3. Arborescence ==

<pre>
custom/stripeaccounting/
├── core/modules/modStripeAccounting.class.php Descripteur (droits, menus, cron, constantes)
├── class/
│ ├── StripeApi.class.php Wrapper SDK Stripe (lecture seule)
│ ├── StripeRepository.class.php Accès SQL + idempotence
│ ├── StripeLogger.class.php Journalisation
│ ├── StripeAccounting.class.php Génération des écritures
│ ├── StripePayout.class.php Rapprochement des virements
│ ├── StripeSync.class.php Orchestrateur (point d'entrée du cron)
│ ├── StripeCsvImporter.class.php Import CSV
│ └── actions_stripeaccounting.class.php Hook 'bankcard'
├── admin/setup.php Configuration
├── import.php Import CSV
├── dashboard.php Tableau de bord
├── transaction_list.php Liste des transactions
├── cron/stripe_sync.php Point d'entrée CLI
├── lib/stripeaccounting.lib.php
├── sql/
├── langs/{fr_FR,en_US,es_ES,it_IT,de_DE}/
└── css/
</pre>

=== Sens des dépendances ===

: pages et hook → <code>StripeSync</code> → (<code>StripeApi</code>, <code>StripeRepository</code>, <code>StripeAccounting</code>, <code>StripePayout</code>) → <code>StripeLogger</code>

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Classe !! Rôle
|-
| <code>StripeApi</code> || Interroge le SDK Stripe (balance transactions, charges, remboursements, litiges, payouts) avec pagination automatique. Aucun accès base, aucune écriture.
|-
| <code>StripeRepository</code> || Tout le SQL des deux tables du module. <code>upsertTransaction()</code> est le point d'idempotence.
|-
| <code>StripeLogger</code> || Écrit dans <code>llx_stripeaccounting_log</code> et en miroir dans <code>dol_syslog()</code>.
|-
| <code>StripeAccounting</code> || Construit les écritures (remboursement, litige, TVA autoliquidation) ou les mouvements bancaires (frais). Expose <code>checkConfig()</code>.
|-
| <code>StripePayout</code> || Crée le virement bancaire interne entre le compte Stripe et la banque réelle.
|-
| <code>StripeSync</code> || Orchestrateur : une méthode par flux, plus <code>reconcileStripeAccount()</code> qui enchaîne tout.
|-
| <code>StripeCsvImporter</code> || Alimente le même pipeline depuis un export CSV Stripe.
|-
| <code>ActionsStripeAccounting</code> || Hook <code>bankcard</code> : lien vers le tableau de bord sur la fiche du compte Stripe.
|}

== 4. Synchronisation et idempotence ==

Chaque flux (<code>syncFees</code>, <code>syncRefunds</code>, <code>syncDisputes</code>, <code>syncPayouts</code>, <code>syncTransactions</code>) suit toujours les mêmes étapes :

# '''Vérifier la configuration''' — si elle est incomplète : log <code>ERROR</code>, arrêt immédiat, aucun appel API.
# '''Lister les objets Stripe''' sur une fenêtre glissante de '''35 jours'''.
# '''Filtrer''' — un objet est ignoré seulement s'il existe déjà ''et'' que son statut est <code>reconciled</code> ou <code>ignored</code>. Une ligne en <code>pending</code> ou <code>error</code> est '''retentée''' à ce run.
# '''Enregistrer''' en statut <code>pending</code>, puis générer l'écriture ou le mouvement bancaire.
# '''Conclure''' — succès : statut <code>reconciled</code>. Échec : statut <code>error</code> avec le message, et '''le lot continue''' sur l'objet suivant.

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Reprise automatique''' — une ligne en <code>error</code> redevient éligible au run suivant. Une fois la cause corrigée (par exemple un exercice comptable créé tardivement), aucune intervention manuelle n'est nécessaire.
</div>

=== Pourquoi les doublons sont impossibles ===

* '''Clé unique en base''' sur <code>(stripe_object_id, entity)</code> — protège même contre deux exécutions concurrentes du cron.
* '''Test explicite avant traitement''' — évite jusqu'à la tentative d'écriture pour un objet déjà finalisé.

=== Cas particuliers : <code>adjustment</code> et <code>payment_failure_refund</code> ===

Ce sont des corrections de solde effectuées par Stripe lui-même (réversion après litige, remboursement d'un paiement finalement échoué). Le module les '''enregistre''' — sinon elles resteraient invisibles — mais ne les comptabilise '''jamais''' automatiquement : le signe du montant et la cause varient trop. Elles sont créées directement en <code>error</code>, avec un message explicite, à traiter manuellement.

== 5. Écritures comptables ==

Toutes les lignes d'un même évènement partagent le triplet <code>doc_type='stripeaccounting'</code>, <code>fk_doc</code>, <code>doc_ref</code> : Dolibarr les regroupe automatiquement sous un même numéro de pièce, sans numérotation propre au module.

=== Vue d'ensemble ===

{| class="wikitable" style="width:100%;"
! Évènement !! Ce que fait le module !! Résultat comptable
|-
| Frais Stripe ''(TVA <code>none</code> ou <code>autoliquidation</code>)'' || Mouvement bancaire <code>PaymentVarious</code> || Écriture 627xxx / 517xxx générée plus tard par Dolibarr
|-
| Frais Stripe ''(mode <code>autoliquidation</code>)'' || En plus : paire TVA postée immédiatement || Débit TVA déductible, crédit TVA autoliquidation ''(impact net nul)''
|-
| Frais Stripe ''(mode <code>french</code>)'' || Écriture directe complète || Débit compte de frais HT + TVA déductible, crédit compte Stripe TTC
|-
| Frais d'abonnement / service ''(Radar, Billing, Connect…)'' || Mouvement bancaire <code>PaymentVarious</code> || Écriture générée plus tard par Dolibarr, sur le compte fournisseur Stripe
|-
| Virement (payout) || Virement bancaire interne entre les 2 comptes || Écriture générée plus tard par Dolibarr
|-
| Remboursement ''(facture retrouvée)'' || Écriture directe || Débit compte client 411xxx, crédit compte Stripe 517xxx
|-
| Remboursement ''(facture introuvable)'' || Rien || Statut <code>error</code>, à traiter manuellement
|-
| Litige / chargeback || Écriture directe || Débit perte sur litiges 658xxx, crédit compte Stripe 517xxx ''(+ compte de frais si frais associés)''
|}

=== Pourquoi frais et virements ne génèrent pas d'écriture directe ===

Le problème historique : quand une facture Stripe est transférée en comptabilité par le workflow standard de Dolibarr, le paiement est comptabilisé pour son montant '''brut''' — les frais sont ignorés à cette étape.

Si le module postait ''en plus'' sa propre écriture ''et'' sa propre ligne bancaire, cette ligne resterait invisible pour <code>bankjournal.php</code> — qui ne reconnaît que les lignes rattachées à <code>doc_type='bank'</code>. Un administrateur transférant « normalement » le compte bancaire en comptabilité créait alors une '''seconde''' écriture pour le même mouvement.

'''La solution retenue :''' pour les frais, les frais d'abonnement et les virements, le module ne crée plus que le '''mouvement bancaire réel''', avec les mécanismes natifs de Dolibarr. C'est ensuite le bouton natif ''« Transférer en comptabilité »'' qui produit l'écriture, comme pour n'importe quel autre mouvement bancaire. Le module ne touche donc plus du tout <code>llx_accounting_bookkeeping</code> dans ces trois cas.

{| class="wikitable" style="width:100%;"
! style="width:22%;" | Cas !! Mécanisme natif utilisé
|-
| Frais et frais d'abonnement || <code>PaymentVarious</code> (mouvement bancaire avec compte de contrepartie, sans tiers ni facture), avec son propre <code>accountancy_code</code> que <code>bankjournal.php</code> lit directement.
|-
| Virements (payouts) || Virement interne Dolibarr : <code>Account::addline()</code> des deux côtés, plus <code>add_url_line(…, 'banktransfert')</code>. La contrepartie est imputée sur <code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code>.
|}

Dans les deux cas, le statut passe à <code>reconciled</code> — le module a fini son travail — mais '''<code>piece_num</code> reste vide''' : l'écriture n'existe pas encore, seul <code>fk_bank</code> est renseigné. Après transfert manuel, on la retrouve avec <code>doc_type='bank'</code> et <code>fk_doc</code> égal au <code>fk_bank</code> de la ligne.

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''À savoir''' — l'écriture des virements ne s'équilibre à zéro sur le compte de transfert que lorsque '''les deux''' comptes bancaires (Stripe ''et'' la banque réelle) ont été transférés en comptabilité, pas seulement un des deux.
</div>

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ <code>STRIPE_AUTO_RECORD_PAYOUT</code> doit rester désactivé'''

Dès lors que ce module gère les virements, décochez « Activer l'enregistrement automatique des paiements Stripe » dans <code>stripe/admin/stripe.php</code> — malgré son libellé, cette case ne concerne que les virements.

Sinon, le webhook du module officiel et ce module créeraient chacun leur propre mouvement bancaire pour le même virement, sans le savoir l'un de l'autre.

Le webhook cœur ne conserve d'ailleurs '''aucune''' trace de l'id du virement traité : en cas de double livraison Stripe (garantie « au moins une fois »), rien ne l'empêche de doublonner tout seul. Ce module, lui, a une vraie idempotence et rattrape automatiquement tout virement manqué sur 35 jours.
</div>

=== Page « Transferts Stripe » masquée ===

À l'activation, <code>modStripeAccounting::init()</code> désactive l'entrée de menu <code>stripe/payout.php</code> : cette page interroge l'API en direct sans rien enregistrer, et sa coexistence avec ce module ne créerait qu'une confusion sur ce qui fait foi pour les virements. <code>remove()</code> restaure la condition d'origine. '''C'est la seule table du cœur que ce module modifie''' — délibéré, et documenté ici pour cette raison.

=== Frais par transaction ou frais d'abonnement ? ===

Stripe facture deux choses distinctes sous le mot « frais » :

{| class="wikitable" style="width:100%;"
! !! Frais par transaction !! Frais d'abonnement / service
|-
! Exemple
| Commission sur chaque encaissement || Radar, Billing, Connect
|-
! Où le trouver
| Champ <code>.fee</code> d'une balance transaction de type <code>charge</code> || Balance transaction dédiée, de type <code>stripe_fee</code> ou <code>application_fee</code> ''(le <code>.fee</code> y vaut toujours 0, le montant est dans <code>.amount</code>)''
|-
! Compte utilisé
| Compte de frais configuré (627xxx) || Code comptable fournisseur du tiers Stripe configuré
|-
! Type en base
| <code>fee</code> || <code>subscription_fee</code>
|}

=== Limite du mode TVA <code>french</code> ===

Ce mode doit scinder le montant TTC en HT + TVA, un découpage que <code>PaymentVarious</code> ne sait pas exprimer. Il reste donc sur l'ancien comportement : écriture directe complète, aucun mouvement bancaire créé. Pas de risque de doublon (puisque aucune ligne bancaire n'est produite), mais le solde <code>llx_bank</code> du compte Stripe ne reflétera jamais les frais tant que ce mode est actif.

== 6. Import CSV ==

L'import couvre le cas d'un compte Stripe '''différent''' de celui configuré dans le module officiel — par exemple une autre boutique PrestaShop avec son propre compte marchand. L'API n'y a pas accès : le contenu est exporté en CSV depuis le dashboard Stripe, puis importé.

=== Hypothèse de départ ===

Les factures et paiements de cette boutique sont '''déjà''' comptabilisés dans Dolibarr par un autre processus, et l'encaissement (débit 517, crédit 411) est déjà posé. Seuls manquent les '''frais''', les '''remboursements''' et les '''virements''' — c'est exactement ce que l'import traite.

=== Interface : un seul champ ===

<code>import.php</code> n'expose plus qu'un champ d'upload, '''Historique général''', câblé sur <code>importGeneralHistory()</code>. Ce fichier couvre à lui seul tous les types de mouvements.

Les méthodes <code>importPayments()</code> et <code>importPayouts()</code> restent implémentées et fonctionnelles, mais ne sont plus atteignables depuis l'interface ; elles sont documentées ci-dessous pour mémoire.

Comme le bouton « Synchroniser maintenant », l'import est bloqué — bandeau d'alerte, bouton désactivé, garde-fou côté serveur — tant que la configuration est incomplète.

=== Les trois méthodes ===

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Méthode !! Export Stripe lu !! Traitement
|-
| <code>importGeneralHistory()</code><br />''(seule exposée)'' || Balance history || Aiguillage par colonne <code>Type</code>, voir tableau ci-dessous
|-
| <code>importPayments()</code> || Payments || Frais → écriture de frais. Montant remboursé → ligne <code>refund</code> toujours en <code>error</code>.
|-
| <code>importPayouts()</code> || Payouts || Exactement le même traitement qu'un payout venu de l'API
|}

Aiguillage de l'historique général, par colonne <code>Type</code> :

{| class="wikitable" style="width:100%;"
! style="width:30%;" | Type Stripe !! Traitement
|-
| <code>payout</code> || Virement bancaire interne, comme via l'API
|-
| <code>charge</code> / <code>payment</code> avec frais || Mouvement de frais
|-
| <code>stripe_fee</code> / <code>application_fee</code> || Frais d'abonnement, sur le compte fournisseur Stripe
|-
| <code>refund</code> || Enregistré, '''toujours''' en <code>error</code>
|-
| <code>payout_minimum_balance_hold</code> / <code>…_release</code> || '''Ignorés''' — réserve glissante Stripe, impact net nul, rien à comptabiliser
|-
| tout autre type || Enregistré en <code>type='other'</code>, statut <code>error</code>, type brut conservé dans la description. Aucune écriture devinée.
|}

Les colonnes sont reconnues '''par leur nom''' : l'ordre importe peu, et les colonnes en plus non utilisées sont ignorées.

=== Idempotence de l'import ===

La clé unique protège contre tout double import : réimporter le même CSV, ou un CSV qui chevauche un import précédent, ne crée aucun doublon.

Point important : dans l'historique général, les lignes <code>payout</code> et <code>charge</code>/<code>payment</code> sont indexées par leur colonne '''<code>Source</code>''' (<code>po_…</code>, <code>ch_…</code>), pas par l'<code>id</code> de la ligne (<code>txn_…</code>) — soit exactement la même clé que les imports dédiés. Importer l'historique général '''en plus''' des exports spécifiques ne poste donc jamais deux fois la même écriture, quel que soit l'ordre.

Les identifiants Stripe étant uniques à l'échelle de la plateforme, mélanger dans la même table des lignes venant du compte API et de plusieurs comptes importés en CSV ne présente aucun risque de collision.

=== Détails pratiques ===

* '''Libellé source''' — un champ libre saisi à l'import (ex. « Boutique DRM ») est stocké sur chaque ligne créée et sert de colonne et de filtre dans la liste, pour distinguer plusieurs boutiques côte à côte.
* '''Format des montants''' — les CSV Stripe utilisent la virgule décimale française, convertie via <code>price2num()</code>. Les dates marquées <code>(UTC)</code> sont interprétées comme telles.

== 7. Configuration ==

La clé API et le mode test/live ne sont '''pas''' ressaisis ici : ils sont lus en lecture seule depuis le module Stripe officiel.

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Champ !! Constante !! Usage
|-
| Compte financier Stripe || <code>STRIPE_BANK_ACCOUNT_FOR_PAYMENTS</code> ''(constante du module officiel)'' || Sélecteur de compte bancaire. Aucune copie locale, donc aucun risque de divergence.
|-
| Compte bancaire principal || <code>STRIPE_BANK_ACCOUNT_FOR_BANKTRANSFERS</code> ''(constante du module officiel)'' || Même sélecteur. Voir l'encadré ci-dessous.
|-
| Compte de frais || <code>STRIPEACCOUNTING_COMPTE_FRAIS</code> || Numéro de compte, ex. 627xxx
|-
| Compte de litiges || <code>STRIPEACCOUNTING_COMPTE_LITIGES</code> || Numéro de compte, ex. 658xxx. '''Requis''' — utilisé dès qu'un litige survient, quel que soit le mode TVA.
|-
| Tiers fournisseur Stripe || <code>STRIPEACCOUNTING_FOURNISSEUR_STRIPE_ID</code> || Tiers marqué fournisseur ; c'est son code comptable fournisseur qui est utilisé. Optionnel, sauf s'il existe des frais d'abonnement.
|-
| Mode TVA || <code>STRIPEACCOUNTING_VAT_MODE</code> || <code>none</code>, <code>french</code> ou <code>autoliquidation</code>
|-
| Compte TVA déductible (intracommunautaire) || <code>STRIPEACCOUNTING_COMPTE_TVA_DEDUCTIBLE</code> || Requis si mode TVA ≠ <code>none</code>. Stripe facturant toujours depuis une entité UE non française, la TVA déductible est intracommunautaire dans tous les cas.
|-
| Compte de TVA due (intracommunautaire) || <code>STRIPEACCOUNTING_COMPTE_TVA_AUTOLIQUIDATION</code> || Requis en mode <code>autoliquidation</code> uniquement — jamais utilisé en mode <code>french</code>.
|-
| Taux de TVA || <code>STRIPEACCOUNTING_VAT_RATE</code> || Pourcentage, 20 par défaut
|-
| Fréquence de synchronisation || <code>STRIPEACCOUNTING_SYNC_UNITFREQUENCY</code> || Répercutée sur la tâche planifiée (en secondes)
|}

<div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;">
'''Pourquoi redéfinir le compte bancaire principal ici ?'''

La page de configuration du module Stripe officiel n'affiche ce champ que si <code>STRIPE_AUTO_RECORD_PAYOUT</code> est activé — et son handler de sauvegarde remet la valeur à 0 à chaque enregistrement tant que le champ n'est pas rendu. Or ce réglage doit justement rester désactivé quand ce module gère les virements. Le champ est donc réexposé ici, en écrivant directement la constante du cœur, pour que la valeur reste configurable et stable.

Les deux sélecteurs de compte n'écrivent leur constante que si un compte réel a été soumis : enregistrer la page pour un tout autre champ n'écrase jamais une valeur correcte.
</div>

=== Vérification de la configuration ===

<code>StripeAccounting::checkConfig()</code> renvoie la liste des constantes manquantes. Elle est appelée à la fois par la page de configuration (bandeau d'information) et par chaque point d'entrée de synchronisation (garde-fou réel qui bloque tout traitement).

=== Piège des sélecteurs de compte comptable ===

Les quatre champs utilisant <code>FormAccounting::select_account()</code> (frais, litiges, les deux comptes TVA) ont une option « rien sélectionné » dont la valeur est '''<code>-1</code>''' — une chaîne non vide, donc vraie en PHP. Un champ laissé vide et enregistré stocke littéralement <code>-1</code>.

<code>StripeAccounting::getAccountConst()</code> normalise cette valeur en chaîne vide à la lecture, partout où ces constantes sont lues. Aucune écriture ne peut donc atterrir sur le compte inexistant <code>-1</code>.

== 8. Interface ==

=== Tableau de bord ===

Solde Stripe (appel API en direct), nombre de transactions non rapprochées, total des frais du mois, payouts en attente, et bouton '''Synchroniser maintenant''' — désactivé, avec bandeau listant les constantes manquantes, tant que la configuration est incomplète.

=== Liste des transactions ===

Liste paginée, triable et filtrable, construite avec le même mécanisme que les listes natives Dolibarr : l'icône en haut à droite du tableau permet à chaque utilisateur de choisir ses colonnes, et la préférence est mémorisée par utilisateur.

{| class="wikitable" style="width:100%;"
! style="width:20%;" | Colonne !! Contenu
|-
| Montant, Frais, Total || Le popup sur les frais indique la TVA sur frais quand une paire d'autoliquidation ou une TVA française a été postée
|-
| Type, Description || Popup avec l'ID Stripe, l'ID d'évènement ou de source, et la description complète non tronquée
|-
| Tiers || Le client résolu via la facture, ou via la charge source pour son frais associé, ou le tiers fournisseur Stripe pour un frais d'abonnement
|-
| Écriture || Lien « Pièce n°X » vers l'écriture, et/ou lien vers le mouvement bancaire associé — voir la nuance ci-dessous
|-
| Source, Statut || Le badge <code>error</code> ouvre un popup avec le message d'erreur complet : plus besoin d'aller en base pour comprendre un échec
|}

<div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;">
'''Lire la colonne « Écriture »''' — sur une ligne <code>fee</code>, <code>subscription_fee</code> ou <code>payout</code>, le lien pointe vers le '''mouvement bancaire''', pas vers une pièce comptable. Le <code>piece_num</code> du module, lui, n'est jamais l'écriture 627/517 du frais : c'est uniquement la paire TVA d'autoliquidation. L'écriture du frais est générée plus tard, par le bouton natif de Dolibarr, et n'est jamais reportée sur cette ligne.
</div>

La page est '''purement consultative''' : aucune comptabilisation manuelle n'y est proposée. Le module comptabilise automatiquement, et le transfert en comptabilité des frais et virements se fait depuis le bouton natif « Transférer en comptabilité ».

=== Lignes <code>charge</code> et <code>fee</code> ===

Chaque paiement produit '''deux lignes''' en base :

* une ligne <code>charge</code>, toujours en statut <code>ignored</code>, frais à 0, jamais traitée — présente uniquement pour l'idempotence ;
* une ligne <code>fee</code> pour le même paiement, liée à la première.

Les deux apparaissent séparément dans la liste, mais la ligne <code>fee</code> porte elle aussi le lien vers le paiement et la facture, résolu par jointure.

=== Bandeau mode test ===

Tant que le mode live n'est pas activé, le tableau de bord, la page de configuration et la liste des transactions affichent tous les trois le même avertissement que le module Stripe officiel. Impossible d'oublier qu'on travaille en mode test.

=== Menus ===

Tout est regroupé sous '''Banques et caisses → Compte Stripe''' (menu du module officiel), à plat, en trois entrées de même niveau :

# Tableau de bord Stripe
# Transactions Stripe
# Import CSV ''(réservé aux administrateurs)''

Un lien vers le tableau de bord est aussi ajouté automatiquement sur la fiche du compte bancaire configuré comme compte Stripe.

== 9. Tâche planifiée ==

Deux façons d'exécuter la synchronisation, toutes deux idempotentes et sans risque à relancer. Dans les deux cas le code exécuté est strictement le même : aucune divergence de comportement.

<div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;">
'''⚠ Aucune des deux ne démarre toute seule.'''

L'activation du module crée la tâche <code>StripeAccountingSync</code>, mais '''désactivée par défaut'''. Et même activée, l'ordonnanceur Dolibarr n'est déclenché par rien tant qu'aucune crontab système ne l'appelle. Sans ces deux étapes, la synchro n'a lieu qu'au clic manuel sur « Synchroniser maintenant ».
</div>

=== Étape 1 — activer la tâche ===

Dans '''Accueil → Configuration → Modules → Tâches planifiées'''. <code>llx_cronjob</code> étant une table du cœur, ce réglage se fait uniquement par l'interface, jamais en SQL direct depuis le module.

=== Étape 2 — un déclencheur système ===

Au choix, l'une des deux options.

'''Option A — ordonnanceur Dolibarr''' ''(recommandé si plusieurs tâches planifiées coexistent)''. Lance toutes les tâches dues, pas seulement celle-ci. Nécessite l'étape 1.

<syntaxhighlight lang="bash">
*/15 * * * * curl "https://votre-dolibarr/public/cron/cron_run_jobs_by_url.php?securitykey=VOTRE_CLE&userlogin=VOTRE_LOGIN"
</syntaxhighlight>

La clé de sécurité se génère sur la page des tâches planifiées, bouton « Sécurité de l'exécution des tâches par URL ».

'''Option B — script CLI du module.''' Autonome, refuse l'exécution depuis un navigateur, et indépendant de l'état activé ou non de la tâche Dolibarr.

<syntaxhighlight lang="bash">
*/15 * * * * php /chemin/vers/htdocs/custom/stripeaccounting/cron/stripe_sync.php >> /var/log/stripeaccounting.log 2>&1
</syntaxhighlight>

== 10. Journalisation et permissions ==

=== Journalisation ===

Chaque appel API, écriture générée, avertissement ou erreur est tracé dans <code>llx_stripeaccounting_log</code>, consultable en base ou via le fichier de log standard Dolibarr. Niveaux : <code>DEBUG</code> < <code>INFO</code> < <code>WARNING</code> < <code>ERROR</code>. La colonne <code>context</code> contient le détail structuré en JSON (payload API, montants calculés…).

=== Permissions ===

{| class="wikitable"
! Droit !! Contrôle
|-
| <code>read</code> || Consultation du tableau de bord et de la liste
|-
| <code>write</code> || Déclarée pour la configuration, mais non vérifiée dans le code aujourd'hui
|-
| <code>reconcile</code> || Déclenchement manuel de la synchronisation
|}

En pratique, <code>admin/setup.php</code> et <code>import.php</code> ne contrôlent que le statut '''administrateur Dolibarr''', pas le droit <code>write</code> : seuls les administrateurs peuvent configurer le module ou importer un CSV, quoi qu'il soit coché dans les permissions.

== 11. Base de données ==

=== <code>llx_stripeaccounting_transaction</code> ===

Une ligne par objet Stripe traité — charge, frais, remboursement, litige ou virement — tous dans la même table, distingués par la colonne <code>type</code>.

{| class="wikitable" style="width:100%;"
! style="width:24%;" | Colonne !! style="width:16%;" | Type !! Rôle
|-
| <code>rowid</code> || int AI || Clé primaire
|-
| <code>entity</code> || int || Multi-société Dolibarr
|-
| <code>stripe_object_id</code> || varchar(80) || Identifiant Stripe — '''ancre d'idempotence'''
|-
| <code>stripe_event_id</code> || varchar(80) || Identifiant d'évènement, informatif seulement
|-
| <code>type</code> || varchar(20) || <code>charge</code>, <code>fee</code>, <code>subscription_fee</code>, <code>refund</code>, <code>dispute</code>, <code>payout</code>, <code>other</code>
|-
| <code>stripe_source_id</code> || varchar(80) || Objet Stripe source (ex. la charge liée à un remboursement)
|-
| <code>source_label</code> || varchar(80) || Libellé libre saisi à l'import CSV ; vide pour les lignes venues de l'API
|-
| <code>description</code> || varchar(255) || Libellé Stripe
|-
| <code>amount</code>, <code>fee</code>, <code>net</code> || decimal(24,8) || Montants déjà convertis depuis les centimes Stripe
|-
| <code>currency</code> || varchar(3) || Code devise ISO
|-
| <code>date_created</code>, <code>date_available_on</code> || datetime || Dates côté Stripe
|-
| <code>fk_facture</code>, <code>fk_paiement</code> || int || Facture et paiement Dolibarr résolus, si trouvés
|-
| <code>fk_bank</code> || int || Ligne <code>llx_bank</code> générée ''(vide pour un frais en mode TVA <code>french</code>)''
|-
| <code>piece_num</code> || varchar(20) || Numéro de pièce comptable généré, quand il y en a un
|-
| <code>status</code> || varchar(16) || <code>pending</code>, <code>reconciled</code>, <code>error</code>, <code>ignored</code>
|-
| <code>error_message</code> || text || Détail en cas d'erreur
|-
| <code>date_creation</code>, <code>date_processed</code> || datetime || Horodatage technique
|-
| <code>fk_user_creat</code> || int || Utilisateur ayant déclenché le traitement
|}

'''Clé unique''' sur <code>(stripe_object_id, entity)</code> — c'est elle qui garantit qu'un même objet Stripe ne peut jamais être inséré deux fois, même en cas d'exécutions concurrentes.

=== <code>llx_stripeaccounting_log</code> ===

{| class="wikitable"
! Colonne !! Rôle
|-
| <code>level</code> || <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>
|-
| <code>message</code> || Message court
|-
| <code>context</code> || Contexte structuré en JSON
|-
| <code>fk_stripeaccounting_transaction</code> || Transaction liée, si applicable
|-
| <code>datec</code> || Horodatage
|}

== 12. Dépannage ==

{| class="wikitable" style="width:100%;"
! style="width:26%;" | Symptôme !! Cause probable !! Action
|-
| Le bouton « Synchroniser maintenant » est désactivé || Configuration minimale incomplète || Compléter les champs listés dans le bandeau d'alerte de la page de configuration
|-
| Une transaction reste en <code>error</code> || Écriture refusée par Dolibarr (compte inexistant, période clôturée), ou remboursement non rattaché || Lire <code>error_message</code> sur la ligne, puis le détail dans la table de logs
|-
| Le solde Stripe ne s'affiche pas || Clé API manquante ou invalide dans le module Stripe officiel || Vérifier <code>stripe/admin/stripe.php</code>
|-
| Un remboursement n'est jamais rapproché || Le paiement d'origine n'a pas été retrouvé via <code>ext_payment_id</code> || Vérifier que le paiement Stripe a bien été enregistré par le module officiel avec cet identifiant
|-
| Un <code>subscription_fee</code> reste en <code>error</code> || Tiers fournisseur Stripe non renseigné, ou sans code comptable fournisseur || Renseigner le champ en configuration, et compléter la fiche du tiers
|-
| Un remboursement importé en CSV reste en <code>error</code> || '''Normal et attendu''' — ce compte n'est pas relié à <code>ext_payment_id</code> || Traiter la facture et le remboursement manuellement en comptabilité
|}

== 13. Pièges rencontrés ==

Notes de développement, conservées pour éviter de retomber dedans.

* '''<code>PaymentVarious::create()</code>''' ne met à jour <code>fk_bank</code> qu'en base, jamais sur l'objet PHP. Un <code>fetch()</code> après <code>create()</code> est indispensable pour récupérer la vraie valeur.
* '''<code>select_comptes()</code>''' affiche son propre HTML ''et'' retourne le nombre de comptes. L'appeler en instruction nue : l'envelopper dans <code>print</code> réafficherait ce nombre juste après la balise select.
* '''<code>master.inc.php</code>, pas <code>main.inc.php</code>''' pour le script CLI. Le second attend une session HTTP et, en pur CLI, se termine silencieusement — aucune sortie, aucun log, code retour 0 — dans sa redirection vers la page de connexion. L'impression trompeuse que le script « ne fait rien » plutôt qu'une vraie erreur.
* '''Bibliothèques du cœur''' — <code>master.inc.php</code> ne charge pas tout ce que <code>main.inc.php</code> charge pour le web (par exemple <code>core/lib/date.lib.php</code>, requis par <code>BookKeeping</code>). À inclure explicitement si le script CLI évolue.
* '''Option « rien sélectionné » à <code>-1</code>''' dans les sélecteurs de compte comptable — voir la section Configuration.

== 14. Limites connues ==

* '''Devises « zéro décimale »''' (JPY, KRW…) non gérées : les montants sont divisés par 100 en supposant deux décimales. Usage prévu : EUR.
* '''Fenêtre de 35 jours''' non configurable. Une synchronisation interrompue plus longtemps devra être rattrapée manuellement.
* '''Rattachement des remboursements''' — dépend de <code>ext_payment_id</code> et <code>ext_payment_site</code> sur <code>llx_paiement</code>, renseignés par le flux de paiement Stripe standard. Un paiement enregistré autrement ne pourra pas être rattaché automatiquement. Le rattachement se fait via le '''PaymentIntent id''', jamais via l'id de charge : le module Stripe du cœur ne stocke jamais ce dernier ''(il y met soit le PaymentIntent brut, soit un composite, selon le chemin de paiement emprunté)''.
* '''Import CSV en notation française''' uniquement : un export à point décimal ne serait pas interprété correctement.
* '''Colonne « Transfer » du CSV Paiements''' stockée à titre informatif seulement : elle ne sert pas à vérifier que le total des paiements correspond au montant du virement importé.
* '''Remboursements importés en CSV toujours en <code>error</code>''' — comportement voulu, pas un bug.
* '''Mode TVA <code>french</code>''' — le solde bancaire du compte Stripe ne reflète pas les frais, voir section 5.

[[Catégorie:Dolibarr]]
[[Catégorie:Modules]]
[[Catégorie:Comptabilité]]

Fichier:Fr.png

2026-08-02T12:33:33Z

Goldron :

2026-08-02T08:56:04Z

Goldron : /* Modules Dolibarr */

2025-08-30T10:39:32Z

Goldron :

'''ADDINVENTORY''' est un module Dolibarr qui permet de '''modifier et corriger rapidement vos stocks''' à partir d’une liste de produits, de lots ou de déclinaisons.

Principales fonctionnalités :
* Correction en masse du stock à partir d’une liste (lots et déclinaisons inclus).
* Création en masse de lots.
* Gain de temps significatif lors des mouvements de stocks.
* Tableau de suivi permettant un aperçu global des références en un coup d’œil.

== Installation ==

Compatible avec Dolibarr 6 et versions supérieures.

# Depuis l’interface Dolibarr, allez dans '''Configuration > Modules/Applications'''.
# Cliquez sur l’onglet '''Déployer/Installer un module externe'''.

Une fois l’installation terminée, les pages '''Inventaire & correction''' et '''Stocks référents''' seront disponibles dans l’onglet '''Produits | Services'''.

== Configuration ==

[[Fichier:Conf addinventory2.png|880px]]

=== Activer les quantités décimales ===
Permet la gestion des stocks avec des valeurs décimales.

=== Correction par quantité Delta ===
Indiquez la quantité à ajouter ou à supprimer.
Vous pouvez saisir directement une valeur (positive ou négative) ou utiliser les flèches pour ajuster la quantité.

=== Correction par substitution ===
Renseignez directement la quantité totale de produit disponible en stock.

=== Choix du mode (Delta ou Substitution) ===
Autorise les utilisateurs à basculer entre les deux méthodes dans la page '''Inventaire & correction'''.

=== Modification du stock des produits parents avec variantes ===
Par défaut, Dolibarr interdit la saisie de stock sur les produits parents à variantes.
Cette option permet de forcer la correction dans certains cas spécifiques (ex. rattrapage d’erreurs).

=== Afficher les services ===
Inclut également les produits de type service dans les listes.

=== Activer la saisie du prix d’achat ===
Ajoute la possibilité de saisir le prix d’achat unitaire pour tous les produits nouvellement ajoutés.

=== Création de nouveaux lots ===
Pour les produits gérés en lots, cette option affiche directement les champs nécessaires :
*n° de lot
*entrepôt
*DLC
*DMD/DLUO
*prix d’achat
*stock

[[Fichier:Conf addinventory list.png|900px]]

== Fonctionnement de la correction du stock ==

[[Fichier:Doc_addinventory.png|880px]]

Pour modifier le stock d’un produit, indiquez soit la quantité totale disponible, soit un delta (en fonction du mode défini).

=== Mode quantité Delta ===
Saisissez une variation de stock (exemple : +10 ou -5).
Cela ne remplace pas la valeur finale, mais ajuste le stock existant.

=== Mode Substitution ===
Saisissez directement la quantité totale disponible en stock.

Pour valider les modifications, cliquez sur le bouton '''Enregistrer''' en bas de page.

'''Important :''' lors d’une recherche filtrée par entrepôt, seuls les produits ayant un stock existant apparaissent. Pour afficher tous les produits, effectuez la recherche sans préciser d’entrepôt.

[[Fichier:Addinventory_screen04.jpg|880px]]

Chaque correction enregistre automatiquement un mouvement de stock dans Dolibarr, avec le delta de quantité (positif ou négatif), quelle que soit la méthode choisie.

== Contact ==

Pour toute question sur ce module ou nos services :

[[Fichier:Siladel.png|link=https://www.siladel.fr|alt=Développeur web à Albi]]

* [https://www.siladel.fr/service/developpement-dolibarr Développement Dolibarr par SILADEL]
* [https://www.dolistore.com/product.php?id=1190&title=addinventory&l=fr Module ADDINVENTORY disponible sur Dolistore]

2025-08-30T10:09:49Z

Goldron : /* Contact */

2025-04-12T03:03:56Z

Goldron : /* Contact */

Module permettant de saisir une remise globale en pourcentage lors de la création de devis, commandes et factures.

ADDRemise inclut la gestion des permissions utilisateurs, la configuration des libellés ainsi que la prise en charge de la TVA.

== Installation ==

Déployez un module externe en utilisant l'assistant d'installation disponible dans Configuration > Modules & Applications.

Vous pouvez également décompressez le fichier dans le dossier "htdocs/custom" ou à la racine htdocs/

== Configuration ==

Une fois le module installé, vous devez l'activer dans l'application Dolibarr via la session "Modules/Applications".

[[Fichier:Conf.jpg]]

== Les paramètres de configurations ==

[[Fichier:addremise_setting1.7.jpg]]

=== Paramétrage d'activation ===
Choisissez d'activer ou non Addremise pour les devis, commandes, factures.

=== Libellés des remises globales par défaut ===
Permet d'ajouter une description à votre remise après le pourcentage.
par exemple par défaut 10% "de remise client".

=== Paramètres additionnels : ===
*'''Affiche la ligne remise globale dans la liste des produits :'''
**Activez cette option si vous voulez faire apparaitre la remise globale en même temps que la liste des produits

*'''Ne pas comptabiliser les produits offerts en tant que remise.'''
**Par défaut sur Dolibarr, les remises 100% appliquées sur les produits donc gratuit sont comptabilisées en tant que remise.
**Vous pouvez désactiver cette option pour ne pas comptabiliser les produits gratuit ou offert en tant que remise.

*'''Afficher les produits offerts sur la même ligne que les produits vendus.'''
**Il s’agit de regrouper les produits de même référence offert ou pas sur une ligne.

*'''Ne pas afficher le taux des remises dans les totaux.'''
**désactive le pourcentage de remise dans les totaux. "Total remise" ou "Total remise (5%)"

*'''Ne pas afficher la colonne TVA dans le PDF.'''
**Permet simplement de ne pas afiicher la colonne TVA dans le tableau des produits.
**N'activer cette option si vous avez plusieurs taux de TVA.

== Permissions et droits d’accès ==
Par défaut les permissions sont activées pour l'administrateur.
Pour gérer les permissions en rapport avec le module, allez dans le menu "Utilisateurs & Groupes", sélectionnez un utilisateur ou un groupe puis l'onglet "permissions utilisateur" ou "permissions groupe" dans le cas d'un groupe.

[[Fichier:permit.jpg]]

== Activer modèle facture PDF avec remise ==

[[Fichier:Screen pdf.jpg|800px]]

Pour activer le modèle crabe en PDF avec les remises dans les totaux, vous devez vous rendre dans la configuration du module '''Factures et avoirs''' qui se trouve dans la session Modules/Applications.

* La remise dans les totaux s'affiche également lorsque vous appliquez une remise standard (remise sur ligne de produit).
* Vous pouvez additionner les remises sur ligne produit et une remise globale.

== Utilisation ==
Après installation et activation des remises pour les factures.

Un bouton remise doit apparaître pendant la saisie de votre facture.
Vous décidez d'ajouter une remise, vous appuyez sur le bouton remise, une fenêtre s'affiche, dans la partie 1, vous saisissez votre pourcentage. Par exemple, le chiffre 10 pour 10%, dans la partie 2, vous saisissez votre texte, dans la partie 3, votre TVA.

Normalement, sauf cas exceptionnel, vous ne devez pas modifier la TVA de votre remise, la remise doit avoir le même taux de TVA que les produits.

'''Comportement de la remise lorsque vous ajoutez un produit après avoir intégré une remise globale'''
<pre style="color: red">
La remise globale appliquée sur un document se mettra à jour automatiquement après modification.
Une seule remise globale peut être appliquée par document.
</pre>

== Contact ==

Pour toutes questions sur les produits et services, veuillez nous contacter:

[[Fichier:Siladel.png|link=https://www.siladel.fr]]

[[link=https://www.siladel.fr/service/developpement-dolibarr|Développement de modules Dolibarr]]

[[link=https://www.dolistore.com/index.php?controller=search&orderby=position&orderway=desc&tag=&website=marketplace&search_query=siladel|Vente en ligne de nos modules]]

Eanprodoc

2025-04-12T03:03:39Z

Goldron : /* Contact */

EANPRODOC est un module Dolibarr permettant d'afficher les codes-barres de vos produits dans vos documents PDF.

* Affichez les codes-barres de vos produits dans vos documents PDF (clients et fournisseurs).
* Insérez automatiquement vos codes produits dans vos factures, commandes et fiches d'expédition.
* Compatible avec tous les modèles PDF.
* Prend en charge tous les codes 1D (EAN8, EAN13, EAN128, GS1, ISBN, UPC).

== Installation ==

Pour les version Dolibarr 6 et plus
*Depuis l'interface à la page Configuration > Modules/Applications Cliquez sur l'onglet Déployer/Installer un module externe.

Après avoir terminé l'installation, rendez-vous sur la page de configuration du module pour activer les options de votre choix.

== Configuration ==
[[fichier:Config-eanprodoc.png|880px]]

'''Affiche les codes-barres pour les factures.'''
Si un produit possède un code-barre, celui-ci sera affiché sur votre facture en PDF.

'''Affiche les codes-barres pour les commandes.'''
Si un produit possède un code-barre, celui-ci sera visible sur votre bon de commande en PDF.

'''Affiche les codes-barres pour les fiches d'expéditions.'''
Si un produit possède un code-barre, celui-ci sera visible sur vos fiches d'expéditions en PDF.

'''Affiche les codes-barres pour les factures fournisseurs. '''
Si un produit possède un code-barre, celui-ci sera affiché sur votre facture fournisseur en PDF.

'''Affiche les codes-barres pour les commandes fournisseurs '''
Si un produit possède un code-barre, celui-ci sera visible sur votre bon de commande fournisseur en PDF.

'''Exclure le template commençant par : '''
permet d'indiquer le nom d'un modèle PDF dans lequel les codes-barres ne seront pas affichés.

'''Afficher la description sous le code-barres'''
Affiche le numero du code sous le code barre.

[[fichier:Num_code_eanprodoc.png|800px]]

'''Afficher la description sous le code-barres.'''
permet un retour à la ligne dans la description au niveau du code-barre.

'''Largeur et Hauteur du code-barres, Largeur de la description'''
permet un positionnement précis du code-barres dans le document PDF.

== Contact ==

Pour toutes questions sur les produits et services, veuillez nous contacter:

[[Fichier:Siladel.png|link=https://www.siladel.fr]]

[[link=https://www.siladel.fr/service/developpement-dolibarr|Développement de modules Dolibarr]]

[[link=https://www.dolistore.com/index.php?controller=search&orderby=position&orderway=desc&tag=&website=marketplace&search_query=siladel|Vente en ligne de nos modules]]