Editores personalizados

Existe trabalho que não está em nenhum painel, porque é só seu: um recálculo próprio de preços pela fórmula do fornecedor, a conferência do catálogo com um sistema de contabilidade externo, uma tela "preencher as características do lote de uma só vez". A seção "Editores personalizados" permite escrever esse mini-editor você mesmo (ou encomendá-lo) e executá-lo dentro do painel administrativo — em uma sandbox, com acesso exatamente aos dados que você autorizou.

Abrir: Painel administrativo → Editores personalizados (admin.cenaly.com/custom-editors). A seção é ativada pelo cartão "Editores personalizados (SDK)" na loja de aplicativos — por padrão, ela fica oculta. O botão "📌 Na barra lateral" na própria página o coloca no menu lateral, quando ele é usado com frequência.

O que é esta seção#

Um plugin é um script compilado (index.js) e sua descrição (manifest.json). O painel carrega o script em um frame isolado: ele não tem acesso à sua sessão, nem ao código do painel administrativo, nem à rede. Ele só pode conversar com os dados através da ponte — um conjunto de requisições permitidas, cada uma delas verificada conforme as permissões concedidas.

A página é composta por blocos:

O editor aberto ocupa a tela inteira, e o endereço da página recebe a marcação ?app=<identificador> — esse link pode ser compartilhado com quem tem acesso.

O que é necessário para começar#

Etapa 1. Decidir quem vai escrever o editor#

Há três caminhos, e eles diferem em quem mantém o código:

Nos três casos, a instalação continua sendo do proprietário: até mesmo um desenvolvedor com permissão só pode executar o próprio código no modo de desenvolvedor, mas não instalá-lo na conta.

Etapa 2. Desenvolvimento com IA (vibe coding)#

O bloco "🤖 Desenvolvimento com IA (vibe coding)" oferece quatro coisas para entregar a tarefa a um agente de IA (Claude Code, Cursor e similares) sem explicar o contrato a ele do zero:

1. "⬇️ Baixar modelo de projeto (zip)" — uma estrutura pronta de plugin: manifesto, ponto de entrada, descrição do contrato (GUIDE.en.md) e instruções para o agente. O arquivo é montado direto no navegador, não é preciso baixar nada externo.
2. "📋 Copiar prompt para o agente" — o texto da tarefa em inglês: começar pelo modelo, conferir com o guia, como verificar o resultado.
3. Configuração do conjunto de ferramentas para o agente — com ele, o agente monta o plugin, sobe um stand local — cópia da sandbox, faz capturas de tela e snapshots de estado e, no final, monta o release: zip para instalação manual ou release no GitHub.
4. "⬇️ Baixar snapshot do catálogo (fixture de teste)" — suas categorias e itens em um arquivo, para que o agente teste com dados reais, e não inventados.

⚠️ Do snapshot são removidos por completo os campos personalizados de outros plugins: os dados que uma extensão de terceiros armazena nos seus cartões não saem da conta junto com a fixture.

Etapa 3. Instalar o editor#

A partir de arquivos. Bloco "Instalar editor": selecione "Bundle (index.js)" e "Manifesto (manifest.json)" → "Verificar e instalar". O painel primeiro verifica o manifesto — identificador, nome localizado, versão, versão mínima do SDK, posicionamentos, permissões e a lista de hosts de rede — e depois mostra o consentimento: "Este editor solicita:" e a lista de permissões em linguagem humana. Enquanto você não clicar em "Instalar", nada é instalado.

Do GitHub. Bloco "Instalação do GitHub": campo "Repositório (URL ou owner/repo)", campo "Tag (vazio = último release)" e o botão "Verificar repositório". A convenção é simples: manifest.json na raiz do repositório, o dist/index.js compilado na tag, tag no formato v{versão}. O manifesto e o bundle são baixados direto do seu navegador. Nos dois casos, na instalação é calculada e memorizada a impressão digital do bundle (sha256): se o arquivo for substituído depois, a execução será bloqueada, e o painel pedirá para reinstalar o editor.

Direitos e locais de exibição#

Os direitos (também chamados de escopos) o plugin solicita no manifesto, e você os confirma na instalação. A lista completa é esta, a Ponte não consegue fazer nada além disso:

O que não está na lista de forma alguma, o plugin não receberá com nenhuma configuração: hóspedes e clientes, pedidos, recibos, finanças, funcionários, conversas e ligações a Ponte não fornece.

Os locais de exibição (slots) são três:

Modo de desenvolvedor e acesso para o contratado#

O modo de desenvolvedor (bloco «🛠️ Modo de desenvolvedor») monta o plugin ao vivo a partir do seu computador: o campo «URL do bundle» aceita apenas endereços localhost / 127.0.0.1, ao lado há o «JSON do manifesto» e o botão «Iniciar sessão de dev». Nesse caso, a impressão digital não é fixada, e a sessão dura até a aba ser fechada; «Parar sessão de dev» a desliga imediatamente.

Os grants para o desenvolvedor (bloco «👩‍💻 Acesso do desenvolvedor») são necessários quando quem escreve não é o proprietário. Para o desenvolvedor é criada uma conta de funcionário comum, e então o proprietário concede o grant: «Email do desenvolvedor (seu login de staff)», «Direitos permitidos», «Prazo de validade (dias)» e uma observação opcional → «Conceder acesso». É possível revogar a qualquer momento com o botão «Revogar».

O que o grant concede e o que não concede:

• concede — apenas o modo de desenvolvedor com os direitos que você marcou (por padrão, prazo de 14 dias, máximo de 90);
• os direitos são limitados pela interseção: o que o manifesto solicita e o que foi concedido pelo grant; o plugin não receberá nada além disso, mesmo que solicite no manifesto;
• não concede — instalação, ativação e remoção de plugins: isso permanece com o proprietário.

Atualização, ativação e remoção#

Não há atualização automática de propósito: uma nova versão de código de terceiros é uma nova impressão digital e, possivelmente, novos direitos, por isso a atualização é sempre uma ação consciente do proprietário.

Extensões integradas#

Parte dos nossos próprios módulos está empacotada no mesmo formato — isso é visível pelo comportamento, mas não é preciso instalá-los: eles vêm junto com o painel e são ativados por um card na loja de aplicativos, e não nesta seção.

Atualmente, esse módulo é um só — «Меркурий/ВетИС» para a Rússia: ele fica em uma aba da seção «Estoque», é executado na mesma sandbox e com as mesmas verificações de impressão digital. As extensões integradas não entram na lista de editores instalados.

O que o editor pode e o que não pode#

Plugins de terceiros são marcados no card com um aviso: «Aplicativo de terceiros em sandbox — ele nunca pede senha». Se um plugin pedir o login do painel, dados de pagamento ou código de SMS — isso é fraude, e não o funcionamento da extensão.

Limitações#

• A seção vem desativada por padrão e é destinada a quem escreve código (ou contrata alguém para escrevê-lo): o proprietário comum não tem o que fazer aqui.
• Tudo, exceto a visualização, é exclusivo do proprietário da conta. O funcionário vê o hub em modo somente leitura; o modo desenvolvedor só funciona com uma concessão ativa.
• Repositórios privados do GitHub não são suportados — o repositório precisa ser público e a instalação é feita por tag.
• Não há atualização automática: a atualização do plugin é sempre iniciada pelo proprietário.
• Não há loja de plugins de terceiros. Extensões prontas não são publicadas nem vendidas pelo painel — a fonte é apenas o seu arquivo ou o seu repositório.
• São três slots (página própria, botão do catálogo, aba do estoque) — o plugin não pode se encaixar em uma tela qualquer do painel.
• A ponte não entrega hóspedes, pedidos, finanças, funcionários nem conversas — não dá para contornar isso com permissões, pois essas consultas simplesmente não existem.
• Não há um log separado do tipo “o plugin fez tal coisa”. As permissões aparecem no cartão, e as alterações no catálogo entram no histórico comum de itens; se você precisa de controle, comece com um plugin que tenha apenas permissão de leitura.
• Tetos técnicos: bundle de até 4 MB, até 8 endereços de rede no manifesto, até 1 MB por chave de armazenamento; execução no servidor — até 30 segundos e até 50 acessos à internet por vez.
• Os dados do plugin permanecem na nuvem da sua marca: em uma conta no cenaly.ru, o estado da parte de servidor fica no contorno russo.

Solução de problemas#

Perguntas frequentes#

É preciso saber programar?#

Para instalar uma versão pronta — não. Para obter a própria versão — sim: ela é escrita por um desenvolvedor ou por um agente de IA seguindo o nosso modelo do bloco “Desenvolvimento com IA”. A seção é uma ferramenta para código, não um construtor “com o mouse”.

Um plugin de terceiros pode ver meus clientes ou meu faturamento?#

Não. O plugin roda em uma sandbox e recebe dados apenas pela ponte, e a ponte faz exatamente seis coisas: catálogo, preços e stop-lists, cadastro do estoque, seu próprio armazenamento, chamada da sua própria parte de servidor e elementos de interface. Hóspedes, pedidos, recibos, finanças, funcionários e conversas não existem ali em absoluto. O que exatamente é permitido a um plugin específico sempre aparece no cartão dele, na linha “Permissões”.

Como entregar o desenvolvimento a um terceiro sem dar a ele acesso total à conta?#

Crie para ele uma conta de funcionário e depois conceda uma concessão no bloco “Acesso do desenvolvedor”: marque apenas as permissões necessárias e defina um prazo (por padrão, 14 dias; no máximo, 90). Ele receberá o modo desenvolvedor e nada mais; a instalação do plugin continuará sendo sua. A concessão é revogada com um clique.

O plugin se atualiza sozinho quando o autor lança uma nova versão?#

Não. A atualização é iniciada pelo proprietário: “Verificar atualizações” → “Atualizar para …”. Assim, uma nova versão não aparece na conta sem o conhecimento da pessoa — junto com a versão, as permissões solicitadas também podem ter mudado.

Onde o plugin armazena suas configurações e seus dados?#

Na sua conta, em um armazenamento separado sob o identificador dele (até 1 MB por chave) e, se ele os usar, nos campos personalizados dos seus cartões — cada plugin vê apenas o próprio espaço. Em uma conta no cenaly.ru, a parte de servidor e seu estado permanecem no contorno russo.

Qual é a diferença em relação à API e ao MCP?#

A API para desenvolvedores e o MCP da sua central telefônica são necessários quando o programa funciona por fora: seu site, um sistema de terceiros, um agente de IA. O editor personalizado é o contrário, uma interface dentro do painel: o funcionário o abre como uma página comum do admin e não sai da janela de trabalho.

Seções relacionadas#

• Loja de aplicativos — onde a seção e as extensões integradas são ativadas
• Estoque — a aba onde vivem extensões como a “ВетИС” e o cadastro de produtos
• Importação de catálogo — o caminho padrão para carregar itens, se a tarefa for só essa
• Vitrine com seu próprio código (headless) — contrato de dados aberto para um site externo
• API e MCP da sua central telefônica e Guest API para agentes de IA — trabalho por fora, não dentro do painel
• Funcionários e turnos — conta para o desenvolvedor e papéis
• Segurança e dados — onde os dados ficam armazenados e quem tem acesso a eles
• Suporte — onde escrever se o plugin se comportar de forma suspeita