espace-paie-odentas/DOCUSEAL_DEBUG_GUIDE.md

Guide de Débogage - Pré-remplissage Signature DocuSeal

Date: 14 octobre 2025

Logs à vérifier dans la console

Lorsque vous ouvrez une signature électronique, vous devriez voir cette séquence de logs :

1. API Backend (/api/contrats/[id]/signature)

🔍 [API SIGNATURE] Recherche contrat ID: xxx
✅ [API SIGNATURE] Contrat trouvé: { id, org_id, ... }
🔍 [API SIGNATURE] org_id présent: xxx
🔍 [API SIGNATURE] Recherche de signature pour org_id...
📋 [API SIGNATURE] Résultat requête organization_details: {
  hasData: true/false,
  hasError: true/false,
  hasSignature: true/false,
  signatureLength: xxx,
  signaturePreview: "data:image/png;base64,..."
}
✅ [API SIGNATURE] Signature trouvée pour l'organisation
📏 [API SIGNATURE] Longueur de la signature: xxx
📤 [API SIGNATURE] Réponse finale: {
  hasSignature: true,
  signatureLength: xxx,
  contractId: xxx,
  orgId: xxx
}

2. Frontend - Récupération des données

🔍 [SIGNATURE] Debug - data complète: { ... }
📋 [SIGNATURE] Données contrat depuis API: { success: true, data: {...} }
🔍 [SIGNATURE] result.data: { ... }
🔍 [SIGNATURE] result.data.signature_b64: "data:image/png;base64,..."
📦 [SIGNATURE] contractData extrait: { ... }
🖊️ [SIGNATURE] signatureB64 extraite: {
  exists: true,
  type: "string",
  length: xxx,
  preview: "data:image/png;base64,..."
}
✅ [SIGNATURE] Signature B64 disponible, longueur: xxx

3. Frontend - Stockage sessionStorage

🔍 [SIGNATURE] Tentative de stockage de la signature...
🔍 [SIGNATURE] signatureB64 value: "data:image/png;base64,..."
📝 [SIGNATURE] Stockage de la signature dans sessionStorage
📝 [SIGNATURE] Longueur de la signature: xxx
📝 [SIGNATURE] Preview: "data:image/png;base64,..."
✅ [SIGNATURE] Signature stockée avec succès, vérification: {
  stored: true,
  length: xxx,
  matches: true
}
✅ [SIGNATURE] URL embed trouvée: https://docuseal.eu/s/xxx

4. Frontend - Rendu du composant

🎨 [SIGNATURE RENDER] Génération du HTML docuseal-form
🎨 [SIGNATURE RENDER] embedSrc: https://docuseal.eu/s/xxx
🎨 [SIGNATURE RENDER] Signature depuis sessionStorage: {
  exists: true,
  length: xxx,
  preview: "data:image/png;base64,..."
}
🎨 [SIGNATURE RENDER] signatureAttr généré: {
  hasAttr: true,
  attrLength: xxx,
  attrPreview: 'data-signature="data:image/png;base64,...'
}
🎨 [SIGNATURE RENDER] HTML final généré
🎨 [SIGNATURE RENDER] HTML length: xxx
🎨 [SIGNATURE RENDER] HTML contient data-signature: true

Points de vérification

Étape 1 : Vérifier la base de données

-- Vérifier que la signature existe
SELECT 
  org_id, 
  structure,
  LENGTH(signature_b64) as signature_length,
  SUBSTRING(signature_b64, 1, 50) as signature_preview
FROM organization_details
WHERE signature_b64 IS NOT NULL;

Attendu :

• Au moins une ligne avec signature_b64 non NULL
• signature_length > 0
• signature_preview commence par "data:image/"

Étape 2 : Vérifier que le contrat a un org_id

-- Vérifier le contrat
SELECT 
  id,
  contract_number,
  org_id,
  signature_status
FROM cddu_contracts
WHERE id = 'VOTRE_CONTRACT_ID';

Attendu :

• org_id non NULL
• org_id correspond à une organisation avec signature_b64

Étape 3 : Tester l'API directement

# Remplacer CONTRACT_ID par l'ID réel
curl http://localhost:3000/api/contrats/CONTRACT_ID/signature

Attendu dans la réponse :

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "signature_b64": "data:image/png;base64,..."
  }
}

Étape 4 : Vérifier la console du navigateur

Ouvrir DevTools (F12) → Console

Chercher les logs :

• ✅ Tous les logs commençant par [API SIGNATURE]
• ✅ Tous les logs commençant par [SIGNATURE]
• ✅ Tous les logs commençant par [SIGNATURE RENDER]

Étape 5 : Vérifier sessionStorage

Dans DevTools → Application → Storage → Session Storage

Chercher la clé : docuseal_signature_b64

Attendu :

• Clé présente
• Valeur commence par "data:image/"
• Valeur ressemble à du base64

Étape 6 : Vérifier le HTML généré

Dans DevTools → Elements

Chercher l'élément <docuseal-form>

Attendu :

<docuseal-form
  data-src="https://docuseal.eu/s/xxx"
  data-language="fr"
  data-with-title="false"
  data-background-color="#fff"
  data-allow-typed-signature="false"
  data-signature="data:image/png;base64,...">
</docuseal-form>

Vérifier :

• ✅ Attribut data-signature présent
• ✅ Valeur commence par "data:image/"
• ✅ Valeur contient du base64

Problèmes courants

Problème 1 : Pas de signature dans la base

Symptôme :

⚠️ [API SIGNATURE] Pas d'org_id sur ce contrat

ou

❌ [API SIGNATURE] Aucune signature trouvée pour cette organisation

Solution : Ajouter la signature dans la base :

UPDATE organization_details 
SET signature_b64 = 'data:image/png;base64,VOTRE_BASE64'
WHERE org_id = 'ID_ORGANISATION';

Problème 2 : Signature trop longue pour sessionStorage

Symptôme :

❌ [SIGNATURE] Erreur lors du stockage: QuotaExceededError

Solution :

• Compresser l'image de signature
• Utiliser un format plus léger (PNG optimisé)
• Limite sessionStorage : ~5-10MB selon le navigateur

Problème 3 : Format de signature incorrect

Symptôme : DocuSeal affiche une erreur ou ne pré-remplit pas

Solution : Vérifier le format :

• ✅ CORRECT : data:image/png;base64,iVBORw0KGgo...
• ❌ INCORRECT : iVBORw0KGgo... (manque le préfixe)
• ❌ INCORRECT : data:image/png,base64,iVBORw0KGgo... (virgule au mauvais endroit)

Problème 4 : Le composant se re-render avant le stockage

Symptôme :

🎨 [SIGNATURE RENDER] Signature depuis sessionStorage: { exists: false }

mais plus tôt on a vu :

✅ [SIGNATURE] Signature stockée avec succès

Solution : Problème de timing React. Le sessionStorage est lu lors du premier rendu avant le stockage.

Fix : Forcer un re-render après le stockage :

if (signatureB64) {
  sessionStorage.setItem('docuseal_signature_b64', signatureB64);
  // Forcer un re-render
  setEmbedSrc(null);
  setTimeout(() => setEmbedSrc(embed), 0);
}

Commandes utiles

Vérifier toutes les organisations avec signature

SELECT 
  o.id,
  o.name,
  od.structure,
  CASE 
    WHEN od.signature_b64 IS NOT NULL THEN '✅ Signature présente'
    ELSE '❌ Pas de signature'
  END as statut,
  LENGTH(od.signature_b64) as taille
FROM organizations o
LEFT JOIN organization_details od ON od.org_id = o.id
ORDER BY od.signature_b64 IS NOT NULL DESC, o.name;

Vérifier les contrats prêts pour le pré-remplissage

SELECT 
  c.id,
  c.contract_number,
  c.org_id,
  o.name as organization_name,
  c.signature_status,
  CASE 
    WHEN od.signature_b64 IS NOT NULL THEN '✅ Signature dispo'
    ELSE '❌ Pas de signature'
  END as signature_employeur
FROM cddu_contracts c
LEFT JOIN organizations o ON o.id = c.org_id
LEFT JOIN organization_details od ON od.org_id = c.org_id
WHERE c.signature_status IN ('En attente', 'Signé par l''employeur')
ORDER BY c.created_at DESC
LIMIT 20;

Contact

Si les logs montrent toutes les étapes OK mais que ça ne fonctionne toujours pas :

1. Copier tous les logs de la console
2. Faire une capture d'écran de l'élément <docuseal-form> dans DevTools
3. Vérifier la version de DocuSeal utilisée
4. Consulter la documentation DocuSeal pour data-signature