Detalhar Modelo

Retorna um modelo completo pelo ID, com as variáveis detectadas (fields), os signatários configurados (signers) e o status. Use antes de gerar documentos para saber quais chaves enviar em templateVariables.

Endpoint

GET /v1/models/{id}

Headers

Header	Valor
Authorization	Bearer {token}

Parâmetros de URL

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

Exemplo de Requisição

curl -X GET https://api.tapsign.com.br/v1/models/3f6b2c1e-8d4a-4f7b-9c2e-5a1d0b7e9f10 \
  -H "Authorization: Bearer {token}"

Resposta de Sucesso

Status: 200 OK

{
  "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,
      "displayOrder": 0,
      "label": "Nome do cliente",
      "helpText": null,
      "inputType": null,
      "required": true,
      "hidden": false,
      "contextText": "CONTRATANTE: {{nome_completo}}, inscrito no CPF {{cpf}}."
    }
  ],
  "signers": [
    {
      "id": "a1c3e5f7-2b4d-4f6a-8c0e-1d3f5a7b9c2e",
      "name": "",
      "email": "",
      "phone": null,
      "role": "SIGNER",
      "signOrder": 1,
      "isDynamic": true,
      "authMethods": [],
      "customRoleName": null,
      "signatureImage": null,
      "signatureType": null,
      "signaturePage": null,
      "signaturePosX": null,
      "signaturePosY": null,
      "signatureWidth": null,
      "signatureHeight": null,
      "positions": []
    }
  ],
  "ownerSign": false,
  "publicToken": "9c1f0a7b3e5d4c2a8b6f1e0d",
  "documentsCount": 127,
  "createdBy": "[email protected]",
  "createdAt": "2026-09-01T10:00:00Z",
  "updatedAt": "2026-09-12T14:30:00Z",
  "whatsappNotification": false,
  "signerAttachments": null,
  "externalEmails": null,
  "redirectUrl": null,
  "formLanguage": null
}

Campos da Resposta

Campo	Tipo	Descrição
id	string (UUID)	ID do modelo. É o templateId das rotas de integração
name	string	Nome do modelo
type	string	Tipo do arquivo do modelo (DOCX ou PDF)
status	string	ACTIVE ou INACTIVE. Só modelos ativos geram documentos
folderId	string (UUID) ou null	Pasta do modelo
organizationId	number ou null	Organização dona do modelo (null quando é pessoal)
fields[].name	string	Nome da variável. No documento aparece entre chaves duplas e é a chave de 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[].displayOrder	number	Ordem de exibição no formulário
fields[].label	string ou null	Rótulo amigável configurado para o campo
fields[].helpText	string ou null	Texto de ajuda exibido no preenchimento
fields[].inputType	string ou null	Tipo de entrada do campo no formulário, quando configurado
fields[].required	boolean	Se o campo é obrigatório no preenchimento
fields[].hidden	boolean	Se o campo fica oculto no formulário
fields[].contextText	string ou null	Parágrafo do DOCX onde a variável aparece
signers[].id	string (UUID)	ID do signatário configurado no modelo
signers[].name	string	Nome do signatário fixo (vazio quando é dinâmico)
signers[].email	string	E-mail do signatário fixo (vazio quando é dinâmico)
signers[].phone	string ou null	Telefone do signatário
signers[].role	string	Papel: SIGNER, WITNESS, APPROVER, ACKNOWLEDGE_RECEIPT, AUTHORIZE ou CUSTOM
signers[].signOrder	number	Ordem de assinatura
signers[].isDynamic	boolean	Se true, nome, e-mail e telefone são informados na hora de criar o documento
signers[].authMethods	string[]	Métodos de autenticação exigidos do signatário
signers[].customRoleName	string ou null	Nome do papel quando role é CUSTOM
signers[].signatureType	string ou null	Tipo da assinatura pré-configurada (DRAWN, TYPED ou UPLOADED)
signers[].signaturePage, signaturePosX, signaturePosY, signatureWidth, signatureHeight	number ou null	Posição da assinatura no documento
signers[].positions	array	Posições adicionais de assinatura (id, page, posX, posY, width, height)
ownerSign	boolean	Se o dono da conta também assina os documentos gerados
publicToken	string	Token do link público de preenchimento do modelo
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
whatsappNotification	boolean	Se os documentos gerados notificam os signatários por WhatsApp
signerAttachments	string ou null	Configuração de anexos exigidos do signatário
externalEmails	string ou null	E-mails externos que recebem cópia
redirectUrl	string ou null	URL de redirecionamento após a assinatura
formLanguage	string ou null	Idioma do formulário

Erros

Código	Quando acontece
400	id que não é um UUID válido
401	Token ausente ou inválido
404	Modelo não encontrado ou de outro usuário

Dica

Monte o objeto templateVariables a partir de fields[].name. Itens com fieldType igual a TABLE_LOOP representam grupos de repetição, e não uma variável de texto simples.