bitrix24-for-ai-agents: a skill for safe work with a Bitrix24 portal

---
name: bitrix24-for-ai-agents
description: Método completo para um agente de IA ler, modificar e configurar um portal Bitrix24 com segurança. Cobre conectar pela API REST (webhook de entrada), consultar e exportar Leads, Negócios, Contatos, Empresas, Smart Processes (SPA), atividades, linha do tempo, tarefas e ligações; alterar registros um a um ou em lote, com backup e confirmação; configurar funis, etapas, campos, regras de automação, processos de negócio e integrações (n8n, webhooks); montar painéis no BI Builder; e entender o que muda para a API nos planos Essentials e Vibe+. Use sempre que o usuário falar de Bitrix24, Bitrix, B24, um portal bitrix24.com.br ou .com, webhook do Bitrix, BI Builder, Smart Process, funil, Kanban de Leads, robô, regra de automação ou processo de negócio, ou pedir para ler, exportar, auditar, corrigir, mover, atualizar em massa, limpar, migrar ou configurar dados e processos do CRM, mesmo que não diga "API".
license: "CC BY 4.0. Uso livre, inclusive comercial, com crédito obrigatório a João Paulo, Atlaas Tecnologia (atlaas.com.br). Texto completo em LICENSE.txt."
metadata:
  author: "João Paulo, Atlaas Tecnologia"
  site: "https://atlaas.com.br"
  version: "1.0.0"
---

# Bitrix24 para agentes de IA

O Bitrix24 aceita quase tudo pela API REST, e é por isso que um agente pode causar estrago rápido: mudar a etapa de 2 mil negócios dispara 2 mil vezes as automações daquela etapa, e algumas mandam mensagem ao cliente. Esta skill dá o método para trabalhar num portal de verdade como um consultor experiente trabalharia: primeiro entende, depois mostra o que vai mudar, faz backup, testa em um registro e só então mexe no resto.

Ela serve para qualquer portal e qualquer segmento. Os exemplos usam nomes genéricos.

## As regras que não mudam

1. **Ler antes de mexer.** Todo trabalho começa só com leitura: o mapa do portal, os registros envolvidos e as automações da etapa. Evidência antes de opinião. Quem muda dado sem entender o processo quebra a operação de alguém.
2. **Nada muda sem o usuário ver e confirmar.** Antes de qualquer escrita, mostre o plano: o que muda, em quantos registros, com que valor, e o que pode disparar junto. Só depois do "pode" o script roda com `--confirmar`. O script bloqueia sozinho todo método que não seja de leitura.
3. **Excluir é a última opção.** A documentação não garante que a exclusão pela API passe pela lixeira. Prefira mover para uma etapa de encerramento, marcar um campo ou arquivar. Excluir só com pedido explícito e com backup, e o script pede uma segunda confirmação (`--confirmar-exclusao`).
4. **Mudar etapa é mais do que mudar um campo.** As regras de automação e os processos de negócio da etapa rodam também quando a mudança vem da API: mandam e-mail ou WhatsApp, criam tarefa, trocam o responsável. Levar o card para uma etapa de perda ou converter o Lead fecha sozinho as atividades abertas. Leia as automações da etapa antes de mover (references/ler.md, seção 7).
5. **O webhook é uma senha.** Ele age com as permissões de quem o criou. Fica numa variável de ambiente (`BITRIX24_WEBHOOK`), nunca no chat, num arquivo versionado ou numa nota. Peça só os escopos que a tarefa precisa.
6. **Respeite o limite do portal.** No máximo 2 chamadas por segundo, lotes de até 50 comandos e espera quando o portal reclamar. Volume grande vai por script ou por automação externa, e não chamada por chamada na conversa.
7. **O dado é do cliente do usuário.** Nome, telefone e valor de negociação não saem do portal sem necessidade. Não copie para outro lugar além do que a tarefa pede.

## Primeiro passo em qualquer portal

1. **Conectar.** Rode `python3 scripts/b24.py ping`. Ele mostra o usuário do webhook, os escopos e a hora do servidor.
   - **Sem webhook:** explique como criar um, em 4 linhas (references/acesso.md, seção 1).
   - **"REST is available only by subscription" ou "only on commercial plans":** o portal está num plano sem API REST: o Essentials, desde 2026, ou o gratuito. Só o Vibe+ tem. Diga isso ao usuário com os caminhos possíveis (references/planos-e-licencas.md, seção 2).
   - **Plano mensal ou trimestral que ainda tem API:** pode perdê-la em 30/11/2026, se não migrar. Avise antes de construir qualquer integração.
2. **Fazer o mapa do portal,** só leitura. Ele inclui funis, etapas, campos personalizados, Smart Processes, usuários e departamentos.
   - **Pergunta simples de leitura:** o mapa mínimo da entidade em questão basta.
   - **Antes de modificar ou configurar:** o mapa completo.

   A sequência de chamadas e onde guardar estão em references/ler.md, seção 2. Use os nomes e os IDs do mapa, sem adivinhar.
3. **Entender o pedido em termos do portal:** qual entidade, qual funil, quais etapas e quais campos.
   - Se faltar uma informação que muda o resultado, pergunte uma coisa só, com uma sugestão.
   - Se dá para seguir com um padrão razoável, siga e diga qual padrão usou.
   - Num projeto de configuração, junte as decisões numa lista numerada, cada uma com uma sugestão.

## Os três modos de trabalho

### Ler: consultar, exportar, auditar

Use quando o pedido é saber, contar, listar, exportar ou diagnosticar.
- **Lista grande:** `b24.py list METODO PARAMS --saida arquivo.jsonl`, e `--por-id` acima de alguns milhares de registros.
- **Muitas consultas pequenas:** `b24.py batch`.
- **Receitas** (quem está parado, o que mudou de etapa, quantos por responsável, duplicados, ligações, histórico) em references/ler.md.
- **O modelo de dados** (entityTypeId, etapas, campos, multicampos) em references/modelo-de-dados.md. Leia antes da primeira consulta num portal novo.
  - A documentação recomenda a API universal (`crm.item.*`, campos em camelCase).
  - A antiga (`crm.lead.*`, `crm.deal.*`, campos em MAIÚSCULAS) está obsoleta, mas funciona e aparece em quase todo fluxo existente.
  - Não misture os nomes de campo das duas.
- **Entrega:**
  - o número com o filtro usado, dito em palavras;
  - o link dos registros (`https://PORTAL/crm/lead/details/ID/`);
  - o que ficou de fora e por quê.

### Modificar: corrigir, mover, atualizar em lote