> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Definir posição exata da chancela (admin)

> Marca o local onde a chancela do signatário será desenhada em um arquivo específico.

Define a posição exata onde a chancela visual deste signatário será desenhada em um arquivo específico. O posicionamento é **por signatário e por arquivo**: o mesmo signatário pode ter posições diferentes em documentos diferentes.

Esta rota é usada pelo passo "Posicionar assinatura" do assistente. Ao marcar a primeira posição em `OPERATOR`, o modo de posicionamento é automaticamente ajustado para `OPERATOR`.

**Autenticação**: `x-api-key` no header. Também aceita `Authorization: Bearer` com headers de projeto/organização.

## Unidades suportadas

| Unidade | Descrição | Exemplo |
| :- | :- | :- |
| `fraction` | Fração da página (0..1) | 0.5 = meio da página |
| `percent` | Percentual (0..100) | 50 = meio da página |
| `px` | Pixels do desenho renderizado | Exige `renderedPageWidth`/`renderedPageHeight` |
| `pt` | Pontos (1/72 polegada) | Padrão tipográfico |
| `mm` | Milímetros | Medida do papel |
| `cm` | Centímetros | Medida do papel |
| `in` | Polegadas | Medida do papel |

## Parâmetros

**uuid** `string` *required*

UUID do envelope.

**signerUuid** `string` *required*

UUID do signatário.

**fileUuid** `string` *required*

UUID do arquivo.

**page** `number` *required*

Página onde a chancela será desenhada, contando a partir de **1** (não 0).

Exemplo: `1` para a primeira página, `2` para a segunda.

**left** `number` *required*

Distância da borda esquerda da página, na unidade declarada em `unit`.

**top** `number` *required*

Distância da borda indicada por `origin` (padrão: topo), na unidade de `unit`.

**unit** `enum` *required*

Unidade de medida: `fraction`, `percent`, `px`, `pt`, `mm`, `cm`, `in`.

**origin** `enum` (default: top-left)

De qual borda o `top` é medido:

* `top-left`: medição a partir do topo (padrão, como na tela).
* `bottom-left`: medição a partir do fundo.

**renderedPageWidth** `number`

**Obrigatório se `unit` é `px`**: largura, em pixels, com que a página foi desenhada na tela.

Exemplo: se a página tem 827px de largura quando renderizada, passe `827`.

**renderedPageHeight** `number`

**Obrigatório se `unit` é `px`**: altura, em pixels, com que a página foi desenhada na tela.

## Respostas

**signerUuid** `string`

UUID do signatário.

**fileUuid** `string`

UUID do arquivo.

**currentPage** `number | null`

Página gravada, contando a partir de **0**. `null` quando não há marcação.

**positionLeft** `number | null`

Fração da largura da página, a partir da borda esquerda (0..1). `null` quando não há marcação.

**positionTop** `number | null`

Fração da altura da página, a partir do **topo** (0..1). `null` quando não há marcação.

## Erros

* **400**: Posição fora dos limites da página, página não existe no documento, ou `px` enviado sem as dimensões renderizadas.
* **401**: Autenticação ausente ou inválida.
* **404**: Envelope, signatário ou arquivo não encontrado neste projeto.
* **409**: Signatário já assinou; a chancela não pode mais ser movida.

```json theme={"theme":"catppuccin-latte"}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "signerUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fileUuid": "f1f2f3f4-f5f6-7890-abcd-ef1234567890",
  "currentPage": 0,
  "positionLeft": 0.25,
  "positionTop": 0.35
}
```

```json theme={"theme":"catppuccin-latte"}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "statusCode": 400,
  "message": "Placement falls outside the page."
}
```

```json theme={"theme":"catppuccin-latte"}
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "statusCode": 409,
  "message": "Signer already signed; the stamp can no longer be moved."
}
```

## Exemplos

### Usando fração (0..1)

```bash theme={"theme":"catppuccin-latte"}
curl -X PUT "https://api.valid.com/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/signers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/f1f2f3f4-f5f6-7890-abcd-ef1234567890/position" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "left": 0.25,
    "top": 0.35,
    "unit": "fraction"
  }'
```

### Usando pixels do desenho renderizado

```bash theme={"theme":"catppuccin-latte"}
curl -X PUT "https://api.valid.com/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/signers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/f1f2f3f4-f5f6-7890-abcd-ef1234567890/position" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "left": 200,
    "top": 350,
    "unit": "px",
    "renderedPageWidth": 827,
    "renderedPageHeight": 1169
  }'
```

### Usando milímetros (medida do papel)

```bash theme={"theme":"catppuccin-latte"}
curl -X PUT "https://api.valid.com/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/signers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/f1f2f3f4-f5f6-7890-abcd-ef1234567890/position" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "left": 50,
    "top": 80,
    "unit": "mm"
  }'
```

## Remover posicionamento

Para voltar ao comportamento padrão (chancela na grade de assinaturas), use:

```bash theme={"theme":"catppuccin-latte"}
curl -X DELETE "https://api.valid.com/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/signers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/f1f2f3f4-f5f6-7890-abcd-ef1234567890/position" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Importante

* **Por arquivo**: o posicionamento é guardado por arquivo. Não há posição global para o signatário.
* **Rejeita se assinado**: uma vez que o signatário assinou, a posição não pode ser alterada.
* **DELETE sem corpo**: para remover o posicionamento, use DELETE simples (sem JSON body).
* **Modo automático**: marcar a primeira posição em modo `MANIFEST` muda automaticamente para `OPERATOR`.
* **Resolução limitada**: as colunas `position_left` e `position_top` têm precisão de \~1% da página (cerca de 2 mm na horizontal).

## Próximas etapas

* Use [`PUT .../:uuid/signers/:signerUuid/placement-mode`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-envelope-signer-placement-mode) para controlar quem decide o local (admin, operador ou signatário).
* Use [`POST .../:uuid/send`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/post-envelope-send) para enviar o envelope aos signatários.

## Relacionado

* [`PUT .../:uuid/signers/:signerUuid/placement-mode`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-envelope-signer-placement-mode) — definir modo de posicionamento
* [`PUT /v1/sign/:sessionToken/files/:fileUuid/position`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-sign-session-files-position) — signatário posiciona na assinatura


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.