UWP API: Managing the SELL&SIGN application

The SELL&SIGN mobile application is designed to be used as a stand-alone application, but also to be interfaced to other applications that can use it to sign evidentiary contracts on mobile phones.

The integration of SELL&SIGN with another application on a Windows device is done by communication between your “host” application (UWP) and the SELL&SIGN application. The SELL&SIGN application must therefore be installed on your device beforehand from the Microsoft Store.

These exchanges between the two applications take place in two modes according to the needs:

  1. url scheme and
  2. Windows.System.Launcher.LaunchFileAsync with a StorageFile

Pairing your application

The SELL&SIGN application requires user authentication to access their dedicated environment in our cloud. To avoid that the user has to enter his password when opening SELL&SIGN from your application, you can create an authentication token with a secure dialog between your servers and the SELL&SIGN cloud.

As with displaying the signature page, you can then create a temporary token that you provide to your application.

The method to use is:

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

It can only be called in HTTP POST. This call requires you to use your API token as described on this Authentication page.

The content of the POST data must be in JSON:

{ email : [email],<br />
time : [time]
}
  • email: email address of the user which will correspond to their login username
  • time: date in UTC milliseconds of the token’s expiration

The service then returns a token of this type:

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

App-to-App call URL

When installed, the SELL&SIGN application, declares the use of the following url scheme: sellsign://

To perform the pairing based on the token you have generated from your server, your application can call the following url:

sellsign://auth?token=[your token]&amp;success_callback_url=[your return url]&amp;error_callback_url=[your error return url]
  • your token: the encoded url token you received in the previous chapter.
  • your return url (optional): this url must be based on a url schema specific to your application. Example: myapp://sellsign/auth/ok
  • your error return url (optional): this url must be based on a url schema specific to your application. Example : myapp://sellsign/auth/error . SELL&SIGN will add a message parameter containing the encoded url message of the error.

All the parameters used for this url must be ‘encoded url”.

Request a synchronization

Since the SELL&SIGN application has offline capabilities, it may be interesting to request up/down synchronization of data if your application has the same capabilities.

To do so, simply call the following url:

sellsign://sync/incremental?success_callback_url=[votre url de retour]&amp;error_callback_url=[votre url de retour en cas d'erreur]
  • your return url (optional): this url must be based on a url schema specific to your application. Example: myapp://sellsign/auth/ok
  • your error return (optional): this url must be based on a url schema specific to your application. Example : myapp://sellsign/auth/error . SELL&SIGN will add a message parameter containing the encoded url message of the error.

All the parameters used for this url must be ‘encoded url’.

This action allows to perform an incremental synchronization, but sometimes you may need to perform a complete synchronization by calling the next url:

sellsign://sync/full?success_callback_url=[votre url de retour]&amp;error_callback_url=[votre url de retour en cas d'erreur]

Send a contract for signature

Sending a contract between our two applications requires a PDF (binary) file. The url schema will not be sufficient and complex, it is necessary to use the object: https://docs.microsoft.com/en-us/windows/uwp/launch-resume/launch-the-default-app-for-a-file.


using Windows.Storage;<br />
using Windows.System;</p>
[...]
<p>StorageFile file = await ApplicationData.Current.LocalFolder.GetFileAsync(image_file_name);<br />
LauncherOptions options = new LauncherOptions();<br />
options.DisplayApplicationPicker = true;<br />
if (file != null)<br />
{<br />
// Launch the retrieved file<br />
var success = await Launcher.LaunchFileAsync(file, options);</p>
<p>if (success)<br />
{<br />
// File launched<br />
}<br />
else<br />
{<br />
// File launch failed<br />
}<br />
}<br />
else<br />
{<br />
// Could not find file<br />
}<br />

The SELL&SIGN application declares itself to be the receptacle for files of the type: .sellsign or application/sellsign. You will generate a .sellsign file containing information about the contract, customer, signatories, and also the pdf file.

This file is structured according to the json format.

Exemple :

{<br />
"customer":<br />
{<br />
"number": "my_customer_number",<br />
"mode": 2,<br />
"contractor_id": -1,<br />
"fields":<br />
[<br />
{<br />
"key": "firstname",<br />
"value": "Jean"<br />
},<br />
{<br />
"key": "lastname",<br />
"value": "Dupont"<br />
},<br />
{<br />
"key": "civility",<br />
"value": "MONSIEUR"<br />
},<br />
{<br />
"key": "companyName",<br />
"value": "cal"<br />
}<br />
]
},<br />
"contractors":<br />
[<br />
],<br />
"contract":<br />
{<br />
"contract_definition_id": 1,<br />
"pdf_file_name":"my_contract.pdf",<br />
"pdf_file_path": "data:application/pdf;base64,JVBERi.....UlRU9GCg==",<br />
"contract_id": -1<br />
},<br />
"contract_properties":<br />
[<br />
{<br />
"key": "my_internal_contract_id",<br />
"value": "AF72379987",<br />
"to_fill_by_user" : 0<br />
}<br />
],<br />
"files":<br />
[<br />
],<br />
"options":<br />
[<br />
],<br />
"error_callback_url": "myapp://error?id=AF72379987",<br />
"success_callback_url": "myapp://success?id=AF72379987"<br />
}

The ‘customer‘ block defines the customer to whom the contract is addressed. It is defined by a unique customer ‘number‘. The signature ‘mode‘ can be defined with:

  • 1: directly by text message
  • 2: by initials (handwritten signature)
  • 3: by email + text message

The ‘fields’ subpart of the ‘customer’ block allows you to define all the fields to be filled in for the customer. The list of supported fields is available here.

The ‘contract‘ block defines the content of the contract and the reference to a standard contract by its identifier with the ‘contract_definition_id‘. The value of this parameter is provided to you when you subscribe to our services. The parameter ‘pdf_file_name‘ is used to name the contract file. Then the parameter ‘pdf_file_path‘ must contain a data uri of your pdf file. The binary part is encoded in base64.

The block ‘contract_properties‘ allows you to define one or more key-value elements which will be associated to the contract.

As in the case of the url schema, it is possible to obtain callbacks with ‘success_callback_url‘ and ‘error_callback_url‘.

When a contract is submitted to SELL&SIGN in this way, the user is directly placed on the signature page if the data is complete. At the end of the signature, they will be offered to synchronize immediately or to do it later depending on the available connection capacities. Once this response is given, callbacks are called.

Adding attachments

To attach attachments to a contract, you must add ‘file’ elements to the ‘files’ list as follows:

 "files":<br />
[<br />
{<br />
"path": "data:image/png;base64,JVBERi0x........",<br />
"name": "cal.png",<br />
"type": "image/png"<br />
},<br />
{<br />
"path": "data:application/pdf;base64,JVBERi0x..",<br />
"name": "notice.pdf",<br />
"type": "application/pdf"<br />
}<br />
]

The ‘path’ attribute must therefore contain the file in a data uri format as for the contract seen above.

What should I do if my application does not know how to generate a PDF?

It's not easy to generate a PDF on an iOS mobile device. So it's possible that your application doesn't know how to do it. No problem, it can ask SELL&SIGN to generate it for it!

Get your PDF generated by SELL&SIGN!

By using a contract template associated to a PDF template and by setting the options to be filled in, you can get SELL&SIGN to generate the PDF before signing!

We'll assist you