API do Bitrix24: como fazer a primeira chamada REST

Publicado por Jardel Cunha · Atualizado em 18/09/2026

Resposta direta: o caminho mais curto até a primeira chamada

A primeira chamada à API do Bitrix24 sai de um webhook de entrada, criado dentro da própria conta. No menu lateral, abra Aplicativos e depois Recursos para desenvolvedores, escolha o webhook de entrada, selecione o método, atribua as permissões de acesso e clique em Executar para ver o resultado (helpdesk oficial).

O código desse webhook é uma das duas formas de autorização aceitas pela API REST. A documentação de autorização descreve as duas: “Specifying a permanent inbound local webhook code” e “Specifying a temporary OAuth 2.0 authorization token, which is used in local and mass-market applications”, ou seja, um código permanente de webhook de entrada ou um token temporário de OAuth 2.0 usado por aplicativos.

A documentação da primeira chamada descreve o mesmo caminho com outros rótulos: “In the Bitrix24 left menu, open the Applications > Developer resources section. Go to the Common use cases > Other > Inbound webhook tab.” Este guia usa os dois nomes lado a lado, porque a tela em pt-BR e a referência em inglês não coincidem.

Antes de começar: o que a conta precisa ter

O acesso contínuo à API REST na nuvem depende da linha de planos. A página oficial de acesso à API registra: “For ongoing REST API access in Bitrix24 Cloud, choose a paid plan in the Vibe+ lineup. The Essentials lineup does not include REST API access.” (verificado em 17/09/2026).

Para desenvolver antes de contratar, a mesma página informa um teste gratuito de 15 dias do plano Professional Vibe+, que inclui acesso à API REST para testes e desenvolvimento e “can be activated only once”, ou seja, pode ser ativado uma única vez.

A comparação entre os caminhos de integração e o requisito de plano de cada um está nos caminhos oficiais para integrar o Bitrix24. Aqui o assunto é a execução: a partir do momento em que a conta tem acesso, o que fazer para a primeira chamada responder.

Webhook de entrada, aplicativo local ou OAuth 2.0: como escolher

A decisão vem antes do código, porque muda quem mantém a integração e o que acontece quando a pessoa que a criou sai da empresa.

Forma	O que resolve	Quando não serve	O que exige de quem mantém
Webhook de entrada	Import e export pontual, integração simples com sistemas internos e externos (ERP, controle de ponto, monitoramento) e automação de leads e negócios em regras do CRM (autorização)	Métodos que só funcionam no contexto de aplicativo, que devolvem WRONG_AUTH_TYPE (escopos e permissões)	Guardar a chave secreta, controlar a data de expiração e acompanhar as permissões de quem o criou
Aplicativo local	Interface dentro do Bitrix24 e métodos de contexto de aplicativo, com token temporário de OAuth 2.0 (autorização)	Teste rápido de um método, porque exige registro do aplicativo	Criação restrita: “Somente administradores de contas Bitrix24 podem criar aplicativos” (helpdesk)
OAuth 2.0 em aplicativo de mercado	Solução instalada em várias contas do Bitrix24 (autorização)	Integração de uso interno de uma conta só	Renovação de token e ciclo de publicação da solução

O detalhe que costuma passar batido é a validade. A documentação de webhooks informa que “the inbound webhook mechanism supports an expiration date. If the expiration date has passed, the request stops working and returns an authorization error”. Uma integração que funcionou meses pode parar por data, não por código.

O funcionamento do webhook de entrada e de saída no Bitrix24, incluindo o que acontece quando o evento não chega ao seu servidor, é assunto de um guia próprio.

Passo a passo: criando o webhook de entrada

Cada passo abaixo tem um resultado observável na tela. Os rótulos em português vêm do helpdesk oficial (artigo atualizado em 25 de julho de 2025) e os equivalentes em inglês, da documentação da primeira chamada.

1. Abra Aplicativos > Recursos para desenvolvedores no menu lateral (na documentação em inglês, Applications > Developer resources). A tela lista as opções de integração da conta.
2. Vá para a guia Casos de uso comum (Common use cases), onde, segundo o helpdesk, “há exemplos de cenários populares para a criação de webhooks”. Se o seu caso não estiver na lista, siga para Outro (Other).
3. Escolha Webhook de entrada (Inbound webhook). O Bitrix24 abre o formulário com o campo do método e a lista de permissões.
4. Selecione o método que a integração vai chamar, por exemplo crm.item.list ou crm.lead.add. O método escolhido aparece montado na URL do webhook.
5. Atribua as permissões. A instrução oficial é direta: “Decida quais ferramentas do Bitrix24 podem ser acessadas com seu webhook.” Só marque o que a integração usa.
6. Execute e confira o resultado. “Para verificar sua solicitação, clique em Executar e visualize o resultado.” A resposta vem em JSON na própria tela, o que separa erro de autorização de erro de parâmetro antes de qualquer linha de código.
7. Salve e guarde a chave em local seguro. A chave é do criador do webhook, e quem a tem acessa os dados da conta.

Como a URL da chamada é montada, parte por parte

A URL segue sempre o mesmo desenho: https://{conta}.bitrix24.com.br/rest/{id do usuário}/{chave secreta}/{método}.json?{parâmetros}. O helpdesk destrincha cada trecho.

Trecho	O que é, segundo a fonte oficial
/rest	“mostra que a operação é realizada via REST com webhooks”
/325	“este é o ID do usuário que criou o webhook”
/88u**********4qx	“esta é a chave secreta. Usando esta chave, você pode visualizar, editar e excluir dados no Bitrix24”
/crm.lead.update	“este é o método REST API que está sendo chamado”
.json	formato da resposta

Parâmetros em array seguem a notação de colchetes da própria documentação, como fields[TITLE]=Novo lead. A chave aparece mascarada com asteriscos nos exemplos oficiais, e é assim que ela deve circular: nunca inteira em repositório, ticket ou mensagem.

A consequência de segurança está na mesma frase oficial. Quem tem a chave visualiza, edita e exclui dados no Bitrix24, sem senha de usuário. Trate a URL completa como credencial.

Escopos: o que o webhook pode chamar

Escopo é o conjunto de ferramentas que o webhook pode acessar, definido na hora de atribuir as permissões. Alguns códigos reais da tabela oficial de escopos: crm, tasks, calendar, telephony, bizproc e biconnector.

Se o método está fora do escopo concedido, a plataforma nem executa: “If an application or a webhook calls a method whose scope has not been granted, Bitrix24 returns the insufficient_scope error and does not execute the request.”

Existe um segundo caso, em que o escopo está correto e a chamada mesmo assim falha. A mesma página explica: “Some methods work only in the application context. When a webhook calls such a method, Bitrix24 returns the WRONG_AUTH_TYPE error with the Application context required description. The placement.bind method behaves this way, for example.” Quando isso aparece, a solução não é ampliar o escopo, e sim trocar o webhook por um aplicativo.

Testar rápido pelo navegador, e por que não deixar assim

Colar a URL na barra de endereços funciona, e a documentação de webhooks reconhece o uso: “GET is suitable for quick tests of simple requests”. O problema é o rastro, porque “the webhook URL can be retained in browser history, logs, and monitoring services”, e essa URL contém a chave secreta.

A orientação oficial para produção é outra: “for production integrations, nested parameters, files, and data changes, use a POST request”. Teste com GET, publique com POST e troque o webhook se a URL de teste circulou.

batch: até 50 chamadas em uma requisição

Quando a integração precisa criar ou ler muitos registros, o método batch agrupa chamadas. A documentação do batch fixa o teto: “A single batch contains no more than 50 subqueries.” O escopo é basic e qualquer usuário pode executar o método.

Duas regras evitam retrabalho. A primeira: “Nesting is prohibited: you cannot call another batch inside batch.” A segunda é o comportamento que quebra integração em produção sem aparecer no monitoramento.

Erro de subchamada não vem com status de erro. A página de códigos de erro avisa: “Recognize an error by the set of fields in the response body, not by the HTTP status: subquery errors of a batch request arrive with status 200.” O campo a ler é o result.result_error, que “is always present in a batch response: in a successful batch it arrives empty”, e devolve o erro “under the same key the command was passed with in the request”.

Uma rotina que só verifica HTTP 200 registra sucesso em subchamadas que falharam. A verificação precisa entrar no corpo da resposta.

Limites que aparecem quando o volume cresce

Os limites da nuvem estão publicados na página de limites da API, verificada em 17/09/2026.

Limite	Valor oficial	O que acontece ao estourar
Tempo por requisição	“one REST request must finish within 60 seconds” na nuvem	a requisição é interrompida por timeout
Intensidade (Enterprise)	“5 per sec” com limite de 250 antes do bloqueio	próxima requisição bloqueada com status 503 e QUERY_LIMIT_EXCEEDED
Intensidade (demais planos)	“2 per sec” com limite de 50 antes do bloqueio	mesmo bloqueio com 503 e QUERY_LIMIT_EXCEEDED
Tempo acumulado por método	contado “in 10 one-minute baskets”	chamada seguinte ao método bloqueada com status 429 e OPERATION_TIME_LIMIT

A própria documentação transforma a intensidade em volume diário: “At an intensity of 2 requests per second, 172,800 requests can be performed per day.” Esse é o número a usar no dimensionamento, junto com a página padrão de 50 registros que a maioria dos métodos de listagem devolve.

Sobre a linha Vibe+, páginas oficiais trazem informações diferentes: a tabela da nova linha de planos traz “REST API … Ilimitada … sem limites de requisições” (helpdesk da nova linha de planos, verificado em 17/09/2026), enquanto a página de limites mantém os valores por plano acima.

A divergência já está registrada com as duas fontes no guia sobre o requisito de plano de cada caminho de integração, e o encaminhamento é o mesmo: confirmar com o suporte da Bitrix24 antes de dimensionar volume.

Quando a chamada volta com erro: o que fazer em cada código

Antes da tabela, a regra que a documentação coloca em primeiro lugar: “Branch on the code from the error field, not on the text from error_description.” O texto muda de idioma e de redação; o código, não.

Código	Status	O que significa	Ação
NO_AUTH_FOUND	401	“Wrong authorization data”	conferir se a URL completa, com ID de usuário e chave, chegou íntegra na requisição
INVALID_REQUEST	401	“Https required”	trocar a chamada para HTTPS
INVALID_CREDENTIALS	401	“No active webhook with the specified user identifier and secret code was found”	verificar se o webhook existe, não expirou e pertence ao usuário informado
ERROR_METHOD_NOT_FOUND	404	método não encontrado	conferir a grafia do método e se ele existe na versão da nuvem
insufficient_scope	recusa da chamada	método fora do escopo concedido	incluir o escopo do método nas permissões do webhook
WRONG_AUTH_TYPE	recusa da chamada	“Application context required”	trocar o webhook por aplicativo local ou OAuth 2.0
QUERY_LIMIT_EXCEEDED	503	contador de intensidade acima do limite do plano	espaçar as chamadas e agrupar com batch
OPERATION_TIME_LIMIT	429	tempo acumulado do método acima do limite	reduzir a frequência daquele método específico e revisar filtros

Fontes dos códigos: página de códigos de erro, escopos e permissões e limites da API, todas verificadas em 17/09/2026.

O que registrar no log, e o que nunca registrar

A documentação de erros define os dois lados em uma frase: “Write error, error_description, the HTTP status, and the name of the called method to the integration log.”

E o que fica de fora: “Do not write authorization data, tokens and webhook codes, to the log: they give access to Bitrix24 data.” Log de integração costuma ser lido por mais gente do que a conta do Bitrix24, e é o lugar mais comum de vazamento de chave.

Checklist antes de colocar a integração em produção

A documentação de webhooks publica quatro verificações, e a operação da conta acrescenta outras três.

1. O método está disponível para o escopo selecionado.
2. O colaborador que criou o webhook tem permissão sobre o objeto que a integração manipula.
3. A conta tem acesso à API REST na linha de planos contratada.
4. As requisições saem por HTTPS.
5. A data de expiração do webhook está anotada com um responsável, porque, passada a data, a requisição para de funcionar e devolve erro de autorização.
6. Alguém tem acesso às estatísticas de carga. O helpdesk indica a guia Estatísticas “para visualizar o número de solicitações para cada webhook e aplicativo”, com duas ressalvas: “o período máximo para visualização das estatísticas é de 14 dias” e “somente administradores podem acessar a seção de estatísticas de carga REST”.
7. A leitura de erro entra no corpo da resposta, e não só no status HTTP.

Se a integração vai conversar com um ERP, os riscos de desenho de uma integração com ERP entram antes deste checklist, porque mudam o desenho e não só a configuração.

Perguntas frequentes

Como posso usar uma API?

No Bitrix24, o caminho mais curto é criar um webhook de entrada em Aplicativos > Recursos para desenvolvedores, escolher o método, atribuir as permissões e executar pela própria tela. O webhook devolve uma URL com chave secreta que autoriza cada chamada, sem exigir registro de aplicativo nem token temporário de OAuth 2.0.

Qual é o limite de requisições da API do Bitrix24?

A página de limites traz intensidade de “5 per sec” com bloqueio em 250 no Enterprise e “2 per sec” com bloqueio em 50 nos demais planos, além de 60 segundos por requisição. A própria documentação calcula 172.800 requisições por dia a 2 por segundo (verificado em 17/09/2026).

Próximo passo

Com a primeira chamada respondendo, o trabalho seguinte é o desenho: quem cria o webhook, quais escopos ficam ativos e como a operação percebe uma falha. A decisão anterior a essa, entre app do Market, iPaaS, API REST e servidor MCP, está no guia do pilar.

A Tiqtech é parceira Bitrix24 e desenha integrações junto com equipes internas de TI: veja como funciona a implantação do Bitrix24 com a Tiqtech ou falar com a Tiqtech sobre a sua integração.