Entidades

Uma entidade é um tipo de registro que o portal mostra: Fatura, Contrato, Boleto de aluguel, Mensalidade. Ela diz de onde os registros vêm, quais campos eles têm e de qual cliente é cada um.

Os registros vêm de um conector: de um endpoint de API, de uma tool MCP, de uma tabela do banco ou de uma consulta SQL. A sincronização copia esses registros para a plataforma, e os blocos do portal leem essa cópia — nunca a origem. Cada usuário do portal vê só os registros cujo titular é igual ao tenant ID dele (veja Titular e tenant ID).

As entidades ficam em Dados › Entidades (/dashboard/entities).

A lista de entidades

No workspace Aurora Energia, as três entidades leem do conector ERP Aurora Energia: Fatura, Nota fiscal e Unidade consumidora.

Coluna	O que mostra
Nome e Chave	O nome que aparece no dashboard e a chave que os blocos e o chat do Construtor usam (fatura)
Conector	De onde vêm os registros
Campos	Quantos campos a entidade tem
Titular	O campo que diz de qual cliente é cada registro. sem titular quer dizer que nenhum cliente vê os registros no portal
Registros	Quantos registros estão sincronizados
Última sync e Sync	Quando foi a última sincronização e como ela está: Em dia, Na fila, Sincronizando, Com erro ou Nunca sincronizada

As abas filtram pela situação da sincronização, a busca procura pelo nome e o filtro Conector mostra só as entidades de um conector. O menu … de cada linha sincroniza, edita ou remove a entidade.

Criar uma entidade

Você precisa de um conector antes. Depois:

1. Em Dados › Entidades, clique em Nova entidade. (Na página do conector, Criar entidade ao lado de um endpoint, tool ou tabela já abre com ela escolhida.)
2. Escolha a Conexão e a operação de onde vêm os dados: o endpoint, a tool ou a tabela. Num banco SQL, você também pode escrever uma consulta SQL.
3. Preencha os Parâmetros que a operação pede, quando houver. Nessa etapa você também ajusta a paginação, quando sincronizar e os filtros do sync.
4. Clique em Buscar dados. A plataforma busca uma amostra na origem e monta os campos a partir do que voltou.
5. Revise a entidade:
   • Nome, Nome no plural e Chave — por exemplo, Fatura, Faturas e fatura.
   • Identificador — o campo que identifica cada registro na origem, como id.
   • Título — o campo que serve de nome de cada registro, como a descrição da fatura.
   • ID do Titular — o campo com o ID do cliente, e como ele é comparado ao tenant ID.
   • Os campos: quais entram, com que nome, tipo e papel.
6. Clique em Criar entidade com N campos.

A entidade é criada e a primeira sincronização entra na fila. Ver a amostra recebida, no fim da tela, mostra os primeiros registros como a origem enviou.

aviso

Sem ID do Titular, nenhum usuário do portal vê os registros da entidade. Escolha o campo com o CPF/CNPJ ou o código do cliente.

Limite de campos

Cada workspace tem um limite de campos para uma entidade nova (10, se nada diferente foi combinado). A tela mostra quantos você escolheu — por exemplo, 8 de 10 campos — e, no limite, você desmarca um campo para escolher outro.

A página da entidade

Clique numa entidade para abrir a página dela. No topo ficam Sincronizar, Sincronização completa e Editar. As abas:

Aba	O que tem
Visão geral	De onde vêm os dados, o identificador, o título, o titular, a situação da sincronização e a Zona de perigo
Registros	Os registros sincronizados (veja Registros)
Campos	Os campos, com chave, nome, tipo, papel, caminho na origem e se são visíveis (veja Campos)
Uso no portal	As páginas do portal que usam a entidade, marcadas como rascunho ou publicado
Tenants	Só nas entidades que sincronizam quando o usuário acessa (veja Sincronização das entidades)
Logs	As chamadas que a sincronização desta entidade fez ao conector

Relacionar entidades

Relacionar entidades junta os registros de duas entidades por um campo em comum e cria uma entidade nova, que você usa nos blocos como qualquer outra. Por exemplo, juntar as faturas com as unidades consumidoras pelo código da unidade.

1. Clique em Relacionar entidades.
2. Escolha a Entidade principal, a entidade para Relacionar com e o campo de cada uma que deve ser igual. Marque Comparar só os dígitos quando o campo é um CPF/CNPJ ou telefone.
3. Escolha se a relação mantém todos os registros da principal (os sem correspondência ficam com os campos da relacionada vazios) ou só os registros com correspondência.
4. Clique em Ver correspondências para conferir quantos registros se encontraram.
5. Escolha os campos da entidade nova, o Titular e o Título, e clique em Criar relação.

Remover uma entidade

Na Visão geral, em Zona de perigo, clique em Remover. Antes de confirmar, a tela mostra as páginas do portal que usam a entidade — elas param de mostrar esses dados. O conector e os dados na origem não mudam.

Para apagar só os registros e manter a entidade, use Limpar (veja Registros).