Versão: 1.0 — 27/04/2026
O Dashboard Kinyx é uma plataforma que centraliza dados operacionais de ERPs em painéis customizáveis. Ele é composto por três peças que conversam entre si:
| Peça | O que é | Onde roda |
|---|---|---|
| Dashboard Web | Painel visual em navegador (login, contas, empresas, usuários, dashboards, vendas, etc.) | Em servidor da Kinyx (na nuvem) |
| Kinyx Sync | Programa que roda na máquina do cliente, conecta ao banco do ERP dele e envia dados para o Dashboard | Servidor/computador do cliente |
| App Mobile | Aplicativo Android/iOS para o cliente final consultar dashboards (somente leitura) | Celular do cliente final |
O Revendedor é o intermediário comercial e técnico: ele configura o sistema para múltiplos clientes finais (contas), faz o cadastro inicial dessas contas no Dashboard, instala o sincronizador no servidor de cada cliente e dá suporte de primeiro nível.
1. Login no Dashboard como Revendedor
2. Criar Cliente (Conta)
3. Entrar no Cliente recém-criado
4. Cadastrar a(s) Empresa(s) do cliente (com CNPJ, endereço, etc.)
5. Criar Usuários para o cliente
6. Gerar API Key da Empresa (vinculada ao perfil de sincronização)
7. Instalar o Kinyx Sync no servidor do cliente
8. Abrir a interface local do sincronizador (http://localhost:8282)
9. Cadastrar o Servidor de banco (MySQL/PostgreSQL/SQL Server)
10. Cadastrar a Conexão (apontando para o servidor + API Key)
11. Instalar as Triggers no banco do ERP
12. Validar a sincronização (logs + dados no Dashboard)
Partner (você, o revendedor)
└── Conta / Cliente (ex.: "Loja do Zé Ltda")
├── Empresa (ex.: "Matriz" — com CNPJ, IE, endereço)
│ └── API Key (chave secreta que o sincronizador usa)
├── Empresa (ex.: "Filial 01" — outro CNPJ)
└── Usuários (admins, gerentes, etc. do cliente)
Observação importante: "Conta" e "Cliente" são a mesma coisa neste documento. Já "Empresa" é cada CNPJ dentro do cliente. Um cliente pode ter várias empresas; cada empresa tem suas próprias API Keys.
O endereço do Dashboard Web depende do ambiente:
| Ambiente | URL típica |
|---|---|
| Produção Kinyx (nuvem) | https://dashboard.kinyx.cloud |
Após o login bem-sucedido, você será redirecionado para dashboard.
Existem três níveis (papéis) dentro de um Partner (revendedor):
| Papel | Pode fazer | Não pode fazer |
|---|---|---|
| Admin (do Partner) | Tudo dentro do partner: criar/editar/excluir clientes, gerenciar usuários do partner, gerenciar tudo dentro de cada cliente | # |
| Manager (do Partner) | Criar e editar clientes e empresas; criar usuários | Excluir clientes; gerenciar usuários do próprio partner |
| Viewer (do Partner) | Ver tudo no escopo do partner | Criar, editar ou excluir qualquer coisa |
Na barra lateral, em Revenda → Meus clientes.
Loja do Zé Ltda.loja-do-ze-ltda). Você só precisa informar manualmente se quiser algo personalizado.Atenção: O slug não pode ser alterado depois que o cliente foi criado. Pense bem antes de salvar. Para mudar, seria necessário excluir e recriar.
Para gerenciar empresas, usuários e API Keys de um cliente, você precisa entrar na conta:
/dashboard).| Conceito | O que é | Onde fica |
|---|---|---|
| Conta (Cliente) | Inquilino — separa logicamente os dados de um cliente do outro | No banco do Dashboard |
| Empresa | CNPJ específico dentro de uma conta. Uma conta pode ter várias empresas | No banco do Dashboard |
| Usuário | Pessoa que faz login. Pode ter acesso a uma ou mais contas/empresas com papel definido | No banco do Dashboard |
| Servidor | (No contexto do sincronizador) representa um banco de dados MySQL/PostgreSQL/SQL Server do cliente | No banco SQLite local do sincronizador (data/connections.db) |
| Conexão | (No contexto do sincronizador) liga um Servidor + uma API Key + um Perfil de sync | No banco SQLite local do sincronizador |
Atenção: "Servidor" no contexto do sincronizador é o banco de dados do ERP do cliente — não confunda com servidor web ou servidor de aplicação. Não há cadastro de "servidor" no Dashboard Web.
Após entrar em um cliente (passo 3.4), a tela de empresas fica em Gestão → Empresas (URL /companies).
| Campo | Obrigatório? | Observações |
|---|---|---|
| Razão social | Sim | Nome jurídico oficial. Ex.: Comércio Ze Ltda |
| CNPJ | Recomendado | 14 dígitos. Há busca automática ao completar — o sistema preenche razão social, endereço e telefone automaticamente |
| Nome fantasia | Não | Nome comercial. Ex.: Loja do Zé |
| Inscrição Estadual | Não | Aceita "ISENTO" |
| Inscrição Municipal | Não |
Ativo é o default. Você pode desativar uma empresa (em vez de excluir) para preservar histórico.A empresa é automaticamente vinculada à conta em que você está. Se você precisar mover uma empresa entre clientes, não há essa funcionalidade — seria preciso excluir e recriar.
Existem dois tipos de usuários que você como Revendedor pode criar:
| Tipo | Onde cadastra | Para quê |
|---|---|---|
| Usuário do Revendedor | em "Revenda → Usuários revenda" | Pessoa da sua equipe que precisa acesso a múltiplos clientes |
| Usuário do Cliente | após entrar no cliente, em "Gestão → Usuários" | Pessoa do cliente final (dono, gerente, vendedor) |
Pré-requisito: apenas Revendedor-Admin pode acessar essa tela.
admin, manager ou viewer (ver tabela em 2.4).O usuário criado terá acesso transitivo a todas as contas vinculadas a Revenda.
admin — gerencia tudo dentro da conta.manager — cria e edita, mas não exclui.viewer — somente leitura.Ativo/Inativo): impede login sem perder histórico — preferível à exclusão.admin para quem só precisa visualizar./profile permite revogar sessões ativas.A API Key é a credencial que autentica o sincronizador (Kinyx Sync) junto ao Dashboard. Sem API Key válida, o sincronizador não consegue enviar dados.
Produção, Servidor Matriz, Backup.databaseName)*** — o nome do banco de dados do ERP no servidor do cliente. Ex.: gestor_loja_ze.gestor-erp-v3). Esse perfil define quais tabelas e como mapear os dados.dk_ seguido de 64 caracteres hexadecimais. Exemplo:dk_7f3a9c2e8b1d4f6a0e5c9b3d7f2a8e1c4b6d0f3a9c2e8b1d4f6a0e5c9b3d7f2a
CRÍTICO: Copie a chave agora e guarde em local seguro.
Após fechar o diálogo, você não consegue mais visualizar essa chave. Se perder, terá que revogar e gerar uma nova.
| Cenário | Ação |
|---|---|
| Perdeu a chave (não copiou na criação) | Revogue a chave atual e crie uma nova |
| Suspeita de vazamento | Revogue imediatamente — workers conectados são desconectados (código WebSocket 4401) |
| Quer trocar por rotina (rotação periódica) | Crie a nova primeiro, configure no sincronizador, depois revogue a antiga |
No gerenciador você vê três estados:
O Kinyx Sync é um programa que roda na máquina do cliente (geralmente no servidor onde está o ERP). Ele:
data/connections.db) para saber o que já foi enviado.É um executável único (kinyx-sync.exe, ~15 MB) sem dependências externas.
| Item | Mínimo recomendado |
|---|---|
| Sistema operacional | Windows 10 ou superior (Server 2016+ para produção) |
| RAM | 2 GB livre (sincronizador usa ~30-150 MB) |
| Espaço em disco | 50 MB para binário + dados locais |
| Rede | Acesso de saída HTTPS (porta 443) ao endereço do Dashboard |
| Permissões no banco do ERP | SELECT em todas as tabelas; ALTER TABLE, CREATE TRIGGER e CREATE INDEX se for usar modo optimized |
| Permissões no Windows | Administrador local (para registrar o serviço) |
A forma recomendada é usar o instalador Windows distribuído pela Kinyx:
kdashboard-sync-setup-X.Y.Z.exe (https://arquivos.kinyx.com.br/?path=kDashboard).C:\Kinyx\Sync\kDashboard\.KinyxSync com inicialização automática.data\.data\ no uninstall (responda NÃO se quiser preservar configuração).Após a instalação, a interface web fica em:
http://localhost:8282
Como o sincronizador está rodando como serviço Windows (modo
service), basta abrir esse endereço no navegador da própria máquina onde ele está instalado.
A interface tem 5 telas principais, acessíveis pelo menu:
| Tela | Rota | Para quê serve |
|---|---|---|
| Dashboard | / |
Status geral: última e próxima sincronização, botão Iniciar/Parar, progresso |
| Servidores | /servers |
Cadastrar bancos de dados do cliente (MySQL) |
| Conexões | /connections |
Cadastrar conexões de sincronização (servidor + API Key + perfil) e instalar triggers |
| Logs | /logs |
Ver logs em tempo real, filtrar por nível (INFO/WARNING/ERROR), download |
| Configurações | /configuration |
URL da API do Dashboard, intervalo de sincronização, paralelismo, full re-sync periódico |
sc query KinyxSync
Saída esperada inclui STATE : 4 RUNNING.
Abra http://localhost:8282. Se carregar a tela Dashboard, o serviço está no ar.
services.msc → procure "KinyxSync" → status deve ser "Em execução".
Lembrete: "Servidor" aqui significa banco de dados do ERP do cliente (MySQL, PostgreSQL ou SQL Server). Não confunda com servidor web.
Crie um servidor uma vez por banco de dados que você for sincronizar. Geralmente: um servidor por máquina onde o ERP roda. Se uma mesma máquina tiver várias bases, basta um servidor (você seleciona a base na Conexão, próxima seção).
/servers).| Campo | Descrição | Exemplo |
|---|---|---|
| Nome* | Nome amigável | Servidor Matriz |
| Tipo* | mysql | postgres | mssql |
mysql |
| Host* | IP ou hostname do banco | localhost ou 192.168.1.10 |
| Porta* | Porta de conexão | MySQL=3306, PostgreSQL=5432, SQL Server=1433 |
| Usuário* | Usuário do banco | kinyx_sync |
| Senha* | Senha do banco | (criptografada antes de salvar) |
| SSL | Ativar TLS | Desligado em LAN; ligado se internet |
A Conexão liga 3 elementos: um Servidor + um banco específico desse servidor + a API Key do Dashboard + um Perfil de sync.
/connections).| Campo | Descrição | Exemplo |
|---|---|---|
| Nome* | Nome amigável | Loja Matriz - Produção |
| Servidor* | Selecione um servidor cadastrado | Servidor Matriz |
| API Key* | A chave gerada no Dashboard (passo 6.2) | dk_7f3a... |
| Modo de sincronização | Como capturar mudanças. Default: trigger |
trigger |
| Habilitada | Participa do agendamento automático | Marcado |
Lembrete: Não precisará preencher o nome do banco, ele buscará automaticamente através da API Key configurada na empresa.
Após criar a conexão, é necessários instalar as triggers para que a sincronização comece.
A vinculação acontece via API Key:
| Erro | Causa provável | O que fazer |
|---|---|---|
Access denied for user... |
Usuário ou senha errados | Confira no servidor, teste com cliente SQL externo |
Unknown database 'X' |
Nome do banco errado ou não existe | Verifique com SHOW DATABASES; ou equivalente |
Can't connect to MySQL server on 'host' |
Host inacessível ou firewall | Pingue o host, verifique porta aberta |
SSL connection error |
SSL forçado sem cert válido | Desligue SSL ou configure cert |
Sincronização já em andamento (409) |
Tentou disparar sync com outro em curso | Aguarde ou clique em Parar |
trim, mas confirme).O sincronizador roda ciclos periódicos (default: 30 minutos). Em cada ciclo:
trigger, faz SELECT ... WHERE sync_timestamp > <último-watermark>.pessoas, orcamento, orcamento_item, pagamentos, monta lotes de até 10000 registros.Na tela Dashboard do sincronizador:
Tela Logs (/logs) da PWA:
Procure por padrões como:
[Engine] SyncAll started with profile: ... — ciclo iniciou.[Sync] Sent batch: table=customers count=500 — lote enviado.[Sync] ERROR: ... — algo falhou.| Sintoma | Onde olhar |
|---|---|
| Sync não inicia | Logs da PWA + status do serviço Windows |
| Volume muito grande, ciclo demora muito | Aumente intervalo (10.4) |
Triggers são pequenas regras automáticas no banco de dados que disparam quando algo acontece (insert, update, delete em uma tabela). O sincronizador as usa para registrar quando cada linha foi modificada, sem precisar reler a tabela inteira.
Sem triggers, o sincronizador teria que reler todos os registros a cada ciclo — caro e lento em bases grandes. Com triggers + a coluna sync_timestamp, ele lê apenas as linhas alteradas desde o último ciclo. Em uma base de 200 mil linhas, a diferença é de minutos para segundos.
Quando você dispara a instalação, o sincronizador, para cada tabela do perfil:
[A-Za-z_][A-Za-z0-9_]{0,63}) — rejeita nomes com hífen, espaço ou acento.sync_timestamp (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP), se não existir.idx_<tabela>_sync_timestamp para acelerar a consulta de delta.trigger_log para deletes):
trg_<tabela>_sync_insert — atualiza sync_timestamp ao inserir.trg_<tabela>_sync_update — atualiza ao alterar.trg_<tabela>_sync_delete — registra deletes em _kinyx_deletion_log (se ativado).sync_timestamp = CURRENT_TIMESTAMP (para serem capturados no primeiro ciclo)./connections).Após a instalação, na lista de conexões aparece um indicador Triggers OK. Você também pode clicar em "Status de triggers" para ver detalhes.
MySQL
As triggers aparecerão junto as tabelas do banco.
A instalação é idempotente — usa IF NOT EXISTS em todos os comandos. Você pode rodar quantas vezes quiser sem causar dano. Se precisar forçar recriação, primeiro desinstale (botão "Desinstalar Triggers") e instale de novo.
CRÍTICO — leia antes de instalar em produção:
Use este checklist no final da implantação para confirmar que tudo está funcionando:
vars)gestor-erp-v3 ou similar)C:\Kinyx\Sync\kDashboard\ existeKinyxSync rodando — sc query KinyxSync mostra RUNNINGhttp://localhost:8282 carregasync_timestamp existe nas tabelas do perfil (validar via SQL direto)config.yaml na mão quando possível — use a PWA, que valida e criptografa corretamente.data/ sem entender o que cada um faz — você perde o estado de sync.| Termo | Definição |
|---|---|
| Partner / Revendedor | Empresa intermediária que revende o Dashboard para múltiplos clientes finais e faz o cadastro / suporte |
Conta / Cliente (Account) |
Inquilino lógico no Dashboard. Separa dados de um cliente do outro |
Empresa (Company) |
CNPJ específico dentro de uma Conta. Uma Conta pode ter várias Empresas |
Usuário (User) |
Pessoa física com login. Tem papéis (role) associados a Contas, Empresas ou Partners |
| API Key | Credencial secreta no formato dk_<64-hex> que autentica o sincronizador no Dashboard. Cada chave pertence a uma Empresa |
| Sincronizador / Kinyx Sync | Programa Go que roda na máquina do cliente, conecta ao ERP e envia dados para o Dashboard |
| PWA (Progressive Web App) | Interface web do sincronizador, embutida no próprio binário, acessível em http://localhost:8282 |
| Servidor (no contexto do sincronizador) | Cadastro de um banco de dados MySQL/PostgreSQL/SQL Server onde está o ERP do cliente |
| Conexão (no contexto do sincronizador) | Configuração que liga um Servidor + um banco específico + uma API Key + um Perfil de sync |
| Trigger | Regra automática no banco que dispara em INSERT/UPDATE/DELETE. Usada para registrar mudanças (sync_timestamp) |
| Banco de dados | Sistema onde os dados do ERP estão armazenados (MySQL, PostgreSQL ou SQL Server) |
| Dashboard | Painel visual do sistema. Pode significar a aplicação inteira ou a tela /dashboard específica |
| Log | Registro de eventos. Usado para auditoria e diagnóstico de problemas |
Perfil de sincronização (SyncProfile) |
Receita que define quais tabelas do ERP mapeiam para quais tabelas do Dashboard. Ex.: gestor-erp-v3 |
| CDC (Change Data Capture) | Técnica para capturar mudanças no banco lendo o log de transações |
| Watermark | Marca de tempo do último registro sincronizado. Permite sync incremental |
| Idempotente | Operação que pode ser repetida sem causar efeito adicional. Ex.: instalação de triggers |
| DDL (Data Definition Language) | Comandos SQL que alteram estrutura do banco: CREATE TABLE, ALTER TABLE, DROP TRIGGER |
Quota de contas (accountLimit) |
Número máximo de Contas que o Partner pode cadastrar. Pode ser ilimitado ou um número fixo |
| Lockout | Bloqueio temporário do login após várias tentativas falhadas (5 falhas → 15 minutos bloqueado) |
Versão deste documento: 1.0 — 27/04/2026