Android 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 an Android mobile device is done by communication between your “host” application and the SELL&SIGN application. The SELL&SIGN application must first be installed on the mobile device from the Google Store.

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

1. url scheme and
2. android.content.Intent with an EXTRA_STREAM

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:

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 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:

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:

• 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’.

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:

• your return url (optional): this url should be based on a url schema of your own app. Exemple : 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’.

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

Sending a contract between the two applications requires a PDF (binary) file. The url schema will not be sufficient and complex, it is necessary to use the  android.content.Intent object and the startActivity method.

Intent shareIntent = new Intent();
shareIntent.setAction( Intent.ACTION_SEND );
shareIntent.putExtra( Intent.EXTRA_STREAM, Uri.fromFile( my_sellsign_file ) );
shareIntent.setType( "application/sellsign" );
startActivity( shareIntent );

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.

Example:

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.

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

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