> ## 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 modo de posicionamento da chancela

> Escolhe quem decide onde a chancela do signatário pousa no PDF.

Define quem decide o local onde a chancela visual deste signatário será desenhada no PDF assinado. A escolha é feita **por signatário** e pode ser alterada enquanto o documento não foi assinado.

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

## Modos de posicionamento

| Modo | Quem escolhe | Descrição |
| :- | :- | :- |
| `MANIFEST` | Ninguém | A chancela vai para a grade da página de assinaturas (padrão) |
| `OPERATOR` | Operador | Quem monta o envelope marca o local exato no passo "Posicionar assinatura" |
| `SIGNER` | Signatário | O próprio signatário arrasta a chancela na tela de assinatura |

## Como funciona

* **O modo manda, não a coordenada**: mesmo que haja coordenada gravada, ela só é usada se o modo autoriza.
* **Sair de `OPERATOR` ou `SIGNER` limpa a marcação**: deixar o modo decide. A resposta informa se algo foi apagado via `clearedPlacements`.
* **Entrar em `OPERATOR` não limpa nada**: é o operador recuperando seu posicionamento anterior.

## Parâmetros

**uuid** `string` *required*

UUID do envelope.

**signerUuid** `string` *required*

UUID do signatário.

**mode** `enum` *required*

Modo de posicionamento: `MANIFEST`, `OPERATOR` ou `SIGNER`.

## Respostas

**signerUuid** `string`

UUID do signatário.

**mode** `string`

O modo atualizado.

**clearedPlacements** `boolean`

`true` se a troca de modo apagou marcações anteriores. Sair de `OPERATOR` ou `SIGNER` descarta a coordenada gravada, porque deixou de valer.

## Erros

* **400**: Modo desconhecido.
* **401**: Autenticação ausente ou inválida.
* **404**: Envelope ou signatário 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",
  "mode": "SIGNER",
  "clearedPlacements": false
}
```

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

{
  "signerUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mode": "MANIFEST",
  "clearedPlacements": true
}
```

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

{
  "statusCode": 401,
  "message": "Missing or invalid authorization."
}
```

```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."
}
```

## Exemplo

```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/placement-mode" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "SIGNER"
  }'
```

## Importante

* **Rejeita se assinado**: uma vez que o signatário assinou, o modo não pode ser alterado.
* **Por signatário**: cada signatário tem seu próprio modo, independentemente dos demais.
* **Coordenadas persistem**: as marcações gravadas não são apagadas ao entrar em `OPERATOR`, apenas ao sair dele.

## Próximas etapas

* Use [`PUT .../:uuid/signers/:signerUuid/files/:fileUuid/position`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-envelope-signer-position) para marcar a posição exata quando o modo for `OPERATOR`.
* 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/files/:fileUuid/position`](https://docs-platform.services-valid.com.br/plataforma/assinatura-digital/api/put-envelope-signer-position) — definir posição exata (admin)
* [`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.