Por Que a Nuvem Tem Teto — e a Caixa Não
Na versão cloud do Bitrix24, você opera dentro de um ambiente compartilhado gerenciado pelo fornecedor. Isso significa segurança e atualizações automáticas, mas também significa que o perímetro do que você pode modificar é definido pela Bitrix, não pela sua empresa. APIs REST, webhooks e aplicativos do Marketplace são os únicos vetores de extensão disponíveis.
Na versão self-hosted (on-premise), a equação muda. Você instala o produto no seu próprio servidor, tem acesso SSH ao sistema de arquivos e pode, dentro dos limites da licença, alterar arquivos PHP, JavaScript e templates diretamente no núcleo da plataforma. Esse nível de acesso abre uma categoria inteiramente diferente de customizações — relevante sobretudo para product owners e diretores de TI que precisam encaixar o Bitrix24 dentro de arquiteturas corporativas complexas.
Importante: acesso ao código-fonte não significa "alterar o que quiser sem consequências". Modificações mal documentadas criam dívida técnica e podem bloquear atualizações futuras. A seguir detalhamos o que fazer, como fazer com segurança e onde estão os limites práticos.
O Que Você Pode Modificar no Código-Fonte
No Bitrix24 self-hosted, todas as camadas da aplicação estão disponíveis para modificação — PHP, JavaScript, templates e componentes —, mas projetos reais mostram que menos de 25 arquivos (cerca de 0,02% da base de ~109 mil) costumam ser alterados nos primeiros ciclos de desenvolvimento.
O Bitrix24 self-hosted é estruturado em módulos independentes — CRM, tarefas, mensageiro interno, rede social corporativa, localização, extranet, entre outros. Com acesso ao servidor, é possível intervir em qualquer camada:
| Camada | Exemplos de modificação |
|---|---|
| PHP / lógica de negócios | Campos customizados em entidades CRM, tipos de endereço, regras de requisito |
| JavaScript / frontend | Comportamento do chat, lista de contatos recentes, widgets de mapa |
| Templates de componentes | Layout do Gantt, telas de votação, páginas de extranet |
| Componentes proprietários | Criação de componentes totalmente novos (vendor:component.name) |
| Módulos adicionais | Instalação/remoção seletiva de módulos; apenas os necessários ficam ativos |
Com base em projetos reais de implementação, uma instalação self-hosted típica com customizações moderadas apresenta algo em torno de 0,02% dos arquivos modificados — ou seja, em uma base de ~109 mil arquivos, menos de 25 costumam ser alterados nos primeiros ciclos de desenvolvimento. Isso confirma que customizações cirúrgicas são suficientes para a maioria dos requisitos de negócio.
Customizações Mais Comuns em Projetos Reais
Em implementações self-hosted, os padrões mais frequentes envolvem CRM, mensageria, tarefas e localização: desde campos customizados em crm_fields.php e coloração do Gantt por prazo até substituição do widget de mapa e criação de componentes com namespace próprio fora do escopo de atualização do núcleo.
Com base na nossa experiência em implementações, os padrões de customização mais frequentes no self-hosted são:
Módulo CRM
- Adição de campos e tipos de endereço personalizados diretamente em
crm_fields.phpeentityaddresstype.php - Criação de lógica de requisitos customizados para entidades (
entityrequisite.php) - Desenvolvimento de handlers (manipuladores de eventos) para processos específicos — por exemplo, associar automaticamente fornecedores homologados a uma ficha de compras ao final de um smart process
Módulo de Mensageria
- Modificação de templates do chat interno para exibir informações adicionais do usuário
- Ajustes no bundle JavaScript do messenger para comportamentos customizados na lista de conversas recentes
Módulo de Tarefas
- Customização visual do Gantt (
tasks.task.gantt) para indicação de cores por prazo e status — funcionalidade que não existe nativamente e exige desenvolvimento específico - Filtros e exportações avançadas de listas de tarefas
Módulo de Localização
- Substituição do widget de mapa padrão por provedores alternativos (ex.: integração com mapas regionais)
- Configuração de popups de endereço com comportamento adaptado ao fluxo de vendas local
Componentes Totalmente Novos
É possível criar componentes próprios com namespace dedicado (ex.: seuvendor:campo.periodo). Esses componentes ficam fora do escopo de atualização do núcleo Bitrix24 e podem ser versionados separadamente no seu repositório Git.
Integrações que Só São Possíveis no Self-Hosted
O self-hosted mantém todas as integrações REST/webhook da nuvem e adiciona 4 categorias exclusivas: acesso direto ao banco de dados, autenticação SSO no nível do SO, filas de mensagens via RabbitMQ/Kafka em handlers PHP e conexão com sistemas legados sem API REST via cron do servidor.
A versão cloud oferece integração via REST API e webhooks. O self-hosted mantém essas opções e adiciona:
- Integração direta com banco de dados: consultas e sincronizações que bypassam a camada de API, úteis para cargas de dados em lote (ex.: sincronização com ERP duas vezes ao dia — manhã e fim de expediente)
- Active Directory / LDAP no nível do sistema operacional: além da integração nativa do Bitrix24, é possível configurar autenticação SSO diretamente no servidor web
- Filas de mensagens internas: integração com sistemas de mensageria (RabbitMQ, Kafka) diretamente via código PHP nos handlers de evento
- Sistemas legados sem API REST: integração com ERPs e sistemas de contabilidade que expõem apenas conectores nativos ou arquivos de troca, possível via scripts agendados no cron do servidor
Para cenários de integração com Active Directory e SSO, veja o guia detalhado em Active Directory, LDAP e SSO com Bitrix24 self-hosted.
Como o Fluxo de Desenvolvimento Funciona na Prática
O fluxo de customização self-hosted percorre 7 etapas obrigatórias — do briefing ao suporte pós-deploy —, sendo a auditoria de arquivos modificados a etapa crítica que cataloga cada mudança, classifica riscos e gera recomendações antes de qualquer atualização de versão do Bitrix24.
O diagrama abaixo mostra o fluxo típico de uma customização em self-hosted, desde o levantamento de requisitos até a entrega em produção:
O processo parte do briefing com o cliente, passa por análise técnica, desenvolvimento em ambiente de homologação, auditoria de modificações e só então vai a produção — com backup prévio obrigatório.
flowchart TD
A[Briefing & Requisito de Negócio] --> B[Análise Técnica: API REST resolve?]
B -- Sim --> C[Desenvolvimento via REST/Webhook]
B -- Não --> D[Customização em Self-Hosted]
D --> E[Desenvolvimento em Homologação]
E --> F[Auditoria de Arquivos Modificados]
F --> G{Modificações documentadas?}
G -- Não --> H[Documentar & Classificar Riscos]
H --> F
G -- Sim --> I[Backup do Portal]
I --> J[Deploy em Produção]
J --> K[Suporte Pós-Deploy]
A etapa de auditoria de modificações é crítica: ela cataloga cada arquivo alterado, classifica o risco de cada mudança e gera recomendações — especialmente importantes antes de atualizações de versão do Bitrix24.
Limites Reais: O Que Você Não Pode (ou Não Deve) Fazer
No self-hosted, 4 riscos concentram a maioria dos problemas em produção: editar o núcleo sem documentação (sobrescrito em atualizações), componentes sem descrição (exigem análise reversa), módulos desatualizados (vetores de vulnerabilidade) e erros de configuração de servidor que amplificam qualquer falha de customização.
Acesso ao código-fonte não é ilimitado. Existem restrições práticas e técnicas que todo product owner deve conhecer:
- Modificar o núcleo sem documentação é dívida técnica garantida. Atualizações de versão podem sobrescrever arquivos alterados. A boa prática é sempre criar componentes ou módulos proprietários em vez de editar os nativos.
- Componentes customizados mal descritos criam problemas de diagnóstico — em projetos reais já encontramos componentes sem descrição que exigiam análise reversa para entender sua função.
- Módulos desatualizados são vetores de vulnerabilidade. Self-hosted coloca sobre você a responsabilidade de manter o núcleo e os módulos atualizados. Instalações que ficam sem atualização acumulam riscos de segurança documentados.
- Erros de configuração de servidor (parâmetros de banco de dados subdimensionados, log de erros exposto ao usuário final) amplificam qualquer problema de customização. O servidor precisa ser endurecido antes de qualquer trabalho de desenvolvimento.
Para uma lista completa de verificações de segurança, consulte o checklist de 25 pontos para Bitrix24 self-hosted.
Migração da Nuvem para o Self-Hosted: Ponto de Partida para Customizações
A migração do Bitrix24 cloud para o self-hosted segue 5 etapas sequenciais — levantamento de servidor, deploy da licença, configuração de SSL e backups, migração de dados e 30 dias de suporte pós-migração —, sendo o ponto de partida obrigatório para quem precisa de customizações além do limite da nuvem.
Muitas empresas chegam ao self-hosted após perceber que a versão cloud não comporta as customizações necessárias. O processo de migração envolve:
- Levantamento de requisitos técnicos de servidor (núcleos, RAM, disco, DNS, SSL)
- Deploy da licença self-hosted com remoção de dados de teste e registro da chave de licença
- Configuração de Push & Pull, certificado SSL (Let's Encrypt ou corporativo) e backups automáticos
- Migração dos dados e configurações do portal cloud
- Período de suporte pós-migração (tipicamente 30 dias de garantia sobre os itens migrados)
O guia completo está em como migrar do Bitrix24 Cloud para o Self-Hosted.
Self-Hosted vs. Cloud: Matriz de Decisão para Customização
A matriz de decisão mostra que 4 necessidades críticas — modificar o Gantt, integrar ERP legado sem API, substituir o widget de mapa e criar componentes proprietários — são impossíveis na nuvem e plenamente viáveis no self-hosted, ao custo de assumir a responsabilidade pela segurança do servidor.
| Necessidade | Cloud | Self-Hosted |
|---|---|---|
| Campos extras em cards CRM | ✅ Nativo | ✅ Nativo + código |
| Smart Processes customizados | ✅ Nativo | ✅ Nativo + handlers |
| Modificar layout do Gantt | ❌ Impossível | ✅ Template PHP/JS |
| Integração com ERP legado sem API | ❌ Limitado | ✅ Cron + PHP direto |
| Widget de mapa alternativo | ❌ Impossível | ✅ Substituição do bundle JS |
| Componente proprietário | ❌ Impossível | ✅ Namespace próprio |
| Controle de atualizações de versão | ❌ Automático | ✅ Sob controle da equipe |
| Responsabilidade por segurança do servidor | ❌ Bitrix | ✅ Sua equipe / parceiro |
Para uma análise de custo total de propriedade entre as duas opções ao longo de 3 anos, veja Self-Hosted vs Cloud Bitrix24: Análise TCO Completa.
Quando Vale o Investimento em Desenvolvimento Self-Hosted
O desenvolvimento sobre o código-fonte do self-hosted se justifica quando pelo menos um de 4 critérios é atendido: funcionalidade ausente no Marketplace e inviável via REST, time de TI capaz de manter documentação e atualizações, exigência regulatória ou estratégica de soberania de dados, ou volume de usuários que justifica infraestrutura dedicada.
Com base em nossa experiência em implementações, o desenvolvimento sobre o código-fonte do self-hosted se justifica quando:
- A funcionalidade necessária não existe no Marketplace e não pode ser construída via REST API dentro de prazo e orçamento razoáveis
- A empresa tem um time de TI interno ou parceiro dedicado capaz de manter a documentação das modificações e o ciclo de atualizações
- Existe uma necessidade de soberania de dados que impede o uso da nuvem — regulatória, contratual ou estratégica
- O volume de usuários e transações justifica a infraestrutura dedicada (ver guia de dimensionamento de hardware)
Se apenas um desses pontos se aplica, a análise de viabilidade técnica é o primeiro passo — e evita projetos que consomem orçamento sem entregar valor mensurável.