# Posicionar firma (opcional)

## Posicionamiento con anclas de texto

Es posible definir dónde se colocarán las **firmas y rúbricas** en documentos **PDF o DOCX** utilizando **textos ancla**.\
Simplemente inserta un identificador, como `"<<signer1>>"`, en el documento, y la plataforma **posicionará automáticamente la firma o rúbrica exactamente donde aparezca este texto**.

**Consejo:** utiliza `<< >>` para evitar conflictos con palabras comunes del documento.

**Campos**

* **`signature_placement`**: define la ubicación de la **firma** utilizando un texto ancla.\
  Ejemplo: `"signature_placement": "<<signer1>>"`
* **`rubrica_placement`**: define la ubicación de la **rúbrica** utilizando un texto ancla.\
  Ejemplo: `"rubrica_placement": "<<signer1Rubrica>>"`

Si el texto aparece más de una vez, la firma o rúbrica se **colocará en todas las ubicaciones**.

**Dónde usar anclas**\
Las anclas pueden configurarse en los siguientes endpoints:

[Crear documento via Upload](https://docs.zapsign.com.br/espanol/documentos/criar-documento)

[Crear documento via Plantilla](https://docs.zapsign.com.br/espanol/documentos/criar-documento-via-modelo)

[Adicionar firmante](https://docs.zapsign.com.br/espanol/firmantes/adicionar-signatario)

[Actualizar firmante](https://docs.zapsign.com.br/espanol/firmantes/atualizar-signatario)

## Posicionamiento con coordenadas en el endpoint posicionar firmas

Es posible definir la posición exacta de cada firma o rúbrica utilizando coordenadas manuales.

<mark style="color:green;">`POST`</mark> `https://api.zapsign.com.br/api/v1/docs/{{doc_token}}/place-signatures/`

#### Encabezado

<table><thead><tr><th width="175">Nombre</th><th width="103">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>Authorization<mark style="color:red;">*</mark></td><td>string</td><td>API token prefijo con la palabra "Bearer". Ex: Bearer c7f35c84-7893-4087-b4fb-d1f06c23</td></tr></tbody></table>

#### Request Body

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

{% tabs %}
{% tab title="200 Placement completed successfully." %}

{% endtab %}
{% endtabs %}

### Request

{% embed url="<https://www.postman.com/zapsign/workspace/zapsign-workspace/request/27495556-c5d8b072-37cf-4e5d-a4b7-3b905f1e1140?ctx=documentation>" %}

### ¿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.](https://content.gitbook.com/content/5FrVBe47d9qwlLisqx07/blobs/ZF9XEASVvT3zZQmyLj6b/image.png)

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:

```javascript
    {
        "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&#x20;
  * **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:

```javascript
{
	"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.

{% hint style="info" %}
**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.
{% endhint %}