CyrilBochet/YousignApiClient

README translation

• English

Client API pour Yousign · solution de signature électronique française.

Sommaire

• Procédure simple
• Procédure avancée
• Téléchargement d'un fichier
• Récupérer les utilisateurs
• Gestion des tags (message du mail)
• Liens utiles

Procédure simple

use YousignApiClient\YousignApiClient;

// Votre clé API
$apikey = 'API_KEY';
$env = 'test';

$client = new YousignApiClient($apikey, $env);


// Nouvelle procédure
$client->newProcedure('test.pdf');

$members = array(
   array(
       'firstname' => 'Cyril',
       'lastname' => 'Bochet',
       'email' => 'cyril@mail.com',
       'phone' => '0102030405',
       'fileObjects' => array(
           array(
           'file' => $client->getIdfile(),
               'page' => 1,
               'position' => "202,205,389,284",
               'mention' => "Lu et approuvé",
               "mention2" => ""
           )
       )
       // Autre membre, etc.
   )
);

$client->addMembersToProcedure($members, 'Procédure test', 'Signature test.');

Procédure avancée

En créant une procédure avancée vous pouvez utiliser des webhooks.

Exemple : Yousign peut vous envoyer une notifcation webhook lorsqu'une personne signe votre document.

Vous pouvez mettre en place une URL qui va traiter la notification envoyée par Yousign.
Ensuite vous traiter la requête selon vos besoins. (mail, enregistrement du statut de la procédure, etc.)
Une procédure avancée vous permet également de créer des notifications mails.

Exemple : vous pouvez créer une notification lorsqu'une personne refuse de signer votre document. (déclencheur : "procedure.refused")

use YousignApiClient\YousignApiClient;

// Votre clé API
$apikey = 'API_KEY';
$env = 'test';

$client = new YousignApiClient($apikey, $env);


// Paramètres de la procédure
$parameters = array(
    'name' => "Ma procédure avancée",
    'description' => "Création d'une procédure avancée.",
    'start' => false
);

// Création de la procédure
// Liste des déclencheurs (mails et webhooks) : "procedure.started", "procedure.finished", "procedure.refused", "member.started", "member.finished"
    
    $emails = [
        "member.started" => array(
            "subject" => "Hey! You are invited to sign!",
            "message" => "Hello <tag data-tag-type=\"string\" data-tag-name=\"recipient.firstname\"></tag> <tag data-tag-type=\"string\" data-tag-name=\"recipient.lastname\"></tag>, <br><br> You have ben invited to sign a document, please click on the following button to read it: <tag data-tag-type=\"button\" data-tag-name=\"url\" data-tag-title=\"Access to documents\">Access to documents</tag>",
            "to" => ["@member"]),
        "procedure.refused" => array(
            "subject" => "John, created a procedure.",
            "message" => "The content of this email is totally awesome.",
            "to" => ["@creator", "@members"]),
            //etc.
    ];
    
    $webhooks = [
        "member.started" => array(
            "url" => "https://testyousign.requestcatcher.com",
            "method" => "POST",
            "headers" => array(
                "X-Custom-Header" => 'test'
            )),
            //etc.
    ];


$client->newAdvancedProcedure($parameters);

$filePath = 'file.pdf';
$fileName = 'file.pdf';


// On ajoute le fichier à signer
$client->advancedProcedureAddFile($filePath, $fileName);

// On définit le·s différent·s emplacement·s de signature
$emplacementsSignature = array(
  [
    'position' => '64,71,245,142',
    'page' => 2,
    'mention' => 'Certifié exact et sincère.',
    'mention2' => '',
    'reason' => ''
  ],
  [
    'position' => '87,297,270,369',
    'page' => 12,
    'mention' => 'Je certifie avoir bien reçu le document.',
    'mention2' => '',
    'reason' => ''
  ]
);

// On ajoute le·s membre·s à la procédure
$member = $client->advancedProcedureAddMember($prenom, $nom, $mail, $tel, $type);

// On ajoute les emplacements de signature à la procédure
foreach ($emplacementsSignature as $emplacement) {
   $client->advancedProcedureFileObject($emplacement["position"], $emplacement["page"], $emplacement["mention"], $emplacement["mention2"], $emplacement["reason"]);
}

// On lance la procédure
$client->advancedProcedureStart();

Téléchargement d'un fichier

// Pour l'exemple je télécharge le fichier directement après avoir lancé la procédure, mais en utilisant les webhooks vous pouvez le télécharger à n'importe quel moment.
// le fichier que l'on souhaite télécharger
$file = $client->advancedProcedureAddFile($filePath, $fileName);
$client->advancedProcedureStart();

// On récupère le fichier en base64 ou en binaire
$binary=false;
$client->downloadFile($file['id'], $binary);

Récupérer les utilisateurs

$client->getUsers();

Gestion des tags (message du mail)

Syntax	Description
<tag data-tag-type=\"button\" data-tag-name=\"url\" data-tag-title=\"Access to documents\">Access to documents</tag>	Show a stylized link to access to the procedure. If the recipent is a member, it will be redirect to the sign view. url params is required but you can change as your convenience the string "Access to documents"
<tag data-tag-type=\"string\" data-tag-name=\"recipient.firstname\"></tag>	It will display the firstname of the recipient.
<tag data-tag-type=\"string\" data-tag-name=\"recipient.lastname\"></tag>	It will display the lastname of the recipient.
<tag data-tag-name="procedure.files" data-tag-type="list"></tag>	It will list files that have been added to a procedure.
<tag data-tag-name="procedure.members" data-tag-type="list"></tag>	It will list members of a procedure.
<tag data-tag-name="procedure.expiresAt" data-tag-type="date" data-tag-date-format="SHORT" data-tag-time-format="NONE" data-tag-locale="fr_FR"></tag>	It will display the expiration date formatted like that : 04/31/2018. Allowed values for data-tag-date-format and data-tag-time-format: **NONE**: Does not display the element // **FULL**: Tuesday, April 12, 1952 AD or 3:30:42pm PST // **LONG**: January 12, 1952 or 3:30:32pm // **MEDIUM**: Jan 12, 1952 // **SHORT** (default value for both parameters): 12/13/52 ou 3:30pm

Liens utiles

Pour connaitre les coordonnées d'un emplacement de signature : https://placeit.yousign.fr

Documentation complète de l'API Yousign : https://dev.yousign.com