Manifesto

O manifesto diz o que o conector pode fazer. Ele é conferido antes de uma versão ser guardada: o gatilho do cron, os hosts e as rotas que o código chama, os agentes locais que ele alcança, os nomes dos segredos e se ele escreve em outro sistema. Nome repetido numa lista é recusado.

Gerada do schema que a API publica em GET /connect/manifest.schema.json (Zoppy-crm/zoppy-connect@f1ae3a72be71). A IA de construção escreve o manifesto junto com o código; ninguém o edita à mão.

Exemplo: um sistema na nuvem e a Zoppy

{
  "version": 1,
  "triggers": [
    {
      "type": "cron",
      "everyMinutes": 30
    }
  ],
  "hosts": ["api.exemplo.com.br", "partners.zoppy.com.br"],
  "routes": [
    {
      "host": "partners.zoppy.com.br",
      "methods": ["GET"],
      "path": "/customers"
    },
    {
      "host": "partners.zoppy.com.br",
      "methods": ["POST", "PUT"],
      "path": "/customers/**"
    }
  ],
  "agents": [],
  "secrets": [
    {
      "name": "EXEMPLO_TOKEN",
      "label": "Token da API do sistema",
      "help": "No sistema, em Configurações > Integrações > Token."
    }
  ],
  "externalWrites": true
}

Exemplo: banco do ERP pelo agente local

{
  "version": 1,
  "triggers": [
    {
      "type": "cron",
      "everyMinutes": 60
    }
  ],
  "hosts": ["partners.zoppy.com.br"],
  "routes": [
    {
      "host": "partners.zoppy.com.br",
      "methods": ["GET", "POST"],
      "path": "/customers/**"
    }
  ],
  "agents": [
    {
      "agentId": "6f1c2b0e-3a4d-4c1b-9e2f-0a1b2c3d4e5f",
      "http": [],
      "databases": [
        {
          "name": "erp",
          "engine": "sqlserver",
          "host": "srvsql01",
          "port": 1433,
          "database": "ERP",
          "username": "ERP_DB_USER",
          "password": "ERP_DB_PASSWORD"
        }
      ]
    }
  ],
  "secrets": [
    {
      "name": "ERP_DB_USER",
      "label": "Usuário só leitura do banco do ERP"
    },
    {
      "name": "ERP_DB_PASSWORD",
      "label": "Senha desse usuário"
    }
  ],
  "externalWrites": true
}

Campos

Campo	Tipo	Obrigatório	Regras	Descrição
version	number	sim	de 1 a 1	Formato do manifesto: sempre 1.
triggers	object[]	sim	mínimo 1 item(ns); máximo 1 item(ns)	O que inicia uma execução: um cron, na V1.
triggers[].type	string	sim	um de cron	Sempre cron: roda a cada everyMinutes minutos.
triggers[].everyMinutes	integer	sim	de 5 a 1440	Intervalo entre execuções, em minutos.
hosts	string[]	sim	máximo 20 item(ns)	Domínios que o código chama com ctx.http e ctx.soap, sempre por https. Um host novo espera uma pessoa da loja aprovar antes do ensaio.
hosts[]	string	sim	—	Um domínio, sem esquema, porta nem caminho. IP e domínio de rede interna (.local, .internal, .lan…) são recusados.
routes	object[]	não	máximo 100 item(ns); padrão []	Método e caminho liberados por host. Um host com rotas só aceita as rotas dele; partners.zoppy.com.br sempre precisa de rotas.
routes[].host	string	sim	—	Um dos hosts do manifesto.
routes[].methods	string[]	sim	mínimo 1 item(ns); máximo 6 item(ns)	Métodos HTTP liberados nesse caminho. DELETE nunca é aceito em partners.zoppy.com.br.
routes[].path	string	sim	—	Padrão de caminho, sem query string, começando com /: segmentos literais, * vale um segmento e ** no fim vale o resto (ex.: /api/v1/customers/*).
readRoutes	object[]	não	máximo 50 item(ns); padrão []	POST, PUT ou PATCH que só consultam (APIs que buscam por POST, operações SOAP de leitura). Fora destas rotas, todo POST, PUT ou PATCH é tratado como escrita. Aprovadas junto com o host; nunca em partners.zoppy.com.br.
readRoutes[].host	string	sim	—	Um dos hosts do manifesto, nunca partners.zoppy.com.br.
readRoutes[].methods	string[]	sim	mínimo 1 item(ns); máximo 3 item(ns)	Métodos que, nesse caminho, são leitura: POST, PUT ou PATCH.
readRoutes[].path	string	sim	—	Padrão de caminho, com a mesma sintaxe de routes[].path.
agents	object[]	não	máximo 3 item(ns); padrão []	Agentes locais dentro da rede da loja e o que o conector alcança por cada um: APIs internas e bancos de dados.
agents[].agentId	string	sim	UUID	Id do agente local (aparece na tela de agentes). O gateway manda essas chamadas pelo túnel dele.
agents[].http	object[]	não	máximo 20 item(ns); padrão []	APIs dentro da rede da loja, chamadas com ctx.http.
agents[].http[]	object	sim	—	Uma API interna. Pelo agente, só GET e HEAD.
agents[].http[].host	string	sim	—	Host na rede da loja, como a máquina do agente o resolve: um nome, um domínio ou um IPv4, sem esquema, porta nem caminho. Um host do agente nunca é chamado pela internet.
agents[].http[].port	integer	sim	de 1 a 65535	Porta da API (8080, 443…).
agents[].http[].tls	boolean	sim	—	true quando a API é https; false quando é http simples dentro da rede.
agents[].databases	object[]	não	máximo 10 item(ns); padrão []	Bancos lidos com ctx.db.query, só leitura.
agents[].databases[]	object	sim	—	Um banco que o agente lê com um usuário só leitura.
agents[].databases[].name	string	sim	formato ^[a-z][a-z0-9_]{0,31}$	Como o código chama este banco em ctx.db.query({ database }): nome curto em minúsculas, como erp.
agents[].databases[].engine	string	sim	um de sqlserver, oracle, firebird, mysql, postgres	O motor do banco.
agents[].databases[].host	string	sim	—	Host do banco na rede da loja.
agents[].databases[].port	integer	sim	de 1 a 65535	Porta do banco (1433 SQL Server, 1521 Oracle, 3050 Firebird, 3306 MySQL, 5432 Postgres).
agents[].databases[].database	string	sim	—	O banco como o servidor o conhece: nome do banco, service name do Oracle, caminho ou alias do Firebird.
agents[].databases[].username	string	sim	formato ^[A-Z][A-Z0-9_]{0,63}$	Nome do segredo do conector com o usuário só leitura do banco. Precisa estar em secrets.
agents[].databases[].password	string	sim	formato ^[A-Z][A-Z0-9_]{0,63}$	Nome do segredo do conector com a senha desse usuário. Precisa estar em secrets.
secrets	object[]	sim	máximo 20 item(ns)	Segredos que o código usa com ctx.secret(nome). Uma pessoa preenche o valor na tela; ele nunca fica no código nem passa pelo chat.
secrets[].name	string	sim	formato ^[A-Z][A-Z0-9_]{0,63}$	Nome que o código usa, em MAIÚSCULAS_COM_SUBLINHADO. ZOPPY_TOKEN é reservado: o acesso à Zoppy é da loja e o gateway o injeta sozinho.
secrets[].label	string	sim	—	O que a pessoa preenche, em português.
secrets[].help	string	não	—	Onde a pessoa encontra o valor no outro sistema.
externalWrites	boolean	sim	—	Se o conector escreve em outro sistema (inclusive na Zoppy). Sem isso, ctx.http.write e client.write são recusados.

Regras entre campos

• Todo routes[].host precisa estar em hosts.
• partners.zoppy.com.br em hosts exige as rotas que o conector usa em routes, e DELETE nunca é aceito nele.
• Hosts, nomes de segredo, rotas (host + caminho), agentes, alvos dos agentes e nomes de banco não se repetem.
• username e password de um banco do agente são nomes declarados em secrets.
• Um host não pode estar ao mesmo tempo em hosts (internet) e em agents[].http (rede da loja).