Docusign dans une extension WordPress : faire signer un contrat sans quitter

Comment déclencher une demande de signature électronique depuis un formulaire WordPress, sans renvoyer le client vers une interface tierce déconnectée du site ? C’est la question posée par une association qui fait signer des conventions de partenariat directement depuis son espace adhérent, sans jongler entre plusieurs outils.

Cette recette construit le flux complet : soumission du formulaire, création d’une enveloppe Docusign via l’API eSignature, envoi du lien de signature à l’intéressé, puis réception du statut par webhook Docusign Connect. Elle ne traite volontairement pas la question de la valeur juridique de la signature électronique elle-même, qui dépend du cadre réglementaire applicable et relève d’un avis juridique, pas d’un choix d’implémentation.

Créer l’enveloppe à la soumission du formulaire

L’API Docusign eSignature attend un document encodé en base64 et une définition des destinataires avec leurs zones de signature (« tabs »). Sur WordPress, cette création se déclenche depuis le traitement d’un formulaire personnalisé :

function wpm_docusign_creer_enveloppe( array $donnees_signataire, string $pdf_base64 ) : string {
    $payload = array(
        'emailSubject' => 'Convention de partenariat à signer',
        'documents'    => array( array(
            'documentBase64' => $pdf_base64,
            'name'           => 'convention.pdf',
            'fileExtension'  => 'pdf',
            'documentId'     => '1',
        ) ),
        'recipients'   => array(
            'signers' => array( array(
                'email'     => $donnees_signataire['email'],
                'name'      => $donnees_signataire['nom'],
                'recipientId' => '1',
                'tabs'      => array(
                    'signHereTabs' => array( array( 'anchorString' => '/signature/' ) ),
                ),
            ) ),
        ),
        'status'       => 'sent',
    );

    $response = wp_remote_post( WPM_DOCUSIGN_BASE_URI . '/envelopes', array(
        'headers' => array(
            'Authorization' => 'Bearer ' . wpm_docusign_jeton_acces(),
            'Content-Type'  => 'application/json',
        ),
        'body'    => wp_json_encode( $payload ),
        'timeout' => 15,
    ) );

    $corps = json_decode( wp_remote_retrieve_body( $response ), true );
    return $corps['envelopeId'] ?? '';
}

Lier l’enveloppe à un contenu WordPress

L’identifiant d’enveloppe retourné par Docusign doit être stocké immédiatement comme métadonnée du post représentant la convention, avant même de recevoir la moindre confirmation de statut. C’est ce lien qui permettra au webhook, reçu plus tard, de retrouver le bon enregistrement :

update_post_meta( $convention_id, '_docusign_envelope_id', $envelope_id );
update_post_meta( $convention_id, '_docusign_statut', 'sent' );

Recevoir le statut par webhook Docusign Connect

Docusign Connect notifie l’application configurée à chaque changement de statut d’une enveloppe (envoyée, complétée, refusée). Le point d’entrée REST WordPress doit vérifier la signature HMAC du webhook avant tout traitement, exactement comme pour n’importe quel webhook entrant sensible :

register_rest_route( 'wpm/v1', '/docusign-webhook', array(
    'methods'             => 'POST',
    'callback'            => 'wpm_docusign_traiter_webhook',
    'permission_callback' => '__return_true',
) );

function wpm_docusign_traiter_webhook( WP_REST_Request $request ) {
    $signature = $request->get_header( 'x-docusign-signature-1' );
    $corps_brut = $request->get_body();

    $attendu = base64_encode( hash_hmac( 'sha256', $corps_brut, WPM_DOCUSIGN_HMAC_KEY, true ) );
    if ( ! hash_equals( $attendu, $signature ) ) {
        return new WP_REST_Response( null, 401 );
    }

    $evenement    = json_decode( $corps_brut, true );
    $envelope_id  = $evenement['data']['envelopeId'] ?? '';
    $statut       = $evenement['data']['envelopeSummary']['status'] ?? '';

    $convention_id = wpm_trouver_convention_par_enveloppe( $envelope_id );
    if ( $convention_id ) {
        update_post_meta( $convention_id, '_docusign_statut', sanitize_key( $statut ) );
    }

    return new WP_REST_Response( array( 'ok' => true ), 200 );
}

Variantes utiles selon le contexte client

• Pour une signature multi-parties (deux signataires successifs), il faut incrémenter recipientId et routingOrder pour chaque destinataire.
• Pour un rappel automatique après cinq jours sans signature, une tâche planifiée peut interroger l’API GET /envelopes/{id} plutôt que d’attendre un webhook qui ne viendra pas.
• Pour archiver le document signé final, l’endpoint GET /envelopes/{id}/documents/combined renvoie le PDF complet avec les signatures apposées, à télécharger et stocker via wp_upload_bits().

Un conseil qui évite bien des tickets de support : ne jamais considérer un statut « sent » comme définitif côté interface utilisateur. Tant que le webhook « completed » n’est pas arrivé, l’espace adhérent doit afficher un état d’attente explicite, jamais une case cochée par anticipation.

En résumé

Intégrer Docusign dans une extension WordPress revient à traiter la signature électronique comme n’importe quel processus asynchrone piloté par API et webhook : création côté serveur, stockage de la référence, puis mise à jour réactive au fil des événements reçus. La rigueur se joue surtout dans la vérification de la signature du webhook et dans la gestion des statuts intermédiaires, pas dans la complexité de l’appel de création lui-même.