Marcadores de posição: quais existem e onde se aplicam
Este artigo explica em que três locais do Univents existem marcadores de posição, como se escrevem em cada um, onde está a lista completa e porque não é possível criar marcadores próprios.
Um marcador de posição é um substituto no texto: escreve-se uma vez num modelo, e o Univents substitui-o, em cada documento e em cada e-mail, pelo valor real correspondente. Em vez de escrever o nome do cliente em cada orçamento, o modelo contém {Customer_Name} — no PDF final aparece o nome do cliente.
Existem três locais onde se usam marcadores de posição. Têm um aspeto semelhante, mas são listas separadas: um marcador de posição de um local não funciona noutro.
Os três locais em resumo
| Onde | Escrita | Exemplo | Lista completa |
|---|---|---|---|
| Modelos para orçamentos, faturas, guias de remessa e notas de crédito (ficheiro Word, convertido em PDF) | Uma chaveta | {Customer_Name} | Como criar layouts para documentos financeiros? |
| Modelos de e-mail em Definições → Modelos de e-mail | Duas chavetas | {{customer_name}} | O botão de marcadores de posição no editor do respetivo modelo |
| Automatizações (assunto, variáveis do modelo, textos de notificação) | Duas chavetas | {{gross_total}} | O botão de marcadores de posição junto ao respetivo campo |
As listas são separadas de propósito, porque por trás de cada uma estão dados diferentes: um documento conhece linhas, totais e taxas de imposto, um e-mail conhece o destinatário e o motivo, e uma automatização conhece apenas o que o respetivo acionador traz consigo.
Modelos de documentos: uma chaveta, nomes fixos
No modelo Word do layout, os marcadores de posição escrevem-se entre chavetas simples. A tabela completa com todos os nomes e o respetivo significado — documento, cliente, evento, empresa própria, totais, tabelas de linhas, textos livres — encontra-se no artigo Como criar layouts para documentos financeiros?.
Três pontos que ali passam facilmente despercebidos:
- A grafia tem de estar exatamente certa — incluindo maiúsculas e minúsculas.
{Customer_Name}devolve o nome do cliente,{customer_name}não. Copiar cada nome exatamente como consta da lista. - Um marcador de posição com erro de escrita nem sempre é detetado. Com um modelo Word, o marcador fica visível no PDF — lê-se aí
{Custmer_Name}e o erro vê-se de imediato. Nos layouts mais recentes, sem modelo Word, o espaço fica antes em branco. Por isso, não contar com o facto de um erro de escrita se tornar evidente por si só. - Um campo vazio dá origem a texto vazio. Se um cliente não tiver NIF-IVA registado,
{Customer_Tax_ID}desaparece do PDF sem deixar rasto. Um espaço em branco não significa, portanto, necessariamente uma lacuna nos dados — sem modelo Word, pode igualmente tratar-se de um erro de escrita.
Modelos de e-mail: duas chavetas, diferentes em cada modelo
Em Definições → Modelos de e-mail, ao abrir um modelo, vê-se junto ao assunto e ao texto um botão com chavetas. Este lista exatamente as variáveis que esse modelo conhece — o aviso de pagamento conhece {{days_overdue}}, a confirmação de turno não.
Se for escrita uma variável que o modelo não conhece, não é possível guardá-lo: o Univents apresenta «Marcadores de posição desconhecidos» e indica os nomes em causa. Esta é a proteção que evita que chegue ao cliente um e-mail com um {{foo}} em bruto.
Automatizações: duas chavetas, consoante o acionador
Numa automatização, podem conter marcadores de posição o Assunto, as Variáveis do modelo (ação «Enviar e-mail»), bem como o Título e a Mensagem (ação «Notificar utilizador»). Os marcadores disponíveis dependem do acionador da regra — uma regra sobre um documento financeiro conhece {{document_number}}, uma regra sobre um pedido não.
Duas exceções:
- O campo Para (e-mail) não aceita marcadores de posição; tem de ser um endereço fixo.
- No acionador E-mail recebido não existem quaisquer marcadores de posição — o conteúdo dos e-mails não está disponível por razões de proteção de dados.
Mais informações no artigo Automatizações: ações.
Criar marcadores de posição próprios — não é possível, e eis a alternativa
Não é possível inventar um marcador de posição próprio: nem um novo nome para documentos, nem uma nova variável para um modelo de e-mail. Ambas as listas são fixas.
Para documentos existem, em alternativa, os Campos de texto livre: dez blocos de texto de preenchimento livre por layout, {custom_text_0} a {custom_text_9}. O conteúdo é definido pelo próprio — e é possível mudar o nome da legenda, para que no editor de documentos apareça «Indicação de pagamento» em vez de «Texto livre 3».
- Abrir Definições → Modelos e aí Layouts PDF.
- Escolher o layout e abrir os Textos livres.
- Atribuir a cada campo uma designação e um texto predefinido.
- Em cada documento, substituir o texto na secção Campos de texto livre, sem alterar o texto predefinido.
Um texto livre pode, por sua vez, conter marcadores de posição — é assim que se constrói, por exemplo, um tratamento próprio com {Customer_First_Name} e {Customer_Last_Name}.
Não é possível criar um décimo primeiro campo, e o nome técnico (custom_text_3) mantém-se, mesmo que a legenda seja alterada. No modelo Word continua, portanto, a constar {custom_text_3}.
Via rápida: perguntar ao assistente
Em vez de consultar as tabelas, pode perguntar-se ao assistente de IA da aplicação: «Que marcadores de posição existem para faturas?» ou «Que variáveis conhece o modelo do aviso de pagamento?». O assistente lê a mesma lista que o Univents usa na geração dos documentos e responde com o nome e o significado.
Perguntas frequentes
No meu PDF aparece {Foo} em vez de um valor. O que aconteceu? O marcador de posição é desconhecido para o Univents — quase sempre um erro de escrita ou uma chaveta a mais. Se o nome errado aparece no PDF ou se apenas surge um espaço em branco depende do layout: com modelo Word, o marcador fica visível; sem modelo Word, o espaço fica em branco. Verificar logo: o nome consta exatamente assim na lista, incluindo maiúsculas e minúsculas? São chavetas simples (documento) e não duplas (e-mail)? O marcador de posição está dentro de uma caixa de texto ou de uma forma do Word? Aí, os marcadores de posição nunca são substituídos.
Posso usar um marcador de posição de documento num modelo de e-mail? Não. Os nomes distinguem-se logo na escrita ({Customer_Name} face a {{customer_name}}) e provêm de listas separadas.
Posso mudar o nome de um marcador de posição? Apenas a Legenda dos dez campos de texto livre. Todos os outros nomes são fixos, porque determinam o valor que o Univents insere.
Porque ficou um marcador de posição vazio? Normalmente porque o valor não está preenchido no documento, no contacto ou no evento. Preenchê-lo aí — por exemplo, o número fiscal em Definições → Empresa, para {workspace_tax_number}. Se se trabalhar com um layout sem modelo Word, verificar também a grafia: um nome com erro de escrita fica igualmente vazio.