ZapSign API
Search…
Opcional: Posicionar assinaturas
Caso você tenha testado a plataforma Web da ZapSign, deve ter conhecido a funcionalidade "Posicionar assinaturas". Essa funcionalidade é totalmente opcional e não influencia na validade jurídica do documento (que já está assegurada pelas demais formas de autenticação). Mesmo assim, alguns clientes ainda gostam de utilizar essa funcionalidade por deixar o documento final mais parecido com uma assinatura física.
Abaixo, há a documentação do endpoint, seguida por um tutorial para entender melhor cada um desses campos e a funcionalidade.
post
https://api.zapsign.com.br
/api/v1/docs/{{doc_token}}/place-signatures/?api_token={{seu_token_de_acesso}}
Posicionar assinaturas
Exemplo de requisição:
1
{
2
"rubricas":[
3
{
4
"page": 0, //primeira página do documento
5
"relative_position_bottom": 42.50,
6
"relative_position_left": 65.71,
7
"relative_size_x": 19.55,
8
"relative_size_y": 9.42,
9
"type":"signature",
10
"signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg" // Token do signatário Fulano
11
},
12
{
13
"page": 1, //segunda página do documento
14
"relative_position_bottom": 13.50,
15
"relative_position_left": 20.71,
16
"relative_size_x": 19.55,
17
"relative_size_y": 9.42,
18
"type":"visto",
19
"signer_token": "aaaaabbbcc-03d3-468b-97ce-3061e3defg" // Token do signatário Siclano
20
}
21
]
22
}
Copied!

Antes de começar, veja como a funcionalidade funciona na plataforma web:

Se ainda não conhece, veja abaixo:
Após subir um novo documento, clique em "Opcional: Posicionar assinaturas"
A assinatura do signatário será posicionada nesses campos.

Como funciona o posicionamento via API?

E como a ZapSign calcula onde essas assinaturas devem ser posicionadas? De acordo com os cálculos abaixo:
Temos o eixo x e eixo y começando no canto inferior esquerdo de cada página.
O posicionamento acima representado, da assinatura de "Fulano Silveira" na metade direita do documento, corresponderia ao JSON:
1
{
2
"page": 0, //primeira página do documento
3
"relative_position_bottom": 42.50, //distância de 0 a 100 da extremidade inferior da página
4
"relative_position_left": 65.71, //distância de 0 a 100 da extremidade esquerda da página
5
"relative_size_x": 19.55, //tamanho de 0 a 100 da assinatura em comparação à largura da página
6
"relative_size_y": 9.42, //tamanho de 0 a 100 da assinatura em comparação à altura da página
7
"signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg" //token do signatário "Fulano Silveira"
8
}
Copied!
Abaixo segue uma explicação detalhada de cada um dos campos.

relative_position_left e relative_position_bottom: Posicionando a assinatura no documento

É necessário tomar alguns cuidados, para que as assinaturas não fiquem fora do documento. Por exemplo, se o relative_position_left for de 80, o relative_size_x não deve ser maior do que 20 (totalizando 100 que é o eixo X). Se essa soma for maior do que 100, a assinatura ficaria em parte para fora do documento.
Matematicamente falando, seu objeto deve respeitar os seguintes limites: 0 <= relative_size_y <= 100 0 <= relative_size_x <= 100 0 <= relative_position_bottom <= 100 0 <= relative_position_left <= 100 E também: 0 <= (relative_size_y + relative_position_bottom) <= 100 0 <= (relative_size_x + relative_position_left) <= 100

relative_size_x e relative_size_y: Mantendo a proporção da assinatura

    Caso seu PDF seja uma folha A4 vertical (mais comum), recomenda-se utilizar sempre os valores relative_size_x: 19.55 e relative_size_y: 9.42, como no exemplo acima. Se você quiser aumentar o tamanho da assinatura, multiplique-os pelo mesmo número, para que a razão seja mantida.
      Obs.: caso se trate de uma rubrica com type "visto", recomenda-se relative_size_x: 13.76 e relative_size_y: 9.42
    Caso o PDF seja uma folha A4 horizontal, recomendam-se os valores de relative_size_x: 15.05 e relative_size_y: 12.13.
      Obs.: caso se trate de uma rubrica com type "visto", recomenda-se relative_size_x: 10.58 e relative_size_y: 12.13

page: Como definir a página em que a assinatura será posicionada

O parâmetro page equivale a cada página do documento, começando no 0. Se você quiser posicionar a assinatura no mesmo local em todas as páginas, é necessário passar o objeto mais de uma vez. Por exemplo:
1
{
2
"rubricas":[
3
{
4
"page": 0, //primeira página do documento
5
"relative_position_bottom": 42.50,
6
"relative_position_left": 65.71,
7
"relative_size_x": 19.55,
8
"relative_size_y": 9.42,
9
"signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg"
10
},
11
{
12
"page": 1, //segunda página do documento
13
"relative_position_bottom": 42.50,
14
"relative_position_left": 65.71,
15
"relative_size_x": 19.55,
16
"relative_size_y": 9.42,
17
"signer_token": "cf1c0b7a-03d3-468b-97ce-3061e3abcdefg"
18
}
19
]
20
}
Copied!

Dúvidas que você pode ter

    Como eu sei se o posicionamento das assinaturas deu certo? R.: Você só saberá depois que o documento for assinado, conferindo diretamente o PDF. As validações devem ser feitas do seu lado.
    Caso o posicionamento tenha sido feito errado, tem como eu mudar? R.: Para sobrescrever o posicionamento das assinaturas anterior, basta fazer um novo POST para essa rota, que todos posicionamentos anteriores serão deletados e substituídos pelos novos.
    Como eu posso cancelar o posicionamento de assinaturas? R.: Basta fazer um post com o objeto rubricas sendo um array vazio. Ex: {"rubricas":[ ]}
    O documento assinado é atualizado sempre que eu mudar o posicionamento das assinaturas? R.: Não!!! O novo posicionamento só será aplicado depois que um novo signatário assinar o documento. Isto é, o documento não será atualizado toda vez que você alterar o posicionamento de assinaturas, mas apenas quando algum signatário assinar.
Last modified 4mo ago