API : Création et usage des liasses | Signature électronique

Définition d’une liasse
Une liasse permet d’associer plusieurs contrats qui pourront être signé en une seule fois par un ou plusieurs signataires.
Pour réunir plusieurs contrats en une seule liasse, il sera nécessaire de réaliser les étapes de création de contrat et d’association des signataires comme vu durant les pages précédentes.

Création d’une liasse

https://[host]/calinda/hub/selling/model/bundle/insert?action=createBundle

input json:
{
  "actor_id" : [identifiant du propriétaire de la liasse],
  "contract_id": [identifiant du premier contrat à ajouter à la liasse]
}

On obtient en retour un objet liasse dont l’attribut ‘id’ est l’identifiant qui sera à réutiliser plus tard :

{
    "id": 22,  //identifiant de la liasse
    "actorId": 2,
    "contractId": 1257,
    "status": 0,
    "master": 1,  // 1 indique que c'est le premier contrat de la liasse
    "syncTimer": 1479422641270,
    "lastModificationPlace": "SERVER"
}

Ajout d’un autre contrat à la liasse
L’appel est très simple, il suffit de faire référence à la liasse créée précédemment en spécifiant l’identifiant retourné.

https://[host]/calinda/hub/selling/model/bundle/update?action=addContract

input json:
{
  "id" : [identifiant de la liasse],
  "actor_id" : [identifiant de l'utilisateur de la liasse],
  "contract_id" : [identifiant du contrat à associer]
}

On obtient en retour l’objet liasse avec cette fois le nouveau contrat associé:

{
    "id": 22, // identifiant de la liasse
    "actorId": 2,
    "contractId": 1258,
    "status": 0,
    "master": 0,
    "syncTimer": 1479422646540,
    "lastModificationPlace": "SERVER"
}

Il est possible d’ajouter ainsi de suite autant de contrat que l’on veut à notre liasse.

Lister le contenu d’une liasse
Il est possible de récupérer une liste complète ou paginée de notre liasse en appelant :

https://[host]/calinda/hub/selling/model/contractstatus/list?action=getContractsForBundle

input json : 
{
  "bundle_id" : [identifiant de la liasse que nous voulons lister],
  "offset" : [position de notre fenêtre dans la liste globale composant la liasse],
  "size" : [taille de notre fenêtre]
}

On obtient en retour une liste structurée comme ceci :

{
    "elements": [{
        "companyName": "Dev",
        "city": "Paris",
        "customerName": "Seb",
        "contractTypeName": "Ad-Hoc",
        "picturesCount": 0,
        "optionStatus": [],
        "contractorName": "",
        "contractDefinitionDocumentToken": "",
        "contractDefinitionShowOptions": false,
        "bundleId": 22,
        "optionsList": [],
        "id": 1257,
        "date": 1479422547490,
        "vendorEmail": "test100@calindasoftware.com",
        "closed": false,
        "transactionId": "",
        "status": "OPEN",
        "customerEntityId": 0,
        "contractDefinitionId": 1,
        "customerNumber": "NC4xNDU1NTU3NjAxNTk0LjY2OTA0",
        "syncTimer": 1479422559940,
        "lastModificationPlace": "SERVER",
        "messageTitle": "",
        "messageBody": "",
        "filename": "consommations-client.pdf",
        "keepOnMove": 0,
        "actorId": 2,
        "parentContractId": 0
    }],
    "totalSize": 2
}

Pour soumettre une liasse à signature
Une fois qu’une liasse est entièrement complétée, il nous reste à la soumettre à la signature de tous les signataires en appelant :

https://[host]/calinda/hub/selling/do?m=deliverBundle&id=[identifiant de la liasse]

On obtient en retour si tout s’est bien passé :

{"Success":true}

Un email est alors envoyé vers les différents signataires dans lequel ils trouveront un lien leur permettant d’accéder à la page de signature de l’ensemble de la liasse.
Le lien ressemble à ceci :

https://[host]/calinda/hub/selling/dispatch.html?b_id=23&j_token=Emd8%21i%7CmgD58ggCx%2F2ySCeIRQON6zN%2F8yyiAmZ4%2FVpEcjZGpGV8dOII%2Bf5nyWAsOdfHk5eDKvEEQKTse%2Bz5DaMrQiCd1iHi9q081fiiWaenAI4ga%2BIw2T%2FfgScU1LqGrHFM0QrCQ64l%2BBCoIi9GYZtTH56VoqcprEE8NOM5uWqJpqkeHxKrwafqF4DNaw%3D%3D

Pour soumettre une liasse à signature via une iFrame

Une fois la liasse créée, il est possible de continuer le processus de signature directement depuis le cloud SELL&SIGN en intégrant une iframe à votre site. Pour réaliser cela, il faut déléguer l’authentification à l’utilisateur de votre site. Nous proposons une mécanique de token temporaire pouvant être restreint à certaines formes d’usages et/ou à l’accès à des contrats précis.

Création d’un token temporaire pour une liasse

Afin de limiter l’accès à la page de signature aux signataires que vous avez définis, vous devez générer un token temporaire qui permettra de les représenter et de contôler leurs accès.

La méthode à utiliser est :

https://[host]/calinda/hub/createTemporaryToken.action

Elle ne peut être appelée qu’en HTTP POST.

Le contenu des données POST doit être en JSON :

{ "actorId" : [actor_id], 
   "time" : [time],
   "profile": "sign_contract"
   "parameters" : { 
	"contract_definition_id": [liste de vos contract_definition_id],
	"customer_id" : [customer_id],
 	"contract_id" : [liste de vos contract_id],
	"contractor_id" : [contractor_id]
   }
}

actor_id : identifiant de l’utilisateur ‘guest’ qui vous sera fourni par Calinda
time : date en millisecondes UTC d’expiration du token
parameters : permet de définir le périmètre d’action autorisé du signataire. Insérez les identifiants de client, des contrats et de signataire obtenus précédemment.
Exemple :

{
	"actorId": 2,
	"profile": "sign_contract",
	"time": 2455557339385,
	"parameters": {
		"contractor_id": "841",
		"contract_id": [
			"8627",
			"8628"
		],
		"customer_id": "1234",
		"contract_definition_id": [
			"1",
			"71"
		]
	}
}

Le service retourne alors un token de ce type :

1P4o!Z|dkKdGePcpSMhJtDKfRofYKH+Ez2Jr8pCUmVFZVYGW/skM0b+gglYMsjhcmAP7DRFYVpmQegWd2Ugs5PoiWQoESrxBECk7Hvs+Q2jK0IgndaAEkmhyC99z5QUVLqiU+5MvfE9QuTD8Ex2H38qFfmmyPgtU4wTpMaK57CNye49ISc=

Affichage de la page de signature

Ce token s’emploie comme le token d’authentification décrit précédemment. Dans le cadre d’un usage par entête HTTP ou cookie, aucune modification n’est requise. En cas d’usage par paramètre (Query string), il faut « url encoder » le paramètre.

Exemple d’usage dans une iframe:

<html>
  <head>
  </head>
  <body>
    <iframe src="https://cloud.sellandsign.com/calinda/s/sign_contract_index.html?customer_number=1234&b_id=1071&j_token=%21%21%215tJ%7CS6Esy6OCRR62Jgp8df5JgUY2f2EoY3wFUmVFZVYGW%2FskM0b%2BgglYMsjhcmAP7DRFYVpmQegWd2Ugs5PoiWQoESrxBECk7Hvs%2BQ2jK0IgndaAEkmhyC99z5QUVLqiU%2B5MvfE9QuTD8Ex2H38qFfmmyPgtU4wTpMaK57CNye49ISc%3D">
    </iframe>
  </body>
</html>

Il sera nécessaire ici de préciser la valeur du paramètre customer_number et b_id qui sont respectivement le numéro de votre client et l’identifiant de votre liasse et de terminer par le token qui aura été généré précédemment.