renaud/espace-paie-odentas
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
espace-paie-odentas/LAMBDA_EMAIL_SIGNATURE_SALARIE_GUIDE.md

9.9 KiB
Raw Blame History

Configuration Lambda → Espace Paie : Email Signature Salarié

📋 Vue d'ensemble

Cette documentation détaille la configuration nécessaire pour faire communiquer la Lambda AWS postDocuSealSalarie avec l'Espace Paie pour l'envoi d'emails de signature aux salariés.

Architecture

DocuSeal Webhook → Lambda postDocuSealSalarie → API Espace Paie → Système Email Universel v2 → AWS SES
                                                                           ↓
                                                                   Logs emails (Supabase)

Avantages de cette architecture

✅ Centralisation : Tous les emails passent par le système universel v2
✅ Logs automatiques : Tous les envois sont enregistrés dans email_logs
✅ Cohérence : Même template et même système que les autres emails
✅ Maintenance simplifiée : Un seul endroit pour gérer les emails
✅ Debugging facilité : Logs accessibles dans l'interface Staff

🔧 Configuration AWS Lambda

Variables d'environnement à ajouter/modifier

Dans la configuration de la Lambda postDocuSealSalarie :

# Existantes (à conserver)
DOCUSEAL_API_TOKEN=xxxxx
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_SERVICE_ROLE=xxxxx
ZAPIER_WEBHOOK_URL=https://hooks.zapier.com/xxxxx

# NOUVELLES variables à ajouter
ESPACE_PAIE_URL=https://paie.odentas.fr
ESPACE_PAIE_API_KEY=<générer une clé secrète forte>

⚠️ Variables à SUPPRIMER

Les variables suivantes ne sont plus nécessaires car l'envoi d'email est géré par l'Espace Paie :

# À SUPPRIMER
AWS_SES_FROM=paie@odentas.fr
S3_BUCKET_NAME_EMAILS=odentas-emails
AIRTABLE_API_KEY=xxxxx

Génération de l'API Key

Pour générer une API Key sécurisée :

# Méthode 1 : OpenSSL
openssl rand -hex 32

# Méthode 2 : Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Méthode 3 : Python
python3 -c "import secrets; print(secrets.token_hex(32))"

Important : Utilisez la même clé dans AWS Lambda et dans l'Espace Paie.

🌐 Configuration Espace Paie

Variables d'environnement à ajouter

Dans .env.local (dev) et dans Vercel (production) :

# API Key pour authentifier les appels depuis la Lambda
LAMBDA_API_KEY=<même clé que ESPACE_PAIE_API_KEY de la Lambda>

Déploiement de la variable sur Vercel

# Ajouter la variable d'environnement sur Vercel
vercel env add LAMBDA_API_KEY

# Saisir la valeur : <la même que dans AWS Lambda>
# Environnements : Production, Preview, Development

# Redéployer pour prendre en compte la nouvelle variable
vercel --prod

📝 Fichiers modifiés/créés

1. Espace Paie (Next.js)

✨ Nouveau fichier créé

  • app/api/emails/signature-salarie/route.ts
    • Route API POST pour recevoir les demandes d'envoi d'email
    • Authentification par API Key
    • Utilise sendUniversalEmailV2()
    • Logs automatiques dans email_logs

📝 Fichiers modifiés

  • lib/emailTemplateService.ts

    • Ajout du type 'signature-request-salarie' dans EmailTypeV2
    • Ajout des champs matricule et typecontrat dans EmailDataV2
    • Configuration du template email avec cartes info et détails

  • lib/cleanEnv.ts

    • Ajout de LAMBDA_API_KEY dans l'objet ENV

2. Lambda AWS

📝 Fichier modifié

  • index.js (version mise à jour fournie : LAMBDA_SIGNATURE_SALARIE_UPDATED.js)
    • ❌ Suppression de sendSignatureEmail() (envoi direct SES)
    • ❌ Suppression de uploadEmailToS3() (stockage S3)
    • ❌ Suppression de logToAirtable() (logging Airtable)
    • ❌ Suppression de generateEmailHtml() (template HTML)
    • ✅ Ajout de l'appel API vers l'Espace Paie
    • ✅ Headers d'authentification avec API Key
    • ✅ Gestion d'erreurs améliorée

🚀 Déploiement

Étape 1 : Déployer l'Espace Paie

# En local, vérifier que la variable existe
grep LAMBDA_API_KEY .env.local

# Si absente, l'ajouter
echo "LAMBDA_API_KEY=votre_cle_secrete_ici" >> .env.local

# Sur Vercel (production)
vercel env add LAMBDA_API_KEY
# Puis redéployer
vercel --prod

Étape 2 : Mettre à jour la Lambda AWS

  1. Via AWS Console :

    • Aller dans AWS Lambda → postDocuSealSalarie
    • Onglet "Configuration" → "Environment variables"
    • Ajouter :
      • ESPACE_PAIE_URL = https://paie.odentas.fr
      • ESPACE_PAIE_API_KEY = <votre clé générée>
    • Supprimer les anciennes variables (optionnel mais recommandé)

  2. Mettre à jour le code :

    • Remplacer le contenu de index.js par celui de LAMBDA_SIGNATURE_SALARIE_UPDATED.js
    • Cliquer sur "Deploy"

Étape 3 : Tester

# Test depuis la Lambda (déclencher un webhook DocuSeal)
# Vérifier les logs CloudWatch pour :
# - "📤 Appel de l'API Espace Paie pour envoi email..."
# - "✅ E-mail envoyé via l'API Espace Paie"

# Vérifier dans l'Espace Paie
# - Aller sur /staff/email-logs
# - Chercher le type "signature-request-salarie"
# - Vérifier le statut "sent"

🔍 Debug & Monitoring

Logs Lambda (CloudWatch)

📤 Appel de l'API Espace Paie pour envoi email...
✅ E-mail envoyé via l'API Espace Paie: { success: true, messageId: '...' }

Logs Espace Paie (Console serveur)

=== API Email Signature Salarié ===
✅ Authentication successful
📦 Données reçues: { employeeEmail: '...', reference: '...', ... }
📧 Préparation de l'envoi de l'email: { to: '...', type: 'signature-request-salarie' }
✅ Email envoyé avec succès: { messageId: '...', recipient: '...', reference: '...' }

Vérification dans l'interface

  1. Interface Staff : /staff/email-logs

    • Filtrer par type : signature-request-salarie
    • Vérifier le statut et le contenu HTML

  2. Base de données : Table email_logs

    SELECT * FROM email_logs 
WHERE email_type = 'signature-request-salarie' 
ORDER BY created_at DESC 
LIMIT 10;

🛡️ Sécurité

API Key

  • ✅ Utilisez une clé de minimum 32 caractères hexadécimaux (256 bits)
  • ✅ Ne commitez JAMAIS la clé dans le code
  • ✅ Utilisez des variables d'environnement différentes par environnement
  • ✅ Renouvelez la clé périodiquement (tous les 6 mois)

HTTPS

  • ✅ L'API Espace Paie doit être en HTTPS uniquement
  • ✅ Vérifiez le certificat SSL (fait automatiquement par axios)

Rate Limiting

À considérer pour le futur :

  • Limiter le nombre de requêtes par minute depuis une IP
  • Implémenter un système de throttling

📊 Données envoyées

Payload de la Lambda vers l'API

{
  "employeeEmail": "salarie@example.com",
  "signatureLink": "https://paie.odentas.fr/signature-salarie/?docuseal_id=abc123",
  "reference": "CDDU-2025-001",
  "firstName": "Jean",
  "organizationName": "Théâtre National",
  "matricule": "SAL001",
  "typecontrat": "CDDU",
  "startDate": "15/01/2025",
  "profession": "Comédien",
  "productionName": "Le Mariage de Figaro",
  "organizationId": "uuid-org",
  "contractId": "uuid-contract"
}

Réponse de l'API

{
  "success": true,
  "messageId": "01000192...",
  "recipient": "salarie@example.com",
  "reference": "CDDU-2025-001"
}

❌ Gestion des erreurs

Erreurs possibles

Code Erreur Cause Solution
401 Unauthorized API Key invalide ou manquante Vérifier LAMBDA_API_KEY et ESPACE_PAIE_API_KEY
400 Bad Request Champs requis manquants Vérifier le payload envoyé
500 Server Error Erreur lors de l'envoi SES Vérifier les credentials AWS SES
500 Configuration Error LAMBDA_API_KEY non définie Ajouter la variable dans Vercel

En cas d'échec

La Lambda retourne une erreur 500 mais ne bloque pas :

  • Le contrat reste signé par l'employeur dans Supabase
  • Le webhook Zapier est appelé quand même
  • L'erreur est loggée dans CloudWatch

🔄 Rollback

Si vous devez revenir en arrière :

  1. Restaurer l'ancien code Lambda

    • Utiliser le fichier /tmp/aws-toolkit-vscode/lambda/eu-west-3/postDocuSealSalarie/index.js

  2. Rétablir les variables d'environnement

    • Réajouter AWS_SES_FROM, S3_BUCKET_NAME_EMAILS, AIRTABLE_API_KEY
    • Supprimer ESPACE_PAIE_URL et ESPACE_PAIE_API_KEY

  3. L'Espace Paie reste compatible

    • La route API peut rester en place (elle ne sera simplement pas appelée)
    • Le nouveau type d'email signature-request-salarie ne causera pas d'erreur

📚 Ressources

✅ Checklist de déploiement

Avant déploiement

  • Générer une API Key sécurisée (32 caractères hex minimum)
  • Tester localement la route API avec un faux payload
  • Vérifier que le template email s'affiche correctement

Espace Paie

  • Ajouter LAMBDA_API_KEY dans .env.local
  • Ajouter LAMBDA_API_KEY sur Vercel (tous les environnements)
  • Déployer sur Vercel
  • Vérifier que la route /api/emails/signature-salarie répond

Lambda AWS

  • Ajouter ESPACE_PAIE_URL dans les variables d'env
  • Ajouter ESPACE_PAIE_API_KEY dans les variables d'env (même valeur que LAMBDA_API_KEY)
  • Mettre à jour le code de la Lambda
  • Déployer

Tests

  • Déclencher un webhook DocuSeal (signature employeur)
  • Vérifier les logs CloudWatch de la Lambda
  • Vérifier les logs de l'API Espace Paie
  • Vérifier que l'email a été reçu par le salarié
  • Vérifier l'entrée dans /staff/email-logs
  • Vérifier le contenu HTML de l'email

Post-déploiement

  • Monitorer les logs pendant 24h
  • Vérifier le taux de succès des emails
  • Documenter tout problème rencontré
  • Célébrer ! 🎉

Dernière mise à jour : 15 octobre 2025