=== Green Cart Carbon — Plantez un arbre (module PrestaShop) ===
Éditeur : SEEDVISION SAS
Compatibilité : PrestaShop 1.7.6 → 8.x
PHP requis : 7.4+
Version : 1.0.0
Licence : AFL-3.0
Site : https://greencartcheckout.com

Proposez à vos clients une contribution climat optionnelle de 1,25 € au
checkout PrestaShop — un arbre planté par contribution, attestation à l'appui.

== Description ==

Green Cart Carbon ajoute une ligne de contribution climat optionnelle (cochée
par défaut, décochable en un clic) au panier et au récapitulatif de commande de
votre boutique PrestaShop. Chaque contribution de 1,25 € finance la plantation
d'un arbre via un projet de reforestation vérifié. Le client reçoit une
attestation de plantation, et votre boutique dispose d'une page d'impact
publique.

**Wording légal.** Conformément au décret français n° 2022-539, ce module parle
exclusivement de « contribution » climatique. Il ne revendique jamais de
« compensation carbone » ni de « neutralité carbone », et n'affiche aucune
équivalence CO2 publique.

== Comment la contribution est ajoutée au panier ==

PrestaShop n'a pas d'API de frais (pas d'équivalent du `add_fee()` de
WooCommerce). La contribution est donc portée par un **produit virtuel dédié**,
« Contribution climat », créé à l'installation du module :

* prix réel (1,25 € par défaut, réglable) — aucun artifice de centimes ;
* `visibility = 'none'` : invisible en catalogue, en recherche et au sitemap ;
* quantité verrouillée à 1 ;
* ajouté automatiquement au panier dès le premier article (si le réglage
  « Case cochée par défaut » est actif), retirable d'un clic par le client.

Conséquence voulue : le total du panier reste un vrai total PrestaShop. Tous
les modules de paiement fonctionnent, la facture et les avoirs sont justes, les
exports comptables aussi, et le module n'écrase aucune classe du cœur.

Les alternatives ont été écartées : override de `Cart::getOrderTotal()`
(fragile et rédhibitoire à la validation Addons), frais de transport
supplémentaires (sémantiquement faux), règles panier (réductions uniquement).

== Installation ==

1. Modules → Ajouter un module → déposez `prestashop-module.zip`, puis
   « Installer ».
2. Créez votre compte et votre clé API sur https://greencartcheckout.com
   (la clé n'est affichée qu'une seule fois).
3. Dans la page de configuration du module, collez la clé et enregistrez.
4. Cliquez sur « Tester la connexion » pour vérifier.
5. C'est tout : la contribution apparaît au panier pour les boutiques en euros.

== Réglages ==

* **Clé API** — la clé `gcc_live_…` de votre tableau de bord. Laisser le champ
  vide conserve la clé en place (elle n'est jamais réaffichée en clair).
* **Contribution au checkout** — interrupteur général.
* **Case cochée par défaut** — contribution proposée cochée (opt-out) ou
  décochée (opt-in). Le client garde le dernier mot dans les deux cas.
* **Montant de la contribution** — appliqué au produit « Contribution climat ».
  1,25 € finance un arbre.
* **Tester la connexion** — appelle `GET /api/v1/ping` et mémorise
  l'identifiant de votre boutique.

== TVA ==

Le produit « Contribution climat » est créé sans règle de taxe (hors champ).
Si votre situation fiscale l'exige, assignez-lui une règle de taxe depuis
Catalogue → Produits → Contribution climat → Prix.

== Hooks utilisés ==

* `actionCartSave` — ajout automatique et nettoyage de la ligne de contribution.
* `actionFrontControllerSetMedia` — script de la case à cocher (panier, commande).
* `displayShoppingCartFooter` — case à cocher sur la page panier.
* `displayCheckoutSummaryTop` — case à cocher dans le récapitulatif de commande.
* `actionValidateOrder` — tampon de la contribution sur la commande naissante.
* `actionOrderStatusPostUpdate` — transmission dès que l'état devient payé.
* `actionPaymentConfirmation` — second filet de capture.
* `actionAdminControllerSetMedia` — reprise des envois en échec.

Certains thèmes tiers n'appellent pas `displayCheckoutSummaryTop`. Dans ce cas,
la case reste disponible sur la page panier ; pour l'afficher aussi au
checkout, ajoutez `{hook h='displayCheckoutSummaryTop'}` au template
`checkout/_partials/cart-summary.tpl` de votre thème.

== Service externe (divulgation obligatoire) ==

Ce module s'appuie sur le service SaaS externe **Green Cart Carbon**
(https://greencartcheckout.com), opéré par SEEDVISION SAS, pour orchestrer les
plantations, générer les attestations et la facturation mensuelle du marchand.

Endpoints appelés (uniquement sur action, jamais au chargement des pages) :

* `GET /api/v1/ping` — au clic sur « Tester la connexion » dans les réglages.
* `POST /api/v1/orders` — quand une commande payée contient une contribution.
  Données envoyées : identifiant et numéro de commande, devise, montant de la
  contribution, nombre d'arbres, plateforme (`prestashop`), e-mail et nom du
  client (pour l'envoi de son attestation de plantation).

Les appels sont authentifiés par votre clé API (`Authorization: Bearer`) et les
envois de commandes sont signés (HMAC-SHA256 du corps brut + horodatage, refusé
au-delà de 300 s d'écart).

Les plantations sont exécutées par **DigitalHumani**
(https://digitalhumani.com), plateforme RaaS (Reforestation-as-a-Service) qui
reverse les fonds à des organismes de reforestation. Le service Green Cart
Carbon transmet à DigitalHumani le nombre d'arbres et un identifiant de
boutique neutre — jamais les données personnelles de vos clients.

Conditions et politique de confidentialité : https://greencartcheckout.com

== Vie privée ==

* Le module n'envoie **aucune** donnée avant que le marchand ait collé et
  enregistré sa clé API (pas de « phone home »).
* Données personnelles transmises au service : e-mail et nom du client,
  uniquement pour les commandes payées comportant une contribution, et
  uniquement afin de générer et d'envoyer son attestation de plantation.
* Le choix du client est stocké en base, dans la table `gcc_cart_pref`
  (indexée par panier) : pas de cookie propre, pas de traçage.
* Journal d'envoi des commandes : table `gcc_order_send`
  (`contribution_amount`, `tree_count`, `sent_at`, `attempts`, `last_error`).
* Demandes d'effacement RGPD : contactez le support Green Cart Carbon pour
  l'effacement côté service.

== Désinstallation ==

* Hooks désenregistrés, configuration (`GCC_*`) supprimée, table
  `gcc_cart_pref` supprimée.
* Le produit « Contribution climat » est **désactivé mais conservé** : les
  commandes déjà passées y font référence, le supprimer casserait factures et
  avoirs. Une réinstallation le retrouve par sa référence `GCC-TREE` et le
  réactive.
* La table `gcc_order_send` est **conservée** : c'est le journal comptable des
  contributions transmises, et la garde anti-doublon en cas de réinstallation.

== Questions fréquentes ==

= Le client peut-il refuser la contribution ? =

Oui, d'un seul geste : décocher la case retire la ligne du panier ; il peut
aussi supprimer la ligne directement depuis le panier. Cocher la case la
remet. Le module ne réimpose jamais un choix déjà exprimé sur un panier.

= Et si ma boutique n'est pas en euros ? =

La contribution n'est pas proposée (V1). Le support multi-devise est prévu.

= Quand la plantation est-elle déclenchée ? =

Uniquement quand la commande passe à un état **payé**. Le hook
`actionValidateOrder` se contente d'enregistrer la contribution : il se
déclenche souvent avant le paiement (virement, chèque, PayPal en attente).

= Que se passe-t-il si l'envoi échoue ? =

Il est rejoué automatiquement, avec un délai croissant, au fil des pages
back-office (5 tentatives maximum). PrestaShop n'ayant pas de cron natif, la
file est drainée une commande à la fois pour ne jamais faire patienter le
marchand. Les tentatives sont tracées dans Paramètres avancés → Logs.

= Que se passe-t-il en cas de remboursement ? =

Les plantations sont exécutées rapidement après paiement et un arbre planté ne
peut pas être « déplanté ». Contactez le support pour les cas particuliers.

= Multiboutique ? =

Le module lit sa configuration dans le contexte de boutique courant. Le produit
« Contribution climat » est créé dans le contexte actif à l'installation ;
en multiboutique, vérifiez son association dans Catalogue → Produits.

== Journal des versions ==

= 1.0.0 =
* Version initiale : contribution climat au panier via produit virtuel dédié,
  case à cocher panier et checkout, connexion par clé API, capture des
  commandes payées (double accroche + file de reprise), i18n FR/EN.
