API : Envoyer un contrat en un seul appel

Pour créer un contrat et l’envoyer directement en signature, on peut utiliser la méthode sendCommandPacket.

Une façon rapide d’appeler cette méthode est d’utiliser l’API REST sous la forme d’un HTTP POST

Prérequis pour l’utilisation de l’API

Pour utiliser l’API vous devez avoir votre token API, votre contrat en pdf et votre fichier sellsign.

Ce fichier formaté en JSON, contient votre contract_definition_id et les informations de votre signataire comme le number du destinataire du contrat, et ses informations générales ainsi que le nom du pdf correspondant au contrat.

Lors de la création du customer et du contractor, vous devez définir un mode de signature :

  • 1 : signature par code à usage unique envoyé immédiatement par SMS (INSTANT_OTP)
  • 2 : signature tactile immédiate (INSTANT_PAD)
  • 3 : envoi d’un mail pour une signature différée par code SMS (MAIL_OTP)
  • 7 : envoi d’un mail à une personne en copie
  • 8 : envoi du contrat à un prévalideur qui va déterminer si le contrat est valide, il sera par la suite envoyé aux signataires

Vous trouverez ci-dessous un exemple du fichier sellsign.

{
    "customer": {
        "number": "mycustomer65778", // l'identifiant de votre client, le destinataire du contrat, que vous définissez 
        "mode": 3,
        "contractor_id": -1,
        "vendor": "vendor_adress_email@calindasoftware.com", // 
		transmit dans vos variables API
        "fields": [{
                "key": "firstname",
                "value": "Jacques"
        },
        {
                "key": "lastname",
                "value": "Dupont"
        },
        {
                "key": "civility",
                "value": "MONSIEUR" // MONSIEUR ou MADAME
        },
        {
                "key": "email",
                "value": "test4814@calindasoftware.com" // pour tester, vous pouvez mettre votre adresse email ici
        },
        {
                "key": "cellPhone",
                "value": "0606060606" // pour tester, vous pouvez 
				mettre votre numéro de téléphone ici
        }
    ]
},
    "contractors": [{
	"number" : "mycustomer65778", // le number de votre 
	customer auquel le contractor est rattaché
	"mode" : 3,
	"id" : -1,
	"fields" : [{
		"key" : "firstname",
		"value" : "Jeanne"
	}, 
	{
		"key" : "lastname",
		"value" : "Martin"
	}, 
	{
		"key" : "civility",
		"value" : "MADAME"
	}, 
	{
		"key" : "email",
		"value" : "test24@calindasoftware.com"
	}
   ]
}],
    "contract": {
        "contract_definition_id": 2, // !!!ATTENTION!!! cet identifiant dépend de votre déploiement et vous est fourni avec votre document 
		descriptif de votre API.
                                      // Il permet d'identifier le type de contrat qui est utilisé et d'y accrocher des comportements (par 
									  exemple les callbacks sur cloture d'un contrat)
        "pdf_file_path": "my_contract.pdf", // le nom du fichier pdf 
		tel qu'il est donné dans le paquet http      
        "contract_id": -1,
        "message_title": "Votre contrat Z pour signature",
        "message_body": "Vous êtes signataire du contrat Z ci-joint pour la {{companyName}}. Merci de bien vouloir le signer électroniquement en cliquant sur le lien ci-dessous.<br>Cordialement,"		
    },
    "contract_properties": [
    {
        "key": "internal_contract_id", // une clé pour votre identifiant interne du contrat, la valeur pourra vous être donné lors du retour 
		du fichier signé
        "value": "ma valeur", // la valeur de la clé
        "to_fill_by_user": 0
    }
    ],
    "files": [], // pour ajouter des annexes, exemple plus bas
    "options": [],

    "to_sign": 1 // Pour déclencher l'émission de l'email 
}

Si vous n’avez pas de contractors vous devez laisser le tableau vide.

L’ajout d’un périmètre au contrat, pour les clients disposant de la version enterprise, s’éffectue en ajoutant « perimeters »:[« nom_de_votre_perimètre »] dans la partie customer du JSON.

  • « key »: « civility »
  • « key »: « firstname »
  • « key »: « lastname »
  • « key »: « address1 »
  • « key »: « address2 »
  • « key »: « postalCode »
  • « key »: « city »
  • « key »: « country »
  • « key »: « cellPhone »
  • « key »: « phone »
  • « key »: « email »
  • « key »: « companyName »
  • « key »: « jobTitle »
  • « key »: « registrationNumber »
  • « key »: « birthdate »
  • « key »: « birthplace »
  • « key »: « customerCode »

Ajouter des annexes au contrat

Il est possible d’ajouter un ou plusieurs fichiers comme annexes au contrat. Pour cela, il faut ajouter les binaires des fichiers à joindre en HTTP multi-part dans votre requête. Ensuite, préciser pour chaque fichier dans la structure « files » du paquet .sellsign :

  • « path » : le chemin d’accès (soit le nom du fichier, tel qu’il est indiqué dans le part HTTP de la requête POST)
  • « name » : le nom à donner à l’annexe dans la transaction SELL&SIGN
  • « type » : le type MIME du fichier

Par ailleurs, il faut ajouter telle quelle (et une seule fois quel que soit le nombre d’annexes) la structure « options » qui permet de raccorder les annexes au contrat.

{
   ...
  "files": // annexes
  [
    {
      "path": "appendix.pdf",			
      "name": "appendix.pdf", 		
      "type": "application/pdf" 
    }
  ],
  "options": 
  [
    {
      "key":"hub.selling.contract.default.picture.option",
      "value":""
    }
  ],
	
  ...
}

Utilisation de l’API en PHP

L’utilisation de la librairie php cURL ne suffit pas à interagir avec l’API car elle ne permet pas de spécifier les différents mime types pour chaque fichier.

L’ajout d’une librairie externe est donc nécessaire, nous vous recommandons Guzzle, un client qui permet d’envoyer simplement des requêtes HTTP. Cliquez ici pour accéder à la documentation de la librairie Guzzle.

Il faut dans le header de votre requête HTTP ajouter votre token API, il faut ensuite ajouter les fichiers, il vous sera demandé name et filename qui sont identiques, il correspond au nom du fichier à importer. Attention toutefois pour le fichier pdf à bien respecter le nom indiqué dans le fichier sellsign.

Enfin vous devez ajouter le contenu du fichier en utilisant la fonction fopen.

$response = $client->request('POST', 'https://cloud.sellandsign.com/calinda/hub/selling/do?m=sendCommandPacket', [
    'headers' => [
        'j_token' => $token
        ],

    'multipart' => [
        [
            'name'     => 'adhoc_light.sellsign',
            'contents' => fopen('C:\\xampp\htdocs\BridgeExample\\ressource/adhoc_light.sellsign', 'r'),
            'filename' => 'adhoc_light.sellsign',
            'headers'  => [
                'Content-type' => 'application/json'
            ]
        ],
        [
            'name'     => 'my_contract.pdf',
            'contents' => fopen('C:\\xampp\htdocs\BridgeExample\\ressource/my_contract.pdf', 'r'),
            'filename' => 'my_contract.pdf',
            'headers'  => [
                'Content-type' => 'application/pdf'
            ]
        ]
    ]
]);

Exemple de code PHP

Utilisation de l’API en Java

Il faut dans le header de votre requête HTTP ajouter votre token API, il faut ensuite ajouter les fichiers, il vous sera demandé nom du fichier , il correspond au nom du fichier à importer. Attention toutefois pour le fichier pdf à bien respecter le nom indiqué dans le fichier sellsign.

 HttpPost post = new HttpPost("https://cloud.sellandsign.com/calinda/hub/selling/do?m=sendCommandPacket"); // url du service
post.setHeader("j_token", "0025514|ccssccscqdcdxesdvdsd/6Gcj/23CEB16hmg=" ); // le token d'authentification

MultipartEntity mpe = new MultipartEntity();
    
// ajout du fichier .sellsign
String json_filename = "adhoc_light.sellsign";
InputStreamBody isb = new InputStreamBody( loadResource( json_filename ), "application/json", json_filename );
mpe.addPart( json_filename, isb);
    
// ajout du fichier .pdf
String pdf_filename = "my_contract.pdf"; // ce nom de fichier se retrouve dans le contenu json généré au dessus (voir le fichier adhoc_list.sellsign fournit en exemple)
isb = new InputStreamBody( loadResource( pdf_filename ), "application/pdf", pdf_filename );
mpe.addPart( pdf_filename, isb);

post.setEntity(mpe);
    
// Emission de la requête
HttpResponse response = client.execute(post);

Exemple de code Java

Utilisation de l’API en C#

Il faut dans la constante J_token ajouter votre token API, il faut ensuite ajouter les fichiers, il vous sera demandé le nom du fichier , il correspond au nom du fichier à importer. Attention toutefois pour le fichier pdf à bien respecter le nom indiqué dans le fichier sellsign.

Les erreurs retournées

Tous les codes présents ci dessous sont des codes erreurs HTTP retournés par le service.
Le body de la réponse peut contenir selon les cas des informations supplémentaires sur
l’erreur.

521 : paquet HTTP structuré en multipar mais aucun fichier json trouvé dans le paquet HTTP.
522 : paquet HTTP vide.
523 : Erreur interne lors du traitement du paquet HTTP.
524/525 : Le flux binaire du PDF ou du JSON est tronqué ou altéré.
526 : Un champ spécifié pour le customer/contractor n’existe pas dans le schéma (le nom est
donné dans le corps).
527 : Un champ spécifié pour le customer/contractor n’a pas la bonne structure (entier, chaine,
téléphone, adresse email, etc…) (le nom est donné dans le corps).
528 : L’utilisateur n’a pas les droits requis pour accéder à des objets spécifiés dans les données du json
(customer, contract_definition).
529 : Le JSON est invalide au sens de la norme JSON.
530 : Le contrat pdf n’a pu être traité pour appliquer les modifications requises par la signature
électronique.
531 : Le processus de signature subit une erreur provenant du tiers de confiance.
532 : Erreur interne lors de l’insertion des données.