--- title: Bitrix24 slug: bitrix24 docTags: createdAt: 2026-06-08T16:57:31.713Z --- ## 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](https://apidocs.bitrix24.com). :::hint{type="info"} 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: :::BlockQuote https\://empresa.bitrix24.com/rest/\{ID\_do\_usuario}/\{token\_do\_webhook}/ ::: O conector monta automaticamente essa base e anexa o método de cada operação a partir dos campos da conexão. :::hint{type="warning"} 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: :::BlockQuote `https://{host}/rest/{userId}/{webhookToken}` ::: ### 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..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**) | :::hint{type="warning"} 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. | :::hint{type="info"} 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`). ::: :::hint{type="info"} 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. 1. Adicione um passo do conector **Bitrix24** ao canvas. 2. Em **Recurso**, selecione **Negócios**. 3. Em **Operação**, selecione **Buscar negócio**. 4. 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](https://apidocs.bitrix24.com/).