Integration API

External Web/Native Application - API and Integration flow

Supported Functionalities

An external native/web application can push PDF documents to a user's SimpleSign instance with a request to sign.

When the user is in the web application session, the T1C-API enables the capability to push a PDF file from the web application to the local SimpleSign running in user space. The external application does not need to know a file location or system dependent info, pushing the document through the API is sufficient.

The external application can provide an external id, and a callback endpoint. The callback endpoint will be used by the SimpleSign, when a document signature process has been successfully completed, to push the signed PDF document towards the external application.

The requester can optionally choose to not receive the callback as Multipart/Form-data but as a application/json, in this case it will return the path to the signed document. Here the user can then choose to use the file-echange module to retrieve the document himself.

The follow image denotes the sequence diagram used for the integration of an external web application with SimpleSign, using the T1C-API (SimpleSign module).

External Application integration with LSA

T1C-SimpleSign Module API

When an application wants to interact with SimpleSign, the application needs to integrate with the SimpleSign CMS API.

Check SimpleSign CMS API availablility

This endpoint can be used to see if the CMS API is available

curl --location 'https://t1c.t1t.io:51984/v3/modules/simplesign' `
--header 'Origin: localhost'

The response will look like the following;

{
    "success": true,
    "data": {
        "version": "0.2.11",
        "localFolder": "/Users/gilles/Desktop/_lsa"
    }
}

Upload a document

The following endpoint will provide the capabilities to send a File to the SimpleSign application.

This is a multi-part/form-data request, with a fileName property and a file property.

curl --location 'https://t1c.t1t.io:51984/v3/modules/fileexchange/apps/file/download' `
--form 'file=@"..."' `
--form 'fileName="T1T_test_green.pdf"'

The response will look like the following

{
    "success": true,
    "data": {
        "name": "T1T_test_green_1729680589.pdf",
        "path": "/Users/gilles/Desktop/_lsa/_uploaded/_external/T1T_test_green_1729680589.pdf",
        "size": 322537,
        "lastModificationTime": "23/10/2024 10:49:49",
        "isDir": false,
        "access": "",
        "entity": "SimpleSign",
        "type": "UPLOAD"
    }
}

When you try to upload a file which already exists in the SimpleSign folders or Database it will automatically rename the file for you. The response will contain the new name in the name property and the full path to the file in the path property.

Upload a context

The following endpoint provides the capabilities to send the necessary context for a CMS file to SimpleSign. SimpleSign will use this context to determine where to send a result when the document has been successfully signed.

sendFile is an optional field. It is used to instruct SimpleSign to only return the fileName that has been signed. This can later be retrieved via the Download endpoint. If it is false or not set it will call the CallbackUrl as Multipart/form-data with the file included

externalId is also an optional field. and will be returned to the callback URL in either FormData or Json format, depending on the sendFile property

curl --location 'https://t1c.t1t.io:51984/v3/modules/simplesign' `
--header 'Content-Type: application/json' `
--data '{
    "filename": "T1T_test_green copy3_1729680589.pdf",
    "callback": "https://t1c.t1t.io:51984/hook",
    "sendFile": true,
    "externalId": "123456"
}'

The response as Multipart;

"fileName": String("T1T_test_green copy3_1729680589_signed.pdf"),
"file": Bytes(),
"createdAt": String("2024-10-23T10:49:56.104047+00:00"),
"updatedAt": String("2024-10-23T10:50:18.265913+00:00"),
"status": String("SIGNED"),
"externalId": String("123456")

The response as JSON;

{
    "fileName": "T1T_test_green copy3_1729680589_signed.pdf",
    "createdAt": "2024-10-23T10:49:56.104047+00:00",
    "updatedAt": "2024-10-23T10:50:18.265913+00:00",
    "status": "SIGNED",
    "externalId": "123456"
}

Download a document

If you have chosen to not send the file as Multipart in the callback flow you can use this endpoint to download the file.

curl --location 'https://t1c.t1t.io:51984/v3/modules/fileexchange/apps/file/upload' `
--header 'Content-Type: application/json' `
--data '{
    "filename": "T1T_test_green copy3_1729680589_signed.pdf"
}'

The response will be a streamed file.

Below an example of how this looks like in postman