Assistente de Criação (Wizard)
Definir posição exata da chancela (admin)
Marca o local onde a chancela do signatário será desenhada em um arquivo específico.
PUT
Definir posição exata da chancela (admin)
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
Parâmetros
string
required
UUID do envelope.
string
required
UUID do signatário.
string
required
UUID do arquivo.
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.number
required
Distância da borda esquerda da página, na unidade declarada em
unit.number
required
Distância da borda indicada por
origin (padrão: topo), na unidade de unit.enum
required
Unidade de medida:
fraction, percent, px, pt, mm, cm, in.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.
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.number
Obrigatório se
unit é px: altura, em pixels, com que a página foi desenhada na tela.Respostas
string
UUID do signatário.
string
UUID do arquivo.
number | null
Página gravada, contando a partir de 0.
null quando não há marcação.number | null
Fração da largura da página, a partir da borda esquerda (0..1).
null quando não há marcação.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
pxenviado 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.
Exemplos
Usando fração (0..1)
Usando pixels do desenho renderizado
Usando milímetros (medida do papel)
Remover posicionamento
Para voltar ao comportamento padrão (chancela na grade de assinaturas), use: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
MANIFESTmuda automaticamente paraOPERATOR. - Resolução limitada: as colunas
position_lefteposition_toptêm precisão de ~1% da página (cerca de 2 mm na horizontal).
Próximas etapas
- Use
PUT .../:uuid/signers/:signerUuid/placement-modepara controlar quem decide o local (admin, operador ou signatário). - Use
POST .../:uuid/sendpara enviar o envelope aos signatários.
Relacionado
PUT .../:uuid/signers/:signerUuid/placement-mode— definir modo de posicionamentoPUT /v1/sign/:sessionToken/files/:fileUuid/position— signatário posiciona na assinatura