# Guide de configuration — Système de paiement WhatsApp

Ce guide couvre la création du compte Meta, la configuration du webhook,
les tests en local, et le passage en production.

## 1. Créer l'application Meta for Developers

1. Va sur https://developers.facebook.com/ et connecte-toi avec un compte
   Facebook (idéalement un compte professionnel dédié à ta boutique/société,
   pas un compte personnel).
2. "Mes apps" → "Créer une app" → type "Entreprise" → donne un nom (ex:
   "STOCK360 Paiement").
3. Dans le tableau de bord de l'app, ajoute le produit **WhatsApp**
   ("Configurer" sous WhatsApp).

## 2. Récupérer les identifiants (mode test)

Dans l'onglet **WhatsApp → Configuration de l'API** :

- **Un numéro de test** est fourni automatiquement par Meta (gratuit, mais
  limité à 5 numéros destinataires en mode test — suffisant pour développer).
- **Phone Number ID** : visible directement sur cette page → copie-le dans
  `backend/whatsapp_config.php`, `WHATSAPP_PHONE_NUMBER_ID`.
- **Jeton d'accès temporaire** (24h) : affiché sur la même page, pour tester
  rapidement. Pour la production, voir l'étape 6 (jeton permanent).

Dans **Paramètres de l'app → Basique** :
- **Clé secrète de l'application** (App Secret) → copie-la dans
  `WHATSAPP_APP_SECRET`.

Choisis toi-même une chaîne aléatoire longue pour `WHATSAPP_VERIFY_TOKEN`
(sert uniquement à la vérification du webhook, ex: génère-la avec
`openssl rand -hex 20` en ligne de commande, ou n'importe quel générateur
de mot de passe).

## 3. Configurer le webhook

Dans **WhatsApp → Configuration** → section **Webhook** :

1. **URL de rappel** : `https://ton-domaine.com/backend/v1/whatsapp_webhook.php`
   (remplace par ton vrai domaine — **doit être en HTTPS**, pas de
   `http://` ni d'IP locale).
2. **Jeton de vérification** : la même valeur que `WHATSAPP_VERIFY_TOKEN`
   dans ton fichier de config.
3. Clique sur "Vérifier et enregistrer" — Meta va appeler ton URL en GET ;
   si tout est bien configuré, la vérification réussit immédiatement.
4. Une fois vérifié, **abonne-toi au champ `messages`** (case à cocher) —
   c'est ce qui fait que Meta t'envoie les messages entrants.

## 4. Tester en local (avant d'avoir un vrai serveur en ligne)

Comme Meta a besoin d'une URL HTTPS publique, tu ne peux **pas** tester le
webhook directement avec WampServer en local. Deux options :

**Option A — ngrok (recommandé pour tester avant d'avoir l'hébergement)** :
1. Télécharge ngrok (https://ngrok.com/download), crée un compte gratuit.
2. Lance `ngrok http 80` dans un terminal (pendant que WampServer tourne).
3. ngrok te donne une URL du style `https://xxxx.ngrok-free.app` — utilise
   `https://xxxx.ngrok-free.app/backend/v1/whatsapp_webhook.php` comme URL
   de webhook dans Meta (étape 3 ci-dessus).
4. ⚠️ Cette URL change à chaque redémarrage de ngrok (sauf abonnement
   payant) — pratique pour tester, pas pour un usage durable.

**Option B — déployer directement sur ton vrai hébergement** et tester
depuis là, en suivant l'étape 5 ci-dessous en parallèle.

## 5. Tester la conversation

1. Depuis un téléphone, envoie un message WhatsApp au numéro de test fourni
   par Meta (il faut d'abord l'ajouter comme destinataire autorisé dans
   Meta for Developers → WhatsApp → Configuration de l'API → "Vers", ajoute
   ton numéro personnel).
2. Le bot doit répondre avec le message de bienvenue et demander
   l'identifiant.
3. Envoie l'email ou le téléphone d'un compte ADMIN existant dans ta base
   (pas un caissier — seuls les comptes admin peuvent recevoir un paiement,
   voir `handle_user_id_step` dans `whatsapp_webhook.php`).
4. Continue la conversation (numéro de paiement, montant).
5. Va dans l'app → connecte-toi en Super-Admin → icône 💰 "Demandes de
   paiement" → la demande doit apparaître en attente.
6. Clique sur "Valider" → vérifie que l'abonnement de la boutique a bien
   été prolongé (icône 📅 dans le tableau de bord Super-Admin, ou
   directement dans la boutique concernée → "Mon abonnement").
7. Le client doit recevoir la confirmation sur WhatsApp.

## 6. Passer en production

1. **Vérification de l'entreprise (Business Verification)** : Meta exige
   une vérification de ton entreprise pour sortir du mode test (limite de
   5 destinataires) et envoyer des messages à n'importe quel numéro.
   Meta Business Suite → Paramètres de l'entreprise → Vérification du
   centre de sécurité. Peut prendre plusieurs jours.
2. **Numéro de téléphone dédié** : ajoute ton propre numéro WhatsApp
   Business (pas celui de test fourni par Meta) dans Meta for Developers →
   WhatsApp → Configuration de l'API → "Ajouter un numéro de téléphone".
3. **Jeton d'accès permanent** : crée un "Utilisateur système" dans Meta
   Business Suite (Paramètres de l'entreprise → Utilisateurs → Utilisateurs
   système) avec la permission `whatsapp_business_messaging`, puis génère
   un jeton d'accès **sans expiration** pour cet utilisateur système.
   Remplace `WHATSAPP_ACCESS_TOKEN` par ce nouveau jeton (le jeton
   temporaire de test expire au bout de 24h).
4. **Hébergement définitif** : assure-toi que ton domaine a un certificat
   SSL valide (Let's Encrypt, gratuit, généralement déjà inclus chez la
   plupart des hébergeurs mutualisés) et met à jour l'URL du webhook dans
   Meta si elle change.
5. **Coûts** : WhatsApp facture par conversation initiée (variable selon
   le pays, souvent quelques centimes) au-delà d'un certain volume gratuit
   mensuel — vérifie la tarification actuelle sur
   https://developers.facebook.com/docs/whatsapp/pricing avant un usage à
   grande échelle.

## 7. Points de sécurité déjà en place (rien à faire de plus)

- Signature de chaque requête webhook vérifiée (HMAC-SHA256) — toute
  requête non signée par Meta est rejetée.
- `whatsapp_config.php` séparé de `db.php`, jamais écrasé lors des mises à
  jour, ajouté à `.gitignore`.
- Double validation impossible (verrouillage de ligne en transaction
  MySQL).
- Aucun secret WhatsApp dans l'app Flutter — tout reste côté serveur.
- Aucun identifiant/mot de passe jamais transmis via WhatsApp.
