> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Adicionar um Template

> Crie um Template no Reporter usando o Template Builder ou enviando um arquivo .tpl preparado.

Use esta página para criar o Template que o Reporter usará para gerar um Relatório. Um Template é a estrutura reutilizável do arquivo de saída: define o layout, os campos, as condições, os loops, os cálculos e o formato final.

## Objetivo

***

Adicionar um Template que os operadores possam selecionar ao gerar Relatórios.

Por exemplo, um Template fiscal mensal pode definir um cabeçalho CSV, uma linha por transação e um valor total no fim do arquivo. Um Template XML regulatório pode definir as tags XML necessárias e preenchê-las com valores de um Data Source.

## Quando usar

***

Use esta tarefa quando:

* você está configurando o primeiro Template para um relatório cujo Data Source já existe;
* uma nova obrigação de relatório exige uma nova estrutura de saída;
* seu time já tem um arquivo `.tpl` revisado e precisa disponibilizá-lo no Console;
* um operador precisa construir o Template visualmente em vez de editar código `.tpl`.

Não use esta tarefa para corrigir um Template que já existe. Use [Atualizar um Template](/pt/lerian-console/reporter-console/updating-a-template) em vez disso.

## Antes de começar

***

Confirme:

* o Data Source que vai alimentar o Template está disponível quando o Template precisa de campos de banco. Pode ser uma fonte interna já configurada para o ambiente ou uma externa adicionada a partir de **Data Sources**;
* o formato de saída esperado é conhecido: CSV, XML, HTML, TXT ou PDF;
* o Template será criado no **Template Builder** ou enviado como arquivo `.tpl`;
* o responsável pelo relatório confirmou os campos que devem aparecer na saída.

<Note>
  Um Template não é um Relatório gerado. É a definição reutilizável que o Reporter aplica depois durante a geração.
</Note>

## Opção 1: Construir no Template Builder

***

Use o Template Builder quando um operador precisar montar o Template visualmente a partir de blocos.

<Steps>
  <Step title="Abra o Template Builder">
    Vá para a página **Templates** e clique em **Template Builder**.
  </Step>

  <Step title="Dê nome ao Template">
    Use um nome que os operadores possam reconhecer depois, como `Monthly tax CSV` ou `Daily transaction PDF`.
  </Step>

  <Step title="Escolha o formato de saída">
    Selecione o formato que o Relatório gerado deve produzir: XML, HTML, CSV, TXT ou PDF.
  </Step>

  <Step title="Adicione os blocos do Template">
    Adicione blocos como **Texto**, **Variável**, **Loop**, **Condicional** ou **Agregação**. Na prática, os blocos representam as peças do arquivo final: texto fixo, valores de banco, linhas repetidas, seções condicionais ou totais.
  </Step>

  <Step title="Conecte campos aos dados">
    Use a sidebar de Data Sources para selecionar campos da conexão configurada. Por exemplo, use um bloco **Variável** para colocar `transactions.amount` na saída.
  </Step>

  <Step title="Salve o Template">
    Clique em **Salvar** para validar os blocos e salvar o arquivo `.tpl` gerado.
  </Step>
</Steps>

## Opção 2: Enviar um arquivo `.tpl`

***

Use o envio quando um time técnico já mantém o Template fora do Console.

<Steps>
  <Step title="Abra o wizard de envio">
    Vá para a página **Templates** e clique em **Novo Template**.
  </Step>

  <Step title="Envie o arquivo">
    No passo **Arquivo**, arraste o arquivo `.tpl` para **Arraste o arquivo aqui**, ou clique em **para selecionar** para procurar no seu computador.
  </Step>

  <Step title="Configure o Template">
    No passo **Config**, preencha **Nome do Template** e **Formato de Saída**.
  </Step>

  <Step title="Revise o resumo">
    No passo **Revisão**, confirme o arquivo, o nome e o formato de saída. Use os botões de edição se algum campo estiver errado.
  </Step>

  <Step title="Salve o Template">
    Clique em **Salvar Template**.
  </Step>
</Steps>

<Tip>
  **API equivalente**: [Endpoint Upload template](/pt/reference/reporter/upload-template)
</Tip>

## Guia de campos

***

### Campos do wizard de envio

| Campo                          | O que informar                                                                                                                       | Exemplo           |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| **Arquivo de Template (.tpl)** | Arquivo `.tpl` obrigatório usado como fonte do Template. Deve ser maior que 0 bytes e não superior a 5 MB. Campo de API: `template`. | `monthly-tax.tpl` |
| **Nome do Template**           | Nome obrigatório visível ao operador. Mapeia para `name` no Console e para `description` na API do Reporter.                         | `Monthly tax CSV` |
| **Formato de Saída**           | Tipo obrigatório de saída. Use `csv`, `xml`, `html`, `txt` ou `pdf`.                                                                 | `csv`             |

### Campos do Template Builder

| Campo                   | O que informar                                                                                                                        | Exemplo                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Nome do template**    | Nome obrigatório no cabeçalho do builder. Vira o nome salvo do Template e o prefixo do nome do arquivo `.tpl` gerado.                 | `Daily transaction PDF`                                               |
| Barra de blocos         | Adicione pelo menos um bloco antes de salvar. Os blocos viram o código `.tpl` gerado.                                                 | Cabeçalho **Texto** + **Loop** sobre transações + **Agregação** total |
| Sidebar de Data Sources | Use os Data Sources configurados para inserir campos em blocos **Variável**. Campos técnicos incluem `dataSource`, `table` e `field`. | `production-postgres.transactions.amount`                             |

## Resultado esperado

***

Após salvar, o Template aparece na página **Templates** e pode ser selecionado no wizard **Gerar Relatório**.

## Erros comuns e pontos de atenção

***

<AccordionGroup>
  <Accordion title="Enviar um arquivo que não é `.tpl`">
    O envio aceita apenas arquivos `.tpl`. Se o Template ainda está em desenho, use primeiro o **Template Builder** ou prepare o arquivo `.tpl` fora do Console.
  </Accordion>

  <Accordion title="Escolher o formato de saída errado">
    O formato de saída controla que tipo de arquivo os operadores vão baixar após gerar um Relatório. Confirme o formato exigido antes de salvar.
  </Accordion>

  <Accordion title="Criar um Template antes de o Data Source estar pronto">
    Templates podem referenciar campos de Data Sources. Se a fonte necessária está faltando ou não foi testada, os operadores podem não saber quais campos são seguros usar.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

* Use [Gerar um Relatório](/pt/lerian-console/reporter-console/generating-a-report) para criar um Relatório a partir do Template.
* Use [Atualizar um Template](/pt/lerian-console/reporter-console/updating-a-template) se a estrutura, o arquivo, o nome ou o formato de saída precisarem de correção.
* Use o [Template Builder](/pt/lerian-console/reporter-console/template-builder) quando os operadores precisarem manter o Template visualmente.