docs/embedded_signup_implementation.md

Implémentation Embedded Signup WhatsApp

Ce document décrit le flux technique pour permettre aux organisations B2B de connecter leur propre numéro WhatsApp à la plateforme.

1. Flux Frontend (SDK Meta)

Le Frontend doit charger le SDK Facebook et déclencher la popup de configuration.

Configuration Requise

• SDK URL : https://connect.facebook.net/en_US/sdk.js
• App ID : Configuré dans le Dashboard Meta App.
• Config ID : Identifiant de la configuration d'Embedded Signup créée sur Meta Business Suite.

Exemple d'appel JS

FB.login((response) => {
  if (response.authResponse) {
    const code = response.authResponse.code;
    // Envoyer le code ou le token au Backend
  }
}, {
  config_id: '<YOUR_CONFIG_ID>',
  response_type: 'code',
  override_default_response_type: true
});

2. Point de Terminaison Backend (API)

L'API réceptionne les données après la validation Meta côté client.

Route : POST /v1/organizations/:id/whatsapp-setup

Authentification : Requiert un token JWT valide d'un administrateur d'organisation ou une clé API d'administration.

Corps de la requête (JSON) :

{
  "wabaId": "1234567890",
  "accessToken": "EAAG...",
  "phoneNumberId": "9876543210",
  "phoneNumber": "+33612345678"
}

Traitement Backend :

1. Validation : Vérification de la présence des champs obligatoires via Zod.
2. Chiffrement : Le accessToken est chiffré à la volée avec l' ENCRYPTION_SECRET (AES-256-GCM).
3. Persistance : Mise à jour de la table Organization (champs systemUserToken et wabaId).
4. Synchronisation : upsert dans la table WhatsAppPhoneNumber pour lier l'ID technique au numéro lisible.
5. Invalidation Cache : Suppression des clés Redis org:config:* et org:phone:* pour forcer le Worker à charger la nouvelle configuration.

3. Sécurité

• Données en transit : Toujours sous HTTPS + JWT.
• Données au repos : Tous les tokens d'accès système sont chiffrés. Seul le code applicatif possédant l' ENCRYPTION_SECRET (non présent en DB) peut les lire.