ZapSign API
English
English
  • General Information
  • Getting Started
  • ZapSign Environments
  • Ready-to-use requests!
  • Authentication
    • Static token
    • JWT Authentication
      • Get access token
      • Refresh your access token
  • Types of Tokens
  • API versioning
  • Rate Limit Policies
  • Incident alerts
  • How Payment Works
  • Status Code
  • Account
    • Plan Information
    • List account users
    • Create account users
    • Delete account user
  • Documents
    • Create document via Upload
    • OneClick (ClickWrap)
      • Create document (OneClick)
    • Create document via Template
    • Add attachment (extra document)
    • Add attachment (extra document) via Template
    • Detail document
    • List documents
    • Delete document
    • Document Audit Trail
    • Optional: Place signatures
    • Reject Documents
  • Signers
    • Detail signer
    • Update signer
    • Add signer
    • Delete signer
    • Batch sign via API
    • Reject Documents by User
  • Templates
    • Create template (DOCX)
      • Configure Template Form
    • List templates
    • Get template
    • Update template
    • Delete template
  • Partnerships
    • Update Payment Status
    • Create Account
  • TIMESTAMP
    • Add timestamp
  • Background Check
  • Introduction
  • Understanding the Result
  • Creating a Background Check
    • Person Check
    • Company check
  • Retrieve a Check
  • Check details
  • Webhooks
    • How webhooks works
    • Testing webhooks on ZapSign
    • Create Webhook
    • Webhooks logs
    • Events
      • Document
        • Doc created
        • Doc deleted
        • Created signer
      • Signer
        • Signature request send
        • Document viewed
        • Reading confirmation
        • Doc signed
        • Doc refused
        • Email bounce
        • Failed Validation
      • Background check
        • Background check completed
    • Reprocessing Documents and Webhooks
    • Delete Webhook
  • Widget
    • How widget works
Powered by GitBook
On this page
  • Place signatures
  • Request
  • How does positioning via API work?
  • relative_position_left e relative_position_bottom: Positioning the signature on the document
  • relative_size_x e relative_size_y: Keeping the signature proportionate
  • page: How to define the page where the signature will be placed
  • Frequently asked questions

Was this helpful?

  1. Documents

Optional: Place signatures

If you have tested ZapSign's web platform, you should have been familiar with the "Place Signatures" functionality. This functionality is completely optional and does not influence the legal validity of the document (which is already guaranteed by other forms of authentication). Even so, some customers still like to use this functionality as it makes the final document more like a physical signature.

Below is the endpoint documentation, followed by a tutorial to better understand each of these fields and functionality.

Place signatures

POST https://api.zapsign.com.br/api/v1/docs/{{doc_token}}/place-signatures/

Headers

Name
Type
Description

Authorization*

string

apiToken ahead of the "Bearer" text.

Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Request Body

Name
Type
Description

rubricas[type]

string

There are two types of rubrics possible, the "signature" or the "visto" (initials). Default: "signature".

rubricas[page]

integer

Page where the signature will be placed. Starts at 0.

rubricas[relative_size_x]

number

(Explained below)

rubricas[relative_size_y]

number

(Explained below)

rubricas[relative_position_bottom]

number

(Explained below)

rubricas[relative_position_left]

number

(Explained below)

rubricas[signer_token]

string

Signer token of the signature that will be placed

Request

How does positioning via API work?

How does ZapSign calculate where these signatures should be placed? According to the calculations below:

The position shown above, of the signature of "Fulano Silveira" in the right side of the document, would correspond to the JSON:

    {
        "page": 0, //1st document page
        "relative_position_bottom": 42.50, //distance from 0 to 100 from the bottom edge of the page
        "relative_position_left": 65.71, //distance from 0 to 100 from the left edge of the page
        "relative_size_x": 19.55, //size from 0 to 100 of signature compared to page width 
        "relative_size_y": 9.42, //size from 0 to 100 of signature compared to page height
        "signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg" //signer token of "Fulano Silveira"
    }

Below is a detailed explanation of each of the fields.

relative_position_left e relative_position_bottom: Positioning the signature on the document

It is necessary to take some care so that signatures are not left out of the document. For example, if relative_position_left is 80, relative_size_x must not be greater than 20 (totaling 100 which is the X axis). If this sum is greater than 100, the signature would be partly outside the document.

Mathematically speaking, your object must respect the following limits: 0 <= relative_size_y <= 100 0 <= relative_size_x <= 100 0 <= relative_position_bottom <= 100 0 <= relative_position_left <= 100

And also: 0 <= (relative_size_y + relative_position_bottom) <= 100 0 <= (relative_size_x + relative_position_left) <= 100

relative_size_x e relative_size_y: Keeping the signature proportionate

  • If your PDF is a vertical A4 sheet (most common), it is recommended to always use relative_size_x: 19.55 and relative_size_y: 9.42, as in the example above. If you want to increase the subscription size, multiply them by the same number so that the ratio is maintained.

    • Note: if it is a rubric with type "visto", relative_size_x: 13.76 and relative_size_y: 9.42 are recommended

  • If the PDF is a horizontal A4 sheet, relative_size_x: 15.05 and relative_size_y: 12.13 are recommended.

    • Note: if it is a rubric with type "visto", relative_size_x: 10.58 and relative_size_y: 12.13 is recommended

page: How to define the page where the signature will be placed

The page parameter is equivalent to each page of the document, starting at 0. If you want to place the signature in the same place on all pages, you need to pass the object more than once. For example:

{
	"rubricas":[
    {
        "page": 0, //1st document page
        "relative_position_bottom": 42.50, 
        "relative_position_left": 65.71, 
        "relative_size_x": 19.55, 
        "relative_size_y": 9.42, 
        "signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg"
    },
    {
        "page": 1, //2nd document page
        "relative_position_bottom": 42.50, 
        "relative_position_left": 65.71, 
        "relative_size_x": 19.55, 
        "relative_size_y": 9.42, 
        "signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg"
    }
  ]
}

Frequently asked questions

  • How do I know if the placement of signatures worked? A.: You will only know after the document is signed, directly checking the PDF. Validations must be done on your side.

  • If the positioning was done wrong, can I change it? A.: To overwrite the placement of the previous signatures, just make a new POST for this route, and all previous placements will be deleted and replaced by the new ones.

  • How can I cancel placement of signatures? A.: Just make a post with the rubrics object being an empty array. E.g.: {"rubricas":[ ]}

  • Is the signed document updated whenever I change the placement of the signatures? A.: No!!! The new placement will only be applied after a new signer signs the document. Thus, the document will not be updated every time you change the placement of signatures, but only when a signer signs.

PreviousDocument Audit TrailNextReject Documents

Last updated 5 months ago

Was this helpful?

https://www.postman.com/zapsign/workspace/zapsign-workspace/request/27495556-c5d8b072-37cf-4e5d-a4b7-3b905f1e1140?ctx=documentationwww.postman.com
We have the x-axis and y-axis starting at the lower left corner of each page.