Usar Modelo

Gera um documento a partir de um modelo existente: o TapSign substitui as variáveis pelos valores enviados, converte o DOCX em PDF e cria um envelope com os signatários configurados no modelo.

Integrando um sistema?

Para integrações servidor a servidor, prefira Criar Documento via Modelo (POST /v1/integration/documents/create-from-template). Em uma única chamada ela gera o documento, grava o e-mail e o telefone do signatário, envia para assinatura e aceita externalId para evitar duplicidade.

Endpoint

POST /v1/models/{id}/documents

Headers

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

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	ID do modelo

Body

Campo	Tipo	Obrigatório	Descrição
signerName	string	Não	Nome do signatário dinâmico do modelo. Também compõe o título do documento (nome do modelo, hífen, signerName). Envie sempre
prefilledFields	object	Não	Mapa com o nome da variável e o valor. As chaves são os fields[].name do modelo
tableFields	object	Não	Linhas dos grupos de repetição: mapa com o nome do grupo e uma lista de objetos (variável e valor)

O que acontece

1. As variáveis presentes em prefilledFields são substituídas. As que não forem enviadas continuam no documento como texto, por exemplo {{cpf}}.
2. O DOCX preenchido é convertido em PDF.
3. Um envelope é criado com status DRAFT e os signatários do modelo. O signatário dinâmico recebe o nome de signerName. Se o modelo não tiver signatários configurados, é criado um signatário com esse nome e papel SIGNER.
4. O envelope não é enviado. Veja Enviar o envelope gerado.

Exemplo de Requisição

curl -X POST https://api.tapsign.com.br/v1/models/3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10/documents \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "signerName": "João Pedro da Silva",
    "prefilledFields": {
      "nome_completo": "João Pedro da Silva",
      "cpf": "123.456.789-00",
      "data_inicio": "01/10/2026",
      "valor_contrato": "R$ 5.000,00"
    }
  }'

Resposta de Sucesso

Status: 201 Created

{
  "instanceId": "b7d9e2a4-1c3f-4e8a-9b5d-2f6a0c8e1d34",
  "token": "4e8a9b5d2f6a0c8e1d34b7d9",
  "signerName": "João Pedro da Silva",
  "status": "PENDING",
  "envelopeId": 1542,
  "createdAt": "2026-09-12T14:30:00Z"
}

Campos da Resposta

Campo	Tipo	Descrição
instanceId	string (UUID)	ID do preenchimento do modelo
token	string	Token do preenchimento
signerName	string	Nome informado em signerName
status	string	Status do preenchimento (PENDING na criação)
envelopeId	number	ID do envelope criado em DRAFT. Use nas rotas /v1/envelopes/{id}
createdAt	string (ISO 8601, UTC)	Data de criação

Enviar o envelope gerado

1. Consulte os signatários com GET /v1/envelopes/{envelopeId} (Detalhar Documento).
2. Para o signatário dinâmico receber o convite, grave o e-mail ou o telefone dele com PUT /v1/envelopes/{envelopeId}/signers/{signerId} (Atualizar Signatário).
3. Envie com POST /v1/envelopes/{envelopeId}/send (Enviar para Assinatura).

---

Gerar e enviar um ou mais modelos

Cria documentos a partir de um ou mais modelos para um único signatário e, por padrão, já envia.

POST /v1/models/bundle-send

Body

Campo	Tipo	Obrigatório	Descrição
modelIds	string[] (UUID)	Sim	IDs dos modelos. Pelo menos um
signer.name	string	Sim	Nome do signatário
signer.email	string	Sim	E-mail do signatário
signer.phone	string	Não	Telefone do signatário
prefilledFields	object	Não	Valores das variáveis, aplicados a todos os modelos
tableFields	object	Não	Linhas dos grupos de repetição, aplicadas a todos os modelos
bundleTitle	string	Não	Título do pacote. Padrão: Pacote de N documentos
sendImmediately	boolean	Não	Envia logo após criar. Padrão: true

Com um modelo, é criado um envelope e, com sendImmediately ligado, ele é enviado ao signatário por e-mail. Com dois ou mais, é criado um pacote: o signatário assina todos os documentos por um único link.

Exemplo de Requisição

curl -X POST https://api.tapsign.com.br/v1/models/bundle-send \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "modelIds": [
      "3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10",
      "8a1d4c7e-2b5f-4e9a-b3c6-7d0e1f2a4b58"
    ],
    "signer": {
      "name": "João Pedro da Silva",
      "email": "[email protected]"
    },
    "prefilledFields": {
      "nome_completo": "João Pedro da Silva"
    }
  }'

Resposta de Sucesso

Status: 201 Created

{
  "type": "BUNDLE",
  "envelopeId": null,
  "bundleId": 88,
  "envelopeIds": [1543, 1544],
  "signingUrl": "https://tapsign.com.br/signing/bundle/5b1e9c3a-7d2f-4a6e-8c0b-3f5d7a9e1c24"
}

Campo	Tipo	Descrição
type	string	ENVELOPE (um modelo) ou BUNDLE (dois ou mais)
envelopeId	number ou null	ID do envelope quando type é ENVELOPE
bundleId	number ou null	ID do pacote quando type é BUNDLE
envelopeIds	number[]	IDs de todos os envelopes criados
signingUrl	string ou null	Link de assinatura do signatário

Erros

Código	Quando acontece
400	ID de modelo em formato inválido, modelo inativo (Este modelo esta inativo.), falha ao processar o DOCX ou campos obrigatórios ausentes em bundle-send
401	Token ausente ou inválido
404	Modelo não encontrado ou de outro usuário

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