> ## 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.

# Signatário posiciona a chancela na assinatura

> Permite que o signatário arraste e posicione a chancela durante o processo de assinatura.

Permite que o signatário defina a posição exata da sua chancela visual enquanto está assinando. Esta operação é chamada quando o signatário arrasta a chancela na tela de assinatura antes de confirmar a assinatura.

O signatário só pode usar esta rota se o modo de posicionamento estiver definido como `SIGNER` (veja [`PUT .../:uuid/signers/:signerUuid/placement-mode`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-envelope-signer-placement-mode)).

**Autenticação**: via `sessionToken` do signatário (extraído da URL).

## 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

**sessionToken** `string` *required*

Token da sessão de assinatura do signatário (extração automática da URL).

**fileUuid** `string` *required*

UUID do arquivo sendo assinado.

**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 (extração automática da sessão).

**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**: Token inválido ou ausente.
* **404**: Arquivo não encontrado neste envelope.
* **409**: Uma das seguintes condições: signatário não está em modo `SIGNER`, já assinou, ou o envelope força todas as assinaturas para a página final.

```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 409 Conflict
Content-Type: application/json

{
  "statusCode": 409,
  "message": "Signer is not in SIGNER mode or already signed."
}
```

## Exemplos

### Signatário usando fração (0..1)

```bash theme={"theme":"catppuccin-latte"}
curl -X PUT "https://api.valid.com/v1/sign/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../files/f1f2f3f4-f5f6-7890-abcd-ef1234567890/position" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "left": 0.25,
    "top": 0.35,
    "unit": "fraction"
  }'
```

### Signatário usando pixels do desenho renderizado

```bash theme={"theme":"catppuccin-latte"}
curl -X PUT "https://api.valid.com/v1/sign/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../files/f1f2f3f4-f5f6-7890-abcd-ef1234567890/position" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "left": 200,
    "top": 350,
    "unit": "px",
    "renderedPageWidth": 827,
    "renderedPageHeight": 1169
  }'
```

## Fluxo de assinatura

1. Signatário acessa a tela de assinatura (sessão de token).
2. Se o modo é `SIGNER`, a interface mostra o gesto de arrastar a chancela.
3. Signatário arrasta a chancela e esta rota é chamada para gravar a posição.
4. Signatário confirma a assinatura com [`POST /v1/sign/:sessionToken/verification/confirm`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/post-sign-session-verification-confirm).

## Importante

* **Modo requerido**: rejeita com **409** se o modo não for `SIGNER`.
* **Após assinatura**: rejeita com **409** se o signatário já assinou.
* **Configuração do envelope**: rejeita se `forceAllSignaturesToEndPage` estiver ativada.
* **Sem ID automático**: o signatário não pode escolher qual signatário está posicionando; é sempre ele próprio (extraído do token).
* **Nenhuma autorização requerida além do token**: a sessão já valida a autenticidade.

## Relacionado

* [`PUT .../:uuid/signers/:signerUuid/placement-mode`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-envelope-signer-placement-mode) — admin define o modo
* [`PUT .../:uuid/signers/:signerUuid/files/:fileUuid/position`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-envelope-signer-position) — admin posiciona (não signatário)
* [`POST /v1/sign/:sessionToken/verification/confirm`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/post-sign-session-verification-confirm) — confirmar assinatura


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