Posicionar Assinaturas

Existem dois recursos nesta página:

• Posições de assinatura (/signer-positions): definem onde a assinatura de cada signatário fica na página. São essas posições que a tela de assinatura recebe pré-configuradas.
• Campos do envelope (/fields): cadastro de campos associados a um signatário.

---

Posições de assinatura

Requisição

PUT /v1/envelopes/{id}/signer-positions

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Bearer {token}
Content-Type	string	Sim	application/json

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
id	number	Sim	Identificador do envelope

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
positions	array	Sim	Lista de posições. Um signatário pode ter mais de uma, por exemplo em páginas diferentes
positions[].signerId	number	Sim	ID do signatário. Precisa pertencer ao envelope
positions[].signaturePage	number	Sim	Página, começando em 1
positions[].signaturePosX	number	Sim	Distância a partir da borda esquerda (maior ou igual a 0)
positions[].signaturePosY	number	Sim	Distância a partir da borda superior (maior ou igual a 0)
positions[].signatureWidth	number	Sim	Largura da assinatura (mínimo 1)
positions[].signatureHeight	number	Sim	Altura da assinatura (mínimo 1)
positions[].refPageWidth	number	Não	Largura da página em que as coordenadas foram medidas
positions[].refPageHeight	number	Não	Altura da página em que as coordenadas foram medidas

Sistema de coordenadas

A origem é o canto superior esquerdo da página, como ela é exibida. Sem refPageWidth e refPageHeight, os valores são usados como pontos do PDF. Por exemplo, uma página A4 em pé mede cerca de 595 x 842 pontos. Com refPageWidth e refPageHeight, as coordenadas são tratadas como proporcionais a essa página de referência e reescaladas para o tamanho real da página do PDF.

Exemplo de requisição

curl -X PUT \
  https://api.tapsign.com.br/v1/envelopes/512/signer-positions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      {
        "signerId": 880,
        "signaturePage": 4,
        "signaturePosX": 72,
        "signaturePosY": 650,
        "signatureWidth": 200,
        "signatureHeight": 50,
        "refPageWidth": 595,
        "refPageHeight": 842
      },
      {
        "signerId": 881,
        "signaturePage": 4,
        "signaturePosX": 330,
        "signaturePosY": 650,
        "signatureWidth": 200,
        "signatureHeight": 50,
        "refPageWidth": 595,
        "refPageHeight": 842
      }
    ]
  }'

Resposta

200 - Sucesso

Nenhum corpo de resposta é retornado.

Substituição

Para cada signatário presente no body, as posições anteriores são apagadas e substituídas pelas enviadas. Signatários que não aparecem no body mantêm as posições que já tinham. A primeira posição de cada signatário também aparece nos campos signaturePage, signaturePosX, signaturePosY, signatureWidth e signatureHeight de Detalhar Documento.

Erros

Código	Quando acontece
400	Valor fora dos limites (a resposta traz fields), ou signerId de outro envelope
401	Token ausente ou inválido
404	O envelope não existe ou não é da sua conta, ou o signerId não existe

---

Campos do envelope

Tipos de campos

Tipo	Descrição
SIGNATURE	Assinatura
INITIALS	Rubrica
TEXT	Texto
DATE	Data
CHECKBOX	Caixa de seleção

Campos não definem a posição da assinatura

Os campos ficam registrados no envelope e voltam nestas rotas, mas não são usados pela tela de assinatura nem na geração do PDF assinado. Para definir onde a assinatura aparece, use as posições de assinatura.

Listar campos

GET /v1/envelopes/{id}/fields

curl -X GET \
  https://api.tapsign.com.br/v1/envelopes/512/fields \
  -H "Authorization: Bearer {token}"

Retorna 200 com a lista de campos do envelope, no mesmo formato da resposta de adicionar campo.

Adicionar campo

Requisição

POST /v1/envelopes/{id}/fields

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
signerId	number	Sim	ID do signatário responsável pelo campo. Precisa pertencer ao envelope
type	string	Sim	Tipo do campo (tabela acima)
page	number	Sim	Página, começando em 1
posX	number	Sim	Posição horizontal (maior ou igual a 0)
posY	number	Sim	Posição vertical (maior ou igual a 0)
width	number	Sim	Largura (mínimo 1)
height	number	Sim	Altura (mínimo 1)
required	boolean	Não	Se o campo é obrigatório
placeholder	string	Não	Texto de apoio, com até 255 caracteres

A API guarda os valores de posição exatamente como enviados.

Exemplo de requisição

curl -X POST \
  https://api.tapsign.com.br/v1/envelopes/512/fields \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "signerId": 880,
    "type": "DATE",
    "page": 4,
    "posX": 72,
    "posY": 710,
    "width": 120,
    "height": 20,
    "required": true
  }'

201 - Criado com sucesso

{
  "id": 3301,
  "envelopeId": 512,
  "signerId": 880,
  "type": "DATE",
  "page": 4,
  "posX": 72.0,
  "posY": 710.0,
  "width": 120.0,
  "height": 20.0,
  "required": true,
  "placeholder": null,
  "createdAt": "2026-09-12T14:33:00Z",
  "updatedAt": "2026-09-12T14:33:00Z"
}

Atualizar campo

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

O PUT substitui o campo: envie type, page, posX, posY, width e height (obrigatórios), além de required e placeholder, que ficam null se forem omitidos. signerId é opcional; sem ele, o campo continua com o mesmo signatário.

curl -X PUT \
  https://api.tapsign.com.br/v1/envelopes/512/fields/3301 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DATE",
    "page": 4,
    "posX": 100,
    "posY": 720,
    "width": 120,
    "height": 20,
    "required": true
  }'

Retorna 200 com o campo atualizado.

Remover campo

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

curl -X DELETE \
  https://api.tapsign.com.br/v1/envelopes/512/fields/3301 \
  -H "Authorization: Bearer {token}"

Retorna 204 sem corpo.

Erros

Código	Quando acontece
400	Envelope fora de DRAFT (ao adicionar, atualizar ou remover), campo inexistente ou de outro envelope, signatário de outro envelope, ou valor inválido (a resposta traz fields)
401	Token ausente ou inválido
404	O envelope não existe ou não é da sua conta, ou o signerId não existe

Somente em rascunho

Campos só podem ser adicionados, atualizados ou removidos enquanto o envelope estiver com status DRAFT.