Marcadores de posição: quais existem e onde se aplicam
Depois de ler este artigo, ficas a saber 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 dentro do texto: escreves-o 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.
Há 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 num relance
| Onde | Notação | Exemplo | Lista completa |
|---|---|---|---|
| Modelos para orçamentos, faturas, guias de remessa, 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 de cada 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 a cada campo |
As listas estão propositadamente separadas porque os dados por trás são 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 seu acionador fornece.
Modelos de documentos: uma chaveta, nomes fixos
No modelo Word do teu 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, a tua empresa, totais, tabelas de linhas, textos livres — encontra-se no artigo Como criar layouts para documentos financeiros?.
Três pontos que facilmente passam despercebidos aí:
- A grafia tem de estar exatamente correta — incluindo maiúsculas e minúsculas.
{Customer_Name}devolve o nome do cliente,{customer_name}não. Copia cada nome exatamente como consta da lista. - Um marcador de posição mal escrito nem sempre é visível. Com um modelo Word, fica visível no PDF — lês aí
{Custmer_Name}e vês logo o erro. Nos layouts mais recentes, sem modelo Word, o local fica antes vazio. Não contes, por isso, com o facto de um erro de digitação se tornar evidente por si só. - Um campo vazio dá texto vazio. Se um cliente não tiver NIF registado,
{Customer_Tax_ID}desaparece do PDF sem deixar rasto. Um local vazio não significa, por isso, necessariamente uma lacuna nos dados — sem modelo Word, pode igualmente tratar-se de um erro de digitação.
Modelos de e-mail: duas chavetas, diferentes em cada modelo
Em Definições → Modelos de e-mail, abre um modelo e verás, junto ao assunto e ao texto, um botão com chavetas. Lista exatamente as variáveis que esse modelo conhece — o lembrete de fatura conhece {{days_overdue}}, a confirmação de turno não.
Se escreveres uma variável que esse modelo não conhece, o modelo não pode ser guardado: o Univents indica «Marcadores de posição desconhecidos» e refere os nomes em causa. É a proteção contra o envio de um e-mail com um {{foo}} em bruto para o cliente.
Algumas variáveis são, em contrapartida, conhecidas por todos os modelos em que {{sender_name}} funciona: {{company_name}}, {{account_name}}, {{sender_name}} e, desde 12/10/2026, também {{sender_email}} e {{sender_phone}}. As duas novas correspondem ao endereço de e-mail e ao número de telefone da pessoa que desencadeia o e-mail — nos e-mails de documentos enviados a partir da caixa de correio de um responsável, os dados dessa pessoa; caso contrário, os dados do teu workspace.
Alguns marcadores existem apenas ao enviar um documento, não em automatizações: {{portal_url}} (ligação ao portal do cliente), {{view_url}} (documentos no portal), {{event_url}} e {{messages_url}} (só se o documento pertencer a um evento), além de {{quote_link}} (apenas orçamentos) e {{invoice_link}} (apenas faturas). Num e-mail de automatização ficariam sem substituir. Mais no artigo Modelos de e-mail e marcadores.
Automatizações: duas chavetas, consoante o acionador
Numa automatizaçã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») podem conter marcadores de posição. Os que estão 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 — por razões de proteção de dados, o conteúdo dos e-mails não está disponível.
Mais informações no artigo Automatizações: ações.
Criar marcadores de posição próprios — não é possível, mas há uma alternativa
Não podes 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, de {custom_text_0} a {custom_text_9}. O que lá escreves fica ao teu critério — e podes mudar o nome do rótulo, para que no editor de documentos apareça «Indicação de pagamento» em vez de «Texto livre 3».
- Abre Definições → Modelos e seleciona o filtro Modelo de layout.
- Seleciona o teu layout e abre os Textos livres.
- Atribui a cada campo uma designação e um texto predefinido.
- Num documento em concreto, substituis 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 podes construir, por exemplo, um tratamento próprio a partir de {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 alteres o rótulo. No modelo Word continua, portanto, a constar {custom_text_3}.
Caminho rápido: perguntar ao assistente
Em vez de percorrer as tabelas, podes perguntar ao assistente de IA na app: «Que marcadores de posição existem para faturas?» ou «Que variáveis conhece o modelo do lembrete de fatura?». Ele 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 digitação ou uma chaveta a mais. Se lês o nome errado no PDF ou vês apenas um local vazio depende do layout: com modelo Word, o nome fica visível; sem modelo Word, o local fica vazio. Verifica logo: o nome está escrito exatamente como 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 já diferem na notação ({Customer_Name} em vez de {{customer_name}}) e provêm de listas separadas.
Posso mudar o nome de um marcador de posição? Apenas o Rótulo 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. Preenche-o aí — por exemplo, o número de contribuinte em Definições → Empresa, para {workspace_tax_number}. Se trabalhas com um layout sem modelo Word, verifica também a grafia: um nome mal escrito também fica vazio nesse caso.