Criar Modelo DOCX

Faz upload de um arquivo DOCX com variáveis no formato {{variavel}} e cria um modelo reutilizável. O TapSign lê o documento, registra cada variável encontrada como um campo do modelo e devolve o modelo já ativo.

Endpoint

POST /v1/models/docx

Headers

Header	Valor
Authorization	`Bearer {token}`
Content-Type	`multipart/form-data`

Body (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
`file`	file	Sim	Arquivo `.docx` (Microsoft Word), com no máximo 10 MB
`name`	string	Sim	Nome do modelo
`folderId`	string (UUID)	Não	Pasta onde o modelo fica guardado
`organizationId`	number	Não	Organização dona do modelo. Você precisa ser membro ativo dela

Tipo do arquivo

A API confere o tipo MIME enviado na parte file: ele precisa ser application/vnd.openxmlformats-officedocument.wordprocessingml.document. Com curl, informe o tipo de forma explícita (;type=...), como no exemplo abaixo. PDF, DOC (formato antigo) e outros formatos são recusados.

Como as variáveis são detectadas

Cada texto no formato {{nome_variavel}} vira um campo do modelo. Espaços nas pontas do nome são descartados.
A leitura cobre os parágrafos do corpo do documento e as células das tabelas.
Um nome repetido no documento gera um único campo.
Um bloco {{#grupo}} ... {{/grupo}} define um grupo de repetição. O grupo aparece em fields com fieldType igual a TABLE_LOOP, e as variáveis dentro dele trazem loopGroup preenchido.
Todo campo detectado nasce com required: true.

Exemplos de variáveis: {{nome_completo}}, {{cpf}}, {{data_inicio}}, {{valor_contrato}}.

Exemplo de Requisição

curl -X POST https://api.tapsign.com.br/v1/models/docx \
  -H "Authorization: Bearer {token}" \
  -F "name=Contrato de Prestação de Serviços" \
  -F "[email protected];type=application/vnd.openxmlformats-officedocument.wordprocessingml.document"

Resposta de Sucesso

Status: 201 Created

Exemplo resumido. A resposta traz todos os campos descritos em Detalhar Modelo.

{
  "id": "3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10",
  "name": "Contrato de Prestação de Serviços",
  "type": "DOCX",
  "status": "ACTIVE",
  "folderId": null,
  "organizationId": null,
  "fields": [
    {
      "name": "nome_completo",
      "fieldType": "TEXT",
      "loopGroup": null,
      "required": true,
      "contextText": "CONTRATANTE: {{nome_completo}}, inscrito no CPF {{cpf}}."
    },
    {
      "name": "cpf",
      "fieldType": "TEXT",
      "loopGroup": null,
      "required": true,
      "contextText": "CONTRATANTE: {{nome_completo}}, inscrito no CPF {{cpf}}."
    }
  ],
  "signers": [],
  "documentsCount": 0,
  "createdBy": "[email protected]",
  "createdAt": "2026-09-12T14:30:00Z",
  "updatedAt": "2026-09-12T14:30:00Z"
}

Campos da Resposta

Campo	Tipo	Descrição
`id`	string (UUID)	ID do modelo. É o `templateId` usado em Criar Documento via Modelo
`name`	string	Nome do modelo
`type`	string	Tipo do arquivo do modelo (`DOCX`)
`status`	string	`ACTIVE` ou `INACTIVE`. O modelo nasce `ACTIVE`
`folderId`	string (UUID) ou null	Pasta do modelo
`organizationId`	number ou null	Organização dona do modelo (null quando é pessoal)
`fields`	array	Variáveis detectadas no DOCX
`fields[].name`	string	Nome da variável, sem as chaves. É a chave usada em `templateVariables`
`fields[].fieldType`	string	`TEXT` para variável comum ou `TABLE_LOOP` para grupo de repetição
`fields[].loopGroup`	string ou null	Grupo de repetição ao qual a variável pertence
`fields[].required`	boolean	Se o campo é obrigatório no preenchimento
`fields[].contextText`	string ou null	Parágrafo do DOCX onde a variável aparece (até 300 caracteres)
`signers`	array	Signatários configurados no modelo. Vazio logo após a criação
`documentsCount`	number	Quantidade de documentos gerados a partir do modelo
`createdBy`	string	E-mail de quem criou o modelo
`createdAt`	string (ISO 8601, UTC)	Data de criação
`updatedAt`	string (ISO 8601, UTC)	Data da última atualização

Substituir o arquivo de um modelo

Troca o DOCX de um modelo existente mantendo o mesmo id, sem precisar reapontar suas integrações. As variáveis são lidas de novo a partir do arquivo novo.

PUT /v1/models/{id}/docx

O body é multipart/form-data com a parte file, seguindo as mesmas regras de tipo e tamanho da criação. A resposta é 200 OK com o modelo atualizado.

curl -X PUT https://api.tapsign.com.br/v1/models/3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10/docx \
  -H "Authorization: Bearer {token}" \
  -F "[email protected];type=application/vnd.openxmlformats-officedocument.wordprocessingml.document"

Erros

Código	Quando acontece
`400`	Arquivo que não é DOCX, arquivo acima de 10 MB, falha ao ler o DOCX ou limite de modelos ativos do plano atingido (`Limite de modelos ativos atingido para o plano atual.`)
`401`	Token ausente ou inválido
`403`	`organizationId` de uma organização da qual você não é membro ativo
`404`	Na substituição: modelo não encontrado ou de outro usuário
`413`	Corpo da requisição acima de 10 MB, recusado antes de chegar à API

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

Dica

Para conferir como o modelo ficou, use GET /v1/models/{id}/pdf-preview, que devolve um PDF de pré-visualização. Com chave de API, essa rota aceita até 10 requisições por minuto.

Endpoint​

Headers​

Body (multipart/form-data)​

Exemplo de Requisição​

Resposta de Sucesso​

Campos da Resposta​

Substituir o arquivo de um modelo​

Erros​