Adicionar Signatario

Adiciona um novo signatario a um envelope existente. O signatario recebera um convite para assinar assim que o envelope for enviado.

Endpoint

POST /v1/envelopes/{id}/signers

Headers

Header	Valor
Authorization	Bearer {token}
Content-Type	application/json

Parametros de URL

Parametro	Tipo	Obrigatorio	Descricao
id	string (UUID)	Sim	ID do envelope

Body

Campo	Tipo	Obrigatorio	Descricao
name	string	Sim	Nome completo do signatario
email	string	Sim	Email do signatario (usado para envio do convite)
role	string	Nao	Papel do signatario. Valores: SIGNER, WITNESS, APPROVER, CARBON_COPY. Padrao: SIGNER
phone	string	Nao	Telefone com DDD (ex: +5511999999999). Usado para envio via WhatsApp

Papeis disponiveis

• SIGNER -- Assina o documento (padrao)
• WITNESS -- Testemunha a assinatura
• APPROVER -- Aprova o documento antes do envio aos signatarios
• CARBON_COPY -- Recebe uma copia do documento finalizado, sem precisar assinar

Exemplo de Requisicao

curl -X POST https://api.tapsign.com.br/v1/envelopes/a1b2c3d4-e5f6-7890-abcd-ef1234567890/signers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Joao da Silva",
    "email": "joao@empresa.com.br",
    "role": "SIGNER",
    "phone": "+5511999999999"
  }'

Resposta de Sucesso

Status: 201 Created

{
  "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
  "name": "Joao da Silva",
  "email": "joao@empresa.com.br",
  "role": "SIGNER",
  "phone": "+5511999999999",
  "status": "PENDING",
  "token": "abc123def456",
  "signingUrl": "https://app.tapsign.com.br/sign/abc123def456",
  "createdAt": "2026-03-29T14:30:00Z"
}

Campos da Resposta

Campo	Tipo	Descricao
id	string (UUID)	ID unico do signatario
name	string	Nome do signatario
email	string	Email do signatario
role	string	Papel atribuido
phone	string	Telefone do signatario
status	string	Status atual. Sempre PENDING ao criar
token	string	Token unico para a URL de assinatura
signingUrl	string	URL publica para o signatario acessar e assinar
createdAt	string (ISO 8601)	Data de criacao

Erros

Codigo	Descricao
400	Campos obrigatorios ausentes ou formato invalido
404	Envelope nao encontrado
409	Envelope ja foi enviado ou finalizado -- nao aceita novos signatarios
422	Email duplicado no mesmo envelope

Atencao

Signatarios so podem ser adicionados enquanto o envelope estiver no status DRAFT. Apos o envio, use a API de atualizacao caso precise alterar dados de um signatario existente.