Guide de démarrage de l’api de signature Universign

Introduction

Ce guide à destination des développeurs et intégrateurs décrit la procédure à suivre pour intégrer le service de signature de contrat d'Universign à un site internet client.

Bien qu'un grand soin ait été apporté pour rendre l'intégration aussi simple que possible, le lecteur est supposé être familier des concepts de programmation dans le langage utilisé pour l'intégration.

Prérequis

Le service de signature de contrats en ligne repose sur la notion de collecte de signatures. Une collecte de signatures est composée de documents à faire signer et d'une liste de signataires qui vont apposer leur signature sur ces documents.

Chaque signataire est défini par ses nom et prénom ainsi qu'un numéro de téléphone mobile ou une adresse email afin de recevoir son code secret.

Chaque document - au format PDF - est défini par son nom et son contenu.

Chaque requête de création de collecte doit contenir l'URL où rediriger le signataire après que le processus de signature se soit achevé. Il est possible de spécifier des URL différentes en cas de succès, d'échec ou d'annulation.

Description de la cinématique

schéma de collecte de signature électronique
La cinématique d'une collecte basique est la suivante :

  1. Lorsque votre client clique sur le bouton 'signer' de votre page web, vous émettez une requête de création de collecte vers Universign. Celle-ci doit contenir toutes les informations concernant le signataire (nom, prénom, numéro de téléphone), mais également les adresses de redirection en fin de processus.
  2. Universign vous répond en vous renvoyant l'URL de signature mais surtout l'identifiant de la collecte. Vous devez conserver cet identifiant (dans une base de données ou dans une session utilisateur) afin de pouvoir par la suite récupérer le document signé.
  3. Rediriger votre client vers l'URL transmise par Universign (en utilisant un code HTTP 302).
  4. Une fois le processus de signature terminé (par un succès ou un échec), le signataire est redirigé vers l'URL que vous avez spécifiée lors de la création de la collecte. Avec l'identifiant de la collecte, vous pouvez récupérer le document signé et le présenter à votre client.

exemples de code

Nos exemples de codes utilisent la librairie "XML-RPC for PHP" disponible à l'adresse http://phpxmlrpc.sourceforge.net.

Cet exemple de code créé une collecte de signature simple contenant un unique document pour un signataire avec authentification par SMS.

          include("path/to/xmlrpc.inc");

          //used variables
          $uni_url = "https://login:password@ws.universign.eu/sign/rpc/"; // address of the universign server with basic authentication
          $firstname = "John"; // the signatory first name
          $lastname = "Doe"; // the signatory last name
          $phoneNumber = "0123456789"; // the signatory mobile phone number
          $doc_name ="documentToSign.pdf"; // the name of the PDF document to sign
          $doc_content = file_get_contents($doc_name); // the binary content of the PDF file
          $returnPage = array (
              "success" => "https://www.google.com/#q=success",
              "fail" => "https://www.google.com/#q=fail",
              "cancel" => "https://www.google.com/#q=cancel"
          );


          //create the request
          $c = new xmlrpc_client($uni_url);

          $signer = array(
              "firstname" => new xmlrpcval($firstname, "string"),
              "lastname" => new xmlrpcval($lastname, "string"),
              "phoneNum"=> new xmlrpcval($phoneNumber, "string")
          );

          $doc = array(
              "content" => new xmlrpcval($doc_content, "base64"),
              "name" => new xmlrpcval($doc_name, "string")
          );

          $language = "fr";
          $signers = array(new xmlrpcval($signer, "struct"));

          $request = array(
              "documents" => new xmlrpcval(array(new xmlrpcval($doc, "struct")), "array"),
              "signers" => new xmlrpcval($signers, "array"),
              // the return urls
              "successURL" =>  new xmlrpcval($returnPage["success"], "string"),
              "failURL" =>  new xmlrpcval($returnPage["fail"], "string"),
              "cancelURL" =>  new xmlrpcval($returnPage["cancel"], "string"),
              //the type of  signature
              "certificateType" =>  new xmlrpcval("simple", "string"),
              "language" => new xmlrpcval($language, "string")
           );

           $f = new xmlrpcmsg('requester.requestTransaction', array(new xmlrpcval($request, "struct")));

           //send request and stores response values
           $r = &$c->send($f);
           if (!$r->faultCode()) {
               //if the request succeeded
               $url = $r->value()->structMem('url')->scalarVal(); //you should redirect the signatory to this url
               $id = $r->value()->structMem('id')->scalarVal(); //you should store this id
           } else {
               //displays the error code and the fault message
               print "An error occurred: ";
               print "Code: " . $r->faultCode(). " Reason: '" . $r->faultString();
           }
				

Cet exemple de code utilise l'identifiant d'une collecte créée précédemment pour récupérer le document signé. Il est exécuté après la redirection du signataire sur l'URL de succès.


           include("path/to/xmlrpc.inc");

          //used variables
          $uni_url = "https://login:password@ws.universign.eu/sign/rpc/"; // address of the universign server with basic authentication
          $uni_id = "99999999-9999-9999-9999-999999999999"; // a collection id

           //create the request
           $c = new xmlrpc_client($uni_url);
           $f = new xmlrpcmsg('requester.getDocumentsByTransactionId', array(new xmlrpcval($uni_id, "string")));

           //Send request and analyse response
           $r = &$c->send($f);
           if (!$r->faultCode()) {
               //if the request succeeded
               $doc['name'] = $r->value()->arrayMem(0)->structMem('name')->scalarVal();
               $doc['content'] = $r->value()->arrayMem(0)->structMem('content')->scalarVal();
           } else {
               //displays the error code and the fault message
               print "An error occurred: ";
               print "Code: " . $r->faultCode(). " Reason: '" . $r->faultString();
           }
				

Si vous avez des doutes ou des questions, n’hésitez pas à nous contacter.


Support et aide Universign

Si une erreur survient lors du processus de signature, votre compte Universign ne sera pas débité.

Lorsqu’une requête échoue, Universign indique un code d’erreur qui vous permet de comprendre et de résoudre le problème rencontré.

  • 73002 - une erreur est survenue pendant l’opération de signature.
  • 73003 - une erreur est survenue pendant la lecture de votre certificat.
  • 73010 - l’authentification a échoué.
  • 73011 - aucun compte disponible.
  • 73024 - le fichier est illisible.

Contactez-nous