Bitrix24
Objetivo
O conector Bitrix24 integra a plataforma Fluid com a API REST do Bitrix24, permitindo a leitura de negócios, clientes (contatos e empresas), requisitos, endereços e produtos diretamente do CRM — incluindo as entregas e pagamentos de um negócio e a consulta de tipos de preço e preços do catálogo. Com ele é possível enriquecer fluxos com dados do CRM, sincronizar cadastros com sistemas externos e orquestrar consultas encadeadas (por exemplo, descobrir os endereços de um cliente a partir de seus requisitos, ou obter o preço base de um produto a partir do tipo de preço).
A comunicação pode ser feita por webhook de entrada (inbound webhook) do Bitrix24, autenticando cada chamada com a URL gerada no próprio portal, ou por OAuth2.
Documentação oficial da API
Este conector utiliza a API REST do Bitrix24 (métodos universais de CRM crm.item.*, além de crm.requisite.list, crm.address.list e dos métodos de catálogo catalog.product.get, catalog.priceType.list e catalog.price.list).
Para detalhes de cada método, parâmetros e formato de resposta, acesse o portal de desenvolvedores: https://apidocs.bitrix24.com.
O Bitrix24 está disponível em versão nuvem (empresa.bitrix24.com) e on-premise. O conector funciona em ambas, desde que a URL do webhook de entrada esteja acessível pela Fluid.
Requisitos (conexão)
Método de autenticação
O Bitrix24 autentica via webhook de entrada ou OAuth2.
Autenticação por Webhook
Ao gerar o webhook no portal (em Recursos para desenvolvedores → Outros → Webhook de entrada), o Bitrix24 fornece uma URL no formato:
O conector monta automaticamente essa base e anexa o método de cada operação a partir dos campos da conexão.
O token do webhook é uma credencial sensível e, por padrão, não expira. Trate-o como uma senha, conceda ao webhook apenas as permissões necessárias (ex.: somente CRM) e faça rotação periódica.
Campos obrigatórios
Campo | Descrição | Exemplo |
|---|---|---|
Subdomínio Bitrix24 | Subdomínio da conta do Bitrix24. | 1b23-01c2de |
Tipo de Conexão | Tipo da conexão; utilizar client_credentials para o tipo Webhook. | client_credentials |
ID do usuário | Identificador do usuário dono do webhook. | 1 |
Token do webhook | Código do webhook de entrada gerado no Bitrix24 (campo sensível). | xxxxxxxxxxxxxxxx |
Internamente, a conexão resulta na URL base:
Autenticação por OAuth2
Ao criar um aplicativo no portal (em Recursos para desenvolvedores → Outros → Aplicativo Local), o Bitrix24 fornece o ID do aplicativo (client_id) e a Chave do aplicativo (client_secret). Também é possível obter essas informações instalando um aplicativo público já existente na Bitrix24.
Campos obrigatórios
Campo | Descrição | Exemplo |
|---|---|---|
Subdomínio Bitrix24 | Subdomínio da conta do Bitrix24. | 1b23-01c2de |
Tipo de Conexão | Tipo da conexão; utilizar authorization_code para o tipo OAuth. | authorization_code |
URL Modal | URL de autenticação da Bitrix24 para obtenção do token de acesso. | https://meu_portal.bitrix24.com.br/oauth/authorize |
APP ID | ID do aplicativo na Bitrix24. | app.s6c2wec1wecw1r59e1cve1 |
Chave Secreta do Cliente | Chave secreta do aplicativo da Bitrix24 (campo sensível). | 546rv1e1r4v961er91r5wee1fcew5c1w951vw51 |
Configuração de fluxo
Cada passo do conector exige a escolha de um Recurso e de uma Operação. A requisição é enviada por POST para o método correspondente, com Content-Type: application/json. O caminho da chamada é sempre o nome do método seguido de .json (ex.: crm.item.get.json).
Corpo da requisição
A forma de montar o corpo (body) depende da operação:
- Campos dinâmicos — você preenche cada campo individualmente na interface e o conector cuida da tipagem automaticamente. É a estratégia da maioria das operações (buscar negócio/cliente/produto, listar entregas e pagamentos do negócio, listar produtos do negócio, listar tipos de preço e listar preços).
- Template — você escreve o corpo em Go Template (Sprig), com liberdade total para referenciar dados de passos anteriores via .steps.<nome_do_passo>.body e montar estruturas dinâmicas. Indicado para corpos complexos e filtros avançados. Esta opção fica disponível, como alternativa aos campos dinâmicos, nas operações Listar requisitos do cliente e Listar endereços do cliente.
Recursos e operações
A seguir, o resumo das operações disponíveis no conector. Os nomes em negrito são os mesmos campos que aparecem na interface do passo.
Negócios
Operação | O que informar |
|---|---|
Buscar negócio | Tipo da entidade (negócio = 2), ID do negócio |
Listar entregas do negócio | Tipo da entidade (negócio = 2), ID do negócio |
Listar pagamentos do negócio | Tipo da entidade (negócio = 2), ID do negócio |
Clientes
Operação | O que informar |
|---|---|
Buscar cliente | Tipo da entidade (Contato = 3, Empresa = 4), ID do cliente |
Listar requisitos do cliente | Tipo da entidade (Contato = 3, Empresa = 4), ID do cliente. Campo Campos a retornar opcional (ex.: ID, RQ_CPF, RQ_CNPJ). |
Listar endereços do cliente | Tipo da entidade (endereço de requisito = 8), ID do requisito (o RQ retornado por Listar requisitos do cliente) |
Os endereços de cliente no Bitrix24 são vinculados ao requisito (RQ), não diretamente ao contato/empresa. Por isso, para chegar aos endereços é necessário primeiro listar os requisitos do cliente e usar o ID retornado como ID do requisito na listagem de endereços (com Tipo da entidade = 8).
Produtos
Operação | O que informar |
|---|---|
Listar produtos do negócio | Tipo do dono (negócio = D), ID do dono (ID do negócio). Campo Paginação (start) opcional. |
Buscar produto do catálogo | ID do produto (no catálogo) |
Listar tipos de preço | Nenhum obrigatório. Filtros opcionais (Tipo de preço base, ID do tipo de preço, Nome do tipo de preço, XML ID) e Campos a retornar opcional. Sem filtro, retorna todos os tipos de preço. |
Listar preços do produto | Nenhum obrigatório, mas normalmente filtra-se por ID do produto e/ou Tipo de preço. Campo Campos a retornar opcional. |
Na operação Listar produtos do negócio, o campo Paginação (start) controla a paginação: cada página retorna sempre 50 registros. Para a 1ª página informe 0, para a 2ª informe 50, para a 3ª informe 100, e assim por diante (start = (N-1) × 50).
Operação | O que informar |
|---|---|
Listar produtos do negócio | Tipo do dono (negócio = D), ID do dono (ID do negócio). Campo Paginação (start) opcional. |
Buscar produto do catálogo | ID do produto (no catálogo) |
Listar tipos de preço | Nenhum obrigatório. Filtros opcionais (Tipo de preço base, ID do tipo de preço, Nome do tipo de preço, XML ID) e Campos a retornar opcional. Sem filtro, retorna todos os tipos de preço. |
Listar preços do produto | Nenhum obrigatório, mas normalmente filtra-se por ID do produto e/ou Tipo de preço. Campo Campos a retornar opcional. |
Na operação Listar produtos do negócio, o campo Paginação (start) controla a paginação: cada página retorna sempre 50 registros. Para a 1ª página informe 0, para a 2ª informe 50, para a 3ª informe 100, e assim por diante (start = (N-1) × 50).
Em Listar preços do produto, o campo Tipo de preço corresponde ao grupo de catálogo do Bitrix24. Para descobri-lo dinamicamente, use antes a operação Listar tipos de preço e reaproveite o id retornado.
Na prática
Nesta seção vamos montar um fluxo de exemplo: buscar um negócio.
Exemplo — Buscar um negócio
Fluxo com um único passo, cujo objetivo é retornar os dados de um negócio pelo seu ID.
- Adicione um passo do conector Bitrix24 ao canvas.
- Em Recurso, selecione Negócios.
- Em Operação, selecione Buscar negócio.
- Em Corpo da requisição, preencha os campos:
- Tipo da entidade = 2
- ID do negócio = 1 (o negócio que deseja consultar)
Ao executar, o passo retorna os dados do negócio informado.
Boas práticas
- Confirme o Tipo da entidade antes de publicar: negócio = 2, contato = 3, empresa = 4, endereço de requisito = 8. Um tipo incorreto retorna registro vazio sem gerar erro explícito.
- Use IDs retornados para operações futuras, como nos encadeamentos requisito → endereço e tipo de preço → preço.
- Descubra o tipo de preço dinamicamente com a operação Listar tipos de preço (filtrando Tipo de preço base = Y para o preço base), em vez de fixar o tipo de preço no fluxo.
- Pagine resultados longos em Listar produtos do negócio com o campo Paginação (start) (50 registros por página).
- Restrinja as permissões do webhook apenas aos escopos necessários (ex.: CRM, catálogo).
Disparo do fluxo
O fluxo pode ser acionado conforme os mecanismos padrão da Fluid: por eventos/webhooks, agendamentos (scheduler), chamada via URL de disparo ou execução manual para teste.
Recomendações de teste
- Comece com uma operação de leitura simples (Buscar negócio) e um ID conhecido, validando headers e o body da resposta.
Conclusão
O conector Bitrix24 conecta a Fluid à API REST do Bitrix24, cobrindo consultas a negócios, clientes, requisitos, endereços, produtos, entregas, pagamentos, tipos de preço e preços do catálogo. A autenticação via webhook de entrada ou OAuth2, aliada à flexibilidade entre campos dinâmicos e template, permite desde consultas diretas até fluxos encadeados mais elaborados. Para aprofundar nos métodos e parâmetros, consulte sempre a documentação oficial do Bitrix24.