Detalhar Documento

Retorna os dados de um envelope da sua conta e a lista de signatários, com o status de cada um e o token do link de assinatura.

Requisição

GET /v1/envelopes/{id}

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	`string`	Sim	`Bearer {token}`

Parâmetros de URL

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

Exemplo de requisição

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

Resposta

200 - Sucesso

{
  "envelope": {
    "id": 512,
    "ownerId": 57,
    "documentId": 1024,
    "organizationId": null,
    "title": "Contrato de Prestação de Serviços",
    "message": "Por favor, revise e assine.",
    "status": "IN_PROGRESS",
    "expiresAt": "2026-10-12T14:35:00Z",
    "signOrder": "PARALLEL",
    "createdAt": "2026-09-12T14:31:00Z",
    "updatedAt": "2026-09-12T15:40:12Z",
    "sentAt": "2026-09-12T14:35:00Z",
    "completedAt": null,
    "createdByEmail": "[email protected]",
    "folderId": null
  },
  "signers": [
    {
      "id": 880,
      "envelopeId": 512,
      "name": "Carlos Eduardo Mendes",
      "email": "[email protected]",
      "phone": "+5511999998888",
      "role": "SIGNER",
      "signOrder": 1,
      "status": "SIGNED",
      "signedAt": "2026-09-12T15:42:00Z",
      "declinedAt": null,
      "declineReason": null,
      "accessToken": "3f2b9c1e-7d4a-4c8e-9a51-2b6f0d8e4c11",
      "whatsappLastStatus": null,
      "whatsappLastStatusAt": null,
      "whatsappLastErrorCode": null,
      "whatsappOwnerMessage": null,
      "signaturePage": 4,
      "signaturePosX": 72.0,
      "signaturePosY": 650.0,
      "signatureWidth": 200.0,
      "signatureHeight": 50.0,
      "authMethods": ["SCREEN_SIGNATURE"]
    },
    {
      "id": 881,
      "envelopeId": 512,
      "name": "Ana Paula Costa",
      "email": "[email protected]",
      "phone": null,
      "role": "SIGNER",
      "signOrder": 2,
      "status": "NOTIFIED",
      "signedAt": null,
      "declinedAt": null,
      "declineReason": null,
      "accessToken": "8d1e0a7b-52c4-4f19-b3aa-6e7c9d2f1b30",
      "whatsappLastStatus": null,
      "whatsappLastStatusAt": null,
      "whatsappLastErrorCode": null,
      "whatsappOwnerMessage": null,
      "signaturePage": null,
      "signaturePosX": null,
      "signaturePosY": null,
      "signatureWidth": null,
      "signatureHeight": null,
      "authMethods": ["SCREEN_SIGNATURE"]
    }
  ],
  "emailsQueNaoRecebem": []
}

Campos da resposta

Campo	Tipo	Descrição
`envelope`	`object`	Dados do envelope. Mesmos campos da resposta de criar envelope
`signers`	`array`	Signatários do envelope
`signers[].id`	`number`	Identificador do signatário
`signers[].envelopeId`	`number`	Envelope do signatário
`signers[].name`	`string`	Nome do signatário
`signers[].email`	`string`	E-mail do signatário
`signers[].phone`	`string`	Telefone em formato internacional (pode ser `null`)
`signers[].role`	`string`	Papel: `SIGNER`, `WITNESS`, `APPROVER`, `ACKNOWLEDGE_RECEIPT`, `AUTHORIZE` ou `CUSTOM`
`signers[].signOrder`	`number`	Ordem informada para o signatário (pode ser `null`)
`signers[].status`	`string`	`PENDING`, `NOTIFIED`, `VIEWED`, `SIGNED` ou `DECLINED`
`signers[].signedAt`	`string`	Data da assinatura (ISO 8601, UTC, `null` se não assinou)
`signers[].declinedAt`	`string`	Data da recusa (`null` se não recusou)
`signers[].declineReason`	`string`	Motivo informado na recusa
`signers[].accessToken`	`string`	Token do link de assinatura do signatário
`signers[].whatsappLastStatus`	`string`	Último status recebido do WhatsApp para a notificação, quando houver
`signers[].whatsappLastStatusAt`	`string`	Data desse último status
`signers[].whatsappLastErrorCode`	`number`	Código de erro do WhatsApp, quando houver
`signers[].whatsappOwnerMessage`	`string`	Explicação do erro do WhatsApp para o dono do envelope, quando houver código de erro
`signers[].signaturePage`, `signaturePosX`, `signaturePosY`, `signatureWidth`, `signatureHeight`	`number`	Primeira posição de assinatura configurada para o signatário (veja Posicionar Assinaturas)
`signers[].authMethods`	`array`	Métodos de autenticação do signatário
`emailsQueNaoRecebem`	`array`	E-mails de signatários deste envelope que recusaram a entrega de e-mail. Lista vazia no caso normal

Status do envelope

DRAFT: rascunho, ainda não enviado.
SENT: enviado aos signatários.
IN_PROGRESS: algum signatário abriu o link de assinatura depois do envio.
COMPLETED: todos os signatários assinaram.
CANCELED: cancelado pelo dono.
EXPIRED: o prazo (expiresAt) passou antes da conclusão.

Uma recusa muda o status do signatário para DECLINED, mas não muda o status do envelope. Como a conclusão exige que todos assinem, um envelope com recusa não chega a COMPLETED.

Link de assinatura

Cada signatário assina em https://tapsign.com.br/signing/{accessToken}. É esse link que o TapSign manda por e-mail e WhatsApp no envio.

Abrir o link registra visualização

Quando o link é aberto, o TapSign marca o signatário como VIEWED, registra o evento no histórico, dispara o webhook doc_viewed e, se o envelope estava SENT, muda para IN_PROGRESS. Não abra o link do signatário para testar ou consultar status. Use esta rota.

Erros

Código	Quando acontece
`401`	Token ausente ou inválido
`404`	O envelope não existe ou não é da sua conta

Exemplo de erro 404 (com Accept-Language: pt-BR):

{
  "title": "Recurso não encontrado!",
  "status": 404,
  "details": "Recurso não encontrado",
  "timestamp": "2026-09-12T15:45:00Z",
  "fields": {}
}

Baixar o PDF

Gera um link temporário para baixar o PDF original ou o PDF assinado do envelope.

Requisição

GET /v1/envelopes/{id}/download?type={type}

Parâmetros

Parâmetro	Local	Tipo	Obrigatório	Descrição
`id`	URL	`number`	Sim	Identificador do envelope
`type`	Query	`string`	Não	`signed` para o PDF assinado. Qualquer outro valor, ou a ausência do parâmetro, retorna o original. Padrão: `original`

Exemplo de requisição

curl -X GET \
  "https://api.tapsign.com.br/v1/envelopes/512/download?type=signed" \
  -H "Authorization: Bearer {token}"

200 - Sucesso

{
  "url": "https://...",
  "fileName": "contrato-assinado.pdf"
}

Campo	Tipo	Descrição
`url`	`string`	Link pré-assinado para o arquivo, válido por 60 minutos
`fileName`	`string`	Nome sugerido. No PDF assinado, é o nome original com o sufixo `-assinado.pdf`

Quando o PDF assinado existe

O PDF assinado é gerado depois que o envelope é concluído (todos assinaram). Antes disso, type=signed retorna erro 400 com a mensagem Documento assinado ainda não foi gerado.

Se preferir receber o arquivo direto, GET /v1/envelopes/{id}/pdf?type={type} devolve o PDF (application/pdf) no corpo da resposta, com a mesma regra para type.

Erros

Código	Quando acontece
`400`	`type=signed` e o PDF assinado ainda não foi gerado
`401`	Token ausente ou inválido
`404`	O envelope não existe ou não é da sua conta

Requisição​

Headers​

Parâmetros de URL​

Exemplo de requisição​

Resposta​

200 - Sucesso​

Campos da resposta​

Link de assinatura​

Erros​

Baixar o PDF​

Requisição​

Parâmetros​

Exemplo de requisição​

200 - Sucesso​

Erros​

Requisição

Headers

Parâmetros de URL

Exemplo de requisição

Resposta

200 - Sucesso

Campos da resposta

Link de assinatura

Erros

Baixar o PDF

Requisição

Parâmetros

Exemplo de requisição

200 - Sucesso

Erros