Vista Portal de clientes

Referência de configuração: Portal de clientes

Visão geral

A vista Portal de clientes mostra na app uma página feita para clientes externos: um documento HTML, gerado com IA, que lê os dados e, com ações, também cria registos. Os clientes abrem-no no endereço do portal, sem usar a app, e cada um vê só as linhas marcadas para ele e as colunas visíveis para clientes.

Usa-a para dar aos clientes uma página própria, por exemplo as encomendas ou os pedidos de cada um, sem lhes abrir o resto do workspace. Para haver dados a mostrar, a tabela precisa de uma coluna Contas externas e de colunas com Visível no portal ligado.

Na app, a vista mostra uma pré-visualização com as linhas da organização e o endereço do portal, com a ação Copiar endereço.

Portal guardado

A vista aponta para um portal guardado no workspace, em vez de trazer o documento dentro de si. O mesmo portal pode ser mostrado por mais do que uma vista, e a lista fica em Administração › Portais.

Um portal tem:

• Nome e Endereço: 2 a 48 letras minúsculas, números e hífenes, único na organização.
• Publicado: os clientes só abrem portais publicados. Só se liga depois de o documento ser gerado.
• Audiência: Todos os clientes ou Só contas escolhidas.
• Acesso: as contas externas que veem o portal, quando a audiência é Só contas escolhidas.
• Ações: o que os clientes podem enviar a partir do portal. Ver Ações.
• Conteúdo: o documento HTML, gerado com Gerar com IA (Alterar com IA depois de existir), e as consultas que ele lê.

Escolher o portal

Em Configurar, o cartão Portal tem:

• O seletor Escolhe um portal, com os portais ativos do workspace.
• Novo portal: abre o editor e liga à vista o portal que criares.
• Com um portal escolhido, os campos de endereço e de documento desaparecem e o cartão mostra o resumo (endereço, estado e audiência) e Editar portal, que edita o próprio portal.

Uma vista sem portal só deixa guardar depois de escolheres um.

Quem vê o portal

Audiência	Quem vê
Todos os clientes	Todas as contas externas da organização
Só contas escolhidas	Só as contas marcadas em Acesso

Um portal Só contas escolhidas sem nenhuma conta não é visível para ninguém. O editor avisa: «Sem contas escolhidas: ninguém vê este portal.»

Em /p, o cliente com um só portal abre-o diretamente. Com vários, vê Os seus portais, agrupados por organização, e escolhe um. Portais por publicar, arquivados ou fora da sua audiência não aparecem.

Ações

Uma ação deixa o cliente enviar um registo a partir do portal, por exemplo uma fatura com um ficheiro e alguns campos. Cada ação só cria registos numa tabela: não edita nem apaga os que já existem.

No editor do portal, a secção Ações tem um cartão por ação:

• Nome: o que o documento usa para enviar. Letras minúsculas, números e _, a começar por uma letra, e único no portal.
• Tabela: uma tabela publicada para clientes, com a coluna Contas externas.
• Uma linha por cada coluna Visível no portal que se pode preencher: texto, número, data, caixa de verificação, lista, ligação a tabela e ficheiro. Cada uma fica em Não (fora da ação), Opcional ou Obrigatório. Fórmulas, rollups e colunas de sistema ou de só leitura não aparecem.
• Em cada coluna de ficheiros, Tamanho máximo (MB), de 1 a 15, e Tipos aceites, por exemplo application/pdf ou image/*. Vazio aceita qualquer tipo.
• Confirmação: o texto que o portal mostra antes de enviar. Vazio envia logo.

Se a tabela exige uma coluna que a ação não pede, o editor avisa e os envios são recusados. Depois de mudares as ações, gera o documento de novo com Gerar com IA (ou Alterar com IA): a IA recebe as ações e desenha o formulário. A pré-visualização do editor não grava nada.

O cliente preenche o formulário do documento. Com confirmação, o portal mostra o texto e o cliente confirma ou cancela. Depois do envio o documento mostra o resultado: o registo criado ou os campos a corrigir. Os valores passam pelas regras da tabela, e um valor repetido numa coluna única é recusado.

Limites:

• 10 ações por portal.
• 5 ficheiros por envio, somando todas as colunas.
• 15 MB por ficheiro, ou o limite mais baixo definido na ação.
• 60 envios por hora para cada cliente.

O registo nasce na tabela escolhida com a origem Portal, criado pelo utilizador Sistema da organização, e fica marcado para o cliente que o enviou: só esse cliente o vê no portal, da próxima vez que o portal carregar os dados. Para a app é um registo como outro qualquer. Para correr uma automação só com estes registos, usa o filtro Origem do gatilho Registo (Mudança).

Para quem escreve a página

O documento recebe sempre window.OUTDO. Sem ações, window.OUTDO.actions é []: para saber se há ações, testa window.OUTDO.actions.length e não window.OUTDO.

• window.OUTDO.file(ref) e window.OUTDO.download(ref): mostram uma imagem ou descarregam um ficheiro de uma coluna de ficheiros, pela ref que cada ficheiro traz nos dados. Ver o manual de developers do portal.

• window.OUTDO.actions: a lista de ações, para desenhar o formulário. Cada uma tem name, confirm, fields (name, label, component, required, config) e files (name, label, required, max_bytes, mime_types, multiple). Nas listas e nas ligações, config.options traz as opções {id, label}.

• window.OUTDO.submit(name, {fields, files}): envia a ação name. fields é {coluna: valor}, onde a chave é o name do campo em window.OUTDO.actions, com datas AAAA-MM-DD, caixas true ou false, números como número e listas ou ligações pelo id da opção. files é {coluna: [File]}, com ficheiros de um <input type="file">.

A promessa nunca falha e resolve com:

• {ok: true, rowId, label}: o registo foi criado. label é o título dele, ou null.
• {ok: false, error, message, errors}: o envio falhou. error é invalid, duplicate, too_large, refused, rate_limited, not_found, busy, cancelled, session ou unavailable. message é um texto pronto para o cliente (não existe em cancelled, quando ele cancela a confirmação) e errors lista os campos a corrigir em invalid.

Envia sempre a partir de um <button type="button">: o documento não pode submeter formulários nem usar confirm(), e a confirmação é do portal. Só corre um envio de cada vez.

// Com <input id="nota">, <input id="fatura" type="file">, <button type="button" id="enviar"> e <p id="estado">
document.getElementById('enviar').onclick = async () => {
  const ficheiro = document.getElementById('fatura').files[0];
  const r = await window.OUTDO.submit('nova_fatura', {
    fields: { Nota: document.getElementById('nota').value },
    files: ficheiro ? { Fatura: [ficheiro] } : {},
  });
  document.getElementById('estado').textContent = r.ok ? 'Enviado: ' + (r.label ?? r.rowId) : r.message;
};

Vistas antigas

As vistas de portal que ainda guardam o documento dentro de si continuam a funcionar como antes. Em Configurar, o cartão avisa: «Esta vista ainda guarda o portal dentro dela. Ao guardar, passa a portal guardado, visível para todos os clientes.»

Na primeira vez que carregas em Guardar, o documento passa para um portal guardado com a audiência Todos os clientes, com o mesmo endereço, e a vista passa a apontar para ele. Os clientes continuam a vê-lo. Para o restringir, edita o portal e escolhe Só contas escolhidas.

Portal arquivado

Se o portal ligado for arquivado, os clientes deixam de o ver e a vista mostra «O portal ligado já não existe.» com a ação Configurar, para escolheres outro. Restaurar o portal em Administração › Portais volta a mostrá-lo.

Sugestões

• Para mudar o documento, edita o portal: a alteração vale para todas as vistas que o mostram e para os clientes.
• Se o editor avisar que o documento tem valores de linhas escritos à mão, pede à IA para os ler de window.OUTDO_DATA; senão todos os clientes veem esses valores.
• Um portal por publicar não abre para os clientes, mesmo com contas escolhidas.