Integration Example

Walk-through

Push PDF document from external application to SimpleSIgn

In this walk-through example, we guide you through the following use case:

From an external web application, ask a user to digitally sign a PDF document using his local SimpleSign application. Once the PDF document has been locally signed by the user, the external application will receive the document using a callback URL.

Prepare to use SimpleSign API

Health check for the SimpleSign module

Verify the SimpleSign CMS module is enabled:

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

Response:

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

The response contains the SimpleSign version installed on your system, and the SimpleSign application folder selected by the user upon startup.

When no SimpleSign has been detected, you will not be able to continue from here.

Push PDf document

The external application can push a new PDF document in 2 steps:

• upload PDF file

• request digital signature - including metadata -

See the sequence diagram

To upload a PDF file, you can use the download function

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

The result of the file upload, is that the file will be uploaded (from the application point of view) to the SimpleSign exchange folder.

The request above is sent to 'download' as the naming is done from a user perspective. Don't be confused, when an application pushes a new PDF document, 'download' endpoint is the correct one 👍

The response will return the information of the file uploaded. This is important as you will need to use the name in the request for adding context information.

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.

After the preceding request, nothing will happen, until the external application pushed the context information as well.

This can be done by sending a request to the SimpleSign CMS module:

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

After a successful request of the latter, the PDF document will be picked up by SimpleSign and will be available in the user's Inbox folder 👏.

You can choose to not receive the actual file in the callback by adding the sendFile property and setting it to false.

This will send the callback not in Multipart form-data but as JSON, the name can then be used with the Download function to get the actual PDF document.

An example json with sendFile propety being false (not returning with Multipart form-data);

{
    "filename": "app_pdf_to_sign.pdf",
    "callback": "https://some_url/hook",
    "sendFile": false,
    "externalId": "some_uuid_or_opaque_id"
}

Receive Signed PDF document

When the document has been signed, the SimpleSign CMS module will send the document information to the defined callback.

Depending on the sendFile property this will be in either application/json or in form-data

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

If you have chosen to get the signed document information as JSON you will need to retrieve the file via the SimpleSign CMS API.

This can be done with the download endpoint. The filename property will be the file received in the callback

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 image on how this looks like in postman