Detalhar Signatário

Retorna os dados que a tela de assinatura usa para um signatário: documento, status, link temporário do PDF e posições de assinatura. É o mesmo acesso feito quando o signatário abre o link https://tapsign.com.br/signing/{token}.

Este é um endpoint público: não requer autenticação. O token na URL é o accessToken do signatário.

Esta chamada registra uma visualização

Enquanto o signatário não assinou nem recusou, cada chamada a este endpoint:

• muda o status do signatário para VIEWED;
• muda o envelope de SENT para IN_PROGRESS;
• grava o evento VIEWED no histórico de atividades;
• dispara o webhook doc_viewed.

Por isso, não use este endpoint para consultar status na sua integração: você registraria visualizações que o signatário não fez. Para consultar, use Detalhar Documento (GET /v1/envelopes/{id}) ou receba webhooks.

Endpoint

GET /v1/signing/{token}

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
token	string (UUID)	Sim	accessToken do signatário, devolvido em Adicionar Signatário e em Detalhar Documento

Exemplo de Requisição

curl -X GET https://api.tapsign.com.br/v1/signing/3f6c2a9e-8b1d-4c7a-9e2f-5d4b8a1c0e77

Resposta de Sucesso

Status: 200 OK

{
  "documentId": 982,
  "title": "Contrato de Prestação de Serviços",
  "description": null,
  "documentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "ownerName": "Maria Souza",
  "status": "IN_PROGRESS",
  "signerName": "João da Silva",
  "signerEmail": "[email protected]",
  "signerPhone": "+5511999999999",
  "signerRole": "SIGNER",
  "signerStatus": "VIEWED",
  "fileUrl": "https://...",
  "sentAt": "2026-09-12T14:30:00Z",
  "expiresAt": "2026-10-12T14:30:00Z",
  "signedAt": null,
  "declinedAt": null,
  "existingSignatures": [
    {
      "page": 3,
      "posX": 72.0,
      "posY": 650.0,
      "width": 200.0,
      "height": 50.0,
      "signerName": "Ana Costa"
    }
  ],
  "preConfiguredPosition": null,
  "preConfiguredPositions": [],
  "authMethods": [],
  "pendingSigners": 2,
  "declinedSigners": 0
}

Campos da Resposta

Campo	Tipo	Descrição
documentId	integer	ID do documento (arquivo) do envelope
title	string	Título do documento
description	string ou null	Descrição do documento
documentHash	string	Hash SHA-256, em hexadecimal, do PDF original. É o valor exigido na assinatura
ownerName	string	Nome do dono do envelope
status	string	Status do envelope: DRAFT, SENT, IN_PROGRESS, COMPLETED, CANCELED ou EXPIRED
signerName	string	Nome do signatário
signerEmail	string	E-mail do signatário
signerPhone	string ou null	Telefone do signatário
signerRole	string	Papel do signatário
signerStatus	string	Status do signatário: PENDING, NOTIFIED, VIEWED, SIGNED ou DECLINED
fileUrl	string	Link temporário para o PDF original, válido por 1 hora
sentAt	string ou null	Data de envio do envelope (UTC, ISO 8601)
expiresAt	string ou null	Data de expiração do envelope (UTC, ISO 8601)
signedAt	string ou null	Data em que o signatário assinou
declinedAt	string ou null	Data em que o signatário recusou
existingSignatures	array	Assinaturas já registradas no envelope com posição no PDF: page, posX, posY, width, height e signerName
preConfiguredPositions	array	Posições pré-configuradas para a assinatura deste signatário: page, posX, posY, width e height
preConfiguredPosition	object ou null	Primeiro item de preConfiguredPositions, mantido por compatibilidade
authMethods	string[]	Canais de código que o signatário precisa validar antes de assinar (EMAIL_CODE, SMS_CODE, WHATSAPP_CODE). Vazio quando basta assinar na tela
pendingSigners	integer	Quantos signatários ainda faltam para o envelope ser concluído
declinedSigners	integer	Quantos signatários recusaram

Signatário que já assinou ou recusou

Se o signatário já está SIGNED ou DECLINED, a chamada apenas devolve os dados, sem registrar nova visualização e sem disparar webhook. O fileUrl continua apontando para o PDF original.

Erros

Código	Quando acontece
400	O envelope passou da data de expiração (expiresAt)
404	O token não corresponde a nenhum signatário

O formato do corpo de erro está em Status de Erros.