iOS API: Managing the SELL&SIGN application

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

The integration of SELL&SIGN with another application on an Apple 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 App Store.

These exchanges between the two applications will be done via two modes according to your needs (and according to the constraints of the iOS platform):

  1. url scheme and
  2. UIDocumentInteractionController

As a prelude to this documentation, you can read this article which explains the two modes of operation: Inter-App Communication.

Pairing your application

The SELL&SIGN application requires user authentication to access its 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.

Use this method:

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], 
   "time" : [time]
}
  • email: email address of the user which will correspond to their login name
  • 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]&success_callback_url=[your callback url]&error_callback_url=[your callback url in case of failure]
  • 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 synchornization

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=[your callback url]&error_callback_url=[your callback url in case of failure]
  • 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 paramètres used for this url must be ‘encoded url’.

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

sellsign://sync/full?success_callback_url=[your callback url]&error_callback_url=[your callback url in case of failure]

Send a contract for signature

The iOS environment is very strict on inter app communication and sending a contract between our two applications requires a PDF (binary) file. The url schema will not be sufficient and it’s necessary to use the UIDocumentInteractionController or UIActivityViewController objects.

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

This file is structured according to the json format.

Example:

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

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 via the contract_definition_id parameter. The value of this parameter is provided to you when you subscribe to our services. The pdf_file_name parameter is used to name the contract file. Then the pdf_file_path parameter must contain a data uri of your pdf file. The binary part is encoded in base64.

The contract_properties block 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.

If the data is complete, the user is directly placed on the signature page when a contract is submitted to SELL&SIGN in this way. At the end of the signature, they will be offered to synchronize immediately or to do it later depending on the connection capacities available. Once this answer 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": 
    [
    	{
        	"path": "data:image/png;base64,JVBERi0x........",
        	"name": "cal.png",
        	"type": "image/png"
    	}, 
    	{
        	"path": "data:application/pdf;base64,JVBERi0x..",
        	"name": "notice.pdf",
        	"type": "application/pdf"
    	}
	]

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