Posicionar firma (opcional)

Si ya has probado la plataforma web de ZapSign, seguramente estés familiarizado con la funcionalidad de "Posicionar Firmas". Esta funcionalidad es completamente opcional y no influye en la validez legal del documento (la cual ya está garantizada por otros métodos de autenticación). Aun así, algunos clientes prefieren utilizar esta opción porque hace que el documento final se asemeje más a una firma física.

A continuación, encontrarás la documentación del endpoint, seguida de un tutorial para entender mejor cada uno de los campos y su funcionalidad.

Posicionar firmas e iniciales

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

Encabezado

Nombre	Tipo	Descripción
Authorization*	string	API token prefijo con la palabra "Bearer". Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

Request Body

Nombre	Tipo	Descripción
rubricas[type]	string	Hay dos tipos de rubricas: la firma "signature" o las iniciales "visto". Valor por defecto: "signature".
rubricas[page]	integer	Página donde se posicionará la firma o iniciales. Empieza en 0.
rubricas[relative_size_x]	number	El tamaño de la firma o iniciales. Mayor explicación a continuación
rubricas[relative_size_y]	number	El tamaño de la firma o iniciales. Mayor explicación a continuación
rubricas[relative_position_bottom]	number	Posición en la página de la firma o iniciales. Mayor explicación a continuación
rubricas[relative_position_left]	number	Posición en la página de la firma o iniciales. Mayor explicación a continuación
rubricas[signer_token]	string	Token del firmante (signer_toke) para posicionar la firma o iniciales.

200 Placement completed successfully.

Request

https://www.postman.com/zapsign/workspace/zapsign-workspace/request/27495556-c5d8b072-37cf-4e5d-a4b7-3b905f1e1140?ctx=documentationwww.postman.com

¿Cómo funciona el posicionamiento de firmas mediante la API?

ZapSign calcula dónde se posicionarán las firmas basándose en las coordenadas definidas en el JSON. A continuación, te explicamos cómo funciona:

We have the x-axis and y-axis starting at the lower left corner of each page.

El eje x y el eje y comienzan desde la esquina inferior izquierda de cada página del documento. Por ejemplo, la posición de la firma de "Fulano Silveira" en el lado derecho del documento correspondería al siguiente 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"
    }

A continuación, se detallan los campos:

Posicionamiento: relative_position_left y relative_position_bottom

Reglas matemáticas a seguir:

Estos valores determinan dónde aparecerá la firma en el documento. Es importante asegurarse de que la firma no quede fuera de los límites del documento. Por ejemplo, si relative_position_left es 80, entonces relative_size_x no debe ser mayor a 20, ya que la suma total (100 en el eje X) excedería los límites y la firma quedaría cortada.

Reglas matemáticas a seguir: 0 <= relative_size_y <= 100 0 <= relative_size_x <= 100 0 <= relative_position_bottom <= 100 0 <= relative_position_left <= 100

Y también 0 <= (relative_size_y + relative_position_bottom) <= 100 0 <= (relative_size_x + relative_position_left) <= 100

Tamaño proporcional: relative_size_x y relative_size_y

• Para documentos en formato vertical A4 (el más común), se recomienda usar

  • Firma: relative_size_x: 19.55 y relative_size_y: 9.42

  • Iniciales: relative_size_x: 13.76 y relative_size_y: 9.42

• Para documentos en formato horizontal A4, se recomienda usar:

  • Firma: relative_size_x: 15.05 y relative_size_y: 12.13

  • Iniciales: relative_size_x: 10.58 y relative_size_y: 12.13

Si deseas ajustar el tamaño, asegúrate de mantener la proporción multiplicando ambos valores por el mismo número.

Página (page)

El campo page corresponde al número de la página donde se colocará la firma, comenzando desde 0 (la primera página). Si deseas posicionar la firma en la misma posición en varias páginas, debes incluir un objeto por cada página en el JSON.

Por ejemplo:

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

Preguntas frecuentes

¿Cómo puedo verificar si la colocación de las firmas funcionó?

Puedes verificarlo directamente en el PDF después de que el documento haya sido firmado. Las validaciones deben hacerse de tu lado.

Si el posicionamiento fue incorrecta, ¿puedo corregirla?

Sí. Para reemplazar las firmas colocadas anteriormente, solo necesitas hacer un nuevo POST en esta ruta. Esto eliminará las firmas anteriores y las reemplazará con las nuevas.

¿Cómo cancelo el posicionamiento de firmas?

Puedes enviar un POST con el objeto rubricas vacío, por ejemplo: { "rubricas": [] }.

¿El documento firmado se actualiza cada vez que cambio la posición de las firmas?

¡No! Los cambios en la posición solo se aplicarán cuando un firmante firme el documento nuevamente. Por lo tanto, el documento no se actualizará automáticamente, sino después de una nueva firma.

Consejo: Si tus documentos no tienen una estructura estándar y no sabes las coordenadas, puedes posicionar las iniciales en la esquina superior derecha y la firma se mostrará en el informe de firmas.