# Intégration Meta Lead Ads → ERP → SharePoint → notification commercial

## Architecture

```mermaid
sequenceDiagram
    participant Meta as Meta Ads
    participant ERP as ERP Laravel
    participant Q as Queue
    participant SP as SharePoint
    participant M365 as Microsoft Graph

    Meta->>ERP: Webhook POST leadgen
    ERP->>ERP: Vérification HMAC
    ERP->>Q: ProcessMetaLead
    ERP-->>Meta: 200 OK
    Q->>Meta: GET lead + campagne
    Q->>ERP: INSERT leads_marketing
    Q->>Q: CreateLeadSharePointItem
    Q->>Q: NotifyCommercialTeams
    Q->>SP: POST list item
    Q->>M365: Mail.Send (email enrichi)
```

## Variables `.env`

| Variable | Description |
|----------|-------------|
| `META_APP_ID` | ID application Meta Developers |
| `META_APP_SECRET` | Secret application (signature webhook) |
| `META_WEBHOOK_VERIFY_TOKEN` | Chaîne aléatoire (~32 car.) pour validation GET webhook |
| `META_PAGE_ACCESS_TOKEN` | Token long-lived page Facebook (60 jours) |
| `META_PAGE_ID` | ID de la page Facebook |
| `META_GRAPH_API_VERSION` | Ex. `v22.0` |
| `LEADS_FALLBACK_COMMERCIAL_USER_ID` | `users.id` si code campagne inconnu |
| `LEADS_SHAREPOINT_SITE_ID` | ID site Graph SharePoint Envol |
| `LEADS_SHAREPOINT_LIST_ID` | ID liste « Prospects Marketing » |
| `META_AD_ACCOUNT_ID` | Compte pub Meta `act_XXXXXXXXX` (import codes campagnes) |

## Webhook Meta

- **URL** : `https://envol.hectare.fr/api/webhooks/meta/leadgen`
- **Vérification (GET)** : Meta envoie `hub_mode=subscribe`, `hub_verify_token`, `hub_challenge`
- **Réception (POST)** : header `X-Hub-Signature-256: sha256=...`
- **Champ souscrit** : `leadgen`

### Test curl (vérification)

```bash
curl -s "https://envol.hectare.fr/api/webhooks/meta/leadgen?hub_mode=subscribe&hub_verify_token=VOTRE_TOKEN&hub_challenge=test123"
```

Réponse attendue : `test123`

## Simulation locale (sans Meta)

```bash
php artisan meta:simulate-lead --code=101 --prenom=Marie --nom=Dupont \
  --email=test@test.fr --tel=0612345678 --campagne="101 - Arborea Été 2026"
```

Par défaut, SharePoint et notification s'exécutent **en synchrone** (résultat dans le terminal). Option `--async` pour la file d'attente comme en prod.

Prérequis : code `101` dans l'admin, `LEADS_FALLBACK_COMMERCIAL_USER_ID`, `LEADS_SHAREPOINT_*` et `AZURE_MAIL_EXPEDITEUR`.

## Mapping codes campagnes (admin ERP)

Route : `/admin/marketing/codes-campagnes`

Import en masse : `/admin/marketing/codes-campagnes/import-meta` (`META_AD_ACCOUNT_ID`, scope `ads_read`). Toutes les campagnes **ACTIVE** sont listées ; le commercial est affecté manuellement (code 3 chiffres optionnel).

**Routage lead** : 1) `meta_campaign_id` 2) code préfixe `^(\d{3})\s*-` dans le nom 3) `LEADS_FALLBACK_COMMERCIAL_USER_ID`.

| meta_campaign_id | Code (opt.) | Programme | Commercial |
|------------------|-------------|-----------|------------|
| ID Meta campagne | 101 | ARBOREA (optionnel) | Utilisateur M365 ERP |

Droits : `GS_DSI`, `GS_ADMIN_ERP`.

**Commercial référent** : tout utilisateur du tenant M365 (liste Graph) peut être affecté. S’il n’a jamais ouvert l’ERP, un compte `users` est créé automatiquement (`preapproved_at`, sans mot de passe utilisable — SSO au premier login).

## Liste SharePoint « PROSPECTS - FACEBOOK »

Liste importée CSV sur le site Envol — noms internes génériques. Le mapping est centralisé dans `config/leads_marketing.php` (`sharepoint_fields`).

| Donnée | Nom interne |
|--------|-------------|
| Nom + Prénom | `Title` |
| Email | `field_1` |
| Téléphone | `field_2` |
| Programme | `field_3` |
| Code Campagne | `field_4` |
| Nom Campagne | `field_5` |
| Commercial Référent | `field_6` (texte : nom + email) |
| Date Réception | `field_7` (Date/Heure ISO 8601 UTC, ex. `2026-05-22T14:30:00Z`) |
| Statut | `field_8` (valeur initiale : `Nouveau`) |
| Champs Supplémentaires | `field_9` (texte multiligne `Libellé: valeur`, pas JSON) |
| URL ERP | `field_10` |
| ID Lead Meta | `field_11` |

Si la liste est recréée avec des colonnes nommées proprement, mettre à jour uniquement `config/leads_marketing.php`.

## Notification commercial

**Implémentation actuelle** : email HTML professionnel via Microsoft Graph `Mail.Send` (mailbox de service `AZURE_MAIL_EXPEDITEUR`).

- **TO** : commercial référent du lead (ou `LEADS_FALLBACK_EMAIL` si absent)
- **CC** : `aurelie.portales@hectare.fr`, `hectarion@hectaregroupe.fr` (sans doublon avec le TO)
- Sujet : `🔥 Nouveau prospect à contacter — {campagne} — {prénom} {nom}`
- CTA SharePoint : liste `PROSPECTS - FACEBOOK` (`LEADS_SHAREPOINT_PROSPECTS_LIST_URL`)

**TODO (option DSI)** : message Teams en DM via `Chat.ReadWrite` + `Chat.Create` (scopes et consentement supplémentaires).

## Setup Meta Developers (DSI)

1. Créer une app : https://developers.facebook.com/apps
2. Ajouter le produit **Webhooks** et **Marketing API**
3. Associer la page Facebook Hectare/Envol à l’app
4. Générer un **Page Access Token** long-lived (Graph API Explorer → échanger en long-lived, validité ~60 jours)
5. Configurer le webhook :
   - URL : `https://envol.hectare.fr/api/webhooks/meta/leadgen`
   - Verify token : valeur de `META_WEBHOOK_VERIFY_TOKEN`
   - Champ : `leadgen`
6. **App Review** (prod) : `leads_retrieval`, `pages_show_list`, `pages_manage_metadata` (délai typique 3–7 jours)

## Renouvellement Page Access Token

Le token page expire environ tous les **60 jours**. Procédure :

1. Graph API Explorer ou Business Manager → régénérer le token long-lived
2. Mettre à jour `META_PAGE_ACCESS_TOKEN` sur OVH
3. `php artisan config:clear && php artisan cache:clear`

## Consultation des leads (ERP)

- Liste : `/admin/leads-marketing`
- Détail : `/admin/leads-marketing/{id}`
- Droits : `GS_DSI` / `GS_ADMIN_ERP` voient tout ; les autres voient leurs leads (`commercial_user_id`)

## Déploiement

```bash
php artisan migrate --force
npm run build
php artisan config:clear && php artisan cache:clear
```

Queue : s’assurer qu’un worker traite `ProcessMetaLead`, `CreateLeadSharePointItem`, `NotifyCommercialTeams`.