Yousign

Vos demandes de signature électronique — pour faire signer une pièce jointe reçue par mail, suivre l’avancement et récupérer le document signé et son dossier de preuve.

Une connexion Yousign permet au nœud Yousign de faire signer une pièce jointe reçue par e-mail : créer une demande de signature, téléverser le document, ajouter signataires et approbateurs, activer la demande, la suivre, puis télécharger le document signé et son dossier de preuve. La même connexion alimente le déclencheur Yousign — événement, qui démarre un workflow quand Yousign signale un événement, par exemple une demande signée par tous.

La connexion porte une clé d’API Yousign, un environnement et, facultativement, une clé de signature des webhooks. Les secrets sont chiffrés au repos, appliqués par le serveur au moment de l’appel, et n’apparaissent jamais dans un workflow. Yousign est en cours de renommage en Youtrust ; son API, ses en-têtes et ses domaines disent toujours « Yousign ».

En bref

• Identifiant : yousign
• Famille : Service
• Configurée par : Un membre (personnelle) ou un administrateur (partagée avec l’organisation)
• Authentification : Clé d’API ou jeton
• Type de credential : service:yousign
• Documentation officielle de l’API : https://developers.youtrust.com/docs/introduction-new
• Environnements : Bac à sable (sandbox) — https://api-sandbox.yousign.app/v3 ; Production (production) — https://api.yousign.app/v3
• Limite de débit appliquée par Mankomail : 30 requêtes par minute et par connexion ; jusqu’à 3 tentatives sur un 429 ou un 5xx
• Signature des webhooks : en-tête x-yousign-signature-256, HMAC-SHA256 du corps brut
• Test de connexion : Oui

Pas à pas

Les mêmes étapes s’affichent dans le formulaire de connexion de l’application.

1. Choisissez l’environnement : « Bac à sable » pour essayer (aucune valeur légale, documents filigranés, rien n’est facturé), « Production » pour signer pour de vrai.
2. Ouvrez Yousign, puis le panneau de droite → section « API » → page « API keys ». Il faut le rôle Admin ou Owner : un simple membre ne voit pas cet écran.
3. Créez une clé avec le MÊME environnement que celui choisi ci-dessus, le périmètre « organization » et la permission « full-access » — « read-only » ne peut pas envoyer de demande de signature.
4. Copiez la clé affichée et collez-la ci-dessous : Yousign ne la montrera plus jamais. Une clé du mauvais environnement produit un 401 dès le test.
5. La clé de signature n’est utile que si vous branchez le déclencheur « Yousign — événement ». Elle s’affiche dans « API > Webhooks » à la création de l’abonnement ; laissez-la vide sinon.

Champs de la connexion

Champ	Nature	Requis	Remarques
Environnement (environment)	Choix	Oui	Les deux mondes sont étanches : une demande créée dans l’un est introuvable dans l’autre, et une clé ne joint que le sien. sandbox (Bac à sable), production (Production) Défaut : sandbox
Clé d’API (apiKey)	Secret — jamais réaffiché	Oui	Elle agit au nom de votre organisation Yousign, avec les permissions choisies à sa création.
Clé de signature des webhooks (webhookSecret)	Secret — jamais réaffiché	Non	Facultative. C’est le « secret key » de l’abonnement webhook, visible dans l’application Yousign ou rendu à la création de l’abonnement.

Avant de commencer

• Il faut le rôle Admin ou Owner dans l’organisation Yousign : un simple membre ne voit pas la page API keys.
• Choisissez d’abord l’environnement, puis créez la clé dans ce même environnement. Une clé de bac à sable ne fonctionne pas en production, et inversement.
• Le Bac à sable sert à essayer : aucune valeur légale, documents filigranés, rien n’est facturé. La Production signe pour de vrai, et chaque activation est facturée : Yousign compte un crédit par signataire invité, au moment de l’activation, qu’il signe ou non.
• Pour créer un abonnement webhook par l’API, il faut une clé de production, même pour écouter le bac à sable, et Yousign ne le permet pas pendant la période d’essai. Les abonnements peuvent aussi se créer à la main dans l’application Yousign (API > Webhooks).

Autorisations

À la création de la clé dans Yousign, choisissez :

Réglage	Valeur	Pourquoi
Environnement	Le même que celui de la connexion	Une clé ne joint que son propre environnement.
Périmètre	organization	La clé agit au nom de toute l’organisation Yousign : demandes, modèles, contacts, utilisateurs et espaces de travail.
Permission	full-access	Nécessaire pour créer, activer, annuler ou supprimer une demande, ajouter des signataires, téléverser des documents et gérer les abonnements webhook. Une clé read-only passe le test de connexion (il ne fait que lire) mais échoue à la première écriture.

Le nœud couvre dix ressources : Demande de signature (créer un brouillon, créer depuis un modèle, obtenir, lister, activer, annuler, relancer une demande expirée, supprimer), Document (téléverser une pièce jointe du mail, lister, télécharger le document signé, télécharger le dossier de preuve), Signataire (ajouter, obtenir, lister, relancer), Approbateur, Suiveur, Modèle, Contact, Utilisateur, Espace de travail et Abonnement webhook (lister, créer, supprimer un abonnement). Activer envoie les e-mails et déclenche la facturation ; l’opération demande une confirmation explicite.

Environnements

C’est la connexion qui porte l’environnement, jamais le nœud : un workflow copié d’un client à l’autre ne peut pas signer pour de vrai parce qu’un champ est resté à sa valeur par défaut.

• Le formulaire propose Bac à sable par défaut.
• Si la valeur stockée est absente ou inconnue, la connexion se replie sur le premier environnement déclaré, le bac à sable : une connexion abîmée ne mène jamais à la production.
• Les deux mondes sont étanches : une demande créée dans l’un est introuvable dans l’autre. Un identifiant valide d’un côté répond 404 de l’autre.
• Pour travailler dans les deux, créez deux connexions (par exemple « Yousign — bac à sable » et « Yousign — production »). L’environnement s’affiche en badge sur chaque connexion, Production mise en évidence. Changer l’environnement d’une connexion existante sans ressaisir la clé n’est pas enregistré : créez plutôt une nouvelle connexion.

Ajouter la connexion

1. Ouvrez Connexions. Dans la section Services tiers, repérez la carte Yousign et cliquez sur Connecter.
2. Donnez un Nom à la connexion, choisissez la Portée — Personnelle (vous seul) ou Organisation (toute l’organisation ; seul un administrateur peut la créer) — puis l’Environnement.
3. Collez la Clé d’API. Laissez vide la Clé de signature des webhooks, sauf si vous utilisez le déclencheur Yousign — événement. Cliquez sur Créer la connexion.
4. De retour dans la liste, cliquez sur Configurer sur la nouvelle connexion, puis sur Tester la connexion.

Le test appelle GET /signature_requests?limit=1, qui valide la clé dans l’environnement choisi, puis GET /workspaces?limit=1 pour afficher le nom d’un espace de travail. Si ce second appel échoue, le test réussit quand même, sans nom. Une clé du mauvais environnement échoue avec « la clé est refusée par le service ».

Dans un nœud, choisissez la connexion dans Connexion Yousign. Les documents et les signataires se listent à l’intérieur de la demande de signature choisie. La liste des demandes inclut celles créées dans l’application Yousign comme celles créées par l’API. Supprimer est refusé tant qu’un workflow publié utilise la connexion.

Webhooks

Le déclencheur Yousign — événement reçoit les webhooks de Yousign sur l’URL du workflow :

<PUBLIC_BASE_URL>/hooks/wf/<jeton>

• Obtenir l’URL. Le jeton est généré à la première publication du workflow et rendu une seule fois. Vous pouvez en générer un nouveau avec POST /api/v1/workflows/{id}/webhook (voir l’API) : la réponse donne webhook.url, à préfixer par <PUBLIC_BASE_URL>. Une nouvelle URL invalide la précédente.
• S’abonner. Soit avec le nœud Yousign, ressource Abonnement webhook, opération Créer un abonnement (clé de production requise ; c’est Écouter le bac à sable, et non la connexion, qui décide de l’environnement écouté ; laissez Rejeu automatique coché), soit à la main dans l’application Yousign, sous API > Webhooks. L’URL doit être publique et en HTTPS.
• Clé de signature. Copiez la secret key de l’abonnement depuis l’application Yousign (le nœud ne la rend jamais) et collez-la dans le champ Clé de signature des webhooks de la connexion. Sans elle, toutes les livraisons sont refusées.
• Signature. Yousign envoie x-yousign-signature-256: sha256=<hex>, un HMAC-SHA256 du corps brut. Mankomail la vérifie en temps constant avant de créer quoi que ce soit. Une signature absente ou fausse reçoit le même 404 qu’une URL inconnue ; la raison n’est écrite que dans les journaux du serveur.
• Filtrage. Un abonnement à tous les événements en reçoit des dizaines de natures, et une demande à trois signataires en produit une dizaine. Mankomail lit event_name et ne crée une exécution que pour les Événements cochés sur le déclencheur (par défaut : Demande signée par tous) ; rien de coché = tout. Les événements écartés sont acquittés par 202.
• Déduplication. Yousign rejoue les livraisons échouées pendant environ quatre jours, avec le même event_id. Mankomail s’en sert comme clé de déduplication : une livraison rejouée est acquittée par 202 et ne crée pas de seconde exécution.
• Charge utile. Le corps arrive sous data.yousign : {{ data.yousign.event_name }}, {{ data.yousign.data.signature_request.id }}, {{ data.yousign.data.signature_request.external_id }} — la clé de corrélation posée à la création. L’exécution n’a pas de mail porteur.
• Le champ Abonnement (diagnostic) est indicatif : il sert à vérifier qu’un abonnement pointe bien sur l’URL de ce workflow, dans le bon environnement.

Erreurs fréquentes

Message ou code	Cause	Que faire
Test : « la clé est refusée par le service » (integration.unauthorized)	Clé erronée, révoquée, ou de l’autre environnement.	Vérifiez l’Environnement ; créez une clé dans cet environnement, ou une nouvelle connexion pour l’autre.
Test : « le quota du service est dépassé » (integration.rate_limited)	Yousign a répondu 429.	La clé est bonne : réessayez dans un moment.
integration.unauthorized pendant une exécution	401, ou 403 pour une clé read-only sur une écriture.	Créez une clé full-access et remplacez-la.
integration.not_found	404 : la demande, le document ou le signataire n’existe pas dans cet environnement.	Vérifiez les identifiants et l’environnement de la connexion.
integration.rejected	400 ou 422 : Yousign a refusé le corps de la requête, ou la requête n’est pas permise dans l’état actuel de la demande.	Lisez le détail dans l’erreur de l’étape, puis corrigez le paramétrage du nœud. Les abonnements webhook exigent une clé de production et ne sont pas disponibles pendant l’essai.
integration.rate_limited	429 après les nouvelles tentatives. Mankomail envoie au plus 30 requêtes par minute et par connexion (la limite du bac à sable) et réessaie jusqu’à 3 fois en respectant Retry-After. Yousign a aussi un plafond horaire.	Temporaire : le moteur reprend l’étape plus tard.
integration.unavailable	5xx, 409 ou panne réseau, après rejeu.	Temporaire : le moteur reprend l’étape plus tard.
integration.connection_unusable	La connexion a été supprimée, n’est pas active, est hors de votre portée, ou appartient à un autre service.	Choisissez une connexion valide dans le nœud.
Les livraisons webhook ne démarrent jamais le workflow	Workflow non publié, clé de signature absente ou d’un autre abonnement, événement non coché, ou abonnement pointant vers une ancienne URL ou vers l’autre environnement.	Publiez, collez la secret key de l’abonnement, relisez Événements, et vérifiez l’abonnement avec Lister les abonnements.

Événements de webhook

Les événements proposés par le déclencheur. Un événement ajouté plus tard par le fournisseur reste accepté quand aucun événement n’est coché.

Événement	Libellé
signature_request.done	Demande signée par tous
signature_request.activated	Demande envoyée
signature_request.declined	Demande refusée par un signataire
signature_request.rejected	Demande rejetée par un approbateur
signature_request.approved	Demande approuvée
signature_request.expired	Demande expirée
signature_request.canceled	Demande annulée
signature_request.reminder_executed	Relance envoyée
signer.done	Un signataire a signé
signer.link_opened	Un signataire a ouvert son lien
signer.declined	Un signataire a refusé
signer.notified	Un signataire a été notifié
signer.notification_delivery_failed	L’e-mail d’un signataire n’est pas arrivé
signer.error	Erreur sur un signataire
approver.approved	Un approbateur a validé
approver.rejected	Un approbateur a rejeté
contact.created	Contact créé

Nœuds qui utilisent cette connexion

• Yousign — événement — trigger.yousign
• Yousign — yousign.api