IA e AutomaçãoGuia
Tutorial Bitrix24 Vibecode: Crie Seu Primeiro App com Claude Code ou Cursor
Com o Bitrix24 (Alaio) Vibecode, qualquer pessoa que saiba descrever um problema em texto pode criar um app funcional para o portal em uma única sessão de trabalho - sem escrever uma linha de código manualmente.
Todo canal termina em um só portal
O Que Esperar do Seu Primeiro App no Vibecode
O Vibecode entrega um protótipo funcional - widget de CRM, bot de notificações ou resumidor de documentos - em uma única sessão. Não é um sistema completo do zero, mas é um app real rodando dentro do seu portal Bitrix24, acessível à equipe no mesmo dia.
A lógica de negócio fica em servidores Black Hole (infraestrutura de nuvem isolada, invisível da internet pública), que se comunicam com o portal via REST API e aparecem no interface através de placements. Dois exemplos concretos do que cabe em uma sessão:
- Widget de relatório na ficha de negócio - exibe as três últimas tarefas vinculadas ao negócio com seus respectivos status.
- Bot de resumo de documento - o usuário sobe um PDF ou DOCX pelo menu lateral do portal e recebe um sumário em texto simples.
Se você quer entender a plataforma antes de começar a construir, o artigo VibeCode no Bitrix24: Como Agentes de IA Criam Aplicativos Sem Programação cobre a arquitetura geral.
Antes de Começar: Acesso, Plano Vibe+ e Créditos
Para usar o Vibecode você precisa de um portal Bitrix24 com qualquer plano Vibe+. Desde 1º de setembro de 2026, todo plano existe em duas versões - Essentials e Vibe+; o Vibe+ inclui o Vibecode, API REST ilimitada e o servidor MCP. Há um período de demonstração gratuito de 15 dias.
Segundo informações oficiais verificadas em 5 de outubro de 2026 em vibecode.bitrix24.com/pricing:
| Item | Detalhe |
|---|---|
| Requisito de plano | Qualquer plano Bitrix24 na versão Vibe+ |
| Demonstração gratuita | 15 dias de acesso Vibe+ sem custo |
| Self-hosted | Bitrix24 on-premise também pode ser conectado à plataforma |
| Bônus de boas-vindas | Novos portais recebem 10 créditos Vibe e 14 dias de acesso trial |
| Créditos Vibe | 1 crédito = US$ 1; pacotes Starter (20), Team (50) e Pro (100); válidos por 365 dias |
O que consome créditos: servidores Black Hole enquanto estão ativos, modelos de IA pagos integrados e pesquisa web com IA. O que não consome: criação e atualização de apps via agente, chamadas de API ao Bitrix24 e modelos de IA gratuitos integrados - incluindo BitrixGPT 5.5, GPT-OSS 120B e Gemma 4 26B.
Exemplos de custo mensais publicados oficialmente (helpdesk.bitrix24.com, 25 set. 2026):
- App de resumo matinal simples: cerca de 3 créditos/mês
- Calculadora de orçamento com 200 usos/mês: cerca de 12-18 créditos/mês
- Assistente de IA processando 50 mensagens recebidas por dia: cerca de 115 créditos/mês
Passo 1 - Criar a Chave de API no Vibecode
A chave de API é o passo obrigatório antes de qualquer coisa: sem ela o agente não acessa dados do seu portal. Escolha o tipo certo e limite as permissões ao mínimo necessário - é possível revogar com um clique a qualquer momento.
- Acesse vibecode.bitrix24.com e entre com sua conta Bitrix24 (funciona via QR code também).
- Vá até a seção de API Keys e crie uma nova chave.
- Escolha o tipo:
-
vibe_api_- para uso pessoal e um único app; age em nome do seu usuário. Ideal para o primeiro projeto. -vibe_app_- para uso da equipe ou app embutido no portal; age em nome do usuário que instalar o app. - Defina o modo de acesso: Somente leitura ou Leitura e gravação. Mantenha apenas as permissões que o app realmente precisa (CRM, tarefas, arquivos etc.).
- Opcionalmente, configure validade (30 a 365 dias ou sem prazo).
- Copie a chave - ela é exibida apenas uma vez.
Boas práticas de segurança: a chave dá ao agente os mesmos acessos da sua conta. Para um primeiro experimento, comece com leitura apenas. Se a chave vazar, revogue-a imediatamente na seção de API Keys - o bloqueio é instantâneo.
Passo 2 - Conectar Claude Code, Cursor ou Codex à Plataforma
O Vibecode é compatível com Claude Code, Cursor, Codex e Antigravity. Cada ferramenta tem sua própria assinatura; o que o Vibecode fornece é a chave de API e a documentação estruturada para que o agente entenda o portal.
Para conectar:
- Na sua ferramenta de IA preferida (Claude Code, Cursor etc.), forneça a chave criada no Passo 1.
- Forneça também o link da documentação oficial - o Vibecode disponibiliza
llms.txt, arquivos.mdpor seção e OpenAPI, todos formatados para leitura por agentes. - Para integração via MCP, use o pacote
@bitrix24/mcp-vibecode-api(mais de 50 ferramentas; modo stdio ou HTTP; configurações prontas para Claude Code, Claude Desktop, Cursor e Codex CLI). - O agente faz uma chamada
GET /v1/mepara verificar o acesso - se retornar seus dados, a conexão está ativa.
O artigo Como Conectar ChatGPT, Claude ou Manus ao Bitrix24 via MCP detalha o processo de configuração do servidor MCP se você preferir essa rota.
Passo 3 - Descrever a Tarefa ao Agente de IA
A qualidade da descrição da tarefa determina quantas iterações você vai precisar. O agente segue o que está escrito - não adivinha intenções. Uma boa tarefa tem contexto, objetivo claro, limites e critério de aceitação.
O fluxo de dados de um app no Vibecode vai do seu pedido em linguagem natural até o portal, passando pela plataforma:
Estrutura de uma boa tarefa para o agente
| Elemento | Para que serve | Exemplo |
|---|---|---|
| Contexto | O agente entende onde o app fica | "Widget embutido na ficha de negócio do CRM" |
| Objetivo | O que deve resultar | "Mostrar as 3 últimas tarefas vinculadas ao negócio com status" |
| Limites | O que NÃO fazer | "Não altere outros campos da ficha, não modifique dados" |
| Exemplo de resultado | Reduz interpretações erradas | "Lista em texto simples, uma tarefa por linha, sem Markdown" |
| Critério de aceitação | Quando a tarefa está pronta | "A lista aparece em menos de 3 segundos após abrir a ficha" |
Tarefa fraca: "Crie um app para o CRM."
Tarefa funcional: "Crie um widget na ficha de negócio do Bitrix24 que exibe as 3 últimas tarefas vinculadas a esse negócio com seus status. Use a chave de API [cole aqui]. Embutir no placement da ficha de negócio. Saída em texto simples, sem Markdown."
Um truque útil: descreva a tarefa livremente primeiro e peça ao agente para reformulá-la como especificação técnica. Valide a especificação antes de o agente começar a codar - isso costuma reduzir o número de iterações.
Se a saída não for o esperado, não recomece do zero. Refine no mesmo chat: "ordene as tarefas por data de criação" ou "adicione um botão de atualizar". O agente mantém o contexto da sessão.
Passo 4 - Deploy, Teste e Publicação no Portal
Após receber a tarefa, o agente escreve o código, cria automaticamente um servidor Black Hole e faz o deploy - tudo em 1 a 2 minutos. Nenhuma configuração de infraestrutura é necessária da sua parte.
Após o deploy:
- O app fica acessível em
https://app-{id}.vibecode.bitrix24.com(não público por padrão). - Se for um widget de UI, aparece no placement configurado dentro do portal.
- Se for um bot, aparece no mensageiro do Bitrix24.
Opções de publicação:
| Cenário | O que fazer |
|---|---|
| Só para você | O app já funciona após o deploy, sem etapa adicional |
| Para toda a equipe | Use uma chave de autorização vibe_app_, feita para uso em equipe e incorporação no Bitrix24 |
| Publicar no Marketplace | Ainda não disponível - função em desenvolvimento, segundo informação oficial de 5 out. 2026 |
Sobre os servidores Black Hole: por padrão, o servidor entra em modo de sono após inatividade (padrão: 60 minutos; configurável para 15, 30, 60, 240 minutos ou desativado). Em modo de sono, o custo é cerca de dez vezes menor do que em modo ativo. Se os créditos Vibe se esgotarem, os servidores param - mas o código do app é preservado. Após 33 dias com saldo zerado, os servidores são excluídos.
Como Depurar sem Tocar no Código
A abordagem correta de depuração no Vibecode é descrever o problema ao agente como usuário, não editar o código manualmente. O agente lê os logs do servidor Black Hole, identifica a causa e corrige - sem que você precise abrir um editor.
Algoritmo prático:
- Abra o app como usuário comum.
- Veja o problema - tire um print de tela.
- Descreva ao agente: "Estou vendo X na tela, mas deveria aparecer Y."
- O agente lê os logs, encontra a causa e corrige.
Casos reais resolvidos apenas com descrição em texto:
| Problema | O que aconteceu | Como foi resolvido |
|---|---|---|
| Agente renomeou o bot | O agente "melhorou" o nome por conta própria | Especificado na tarefa: "não altere o nome do bot" |
| "Cliente não encontrado" | Retornava erro mesmo com o cliente no CRM | Print + descrição do fato; agente corrigiu a lógica da consulta |
| Markdown em vez de texto simples | Saída com **negrito** que o portal não renderizava |
Especificado na tarefa: "saída em texto simples, sem Markdown" |
Errar é esperado. Tentar corrigir manualmente é o problema - você perde o contexto do agente e cria inconsistências difíceis de rastrear.
Erros Típicos no Primeiro Projeto e Como Evitá-los
Os erros mais comuns no primeiro projeto com Vibecode não são de código - são de formulação de tarefa, permissões excessivas e gestão de servidor.
- Tarefa genérica demais. "Automatize o atendimento" não funciona. Comece com uma única ação concreta e específica.
- Permissões excessivas na chave. Dar acesso total em um projeto de teste é má prática. Limite a chave às entidades que o app usa.
- Esperar mudanças no núcleo do sistema. Se a tarefa for "altere o formulário padrão de negócio", isso está fora do que o Vibecode faz na versão cloud - veja a seção de limites abaixo.
- Ignorar limites de REST API. A plataforma Vibecode e a conta Bitrix24 limitam o número de requisições por segundo - agrupe e armazene em cache as requisições e peça ao agente que leia os logs do servidor se o app ficar lento.
- Esquecer de colocar o servidor em modo de sono. Um servidor ativo sem uso continua sendo cobrado. Após testes, configure o modo de sono ou desligue o servidor.
- Trocar de modelo de IA no meio do projeto. Mudanças de modelo durante o desenvolvimento perdem o contexto acumulado. Novas tarefas devem ser iniciadas em sessões separadas.
Limites Reais da Plataforma: O Que o Vibecode Não Faz
O Vibecode opera sobre o Bitrix24 via REST API - não dentro dele. Isso significa que modificações no núcleo, acesso direto ao banco de dados e PHP server-side dentro do portal não são possíveis na versão cloud. Para essas necessidades, a versão self-hosted é o caminho.
Tabela de capacidades:
| Capacidade | Cloud (Vibecode) | Self-hosted |
|---|---|---|
| Apps e widgets via REST API e placements | ✅ | ✅ |
| Bots de chat e automações | ✅ | ✅ |
| Modelos de IA integrados (BitrixGPT 5.5, GPT-OSS, Gemma) | ✅ | ✅ (após conectar o portal ao Vibecode) |
| Deploy em servidores Black Hole | ✅ | ✅ (após conectar o portal ao Vibecode) |
| Modificação do código-fonte do núcleo | ❌ | ✅ |
| PHP server-side dentro do portal | ❌ | ✅ |
| Acesso direto ao banco de dados do portal | ❌ | ✅ |
| Tipos de campos personalizados no nível do BD | ❌ | ✅ |
| Publicação no Marketplace Bitrix24 | ❌ (em desenvolvimento) | ❌ (em desenvolvimento) |
Outros limites conhecidos, conforme experiência com a plataforma:
- A API do Vibecode é uma camada sobre REST - nem todos os métodos do Bitrix24 estão cobertos. Em cenários não convencionais, uma chamada REST direta pode ser mais rápida.
- UIKit e Tailwind não estão incluídos nas instruções padrão da plataforma - se necessários, especifique na tarefa ao agente.
- O Vibecode é descrito oficialmente como plataforma em desenvolvimento ativo; verifique a documentação em vibecode.bitrix24.com para informações atualizadas.
Se a sua necessidade exige mudanças no núcleo do portal, o artigo Customização Além dos Limites da Nuvem: O Que é Possível no Bitrix24 Self-Hosted cobre as opções disponíveis.
Checklist: O Que Verificar Antes de Liberar para a Equipe
Antes de colocar o app em uso pela equipe, percorra esta lista. A maioria dos problemas pós-lançamento vem de permissões mal configuradas ou de comportamento do servidor não testado em condições reais.
✅ Checklist pré-produção
Chave de API
- O tipo de chave está correto (
vibe_api_para uso pessoal,vibe_app_para equipe) - As permissões estão limitadas ao mínimo necessário
- A validade da chave está configurada (se aplicável)
- A chave não foi exposta em commits ou logs
Funcionalidade
- O app foi testado com dados reais (não apenas mockados)
- O comportamento com dados ausentes ou campos vazios foi verificado
- A saída de texto não contém Markdown onde o portal espera texto simples
- O app responde em tempo aceitável (referência: menos de 10 segundos para consultas simples)
Servidor Black Hole
- O modo de sono está configurado adequadamente (padrão: 60 min de inatividade)
- O custo estimado mensal está dentro do orçamento esperado
- O app foi acessado após o servidor acordar do modo de sono (verificar tempo de wake-up)
Acesso e publicação
- Para uso da equipe, o app usa uma chave
vibe_app_e está incorporado no placement certo - Os usuários que precisam do app têm acesso ao placement configurado
- Há um responsável definido para manutenção e atualização do app
Segurança
- Dados sensíveis não são armazenados em variáveis de ambiente expostas
- O log de mudanças do app foi revisado (toda alteração é registrada pela plataforma)
- Você sabe como revogar a chave imediatamente se necessário
Um parceiro Gold Bitrix24 pode ajudar a definir a tarefa, construir o app no Vibecode, testar o cenário e entregar uma ferramenta pronta para uso - conforme descrito na documentação oficial da plataforma (helpdesk.bitrix24.com/open/25982183/). A ACP Group, parceiro Gold do Bitrix24, trabalha com projetos de Vibecode para equipes que precisam de um primeiro app funcional sem desviar o time de suas atividades principais.
Para projetos onde a automação padrão do Bitrix24 já resolve bem o problema, o artigo Bitrix24 Business Process Automation: Robots, Triggers and the Workflow Designer é um bom ponto de partida antes de decidir pelo Vibecode.
Perguntas que nos fazem
Perguntas frequentes: Tutorial Bitrix24 Vibecode
Preciso saber programar para criar um app no Bitrix24 Vibecode?
Não. O agente de IA escreve o código com base na sua descrição em linguagem natural. Sua função é formular bem o que o app deve fazer e onde deve aparecer - o agente faz o resto.
Qual plano do Bitrix24 dá acesso ao Vibecode?
Qualquer plano Bitrix24 na versão Vibe+. Desde 1º de setembro de 2026, todo plano existe em duas versões - Essentials e Vibe+. Há um período de demonstração gratuito de 15 dias para experimentar antes de contratar.
O que são créditos Vibe e o que consome créditos?
Créditos Vibe são a moeda da plataforma (1 crédito = US$ 1). Consomem créditos: servidores Black Hole ativos, modelos de IA pagos e pesquisa web com IA. Não consomem: criação de apps via agente, chamadas REST ao Bitrix24 e modelos gratuitos como BitrixGPT 5.5 e Gemma 4 26B.
O que acontece com o app se meus créditos acabarem?
Os servidores dos apps param de funcionar, mas os apps ficam salvos; ao recarregar o saldo, eles voltam a rodar. Após 33 dias com saldo zerado, os servidores são excluídos - mas há tempo para recarregar os créditos antes disso.
Como depuro o app quando algo não funciona?
Tire um print do que está vendo, descreva ao agente o que vê e o que deveria aparecer. O agente lê os logs do servidor Black Hole, identifica a causa e corrige. Não edite o código manualmente - isso quebra o contexto do agente.
Posso publicar meu app no Marketplace do Bitrix24?
Ainda não. Segundo informação oficial verificada em 5 de outubro de 2026, a publicação no Marketplace está em desenvolvimento. Por enquanto, os apps funcionam dentro do seu portal; para uso da equipe ou incorporação no Bitrix24 é usada a chave vibe_app_.
Qual a diferença entre chave vibe_api_ e vibe_app_?
A chave vibe_api_ é para uso pessoal e um único app - age em nome do seu usuário, ótima para começar. A chave vibe_app_ é para apps compartilhados com a equipe ou embutidos no portal - age em nome do usuário que instalar o app.
O que ouvimos nos primeiros dez minutos
Mande uma mensagem e pule a reunião de descoberta
Escreva para +971 55 780 1481 no WhatsApp. Conte o seu cenário e quantas pessoas, e você recebe escopo e preço por escrito em um dia útil.