SkillFoxx
Telegram

owners-registry-import: скилл загрузки реестра собственников в Битрикс24

ai-agent-bitrix24-portfolio

Скилл в Cursor и Claude Code загружает дома, помещения и собственников из CSV в смарт-процессы Битрикс24 с режимом «Только проверить»

  • 0 ★ репозитория
  • Последний коммит
  • MIT
Скилл

Широкий доступ

Почему такой уровень

  • Вебхук с правом `crm` позволяет записывать контакты, компании и элементы смарт-процессов, а запись затрагивает персональные данные собственников
  • Опечатка в коде поля остается незамеченной, пока не пройдена сверка `--check-fields`
Все причины и проверки
Российский стек

pavelpruss/ai-agent-bitrix24-portfolioАвтор:pavelpruss

Установка

Работает в
Сервисы

В терминале, через SkillFoxx CLI

npx skillfoxx add skills/ai-agent-bitrix24-portfolio

Определит агенты на машине, покажет уровень доступа и зафиксирует версию.

Другие способы установки

Доступ и проверки

Как мы проверяем

Широкий доступИнструмент может менять данные, выполнять команды или работать с секретами.

  • Вебхук с правом `crm` позволяет записывать контакты, компании и элементы смарт-процессов, а запись затрагивает персональные данные собственников
  • Опечатка в коде поля остается незамеченной, пока не пройдена сверка `--check-fields`

Это чужой код. Посмотрите файлы в репозитории перед установкой.

Что делает

Скилл `owners-registry-import` ведет агента по загрузке реестра в Битрикс24: из трех CSV-файлов (дома, помещения, собственники) создаются элементы смарт-процессов «Дома» и «Помещения», а собственники становятся контактами для физлиц и компаниями для юрлиц с привязкой к помещениям. Соответствие колонок и полей CRM лежит в `mapping.yaml`, коды полей агент не угадывает. Код на Python работает в трех режимах. `python -m owners_import --data <папка>` проверяет файлы и пишет отчет без обращений к порталу. С `--check-fields` читает поля портала, с `--apply` записывает данные по вебхуку и затем перечитывает элементы и сверяет их с планом. Повторный запуск того же файла ничего не создает заново. Данные в репозитории синтетические.

Для кого. Руководителям IT-проектов и администраторам Битрикс24 в управлении недвижимостью, которые заводят дома и собственников из реестров.

Подходит, если

  • Пришел реестр нового дома, и его надо завести в CRM по таблице соответствия полей
  • Файл перед загрузкой нужно проверить: суммы долей, помещения без собственников, несколько юрлиц на помещение
  • После загрузки данные оказались не в тех полях, и нужна сверка с порталом
  • Агенту в Cursor нужен образец файлов `AGENTS.md` и `CLAUDE.md` с правилами для работы с CRM

Не подходит, если

  • Нужна универсальная загрузка любых данных в Битрикс24: скилл заточен под дома, помещения и собственников
  • Исходник в Excel или выгрузке учетной системы: сначала его приводят к трем CSV отдельным шагом
  • Портал без смарт-процессов «Дома» и «Помещения»: коды и типы придется взять из `crm.type.list`

Пример запроса к агенту

Проверь папку data/sample перед загрузкой в Битрикс24 в режиме «Только проверить» и покажи таблицу «колонка, поле, пример»

Ограничения

Проект выложен как портфолио автора и показывает подход, готового продукта здесь нет: боевой код компании в репозиторий не входит, данные синтетические. Нужны Python и вебхук тестового портала с правом `crm`, значение хранится в `.env` как `B24_WEBHOOK_URL`. Таблицу полей надо сверить с реальным порталом, иначе Битрикс24 молча проигнорирует код с опечаткой. Автор сам называет себя не профессиональным программистом. Последний коммит в октябре 2026 года, звезд нет.

Как отключить. Удалите папку `skills/owners-registry-import` из проекта и отзовите вебхук портала. Загруженные элементы смарт-процессов остаются в CRM и удаляются вручную.

Частые вопросы

Можно ли сначала ничего не записывать?

Да. Запуск без флагов только проверяет файлы и пишет отчет в `reports/`, к порталу обращений нет.

Что делает `--apply`?

Записывает дома, помещения и собственников в портал, если в файлах нет ошибок. Затем элементы перечитываются и сверяются с планом.

Что с ошибками и предупреждениями?

Ошибки блокируют строку, а предупреждения не блокируют запись, но агент обязан показать их человеку. `--allow-partial` записывает только чистые строки по явному решению человека.

Не создаст ли повторный запуск дубли?

Нет. Элементы связываются по `xmlId` и `originId`, повторный запуск того же файла показывает, что создавать нечего.

Чем полезны `AGENTS.md` и `CLAUDE.md` в репозитории?

Это образец постоянного контекста для агента: роль, правила работы с CRM, определение «готово». Там же описана схема из семи файлов проекта.

Обсуждение

Вопросов и отзывов пока нет.

Битрикс24 — все инструменты
Российский стек

Скилл Битрикс24 REST с разбивкой по модулям, allowlist методов, подтверждением рискованных действий и аудит-логом

СкиллШирокий доступ26
Российский стек

Claude Code skill с проверенными на живом портале нюансами REST API Битрикс24: авторизация, ошибки под HTTP 200, ретраи и лимиты

СкиллМинимальный доступ
Российский стек

Скилл для администрирования, диагностики и разработки коробочного Битрикс24 и Bitrix Framework по официальной документации

СкиллРасширенный доступ1
Российский стек

Скилл и скрипт, которые дважды в неделю проверяют просроченные задачи Битрикс24, пингуют исполнителей и шлют сводку владельцу

СкиллРасширенный доступ

Коротко о README

Репозиторий представляет автора и его работу с агентами в Cursor, рассказывает про схему семи файлов, ошибку агента с полями CRM и содержит скилл с кодом загрузки, тесты и синтетические данные.

Бейдж для README

Исходный SKILL.md

---
name: owners-registry-import
description: Загрузка реестра домов, помещений и собственников (CSV) в Bitrix24 — смарт-процессы «Дома» и «Помещения», «Контакты» для физлиц и «Компании» для юрлиц, с привязкой к помещениям. Использовать, когда нужно завести новый дом в CRM из реестра, проверить реестр перед загрузкой или разобраться, почему данные легли не в те поля.
---

# Скилл: загрузка реестра собственников в Bitrix24

## Когда применять
- Пришел реестр по новому дому: дом, помещения, собственники.
- Нужно проверить файл до загрузки («Только проверить»).
- После загрузки что-то не сходится и нужна сверка с CRM.

## Входные данные
Папка с тремя CSV (UTF-8, первая строка — заголовки). Формат колонок — в [`mapping.yaml`](mapping.yaml):
- `houses.csv` — `house_id, address, cadastral_number, floors, year_built`
- `premises.csv` — `premise_id, house_id, number, premise_type, area`
- `owners.csv` — одна строка = «собственник ↔ помещение»: `owner_id, premise_id, owner_type (person|company), share, last_name, first_name, middle_name, company_name, inn, phone, email`

Если исходник в другом виде (Excel, выгрузка учетной системы), сначала приведи его к этим колонкам
отдельным шагом и покажи человеку 5 первых строк результата.

## Шаги
1. **Сверь таблицу полей.** Открой `mapping.yaml`. Если портал новый, получи реальные `entityTypeId`
   (`crm.type.list`) и коды полей (`crm.item.fields`) и обнови таблицу. Не угадывай коды полей.
2. **Только проверить:**
   ```bash
   python -m owners_import --data <папка>
   ```
   Ни одного запроса к порталу. Результат — `reports/report-*.md` и `.json`.
3. **Разбери отчет с человеком.** Ошибки (❌) блокируют строку. Предупреждения (⚠️) запись не блокируют,
   но их нужно показать человеку: суммы долей, помещения без собственников, несколько юрлиц на помещение.
   Попроси человека проверить таблицу «колонка → поле → пример значения».
4. **Сверка полей с порталом (только чтение):**
   ```bash
   python -m owners_import --data <папка> --check-fields
   ```
5. **Запись** — только после подтверждения человека:
   ```bash
   python -m owners_import --data <папка> --apply
   ```
   Если в файле есть ошибки, запись отменяется. `--allow-partial` записывает только чистые строки,
   используй его только по явному решению человека.
6. **Смоук-проверка** запускается автоматически после записи: элементы перечитываются из портала
   и сверяются с планом (поля, привязка помещения к дому, собственника к помещению).
   Повторный запуск того же файла должен показать «Создано: ничего».

Сообщить о проблеме