Adicionar Signatário

Adiciona um signatário a um envelope que ainda está em rascunho (DRAFT). O signatário só é notificado quando o envelope for enviado para assinatura: nesse momento ele recebe o link por e-mail e, se tiver telefone cadastrado, também pelo WhatsApp.

Endpoint

POST /v1/envelopes/{id}/signers

Headers

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

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
id	integer	Sim	ID do envelope. O envelope precisa pertencer ao usuário dono da chave de API

Body

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome completo do signatário, de 2 a 100 caracteres
email	string	Sim	E-mail do signatário. Além do formato, a API consulta o DNS e recusa domínios que não recebem e-mail (ex: gmial.com). Não pode repetir o e-mail de outro signatário do mesmo envelope
phone	string	Não	Telefone em formato internacional, com + opcional (ex: +5511999999999). Usado para enviar o link pelo WhatsApp
role	string	Sim	Papel do signatário. Veja a tabela abaixo
signOrder	integer	Não	Número de ordem do signatário no envelope
authMethods	string[]	Não	Como o signatário se identifica antes de assinar. Se omitido, vale SCREEN_SIGNATURE

Papéis disponíveis

Valor	Rótulo no painel
SIGNER	Assinar
WITNESS	Testemunha
APPROVER	Aprovador
ACKNOWLEDGE_RECEIPT	Assinar para acusar recebimento
AUTHORIZE	Autorizar
CUSTOM	Função personalizada (o nome da função não é definido por este endpoint)

Hoje todos os papéis assinam da mesma forma: o envelope só é concluído quando todos os signatários, de qualquer papel, assinam.

Métodos de autenticação

Valor	O que o signatário precisa fazer
SCREEN_SIGNATURE	Apenas assinar na tela
EMAIL_CODE	Validar um código enviado por e-mail
SMS_CODE	Validar um código enviado por SMS
WHATSAPP_CODE	Validar um código enviado pelo WhatsApp

Com métodos por código, o signatário precisa validar o código antes de assinar, e a validação vale por 15 minutos. Qualquer outro valor é recusado com erro 400.

Exemplo de Requisição

curl -X POST https://api.tapsign.com.br/v1/envelopes/1523/signers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João da Silva",
    "email": "[email protected]",
    "phone": "+5511999999999",
    "role": "SIGNER",
    "signOrder": 1,
    "authMethods": ["EMAIL_CODE"]
  }'

Resposta de Sucesso

Status: 201 Created

{
  "id": 4821,
  "envelopeId": 1523,
  "name": "João da Silva",
  "email": "[email protected]",
  "phone": "+5511999999999",
  "role": "SIGNER",
  "signOrder": 1,
  "status": "PENDING",
  "signedAt": null,
  "declinedAt": null,
  "declineReason": null,
  "accessToken": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b8a1c0e77",
  "whatsappLastStatus": null,
  "whatsappLastStatusAt": null,
  "whatsappLastErrorCode": null,
  "whatsappOwnerMessage": null,
  "signaturePage": null,
  "signaturePosX": null,
  "signaturePosY": null,
  "signatureWidth": null,
  "signatureHeight": null,
  "authMethods": ["EMAIL_CODE"]
}

Campos da Resposta

Campo	Tipo	Descrição
id	integer	ID do signatário
envelopeId	integer	ID do envelope
name	string	Nome do signatário
email	string	E-mail do signatário
phone	string ou null	Telefone do signatário
role	string	Papel atribuído
signOrder	integer ou null	Número de ordem informado
status	string	PENDING ao criar. Depois muda para NOTIFIED (notificado no envio), VIEWED, SIGNED ou DECLINED
signedAt	string ou null	Data da assinatura (UTC, ISO 8601)
declinedAt	string ou null	Data da recusa (UTC, ISO 8601)
declineReason	string ou null	Motivo informado na recusa
accessToken	string (UUID)	Token do signatário. Forma o link de assinatura https://tapsign.com.br/signing/{accessToken} e é o token das rotas públicas /v1/signing/{token}
whatsappLastStatus	string ou null	Último status informado pelo WhatsApp para a mensagem enviada ao signatário
whatsappLastStatusAt	string ou null	Data desse último status
whatsappLastErrorCode	integer ou null	Código de erro retornado pelo WhatsApp, quando houver
whatsappOwnerMessage	string ou null	Explicação legível do erro do WhatsApp, quando houver
signaturePage, signaturePosX, signaturePosY, signatureWidth, signatureHeight	number ou null	Posição configurada para a assinatura no PDF. Veja Posicionar Assinaturas
authMethods	string[]	Métodos de autenticação configurados

Guarde o accessToken com cuidado

As rotas /v1/signing/{token} não exigem login: quem tem o accessToken consegue abrir o documento, recusar e assinar (a assinatura ainda passa pelos métodos de autenticação configurados). Compartilhe o token apenas com o próprio signatário.

Erros

Código	Quando acontece
400	Campo inválido: nome fora do tamanho, e-mail mal formado ou de domínio que não recebe e-mail, telefone fora do formato ou role ausente. A resposta traz o motivo em fields
400	O envelope não está em DRAFT
400	Já existe um signatário com o mesmo e-mail neste envelope
400	authMethods contém um método indisponível
401	Chave de API ou token ausente ou inválido
404	Envelope inexistente ou de outro usuário

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

Atenção

Signatários só podem ser adicionados enquanto o envelope estiver no status DRAFT. Depois do envio, não é possível adicionar, alterar nem remover signatários.