Posicionar Assinaturas

Gerencia os campos de assinatura posicionados no documento. Voce pode adicionar, atualizar e remover campos que os signatarios deverao preencher.

Tipos de campos

Tipo	Descricao
SIGNATURE	Campo de assinatura (desenho ou digitada)
INITIALS	Campo para rubrica
DATE	Campo de data (preenchido automaticamente)
TEXT	Campo de texto livre
CHECKBOX	Caixa de selecao
FULL_NAME	Nome completo (preenchido automaticamente)
EMAIL	Email (preenchido automaticamente)

---

Adicionar Campo

Requisicao

POST /v1/envelopes/{id}/fields

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	string	Sim	Bearer token de autenticacao
Content-Type	string	Sim	application/json

Parametros de URL

Parametro	Tipo	Obrigatorio	Descricao
id	string	Sim	Identificador unico do envelope

Body (JSON)

Campo	Tipo	Obrigatorio	Descricao
signerId	string	Sim	ID do signatario responsavel por este campo
type	string	Sim	Tipo do campo (ver tabela acima)
page	number	Sim	Numero da pagina (comeca em 1)
x	number	Sim	Posicao horizontal em pontos (pts) a partir da esquerda
y	number	Sim	Posicao vertical em pontos (pts) a partir do topo
width	number	Sim	Largura do campo em pontos
height	number	Sim	Altura do campo em pontos
required	boolean	Nao	Se o campo e obrigatorio. Padrao: true

Exemplo de requisicao

curl -X POST \
  https://api.tapsign.com.br/v1/envelopes/env_d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a/fields \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "signerId": "sgn_aaa111bbb",
    "type": "SIGNATURE",
    "page": 4,
    "x": 72.0,
    "y": 650.0,
    "width": 200.0,
    "height": 50.0,
    "required": true
  }'

Resposta

201 - Criado com sucesso

{
  "id": "fld_x1y2z3",
  "signerId": "sgn_aaa111bbb",
  "type": "SIGNATURE",
  "page": 4,
  "x": 72.0,
  "y": 650.0,
  "width": 200.0,
  "height": 50.0,
  "required": true,
  "createdAt": "2026-03-29T15:00:00Z"
}

Dica sobre posicionamento

As coordenadas x e y sao medidas em pontos (pts) a partir do canto superior esquerdo da pagina. Uma pagina A4 tem aproximadamente 595 x 842 pontos. Use essas referências para posicionar os campos corretamente.

---

Atualizar Campo

Requisicao

PUT /v1/envelopes/{id}/fields/{fieldId}

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	string	Sim	Bearer token de autenticacao
Content-Type	string	Sim	application/json

Parametros de URL

Parametro	Tipo	Obrigatorio	Descricao
id	string	Sim	Identificador unico do envelope
fieldId	string	Sim	Identificador unico do campo

Body (JSON)

Envie apenas os campos que deseja atualizar:

Campo	Tipo	Obrigatorio	Descricao
page	number	Nao	Numero da pagina
x	number	Nao	Posicao horizontal em pontos
y	number	Nao	Posicao vertical em pontos
width	number	Nao	Largura do campo em pontos
height	number	Nao	Altura do campo em pontos
required	boolean	Nao	Se o campo e obrigatorio

Exemplo de requisicao

curl -X PUT \
  https://api.tapsign.com.br/v1/envelopes/env_d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a/fields/fld_x1y2z3 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "x": 100.0,
    "y": 700.0
  }'

Resposta

200 - Sucesso

{
  "id": "fld_x1y2z3",
  "signerId": "sgn_aaa111bbb",
  "type": "SIGNATURE",
  "page": 4,
  "x": 100.0,
  "y": 700.0,
  "width": 200.0,
  "height": 50.0,
  "required": true,
  "updatedAt": "2026-03-29T15:10:00Z"
}

---

Remover Campo

Requisicao

DELETE /v1/envelopes/{id}/fields/{fieldId}

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	string	Sim	Bearer token de autenticacao

Parametros de URL

Parametro	Tipo	Obrigatorio	Descricao
id	string	Sim	Identificador unico do envelope
fieldId	string	Sim	Identificador unico do campo

Exemplo de requisicao

curl -X DELETE \
  https://api.tapsign.com.br/v1/envelopes/env_d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a/fields/fld_x1y2z3 \
  -H "Authorization: Bearer {token}"

Resposta

204 - Sucesso (No Content)

O campo foi removido com sucesso. Nenhum corpo de resposta e retornado.

---

Erros comuns

400 - Requisicao invalida

{
  "error": "BAD_REQUEST",
  "message": "O signatario informado nao pertence a este envelope."
}

401 - Nao autorizado

{
  "error": "UNAUTHORIZED",
  "message": "Token de autenticacao invalido ou expirado."
}

404 - Nao encontrado

{
  "error": "NOT_FOUND",
  "message": "Campo nao encontrado neste envelope."
}

422 - Estado invalido

{
  "error": "UNPROCESSABLE_ENTITY",
  "message": "Campos so podem ser gerenciados em envelopes com status DRAFT."
}

Atencao

Os campos de assinatura so podem ser adicionados, atualizados ou removidos enquanto o envelope estiver com status DRAFT. Apos o envio para assinatura, os campos sao bloqueados.

Campos automaticos

Campos do tipo DATE, FULL_NAME e EMAIL sao preenchidos automaticamente com os dados do signatario no momento da assinatura. O signatario nao precisa digitar essas informacoes manualmente.