> ## 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.

# Configurando o Integrador Local

> Entenda os campos de configuração do Integrador Local do Plug4ia e como preencher dados de banco, limites e token da empresa.

O Integrador Local usa um arquivo chamado `config.yaml` para guardar as informações necessárias para conectar a empresa ao Plug4ia e acessar os dados do ERP.

Em instalações Windows, esse arquivo é criado pelo assistente de instalação, na pasta do integrador (padrão `C:\Program Files (x86)\Plug4IA\Integrador`). Em instalações Linux, ele é criado pelo script de instalação, no diretório escolhido (padrão `/opt/plug4ia-integrador`).

> [!WARNING]
>
> O `config.yaml` contém token da empresa e credenciais de acesso ao banco. Proteja esse arquivo no servidor do cliente.

O integrador só lê o `config.yaml`, nunca o altera. Depois de editar o arquivo, reinicie o serviço (Windows) ou o container (Linux) para a mudança valer.

## Exemplo básico

```yaml theme={null}
token_empresa: "token-gerado-no-portal"
server_base_url: "https://app.plug4ia.com"

database:
  host: "127.0.0.1"
  port: 3306
  user: "plug4ia_leitura"
  password: "senha"
  database: "erpdb"

limits:
  max_rows: 1000
  max_payload_kb: 512
  query_timeout_s: 15
```

## Token da empresa

| Campo | Descrição |
| - | - |
| `token_empresa` | Token gerado no Portal Administrativo para a empresa |
| `server_base_url` | Endereço do Plug4ia. Padrão: `https://app.plug4ia.com`. Não altere |

Esse token identifica a empresa durante a conexão do integrador.

Para gerar:

1. Acesse **Empresas** no Portal Administrativo.
2. Edite a empresa.
3. Abra a aba **Integração**.
4. Clique em **Gerar Token**.
5. Copie o token para a instalação do integrador.

> [!NOTE]
>
> O token é específico da empresa. Não reutilize o token de uma empresa em outra instalação. Gerar um novo token desconecta na hora o integrador que usava o anterior.

## Usuário só leitura no banco (obrigatório)

O integrador só executa consultas. Crie no banco do ERP um usuário que tenha **apenas permissão de leitura** e use esse usuário no `config.yaml`. Nunca use o usuário administrador do banco (`root`, `sa`, `postgres`, `SYSDBA`) nem o usuário com que o próprio ERP grava os dados.

O integrador também se protege sozinho: recusa qualquer comando que não seja um único `SELECT` ou `WITH` e, onde o banco permite, abre a sessão em modo só leitura (MySQL 5.6 ou mais novo, MariaDB, PostgreSQL e Firebird). Isso não substitui o usuário só leitura, porque um `SELECT` ainda pode chamar uma função que grava dados.

> [!WARNING]
>
> **SQL Server e MySQL 5.5 não têm sessão só leitura.** Nesses bancos, o usuário só leitura é a única proteção contra alteração de dados.

Exemplos com nomes fictícios (banco `erp_loja`, usuário `plug4ia_leitura`, máquina do integrador em `192.168.0.10`). Troque os nomes, o IP e a senha pelos do cliente.

```sql MySQL / MariaDB theme={null}
-- Troque 192.168.0.10 pelo IP da máquina do integrador ('%' libera qualquer máquina)
CREATE USER 'plug4ia_leitura'@'192.168.0.10' IDENTIFIED BY '<senha-forte>';
GRANT SELECT ON erp_loja.* TO 'plug4ia_leitura'@'192.168.0.10';
```

```sql SQL Server theme={null}
-- Login no servidor + usuário no banco com o papel db_datareader
CREATE LOGIN plug4ia_leitura WITH PASSWORD = '<senha-forte>';
USE erp_loja;
CREATE USER plug4ia_leitura FOR LOGIN plug4ia_leitura;
ALTER ROLE db_datareader ADD MEMBER plug4ia_leitura;
```

```sql PostgreSQL theme={null}
-- Repita os GRANT para cada schema usado pelo ERP (aqui, public)
CREATE ROLE plug4ia_leitura LOGIN PASSWORD '<senha-forte>';
GRANT CONNECT ON DATABASE erp_loja TO plug4ia_leitura;
GRANT USAGE ON SCHEMA public TO plug4ia_leitura;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO plug4ia_leitura;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO plug4ia_leitura;
```

```sql Firebird theme={null}
-- Não existe permissão para "todas as tabelas": dê SELECT em cada tabela usada pelas consultas
CREATE USER PLUG4IA_LEITURA PASSWORD '<senha-forte>';
GRANT SELECT ON CLIENTES TO PLUG4IA_LEITURA;
GRANT SELECT ON VENDAS TO PLUG4IA_LEITURA;
```

Arquivos DBF não têm usuário: o integrador só lê os arquivos da pasta configurada.

## Seção do banco

A seção do banco precisa ter o nome que corresponde ao banco do ERP cadastrado no portal: `database` para MySQL ou MariaDB, `sqlserver` para SQL Server, `postgres` para PostgreSQL, `firebird` para Firebird e `dbf` para arquivos DBF. Se a seção tiver outro nome, toda consulta volta com o erro `database configuration missing`.

### MySQL ou MariaDB

```yaml theme={null}
database:
  host: "127.0.0.1"
  port: 3306
  user: "plug4ia_leitura"
  password: "senha"
  database: "erpdb"
```

| Campo | Descrição |
| - | - |
| `database.host` | IP ou endereço do servidor do banco |
| `database.port` | Porta do banco, normalmente `3306` |
| `database.user` | Usuário só leitura |
| `database.password` | Senha do usuário |
| `database.database` | Nome do banco |

### SQL Server

```yaml theme={null}
sqlserver:
  host: "127.0.0.1"
  port: 1433
  user: "plug4ia_leitura"
  password: "senha"
  database: "erpdb"
  driver: "ODBC Driver 17 for SQL Server"
```

| Campo | Descrição |
| - | - |
| `sqlserver.host` | IP ou endereço do SQL Server |
| `sqlserver.port` | Porta do SQL Server, normalmente `1433` |
| `sqlserver.user` | Usuário só leitura |
| `sqlserver.password` | Senha do usuário |
| `sqlserver.database` | Nome do banco |
| `sqlserver.driver` | Driver ODBC instalado no servidor (padrão: `ODBC Driver 17 for SQL Server`) |

> [!NOTE]
>
> No Linux com Docker, a imagem do integrador já inclui o driver ODBC 17 do SQL Server.

### PostgreSQL

```yaml theme={null}
postgres:
  host: "127.0.0.1"
  port: 5432
  user: "plug4ia_leitura"
  password: "senha"
  database: "erpdb"
```

| Campo | Descrição |
| - | - |
| `postgres.host` | IP ou endereço do PostgreSQL |
| `postgres.port` | Porta do PostgreSQL, normalmente `5432` |
| `postgres.user` | Usuário só leitura |
| `postgres.password` | Senha do usuário |
| `postgres.database` | Nome do banco |

### Firebird

Disponível no integrador para Windows.

```yaml theme={null}
firebird:
  host: "127.0.0.1"
  port: 3050
  user: "PLUG4IA_LEITURA"
  password: "senha"
  database: "C:/caminho/para/o/banco.fdb"
```

| Campo | Descrição |
| - | - |
| `firebird.host` | IP ou endereço do servidor Firebird |
| `firebird.port` | Porta do Firebird, normalmente `3050` |
| `firebird.user` | Usuário só leitura |
| `firebird.password` | Senha do usuário |
| `firebird.database` | Caminho do arquivo `.fdb` |

### Arquivos DBF

```yaml theme={null}
dbf:
  base_path: "C:/dados/dbf"
  encoding: "latin-1"
```

| Campo | Descrição |
| - | - |
| `dbf.base_path` | Pasta onde ficam os arquivos `.dbf` |
| `dbf.encoding` | Codificação dos arquivos (padrão: `latin-1`) |

## Várias empresas no mesmo integrador

Um único integrador pode atender várias empresas. Cada empresa é um bloco completo no `config.yaml`, com o próprio `token_empresa` e a própria seção de banco, e os blocos são separados por uma linha contendo apenas `---`:

```yaml theme={null}
token_empresa: "token-da-empresa-1"
sqlserver:
  host: "SERVIDOR"
  port: 1433
  user: "plug4ia_leitura"
  password: "senha"
  database: "ERP"
---
token_empresa: "token-da-empresa-2"
sqlserver:
  host: "SERVIDOR"
  port: 1433
  user: "plug4ia_leitura"
  password: "senha"
  database: "ERP"
```

* Cada empresa usa o próprio token, gerado no portal no cadastro da empresa.
* As empresas podem usar o mesmo banco (basta repetir a seção, como no exemplo) ou bancos diferentes, inclusive de tipos diferentes.
* `server_base_url`, `limits` e `heartbeat_seconds` valem por bloco: repita-os no bloco que precisar de um valor diferente do padrão.
* Se uma empresa não consegue se conectar quando o serviço inicia (portal ou internet fora do ar), o integrador tenta de novo a cada 30 segundos, sem parar as outras empresas.

> [!WARNING]
>
> Sem a linha `---`, o arquivo é lido como uma empresa só e vale apenas o último bloco. O sintoma é o portal mostrar conectada somente a última empresa da lista, e o log do integrador mostrar `config.duplicate_key` com a chave e a linha repetidas.

## Limites de consulta

Os limites ajudam a evitar respostas grandes demais ou consultas demoradas.

```yaml theme={null}
limits:
  max_rows: 1000
  max_payload_kb: 512
  query_timeout_s: 15
```

| Campo | Descrição |
| - | - |
| `limits.max_rows` | Quantidade máxima de linhas por consulta (padrão: `1000`). O Plug4ia pode pedir menos, nunca mais |
| `limits.max_payload_kb` | Tamanho máximo do resultado enviado, em KB (padrão: `512`) |
| `limits.query_timeout_s` | Tempo máximo de cada consulta, em segundos (padrão: `15`), limitado ao tempo que o Plug4ia espera pela resposta |
| `heartbeat_seconds` | Intervalo dos sinais de funcionamento enviados ao portal, em segundos (padrão: `30`) |

> [!NOTE]
>
> O limite de tempo da consulta vale para MySQL 5.7 ou mais novo, MariaDB e PostgreSQL, e para SQL Server no integrador para Windows. Firebird, MySQL 5.5 e 5.6, e SQL Server no Linux não têm esse limite.

> [!TIP]
>
> Para uso normal pelo WhatsApp, prefira consultas objetivas e resultados resumidos. Respostas muito grandes são difíceis de ler no celular.

## Boas práticas

| Prática | Motivo |
| - | - |
| Use um usuário só leitura | É obrigatório e protege os dados do cliente |
| Proteja o arquivo de configuração | Ele contém credenciais sensíveis |
| Evite compartilhar o token | O token identifica a empresa |
| Valide o acesso ao banco antes da instalação | Facilita a implantação |
| Reinicie o serviço depois de editar o arquivo | O integrador só lê o arquivo ao iniciar |
| Confira o status no portal após salvar | Confirma que o integrador conectou |

> [!WARNING]
>
> Não armazene o `config.yaml` em repositórios, pastas públicas ou locais acessíveis por usuários sem autorização.


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