Como funciona

O Zoppy Connect é um produto separado da Zoppy: tem a própria API, o próprio banco e a própria infraestrutura. Ele fala com a Zoppy só pela API de Parceiros (partners.zoppy.com.br), como faria com qualquer outro sistema, e nunca acessa o banco, as filas ou o cache da Zoppy.

 Loja (tela do Connect)          Nuvem do Connect                         Outros sistemas
 ┌──────────────────┐     ┌────────────────────────────────┐
 │ Copiloto e       │────►│ API ─── IA de construção       │
 │ conversa de      │     │  │                             │
 │ construção       │     │  ▼                             │      ┌──────────────────────┐
 └──────────────────┘     │ Worker ── fatias ──► Runner    │      │ partners.zoppy.com.br│
                          │                   (sem rede)   │      ├──────────────────────┤
                          │                       │        │      │ ERP / plataforma     │
                          │                       ▼        │ ───► │ na nuvem (https)     │
                          │                    Gateway ────┼──────┤                      │
                          │                       ▲        │      └──────────────────────┘
                          └───────────────────────┼────────┘
                                 túnel de saída (443)
                          ┌───────────────────────┴────────┐
                          │ Agente local (rede da loja)    │──► banco do ERP (só leitura)
                          └────────────────────────────────┘──► API interna (GET/HEAD)

O conector

Um conector é um arquivo TypeScript (export default async function run(ctx)) e um manifesto JSON. A IA de construção escreve os dois; não existe editor manual. Cada mudança vira uma versão nova, com diff e restauração. A versão é compilada num arquivo só, e a compilação recusa qualquer import que não seja do próprio Node ou de tipos.

O manifesto declara o horário (triggers), os domínios que o código chama (hosts), os métodos e caminhos liberados em cada um (routes), os agentes locais e o que cada um alcança (agents), os nomes dos segredos (secrets) e se o conector escreve em outro sistema (externalWrites). Detalhes em Manifesto.

Execução isolada

O código roda num processo novo, numa função isolada sem acesso à rede, sem as variáveis de ambiente da plataforma e com teto de memória e de tempo. Uma execução é dividida em fatias de até 10 minutos: quando a fatia está perto do fim, o código guarda o cursor (ctx.state) e pede a próxima. Uma fatia que estoura o tempo é encerrada à força. Os números estão em Limites.

O gateway

Toda chamada do código sai pelo gateway, autenticada por um token assinado para aquela execução e fatia. O gateway:

• só deixa passar os hosts do manifesto, por https, e, quando o host tem routes, só os métodos e caminhos delas;
• bloqueia endereços internos, link-local e de metadados depois de resolver o DNS, para que um domínio não aponte para dentro da rede;
• troca as referências ctx.secret('NOME') pelo valor do segredo na saída, de forma que o código nunca vê o valor;
• separa leitura (ctx.http.request) de escrita (ctx.http.write): no ensaio as escritas são só registradas, e em produção a primeira escrita em cada host espera uma pessoa confirmar;
• injeta o acesso da loja à Zoppy só em chamadas para partners.zoppy.com.br, recusa DELETE nele e troca esse host lógico pelo endereço da API de Parceiros do ambiente;
• registra cada chamada como um passo da execução, com dados pessoais mascarados.

Segredos

Os segredos (tokens, senhas, usuário e senha do banco local) são preenchidos pela pessoa num formulário fora do chat, guardados cifrados (AES-256-GCM) e são só de escrita: a API nunca devolve o valor. Um segredo colado por engano no chat é mascarado antes de chegar ao modelo e vira um pedido de acesso. O acesso à Zoppy (ZOPPY_TOKEN) é da loja, gerado pelo Connect na primeira construção, e não pode ser declarado nem lido por um conector.

Agente local

Para um sistema dentro da rede da loja, o time da Zoppy instala o agente local numa máquina sempre ligada. O agente abre uma conexão de saída (WebSocket na porta 443) até o gateway; a loja não abre porta nem precisa de VPN. Antes de qualquer acesso, o agente confere a lista local, que fica só naquela máquina e que a nuvem não consegue mudar. No banco, só SELECT, por um usuário só leitura e dentro de transação só leitura ou sempre desfeita; nas APIs internas, só GET e HEAD. Usuário e senha do banco ficam cifrados na nuvem e descem pelo túnel a cada consulta, sem nunca ir para o disco da máquina nem para logs. Veja Agente local: instalação.

Separação entre lojas

Toda consulta é filtrada pela loja de quem está logado: uma loja não enxerga conectores, versões, execuções, segredos, agentes nem quarentena de outra. O código de um conector nunca é compartilhado entre lojas. O que o Connect aprende sobre um sistema (notas curtas, sem código, link, segredo nem dado pessoal) só passa a ajudar outras lojas depois de um ensaio limpo do conector que o registrou.

Quem acessa

O Connect abre com o mesmo login da Zoppy. Só usuários MASTER ou ADMIN de lojas com o Connect liberado pelo time da Zoppy e com plano pago entram; tokens de propósito restrito (integrações externas, MCP) são recusados. Desligar a liberação barra a entrada, mas não pausa os conectores já ligados. O time da plataforma tem uma pausa de emergência por conector, por loja ou para o Connect inteiro.