REST API Bitrix24: Documentação Prática

Guia Atualizado da REST API do Bitrix24

Seja bem-vindo ao nosso guia definitivo sobre a REST API do Bitrix24! Aqui você encontrará tudo o que precisa para começar a explorar e aplicar os recursos da API com confiança, eficiência e de forma atualizada com base na documentação oficial do Bitrix24.

Ao final deste guia, disponibilizamos materiais complementares, links úteis e dicas para quem quer se aprofundar. Caso tenha dúvidas, entre em contato conosco pelo WhatsApp ou agende uma consultoria especializada.

O que é o Bitrix24?

O Bitrix24 é uma plataforma completa de CRM e colaboração, com recursos que vão desde vendas e gestão de clientes até tarefas, projetos, RH e comunicação. Disponível na nuvem e com versão gratuita, ele também oferece acesso à sua REST API (em planos pagos e durante o trial de 15 dias).

Quer ver mais de 130 formas de uso? Acesse aqui . Faça agora sua versão gratuita do Bitrix24 e veja também dicas para começar trabalhar no Bitrix24.

Acesso à REST API: planos, permissões e primeiros passos

Disponibilidade:

• REST API está disponível apenas em planos pagos ou durante o período de demonstração (15 dias).
• Para saber se está ativo, clique em “Meu Plano” no cabeçalho do Bitrix24.
• Desenvolvedores podem solicitar ambiente NFR (sandbox).

Permissões:

• Toda chamada à API é executada em nome de um usuário.
• Utilize uma conta com perfil de administrador para ter acesso total.

Como acessar e autenticar a API

1. Webhook de Entrada

O jeito mais simples de testar a API é com webhooks:

• Acesse “Recursos do Desenvolvedor” > Outros > Webhook de entrada
• Escolha os módulos que o webhook pode acessar
• Copie a URL gerada com token exclusivo

2. Construtor de Solicitações

Ferramenta nativa do Bitrix24 para criar chamadas REST:

• Escolha o método (ex: crm.deal.list)
• Insira os parâmetros desejados
• Clique em Executar para ver o retorno JSON

3. OAuth 2.0 (para apps e integrações mais complexas)

Use OAuth quando precisar de:

• Login de múltiplos usuários
• Publicação de apps no Marketplace

Veja documentação oficial de OAuth

Estrutura básica da chamada REST API

https://empresa.bitrix24.com/rest/user_id/token/method.json?param1=valor1

Exemplo prático:

https://empresa.bitrix24.com/rest/276/xbnc9mu1u0yxkglr/crm.deal.list.json?SELECT[]=ID&SELECT[]=TITLE

Componentes:

• empresa.bitrix24.com: seu portal Bitrix
• 276: ID do usuário (dono do webhook)
• token: chave de autenticação
• crm.deal.list: método a ser chamado

Métodos HTTP principais

Perceba na API que praticamente existe uma função para cada ação desejada. Compreender e utilizar esses métodos de forma eficaz é crucial para aproveitar ao máximo as capacidades de integração e automação oferecidas pela API do Bitrix24. Nesta tabela trago os principais endpoints, sua utilidade e um exemplo de URL, onde […] é o mesmo que https://empresa.bitrix24.com.br/rest/276/xbnc9mu1u0yxkglr

Dica bônus: Para ter uma visualização melhor dos campos, utilize a extensão JSON FORMATTER no Google Chrome

O Bitrix24 disponibiliza uma tabela com a estrutura básica dos campos padrões de Empresas, Negócios, Leads, Contatos, Recursos e Atividades. Também possuímos uma tabela personalizada para consultar os principais campos que você pode baixar aqui.

A API Bitrix24 tem um método específico para cada ação. Exemplo:

https://empresa.bitrix24.com/rest/…/crm.contact.get/?id=123

Filtros, ordenação e seleção de campos

A maioria dos métodos aceita os parâmetros:

• ORDER[]=: ordenação, ex: ORDER[]=NAME:ASC
• FILTER[]=: filtrar dados, ex: FILTER[>PROBABILITY]=50
• SELECT[]=: especificar campos, ex: SELECT[]=ID&SELECT[]=UF_*

Dicas:

• Para todos os campos personalizados: SELECT[]=*&SELECT[]=UF_*
• Use % como curinga, ex: FILTER[NAME]=%an% para pegar “Jan”, “Brian”…
• A filtragem é case-insensitive mas depende do formato exato (ex: telefone precisa estar idêntico)

Diferença entre crm.deal.get e crm.deal.list

A maioria dos métodos aceita os parâmetros:

Exemplos práticos

# Listar todos os contatos
crm.contact.list.json?select[]=ID&select[]=NAME

# Buscar contato por telefone
crm.contact.list.json?filter[PHONE]=8903227&select[]=ID&select[]=NAME

# Buscar todos os produtos de um Negócio
crm.deal.productrows.get.json?id=226935

Utilize a extensão JSON Formatter no Chrome para facilitar a leitura do retorno.

Enviando arquivos via API

Para transferir um arquivo, é necessário especificar dois parâmetros – o nome do arquivo com sua extensão, além do código base64, que na verdade é um conjunto de dados para o arquivo.

Os dados no campo são enviados em um arquivo compactado. Visualmente, isso pode ser representado assim:

[[somefile.txt,base64],[somefile2.txt,base64]]

Os dados no campo são enviados em um arquivo compactado. Visualmente, isso pode ser representado assim:

/crm.deal.update?ID=123&FIELDS[UF_CRM_1674832920][0][fileData][0]=somefile.txt&FIELDS[UF_CRM_1674832920][0][fileData][1]=SGVsbG8gd29ybGQ%3D

Explicação:

• /crm.deal.update?ID=123 – acessa o negócio com ID 123 para atualizá-lo.
• FIELDS[UF_CRM_1674832920][0][fileData][0]=somefile.txt – envia o nome do arquivo.
• FIELDS[UF_CRM_1674832920][0][fileData][1]=SGVsbG8gd29ybGQ%3D – envia o conteúdo do arquivo em base64.

Testando com Postman

Uma maneira prática e segura de testar chamadas da API Bitrix24 é usando o Postman:

1. Baixe o arquivo de coleção .postman_collection.json
   
2. No Postman, clique em Importar > Arquivo e selecione o arquivo
   
3. Configure as variáveis {{domain}}, {{user_id}} e {{token}} no ambiente
   
4. Execute requisições como crm.contact.get, crm.deal.list, crm.status.list, entre outras já preparadas

Exemplo de chamada:

https://empresa.bitrix24.com.br/rest/25/s9epahw88mj42jlv/crm.deal.get/?id=7323

https://empresa.bitrix24.com.br/rest/25/s9epahw88mj42jlv/crm.deal.get/?id=7323

Com o Postman, você pode montar, testar e automatizar chamadas REST com mais agilidade. Ideal para desenvolvedores, agências e parceiros Bitrix24.

Webhooks: como utilizar

Os webhooks são uma ferramenta poderosa para integrar e automatizar processos no Bitrix24, permitindo que você receba notificações em tempo real sobre eventos específicos. Vamos explicar como configurar e utilizar Webhooks no Bitrix24, com base na documentação oficial, facilitando a comunicação entre o Bitrix24 e outros sistemas ou até entre ele mesmo.

1. Acesse Recursos do Desenvolvedor > Webhook de Entrada
   
2. Dê um nome ao webhook
   
3. Escolha o escopo e permissões
   
4. Use o Construtor de Solicitação para gerar exemplos
   

Após abrir a seção de webhook, você pode realizar as seguintes ações:

– Alterar o nome do webhook;
– Selecionar o método REST API no Construtor de solicitações (você pode ler a descrição do método e baixar um exemplo de código completo com os parâmetros necessários para executar as solicitações);

-Adicionar Parâmetros
– Verificar se o webhook está operacional, clicando em Executar;
– Atribuir permissões de acesso para módulos e ferramentas individuais do Bitrix24.

O Construtor de solicitações contém uma URL que deve ser usada ao enviar dados de um sistema externo de terceiros para o Bitrix24.

Você pode sempre contar com o auxílio da equipe Sapiens. Surgiu alguma dúvida? Nos chame no Whatsapp!

Dica: biblioteca oficial e exemplos

A Bitrix disponibiliza bibliotecas para PHP (Crest), JavaScript (BX24.js) e SDKs para aplicações em nuvem. Utilize para facilitar suas chamadas e lidar com autenticação de forma segura.

Materiais complementares

• Documentação oficial da API Bitrix24
• Curso Oficial de REST API da Bitrix24
• Ajuda on-line da API Bitrix
• Exemplos de webhooks para desenvolvedores
• Como desenvolver e consumir API do Bitrix24

Conclusão

A REST API do Bitrix24 é uma poderosa aliada para quem deseja automação e integração. Com as informações e exemplos deste guia, você está pronto para começar a criar soluções práticas e avançadas. E lembre-se: a equipe Sapiens está pronta para ajudar sempre que você precisar!

Vamos juntos acelerar seus processos e resultados!