Create, seal or sign and download new PDF document

Introduction

In this scenario, the goal is to create and seal (or sign) new PDF document and download the completed file. To achieve this, the following steps will be taken:

• Upload a file: The first step is to create a file that will be used to store the PDF document.

• Create document: New PDF document will be created.

• Retrieve document: Once the document has been created, it will be retrieved from the storage to show additional data needed in following steps.

• Seal or sign the document: The PDF document will be sealed or signed to ensure its authenticity and prevent any unauthorized modifications. This can be done using various techniques such as adding digital signatures or applying certification. Once the document is sealed or signed, it will be ready for distribution or download.

  

  To clearly understand difference between seal and sign please read following article - What is the difference between a signature and a seal?

• Download: Once the document is completed it is now ready to be downloaded from Circularo to your local storage or integration software.

Step 1 - Sign in (optional)

Sign user in.

Please note that this step is optional, we recommend you create an API key to be used as a token with all requests - Create new API key

Read more about authentication - Authentication

Endpoint

POST /login

Request

POST /login

Content-Type: application/json

{
  "name": "mary.griffin@circularo.com",
  "password": "#32Password1!",
  "tenant": "default"
}

Response

Note following properties in response object:

• token - In response object at position token.

  • It may have value of nTZExBi4jl1NTlpJsco6VWZnzWjt8QUZ0np8YSN8YKc3G6CBAZiNHQNN1kbR21ps.

• signatureFileId - In response object at position user.config.signature[0].imageId.

  • It may have value of 5fYu41Rg0KvSqKjADG5FYjvHkZj0dqyaBUyjd9ka4zHDbU2RQ3jDsMebeHMhMfAu.

Step 2 - Upload file

Upload new PDF file to the Circularo storage from which the document will be created.

Read more about file creation - Create file

Endpoint

POST /files/saveFile

Request

POST /files/saveFile?token=nTZExBi4jl1NTlpJsco6VWZnzWjt8QUZ0np8YSN8YKc3G6CBAZiNHQNN1kbR21ps

Content-Type: multipart/form-data

{
  "file": "blob",
  "fileName": "My PDF file"
}

Response

Note following properties in response object:

• fileHash - In response object at position file.id.

  • It may have value of aTnA9Mw9GqLICr0UJmIKrrI2iWekBXTxefgRo2x9qql25f6Ela4dhqHmbUOJF0ul.

The file is now created.

Step 3 - Create document from file

Create new document from existing PDF file in storage.

Read more about document creation - Create document

Read more about Circularo documents - Document structure

Endpoint

POST /documents

Request

POST /documents?token=nTZExBi4jl1NTlpJsco6VWZnzWjt8QUZ0np8YSN8YKc3G6CBAZiNHQNN1kbR21ps

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "My Document",
    "pdfFile": {
      "content": "aTnA9Mw9GqLICr0UJmIKrrI2iWekBXTxefgRo2x9qql25f6Ela4dhqHmbUOJF0ul"  //specify existing file hash
    }
  },
  "definitionType": "ext",
  "workflow": "wf_archive",
  "optionalData": {
    "folder": "8338e0b9-401d-4361-a1b9-a59f6bc78838"  //optional - specify to which folder document will be placed
  }
}

Response

Note following properties in response object:

• documentId - In response object at position results[0].documentId.

  • It may have value of e0e6d813-2c78-46ec-a4b6-71b5413ac8d9.

The PDF document is now created.

Step 4 - Retrieve document info

Retrieve document information. This step is required in order to obtain document version which is needed in following requests.

Read more about document retrieval - Retrieve the document

Endpoint

GET /documents/:documentId

Request

GET /documents/e0e6d813-2c78-46ec-a4b6-71b5413ac8d9?token=nTZExBi4jl1NTlpJsco6VWZnzWjt8QUZ0np8YSN8YKc3G6CBAZiNHQNN1kbR21ps

Response

Note following properties in response object:

• documentVersion - In response object at position results[0]._version.

  • It may have value of 6.

Returned object contains additional information about the document.

If any of following endpoint fails with status code '409 - Version mismatch', please call this endpoint again to receive updated document version. There may be some background tasks that change document version after it is created.

Step 5A - Seal the document

Put a seal on the document = apply electronic certificate

Read more about document seal - Seal the document

Endpoint

PUT /documents/seal/:documentVersion

Path parameters:

• documentVersion - Document version taken from previous step.

Request

PUT /documents/seal/6?token=nTZExBi4jl1NTlpJsco6VWZnzWjt8QUZ0np8YSN8YKc3G6CBAZiNHQNN1kbR21ps

Content-Type: application/json

{
  "id": "e0e6d813-2c78-46ec-a4b6-71b5413ac8d9"
}

Step 5B - Sign the document

Apply electronic certificate and insert image of your signature.

Read more about document signing - Sign the document

Endpoint

PUT /documents/sign/:documentVersion

Path parameters:

• documentVersion - Document version taken from previous step.

Request

PUT /documents/sign/6?token=nTZExBi4jl1NTlpJsco6VWZnzWjt8QUZ0np8YSN8YKc3G6CBAZiNHQNN1kbR21ps

Content-Type: application/json

{
  "signatures": [
    {
      "pages": [  //specify on which page should the signature be placed
        1
      ],
      "position": {  //position and size of the signature in the document page
        "percentX": 0.5336425978217023,
        "percentY": 0.2360980475986889,
        "percentWidth": 0.3910665378654381,
        "percentHeight": 0.1
      },
      "blob": "5fYu41Rg0KvSqKjADG5FYjvHkZj0dqyaBUyjd9ka4zHDbU2RQ3jDsMebeHMhMfAu",  //signature image
      "decorationType": "empty",
      "type": "signature",  //other possible types: initials, stamp, wacom, annotation, and image
      "timestamp": false  //if true places timestamp under the signature
    }
  ],
  "id": "e0e6d813-2c78-46ec-a4b6-71b5413ac8d9"  //ID of the document you want to sign
}

Step 6 - Download signed document

Download completed document with electronic certificate or inserted signature.

Read more about document download - Download document file

Endpoint

GET /files/loadFile/hash/:hash

Path parameters:

• hash - The file hash of the document you want to download.

Request

GET /files/loadFile/hash/aTnA9Mw9GqLICr0UJmIKrrI2iWekBXTxefgRo2x9qql25f6Ela4dhqHmbUOJF0ul?token=nTZExBi4jl1NTlpJsco6VWZnzWjt8QUZ0np8YSN8YKc3G6CBAZiNHQNN1kbR21ps

The response of the API call will be the main file of the specified document.