Usar Modelo

Cria um documento preenchido a partir de um modelo existente, substituindo as variaveis pelos valores informados. O documento e automaticamente inserido em um novo envelope com os signatarios definidos.

Endpoint

POST /v1/models/{id}/documents

Headers

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

Parametros de URL

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

Body

Campo	Tipo	Obrigatorio	Descricao
variables	object	Sim	Objeto com chave-valor das variaveis do modelo
signers	array	Sim	Lista de signatarios para o envelope
signers[].name	string	Sim	Nome do signatario
signers[].email	string	Sim	Email do signatario
signers[].role	string	Nao	Papel: SIGNER, WITNESS, APPROVER, CARBON_COPY. Padrao: SIGNER
signers[].phone	string	Nao	Telefone com DDD
envelopeName	string	Nao	Nome do envelope. Se nao informado, usa o nome do modelo
autoSend	boolean	Nao	Se true, envia o envelope automaticamente apos a criacao. Padrao: false

Fluxo completo

Ao usar um modelo, o TapSign executa os seguintes passos automaticamente:

1. Substitui todas as variaveis {{...}} pelos valores fornecidos
2. Gera um PDF a partir do DOCX preenchido
3. Cria um novo envelope com o documento
4. Adiciona os signatarios informados
5. Se autoSend: true, envia o envelope imediatamente

Exemplo de Requisicao

curl -X POST https://api.tapsign.com.br/v1/models/m1o2d3e4-l5o6-7890-abcd-ef1234567890/documents \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "nome_completo": "Joao Pedro da Silva",
      "cpf": "123.456.789-00",
      "data_inicio": "01/04/2026",
      "valor_contrato": "R$ 5.000,00"
    },
    "signers": [
      {
        "name": "Joao Pedro da Silva",
        "email": "joao@empresa.com.br",
        "role": "SIGNER"
      },
      {
        "name": "Maria Souza",
        "email": "maria@empresa.com.br",
        "role": "WITNESS"
      }
    ],
    "envelopeName": "Contrato - Joao Pedro da Silva",
    "autoSend": true
  }'

Resposta de Sucesso

Status: 201 Created

{
  "envelope": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Contrato - Joao Pedro da Silva",
    "status": "SENT",
    "createdAt": "2026-03-29T14:30:00Z"
  },
  "document": {
    "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
    "name": "Contrato de Prestacao de Servicos.pdf",
    "pages": 5
  },
  "signers": [
    {
      "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
      "name": "Joao Pedro da Silva",
      "email": "joao@empresa.com.br",
      "role": "SIGNER",
      "status": "PENDING",
      "signingUrl": "https://app.tapsign.com.br/sign/abc123def456"
    },
    {
      "id": "a9b8c7d6-e5f4-3210-9876-543210fedcba",
      "name": "Maria Souza",
      "email": "maria@empresa.com.br",
      "role": "WITNESS",
      "status": "PENDING",
      "signingUrl": "https://app.tapsign.com.br/sign/xyz789ghi012"
    }
  ],
  "model": {
    "id": "m1o2d3e4-l5o6-7890-abcd-ef1234567890",
    "name": "Contrato de Prestacao de Servicos"
  }
}

Campos da Resposta

Objeto envelope

Campo	Tipo	Descricao
id	string (UUID)	ID do envelope criado
name	string	Nome do envelope
status	string	DRAFT (se autoSend: false) ou SENT (se autoSend: true)
createdAt	string (ISO 8601)	Data de criacao

Objeto document

Campo	Tipo	Descricao
id	string (UUID)	ID do documento gerado
name	string	Nome do arquivo PDF gerado
pages	number	Numero de paginas

Array signers

Campo	Tipo	Descricao
id	string (UUID)	ID do signatario
name	string	Nome do signatario
email	string	Email do signatario
role	string	Papel atribuido
status	string	Status inicial (PENDING)
signingUrl	string	URL de assinatura

Erros

Codigo	Descricao
400	Variaveis obrigatorias ausentes ou formato invalido
404	Modelo nao encontrado
422	Variavel desconhecida enviada (nao existe no modelo)

Atencao

Todas as variaveis marcadas como required no modelo devem ser preenchidas. Caso alguma esteja ausente, a requisicao sera rejeitada com erro 400.

Dica

Use autoSend: true para automatizar o fluxo completo em uma unica chamada. Isso e especialmente util em integracoes onde voce ja tem todos os dados prontos e quer evitar uma segunda chamada para enviar o envelope.