Criar Documento

Criar um documento para assinatura pela API tem duas etapas:

1. Enviar o arquivo com POST /v1/documents. O TapSign guarda o PDF e devolve o id do documento.
2. Criar o envelope com POST /v1/envelopes. O envelope liga o documento aos signatários e ao envio, e nasce com status DRAFT.

Depois, adicione os signatários e envie para assinatura.

Documento a partir de modelo

Se o documento sai de um modelo com variáveis, veja Criar Documento via Modelo.

Etapa 1: enviar o arquivo

Requisição

POST /v1/documents

Headers

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

Parâmetros (form-data)

Campo	Tipo	Obrigatório	Descrição
file	file	Sim	Arquivo PDF ou DOCX, com até 10 MB
title	string	Sim	Título do documento
description	string	Não	Descrição do documento
organizationId	number	Não	Organização à qual o documento pertence
folderId	string (UUID)	Não	Pasta de destino. Precisa pertencer à organização informada em organizationId

PDF e DOCX

O tipo do arquivo é lido do Content-Type da parte file. São aceitos application/pdf e application/vnd.openxmlformats-officedocument.wordprocessingml.document. Qualquer outro tipo, inclusive application/octet-stream, é recusado com erro 400. Arquivos DOCX são convertidos para PDF no envio, e a resposta já descreve o PDF gerado.

Exemplo de requisição

curl -X POST \
  https://api.tapsign.com.br/v1/documents \
  -H "Authorization: Bearer {token}" \
  -F "file=@/caminho/para/contrato.pdf;type=application/pdf" \
  -F "title=Contrato de Prestação de Serviços"

Resposta

201 - Criado com sucesso

{
  "id": 1024,
  "ownerId": 57,
  "title": "Contrato de Prestação de Serviços",
  "description": null,
  "originalFilename": "contrato.pdf",
  "contentType": "application/pdf",
  "fileSize": 245780,
  "status": "DRAFT",
  "documentHash": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
  "createdAt": "2026-09-12T14:30:00Z",
  "updatedAt": "2026-09-12T14:30:00Z",
  "completedAt": null,
  "folderId": null
}

Campos da resposta

Campo	Tipo	Descrição
id	number	Identificador do documento. Use em documentId na etapa 2
ownerId	number	ID do usuário dono do documento
title	string	Título informado
description	string	Descrição informada (pode ser null)
originalFilename	string	Nome original do arquivo enviado
contentType	string	Sempre application/pdf, porque o DOCX é convertido
fileSize	number	Tamanho do PDF armazenado, em bytes
status	string	Status do documento: DRAFT, PENDING_SIGNATURES, COMPLETED ou CANCELED
documentHash	string	Hash SHA-256, em hexadecimal, do PDF armazenado
createdAt	string	Data de criação (ISO 8601, UTC)
updatedAt	string	Data da última atualização (ISO 8601, UTC)
completedAt	string	Data de conclusão (null até todos assinarem)
folderId	string	Pasta do documento (pode ser null)

Erros

Código	Quando acontece
400	O tipo do arquivo não é PDF nem DOCX
401	Token ausente ou inválido
403	folderId não pertence à organização informada
413	Arquivo acima de 10 MB. A requisição é recusada antes de chegar à API

Exemplo de erro 400 (com o header Accept-Language: pt-BR; sem ele, o title volta em inglês):

{
  "title": "Violação de regra de negócio!",
  "status": 400,
  "details": "Apenas arquivos PDF ou DOCX são aceitos.",
  "timestamp": "2026-09-12T14:30:00Z",
  "fields": {}
}

O formato completo dos erros está em Status de Erros.

---

Etapa 2: criar o envelope

Requisição

POST /v1/envelopes

Headers

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

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
documentId	number	Sim	id devolvido na etapa 1. O documento precisa ser da sua conta
title	string	Sim	Título do envelope, com até 255 caracteres
message	string	Não	Mensagem do envelope, com até 1000 caracteres
expiresAt	string (ISO 8601)	Não	Prazo para assinar. Sem valor, o prazo é definido no envio: 30 dias depois dele
signOrder	string	Sim	Ordem de assinatura: SEQUENTIAL ou PARALLEL
organizationId	number	Não	Organização do envelope. Você precisa ser membro ativo dela
folderId	string (UUID)	Não	Pasta de destino, da mesma organização

Datas

Envie expiresAt em ISO 8601. Com fuso (2026-10-12T23:59:59-03:00), a data é convertida para UTC. Sem fuso (2026-10-13T02:59:59), ela é tratada como UTC.

Exemplo de requisição

curl -X POST \
  https://api.tapsign.com.br/v1/envelopes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": 1024,
    "title": "Contrato de Prestação de Serviços",
    "message": "Por favor, revise e assine.",
    "signOrder": "PARALLEL",
    "expiresAt": "2026-10-12T23:59:59-03:00"
  }'

Resposta

201 - Criado com sucesso

{
  "id": 512,
  "ownerId": 57,
  "documentId": 1024,
  "organizationId": null,
  "title": "Contrato de Prestação de Serviços",
  "message": "Por favor, revise e assine.",
  "status": "DRAFT",
  "expiresAt": "2026-10-13T02:59:59Z",
  "signOrder": "PARALLEL",
  "createdAt": "2026-09-12T14:31:00Z",
  "updatedAt": "2026-09-12T14:31:00Z",
  "sentAt": null,
  "completedAt": null,
  "createdByEmail": "[email protected]",
  "folderId": null
}

Campos da resposta

Campo	Tipo	Descrição
id	number	Identificador do envelope. É o {id} das demais rotas de /v1/envelopes
ownerId	number	ID do usuário dono do envelope
documentId	number	Documento do envelope
organizationId	number	Organização do envelope (pode ser null)
title	string	Título do envelope
message	string	Mensagem do envelope (pode ser null)
status	string	DRAFT, SENT, IN_PROGRESS, COMPLETED, CANCELED ou EXPIRED
expiresAt	string	Prazo para assinar (ISO 8601, UTC). Pode ser null até o envio
signOrder	string	SEQUENTIAL ou PARALLEL
createdAt	string	Data de criação (ISO 8601, UTC)
updatedAt	string	Data da última atualização (ISO 8601, UTC)
sentAt	string	Data do envio (null enquanto for rascunho)
completedAt	string	Data da conclusão (null até todos assinarem)
createdByEmail	string	E-mail da conta autenticada que fez a requisição
folderId	string	Pasta do envelope (pode ser null)

Cota mensal do plano

A cota mensal de documentos do plano é descontada na criação do envelope, e não no envio. Mover o envelope para a lixeira ou excluí-lo não devolve a cota. Quando organizationId é informado, vale a cota do plano do dono da organização.

Erros

Código	Quando acontece
400	Campo obrigatório ausente ou inválido (a resposta traz fields), documento cancelado ou limite mensal de documentos do plano atingido
401	Token ausente ou inválido
403	Você não é membro ativo da organizationId informada, ou folderId pertence a outra organização
404	documentId não existe ou não é da sua conta

Exemplo de erro de validação (com Accept-Language: pt-BR):

{
  "title": "Argumentos inválidos!",
  "status": 400,
  "details": "Falha na validação",
  "timestamp": "2026-09-12T14:31:00Z",
  "fields": {
    "signOrder": "Ordem de assinatura é obrigatória"
  }
}

Exemplo de limite do plano atingido:

{
  "title": "Violação de regra de negócio!",
  "status": 400,
  "details": "Limite mensal de documentos atingido: 5/5. Faça upgrade do seu plano para enviar mais documentos.",
  "timestamp": "2026-09-12T14:31:00Z",
  "fields": {}
}

Próximos passos

1. Adicionar signatários ao envelope
2. Opcional: posicionar as assinaturas no PDF
3. Enviar para assinatura