API: Creation and use of bundles

« Bundle » definition
A bundle makes it possible to associate several contracts that can be signed at once by one or more signatories.
To combine several contracts into a single bundle, it is necessary to carry out the steps of contract creation and association of signatories as seen in the previous pages.

Creating a Bundle

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

input json:
{
  "actor_id" : [bundle owner id],
  "contract_id": [id of the first contract to be added to the bundle]
}

In return, we obtain a bundle object which ‘ID’ attribute is the identifier that will be reused later:

{
    "id": 22,  //bundle id
    "actorId": 2,
    "contractId": 1257,
    "status": 0,
    "master": 1,  // 1 indicates this is the first contract of the bundle
    "syncTimer": 1479422641270,
    "lastModificationPlace": "SERVER"
}

Add another contract to the bundle
The call is very simple, just refer to the previously created bundle by specifying the returned identifier.

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

input json:
{
  "id" : [bundle id],
  "actor_id" : [bundle user id],
  "contract_id" : [id of the contract to be associated]
}

In return, we get the bundled object with the new associated contract this time:

{
    "id": 22, // bundle id
    "actorId": 2,
    "contractId": 1258,
    "status": 0,
    "master": 0,
    "syncTimer": 1479422646540,
    "lastModificationPlace": "SERVER"
}

It is possible to add as many contracts to the bundle as you like.

List the contents of a bundle
It is possible to retrieve a complete or paginated list of our bundle by calling:

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

input json : 
{
  "bundle_id" : [id of the bundle that we want to display],
  "offset" : [our window position in the global bundle list],
  "size" : [list size]
}

In return, you get a structured list like this:

{
    "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
}

To submit a bundle for signature
Once a bundle is fully completed, you then submit it for signature by calling:

https://[host]/calinda/hub/selling/do?m=deliverBundle&id=[bundle id]

In retrun, you get this, if everything went well:

{"Success":true}

An email is then sent to the different signatories, and they will find a link allowing them to access the signature page of the whole bundle.
The link looks like this:

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

To submit a bundle for signature with an iFrame

Once the bundle has been created, it is possible to continue the signing process directly from the SELL&SIGN cloud by integrating an iframe into your website. To achieve this, you need to delegate the authentication to your web user. We offer a temporary token system that can be restricted to certain forms of use or access to specific contracts.

Creation of a temporary token for a bundle

In order to limit access to the signature page to the signatories you have defined, you must generate a temporary token to represent them and control their access.

The method to use is:

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

It can only be called in HTTP POST.

The content of POST data must be in JSON:

{ "actorId" : [actor_id], 
   "time" : [time],
   "profile": "sign_contract"
   "parameters" : { 
	"contract_definition_id": [your contract_definition_id list],
	"customer_id" : [customer_id],
 	"contract_id" : [your contract_id list],
	"contractor_id" : [contractor_id]
   }
}
  • actor_id: a ‘guest’ user id that will be given to you by Calinda
  • time: date in UTC milliseconds of the expiry of the token
  • parameters: allows you to define the signatory’s authorized scope of action. Insert the customer, contract, and signatory IDs obtained previously.

    Example:

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

The service then returns a token of this type:

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

Display of the signature page

This token is used like the authentication token described previously. To use in a HTTP header or cookie, no modification is required. In case of use by parameter (Query string), the parameter must be « url encoded ».

Example of usage in an 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>

It will be necessary here to specify the value of the parameter customer_number and b_id which are respectively the number of your customer and the identifier of your bundle and to finish with the token that has been generated previously.