Templates

Gerenciamento de templates de documentos com versionamento imutável.

Criar Template

POST /api/v1/document-templates

Request

{
  "data": {
    "type": "document-templates",
    "attributes": {
      "name": "Contrato de Empréstimo",
      "slug": "contrato-emprestimo-v1",
      "description": "Template padrão para contratos de empréstimo pessoal",
      "category": "CONTRACT",
      "content": "<h1>Contrato de Empréstimo</h1>\n<p>Eu, {{clientName}}, CPF {{clientCpf}}, declaro...</p>\n<p>Valor: R$ {{loanAmount}}</p>\n<p>Parcelas: {{installments}}x de R$ {{installmentValue}}</p>\n{{#if hasGuarantor}}\n<p>Avalista: {{guarantorName}}</p>\n{{/if}}",
      "variables": [
        { "name": "clientName", "type": "STRING", "required": true },
        { "name": "clientCpf", "type": "STRING", "required": true },
        { "name": "loanAmount", "type": "NUMBER", "required": true },
        { "name": "installments", "type": "NUMBER", "required": true },
        { "name": "installmentValue", "type": "NUMBER", "required": true },
        { "name": "hasGuarantor", "type": "BOOLEAN", "required": false, "default": false },
        { "name": "guarantorName", "type": "STRING", "required": false }
      ],
      "sampleData": {
        "clientName": "João da Silva",
        "clientCpf": "123.456.789-00",
        "loanAmount": 10000,
        "installments": 12,
        "installmentValue": 916.67,
        "hasGuarantor": true,
        "guarantorName": "Maria da Silva"
      }
    }
  }
}

Response

{
  "data": {
    "type": "document-templates",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "links": {
      "self": "/api/v1/document-templates/550e8400-e29b-41d4-a716-446655440000"
    },
    "attributes": {
      "name": "Contrato de Empréstimo",
      "slug": "contrato-emprestimo-v1",
      "description": "Template padrão para contratos de empréstimo pessoal",
      "category": "CONTRACT",
      "status": "DRAFT",
      "content": "...",
      "variables": [...],
      "sampleData": {...},
      "currentVersionNumber": 0,
      "isActive": true,
      "createdAt": "2024-01-28T10:00:00.000Z",
      "updatedAt": "2024-01-28T10:00:00.000Z"
    }
  }
}

Listar Templates

GET /api/v1/document-templates

Query Parameters

Parâmetro	Tipo	Descrição
page[number]	integer	Número da página (default: 1)
page[size]	integer	Itens por página (default: 20)
filter[status]	string	Filtrar por status: DRAFT, PUBLISHED, ARCHIVED
filter[category]	string	Filtrar por categoria
filter[active]	boolean	Filtrar por ativo/inativo

Response

{
  "links": {
    "self": "/api/v1/document-templates?page[number]=1&page[size]=20",
    "first": "/api/v1/document-templates?page[number]=1&page[size]=20",
    "next": "/api/v1/document-templates?page[number]=2&page[size]=20",
    "last": "/api/v1/document-templates?page[number]=5&page[size]=20"
  },
  "meta": {
    "totalItems": 100,
    "totalPages": 5,
    "currentPage": 1,
    "itemsPerPage": 20
  },
  "data": [
    {
      "type": "document-templates",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "Contrato de Empréstimo",
        "slug": "contrato-emprestimo-v1",
        "category": "CONTRACT",
        "status": "PUBLISHED",
        "currentVersionNumber": 2,
        "isActive": true
      }
    }
  ]
}

Obter Template

GET /api/v1/document-templates/:id

Response

{
  "data": {
    "type": "document-templates",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "links": {
      "self": "/api/v1/document-templates/550e8400-e29b-41d4-a716-446655440000"
    },
    "attributes": {
      "name": "Contrato de Empréstimo",
      "slug": "contrato-emprestimo-v1",
      "description": "Template padrão para contratos de empréstimo pessoal",
      "category": "CONTRACT",
      "status": "PUBLISHED",
      "content": "<h1>Contrato de Empréstimo</h1>...",
      "variables": [
        { "name": "clientName", "type": "STRING", "required": true },
        { "name": "loanAmount", "type": "NUMBER", "required": true }
      ],
      "sampleData": {
        "clientName": "João da Silva",
        "loanAmount": 10000
      },
      "currentVersionNumber": 2,
      "isActive": true,
      "createdAt": "2024-01-28T10:00:00.000Z",
      "updatedAt": "2024-01-28T12:00:00.000Z"
    }
  }
}

Atualizar Template

PATCH /api/v1/document-templates/:id

Request

{
  "name": "Contrato de Empréstimo Pessoal",
  "description": "Template atualizado",
  "content": "<h1>Contrato de Empréstimo Pessoal</h1>...",
  "variables": [...],
  "sampleData": {...}
}

Working Draft Pattern

Templates publicados podem ser editados. As edições modificam o "working draft", enquanto versões publicadas permanecem imutáveis. Para aplicar as edições, publique uma nova versão.

Response

{
  "data": {
    "type": "document-templates",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Contrato de Empréstimo Pessoal",
      "status": "PUBLISHED",
      "currentVersionNumber": 2,
      "updatedAt": "2024-01-28T14:00:00.000Z"
    }
  }
}

Excluir Template

DELETE /api/v1/document-templates/:id

Realiza soft delete (marca como deletado, não remove do banco).

Response

204 No Content

Publicar Versão

POST /api/v1/document-templates/:id/publish

Cria uma versão imutável do template atual. A renderização sempre usa a última versão publicada.

Request

{
  "changelog": "Ajuste na cláusula de multa por atraso"
}

Response

{
  "data": {
    "type": "document-templates",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Contrato de Empréstimo",
      "status": "PUBLISHED",
      "currentVersionNumber": 3
    }
  }
}

Listar Versões

GET /api/v1/document-templates/:id/versions

Response

{
  "data": [
    {
      "type": "document-template-versions",
      "id": "version-uuid",
      "attributes": {
        "versionNumber": 3,
        "content": "<h1>Contrato...</h1>",
        "variables": [...],
        "changelog": "Ajuste na cláusula de multa por atraso",
        "publishedAt": "2024-01-28T14:00:00.000Z"
      }
    },
    {
      "type": "document-template-versions",
      "id": "version-uuid-2",
      "attributes": {
        "versionNumber": 2,
        "changelog": "Adicionado campo de avalista",
        "publishedAt": "2024-01-20T10:00:00.000Z"
      }
    }
  ]
}

Obter Versão Específica

GET /api/v1/document-templates/:id/versions/:versionNumber

Response

{
  "data": {
    "type": "document-template-versions",
    "id": "version-uuid",
    "attributes": {
      "versionNumber": 2,
      "content": "<h1>Contrato de Empréstimo</h1>...",
      "variables": [
        { "name": "clientName", "type": "STRING", "required": true }
      ],
      "changelog": "Adicionado campo de avalista",
      "publishedAt": "2024-01-20T10:00:00.000Z"
    }
  }
}

Sintaxe Handlebars

O Document Template usa Handlebars como engine de templates.

Variáveis Simples

<p>Nome: {{clientName}}</p>
<p>Valor: R$ {{loanAmount}}</p>

Condicionais

{{#if hasGuarantor}}
  <p>Avalista: {{guarantorName}}</p>
{{else}}
  <p>Sem avalista</p>
{{/if}}

Loops

<ul>
{{#each installments}}
  <li>Parcela {{this.number}}: R$ {{this.value}} - Vencimento: {{this.dueDate}}</li>
{{/each}}
</ul>

Negação

{{#unless isPaid}}
  <p class="warning">Pagamento pendente</p>
{{/unless}}

Códigos de Erro

Código	Descrição
404 NOT_FOUND	Template não encontrado
409 CONFLICT	Slug já existe na organização
400 VALIDATION	Dados inválidos
400 VALIDATION	Template arquivado não pode ser editado