Bonnes pratiques pour l'urlcallback et le getInfosFromCosignatureDemand | Yousign - Base de connaissance

Bonnes pratiques pour l'urlcallback et le getInfosFromCosignatureDemand

Vous souhaitez connaître le statut d'une procédure de signature pour être certain de télécharger le document une fois qu'il sera signé par Yousign ?

Pour suivre et notifier votre système des différentes étapes d'une procédure de signature, 2 options s'offrent à vous en terme de développement : l' "urlcallback" et le "getInfosFromCosignatureDemand".

Vous pouvez retrouver toutes les informations techniques concernant ces méthodes sur notre documentation API accesible en ligne à partir des liens suivants :

Quelle est la différence entre ces 2 méthodes ?

  • URLCALLBACK

L' "urlcallback" est une notification dite de serveur à serveur. Cela signifie que le serveur de Yousign enverra des notifications automatiquement à votre serveur lorsqu'une nouvelle étape sera franchie sur une de vos procédures de signature.

Ces notifications enverront les informations suivantes :

  • le statut (par ordre chronologique : 'init', 'waiting', 'signed', 'signed_complete' et éventuellement 'cancel' et 'error')
  • le token de la procédure de signature
  • en option : les informations de consommation de vos crédits de signature (lire l'article sur "needconso")
  • en option : le nombre de tentatives pour la réception du code de sécurité (lire l'article sur "nb_attempts_reached")

Ces notifications seront envoyées en GET sur une URL que vous devrez définir lors de l'initialisation de la procédure de signature (pour plus de détails, rendez-vous sur notre documentation API à la rubrique "initCosign").

  • Schéma de principe de l'urlcallback sans redirection automatique :

  • GETINFOSFROMCOSIGNATUREDEMAND

Le "getInfosFromCosignatureDemand", quant à lui, doit être implémenté de votre côté, par exemple au sein d'une tâche planifiée (CRON). Ainsi, cela vous permettra de venir interroger notre solution Yousign pour connaître le statut à l'instant T d'une procédure de signature.

  • Schéma de principe du getInfosFromCosignatureDemand sans redirection automatique :

Pour résumer, avec l' "urlcallback", Yousign vient notifier votre serveur et avec le "getInfosFromCosignatureDemand" c'est vous qui venez interroger notre solution Yousign pour connaître les détails d'une procédure de signature.

Quelques précisions pour mieux comprendre les délais pour que votre système soit notifié.

La signature d'un document peut prendre quelques secondes du côté de Yousign pour être réalisée. En effet, généralement il faut compter entre 9 secondes et quelques dizaines de secondes pour réaliser les opérations cryptographiques, de sécurités et de signature sur le document lui-même.

Ce délai technique peut expliquer le fait qu'un signataire ne puisse pas télécharger immédiatement son document signé, mais bien quelques secondes après.

Néanmoins, il est très important de souligner que le document est considéré comme signé dès que le signataire a cliqué sur le bouton "Lancer la signature". En effet, ce sont bien ces dates et heures qui seront enregistrées pour la signature du document.

Pour ces raisons, il convient donc de travailler en asynchrone afin de ne pas bloquer le processus de signature et l'expérience utilisateur pour le signataire.

Comment rendre ce mécanisme transparent pour les signataires ? 

Le bouton permettant d'inviter le signataire à retourner vers le site n'apparaît qu'une fois le document signé par Yousign.

Par conséquent, pour rendre transparente cette phase de traitement, vous pouvez automatiser la redirection vers l' "urlsuccess" simplement avec notre forfait API contenant l'option de personnalisation. Ainsi, vous pourrez bénéficier d'une interface complète avec l'option suivante :

En activant cette option, la dernière page du processus de signature indiquant le message suivant "Félicitations, les documents ont bien été signés" sera remplacée directement par la page de votre choix de votre site internet.

Ainsi, chez Yousign, nous conseillons par exemple d'informer les signataires par un message du type : "La signature des documents a bien été prise en compte, vous pourrez accéder aux documents signés dans votre Espace Client d'ici quelques secondes".

Avec ce mécanisme, le signataire sait qu'il a bien terminé sa procédure de signature et qu'il pourra accéder d'ici quelques secondes à son document.

  • Schéma de principe de l'urlcallback avec redirection automatique :
  • Schéma de principe de getInfosFromCosignatureDemand avec redirection automatique :

 

Si vous souhaitez disposer de cette option, n'hésitez pas à contacter notre équipe Yousign par e-mail sur support@yousign.fr ou bien par téléphone au +33 (0)1 84 88 02 89.

Quelques précautions d'utilisation pour le getInfosFromCosignatureDemand

Afin d'éviter de solliciter inutilement votre serveur et celui de Yousign, il convient de souligner qu'une fois que vous avez récupéré le statut 'signed_complete' d'une procédure de signature, il n'est plus nécessaire de continuer d'interroger notre serveur sur ce même token.

En effet, cettte vérification n'aura plus aucune utilité car le statut ne pourra plus être modifié après le 'signed_complete'.

Vous devez également prévoir de stopper ces appels au bout d'un certain temps car si le signataire ne signe jamais le document, votre serveur continuera indéfiniement de solliciter notre infrastructure Yousign.

De plus, les demandes faites avec le "getInfosFromCosignatureDemand" peuvent être réalisées toutes les X secondes ou minutes en fonction de l'importance pour vous de télécharger le document rapidement ou non.

Toutefois, il ne sera pas autorisé de descendre en dessous d'une fréquence de toutes les secondes pour des raisons de sécurité et éviter les surcharges.

Le mot de la fin

Nous préconisons chez Yousign d'implémenter l' "urlcallback" plutôt que le "getInfosFromCosignatureDemand".

En effet, afin d'assurer une bonne qualité de service, il est préférable pour Yousign de gérer les différentes notifications à nos clients plutôt que d'être sollicité par l'ensemble de nos clients API.

Si vous souhaitez plus de renseignements ou bénéficier de notre expertise personnalisée, n'hésitez pas à contacter notre équipe support par e-mail sur support@yousign.fr ou bien par téléphone au +33 (0)1 84 88 02 89