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

# Segurança do Integrador Local

> Entenda como o Integrador Local do Plug4ia protege credenciais, comunicação e acesso aos dados do ERP no ambiente do cliente.

O **Integrador Local** foi desenhado para conectar o Plug4ia ao ERP do cliente sem expor o banco de dados diretamente na internet.

Ele roda dentro do ambiente do cliente, acessa o banco localmente e envia ao Plug4ia apenas os resultados necessários para responder às consultas autorizadas.

## Princípio principal

O Plug4ia não precisa receber as credenciais do banco do ERP.

As credenciais ficam no servidor do cliente, dentro do arquivo de configuração do integrador. A Software House configura esse arquivo durante a instalação e mantém o controle sobre onde ele fica armazenado.

> [!NOTE]
>
> O banco do ERP permanece acessível apenas pelo ambiente do cliente. O Plug4ia não abre conexão direta com esse banco.

## Camadas de segurança

> [card] Credenciais locais
>
> Usuário, senha, host e banco ficam no `config.yaml`, armazenado no servidor do cliente.

> [card] Token por empresa
>
> Cada empresa possui um token próprio, gerado no Portal Administrativo, usado para registrar o integrador.

> [card] Comunicação protegida
>
> A comunicação entre integrador e Plug4ia é sempre criptografada com TLS, e o certificado do servidor é validado.

> [card] Execução local
>
> As consultas são executadas no ambiente do cliente. Apenas o resultado necessário retorna ao Plug4ia.

> [card] Somente leitura
>
> O integrador só executa consultas de leitura, com um usuário de banco só leitura.

> [card] Acesso próprio por integrador
>
> Cada integrador recebe um acesso próprio ao servidor de mensagens, que só enxerga os comandos da própria empresa.

## Comunicação segura

O Integrador Local se comunica com o Plug4ia usando uma conexão autenticada e criptografada com TLS. O integrador valida o certificado do servidor antes de enviar qualquer dado.

Isso protege:

* O registro do integrador.
* O envio de comandos de consulta.
* O retorno dos resultados.
* Os sinais de status usados para monitoramento.

Ao se registrar com o token da empresa, o integrador recebe um acesso próprio ao servidor de mensagens do Plug4ia. Esse acesso só permite receber os comandos e enviar os resultados daquela empresa, e é renovado a cada novo registro.

> [!NOTE]
>
> A configuração de TLS faz parte da infraestrutura do Plug4ia. A Software House não precisa cadastrar certificados no Portal Administrativo nem no integrador.

## Somente leitura

O integrador foi feito apenas para consultar dados. Ele se protege em duas camadas:

1. Recusa qualquer comando que não seja uma única consulta `SELECT` ou `WITH`. Comandos como `INSERT`, `UPDATE`, `DELETE`, `DROP` ou várias instruções juntas nem chegam ao banco.
2. Onde o banco permite, abre a sessão em modo só leitura (MySQL 5.6 ou mais novo, MariaDB, PostgreSQL e Firebird).

Mesmo assim, o usuário de banco do integrador **precisa ser só leitura**: um `SELECT` ainda pode chamar uma função que grava dados, e SQL Server e MySQL 5.5 não têm sessão só leitura. Veja como criar esse usuário em [Configuração](https://docs.plug4ia.com/integrador/configuration.md).

## Token da empresa

O token da empresa identifica qual instalação do integrador pertence a qual empresa cadastrada no portal.

Boas práticas:

| Prática | Motivo |
| - | - |
| Gere um token por empresa | Evita reutilização indevida entre clientes |
| Copie o token apenas no momento da instalação | Reduz exposição desnecessária |
| Guarde o token em local seguro | Ele identifica a integração da empresa |
| Gere um novo token se houver suspeita de exposição | O integrador que usava o token anterior é desconectado na hora e precisa ser reconfigurado com o novo valor |

> [!WARNING]
>
> Não compartilhe tokens por e-mail aberto, mensagens públicas ou documentos sem controle de acesso.

## Proteção das credenciais do banco

O arquivo `config.yaml` contém dados sensíveis. Proteja esse arquivo no servidor do cliente.

Recomendações:

* Restrinja o acesso ao diretório de instalação.
* Permita leitura apenas para o usuário ou serviço responsável pelo integrador.
* Não envie o arquivo para terceiros.
* Não salve o arquivo em repositórios.
* Use um usuário de banco dedicado ao integrador, **obrigatoriamente só leitura**.
* Nunca use o usuário administrador do banco nem o usuário com que o ERP grava os dados.

> [!TIP]
>
> O usuário de banco usado pelo integrador deve ter acesso apenas às tabelas necessárias para as Tools configuradas.

No Linux, o instalador grava o `config.yaml` com permissão de leitura só para o integrador.

## Serviço do sistema operacional

Em Windows, o integrador é instalado como serviço **Plug4IAIntegrador**. Em Linux, a instalação usa Docker Compose com reinício automático do container.

Isso melhora a confiabilidade porque:

* O integrador inicia junto com o servidor.
* O serviço pode ser reiniciado em caso de falha.
* A operação não depende de uma janela de terminal aberta.
* A Software House consegue orientar o cliente a verificar o status do serviço.

## Monitoramento de status

O integrador envia sinais periódicos de funcionamento para que o Portal Administrativo mostre se a empresa está conectada.

No portal, a Software House consegue acompanhar:

* Empresas com integrador conectado.
* Empresas com integrador desconectado.
* Situação geral dos conectores pelo Dashboard.

> [!NOTE]
>
> O status do integrador ajuda a identificar rapidamente se uma falha de consulta está relacionada à conexão local da empresa.

## O que não fica exposto

| Informação | Fica exposta no portal? |
| - | - |
| Senha do banco do ERP | Não |
| Usuário do banco do ERP | Não |
| Host interno do banco | Não |
| Estrutura completa do banco | Não |
| Arquivo `config.yaml` | Não |

O portal usa apenas as informações necessárias para controlar a empresa, o token, o status da integração e as consultas configuradas.

## Checklist de segurança para implantação

Antes de liberar o cliente para uso, valide:

* A empresa correta recebeu o token correto.
* O integrador foi instalado no servidor autorizado.
* O arquivo de configuração está protegido.
* O usuário de banco é só leitura.
* Não existe outra instalação do integrador rodando com o mesmo token.
* O integrador aparece conectado no portal.
* As Tools foram revisadas e ativadas apenas quando aprovadas.
* O usuário final tem acesso somente às empresas permitidas.

> [!WARNING]
>
> A segurança da integração depende também das permissões concedidas no banco e das Tools configuradas. Revise consultas SQL antes de ativá-las para clientes em produção.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.