# Работа с инструментом (/ru/docs/b24/usage) Здесь объясняется, как устроена команда и как инструментом пользуется агент. Прочитайте это перед первой командой. ## Сначала профиль [#сначала-профиль] Профиль — имя, которое вы выбираете для одного аккаунта. Это первое слово каждой команды, которая работает с аккаунтом: ```sh b24 work config show ``` `B24_PROFILE=work` делает то же для одного сеанса оболочки. Профиль никогда не подставляется сам, даже единственный: команда без профиля останавливается с кодом выхода 2 и показывает профили на этом компьютере. ## Вход [#вход] Создайте в Битрикс24 входящий вебхук (Ресурсы для разработчиков → Другое → Входящий вебхук) с правами `crm`, `user_basic` (или `user`) и `department` и скопируйте его адрес. Без `user_basic` синхронизация не получит e-mail сотрудников, а без `department` не получит, кто кому подчиняется. Подробнее в разделе [Кто есть кто](#who-is-who). Затем: ```sh b24 work session start ``` `b24` спрашивает адрес, не показывая его, или читает его из stdin, проверяет на портале и сохраняет в системной связке ключей. `--credential-storage file` вместо этого хранит его в закрытом файле, для компьютера без связки ключей. `B24_TOKEN` с этим адресом используется раньше обоих. Адрес и есть пароль: любой, у кого он есть, может делать то же, что сотрудник вебхука. `b24 work session status --check` показывает сотрудника, от имени которого действует вебхук, и является ли он администратором. `b24 work session end` забывает адрес на этом компьютере; сам вебхук остается в Битрикс24, пока вы не удалите его там. `b24 session list` перечисляет профили на этом компьютере. ### Через локальное приложение [#через-локальное-приложение] Вебхук действует от имени сотрудника, который его создал. Локальное приложение действует от имени сотрудника, который входит через него. Его токены живут всего час, и `b24` сам их обновляет. Создает приложение один раз администратор Битрикс24 или сотрудник, которому это разрешено: 1. Разработчикам → Готовые сценарии → Другое → Локальное приложение. 2. Выберите вариант **Серверное**. В поле **Путь вашего обработчика** (Your handler path) укажите `https://wirecat.dev/webhooks/apps/b24-callback`. Поле **Путь для первоначальной установки** (Initial installation path) и тексты пункта меню оставьте пустыми, а флажок **Приложение само завершает установку** (Application completes the installation itself) не ставьте, тогда портал установит приложение при сохранении. 3. Отметьте права доступа `crm`, `user_basic` (или `user`) и `department` и сохраните. 4. Скопируйте **Код приложения (client_id)** и **Ключ приложения (client_secret)**, которые покажет Битрикс24. Затем войдите: ```sh b24 work session start --portal example.bitrix24.ru --client-id local.0123abcd.45678901 ``` `b24` спрашивает ключ, не показывая его, или читает его из stdin или `B24_BITRIX24_CLIENT_SECRET`, и открывает вход на портал в браузере. Когда вы разрешите приложению доступ, страница `wirecat.dev/webhooks/apps/b24-callback` передаст ответ `b24` на этом компьютере. Если браузер не может достучаться до `b24`, например при работе по SSH, вставьте в терминал адрес, на котором остановился браузер. После этого `session status` показывает `kind: app`. Если снова задать вебхук через `session start`, вход через приложение забудется, и наоборот. `session end` забывает токены на этом компьютере. Отозвать их Битрикс24 не дает, поэтому, чтобы они перестали работать, удалите приложение на портале. ## Синхронизация [#синхронизация] Сделки, лиды, воронки и стадии читаются из локального хранилища WireCat, того самого, в котором ищет каждый инструмент WireCat. `sync` обновляет его: ```sh b24 work sync # what changed since the last sync; everything on the first one b24 work sync --rescan # everything again, every id too b24 work store status # how far each kind is, and how many are stored ``` Синхронизация читает записи по времени их изменения, с перекрытием, поэтому запись, измененная во время запуска, придет снова в следующий раз. Раз в день она также перечисляет все id и помечает удаленными те, которых на портале больше нет; список, который пометил бы больше половины из них, откладывается, потому что вебхук, потерявший права, не выдает ни одного. Синхронизация останавливается до своего срока или `--max-pages`, а следующая продолжает с этого места. ### Чьи сделки и лиды [#чьи-сделки-и-лиды] Синхронизация копирует сделки и лиды тех пользователей Битрикс24, которых вы выбрали в `crm.bitrix24:.unassigned`, и клиентов из них. Никто не выбран за вас, даже пользователь самого вебхука, ведь вебхук часто принадлежит коллеге. Пока вы не выберете, синхронизация ничего не копирует и подсказывает, что сделать. Ни одна синхронизация не копирует всю CRM, даже у администратора. Остальных клиентов ищите на самом портале. ```sh b24 work users list # who is who on the portal b24 work config set crm.bitrix24:example.bitrix24.ru.unassigned 3327 # copy the deals and leads of user 3327 b24 work config set crm.bitrix24:example.bitrix24.ru.scope mine # the default; an old "all" is refused b24 work people list name:ivan* # any contact, read from the portal now ``` `example.bitrix24.ru` здесь означает адрес вашего портала. Вебхук администратора Битрикс24 может выбрать кого угодно. Вебхук любого другого сотрудника может выбрать только себя, уволенного пользователя или пользователя, который не сотрудник (экстранет, e-mail или бот, как говорит `USER_TYPE` Битрикс24). Синхронизация проверяет список каждый раз. Пользователь, которого брать нельзя, пропускается, причина пишется в `issues` (`crm.unassigned-dropped`), а его сделки и лиды уходят из копии. Вебхук без права `user` оставляет только своего пользователя. Заданный раньше `scope all` отклоняется при следующей синхронизации, и она подсказывает задать `mine`. После этого сделки и лиды невыбранных пользователей помечаются здесь удаленными. Ответ синхронизации называет `scope`, который она применила, и пользователя самого вебхука (`self`). Сделка, отданная невыбранному пользователю, уходит из локальной копии при следующей синхронизации, а сделка, отданная выбранному, появляется. Переход на `mine` помечает остальные удаленными здесь, только по копии, без запроса к порталу. Удаленные здесь значит, что они пропадают из списков и поиска, а их прежняя копия остается в файле хранилища. Если вы ни разу не задавали `scope`, а `mine` пометил бы удаленными больше половины сохраненных сделок или лидов, синхронизация оставляет их и сообщает об этом (`crm.narrowing-held`), пока вы не зададите `scope` равным `mine`. Задать `scope`, `self` и `unassigned` можете только вы, агенту откажут. При `mine` синхронизация копирует только ваших клиентов: контакты и компании, назначенные вам или пользователю из списка неназначенных, и те, что указаны в копируемых сделках и лидах. Остальная клиентская база остается на портале. Копия одного портала принадлежит одному пользователю. Первая синхронизация запоминает пользователя вебхука как `crm.bitrix24:.self`. Синхронизация через вебхук другого пользователя отклоняется, а `b24 work config unset crm.bitrix24:example.bitrix24.ru.self` передает копию следующему. ### Кто есть кто [#кто-есть-кто] Синхронизация также сохраняет, кто к чему относится, в виде связей между людьми, организациями и сделками. Каждый инструмент WireCat читает их из того же хранилища. | В Битрикс24 | В хранилище | |---|---| | Компания | Организация. Компания с таким же названием в другом месте остается отдельной организацией. | | Ваши компании ("Мои компании") | Организации, отмеченные как ваши, читаются при каждой синхронизации. | | Контакт | Человек. С уже известным человеком он объединяется только по тому же адресу e-mail. | | Компании контакта | Человек состоит в каждой из них с ролью `contact`. Первая компания главная. Должность (`post`) хранится рядом, но не как роль. | | Контакты сделки или лида | Люди в сделке с ролью `contact`. Главный контакт отмечен. | | Ответственный за сделку или лид | `owner` сделки. | | Сотрудник (пользователь портала) | Человек, член вашей компании с ролью `employee`. У ушедшего сотрудника человек остается, а членство заканчивается. | | Руководитель отдела | Каждый сотрудник подчиняется руководителю своего отдела, а руководитель подчиняется руководителю вышестоящего отдела. | | Лид, ставший сделкой | Лид указывает на свою сделку. | Битрикс24 говорит не все, поэтому некоторые связи можете задать только вы: - Роль контакта в сделке (принимает решение, влияет). Битрикс24 не хранит роль контакта сделки. - Кому подчиняется контакт. Подчинение в Битрикс24 есть только между его собственными сотрудниками. - Головная компания. В Битрикс24 нет для нее поля. - Когда связь началась или закончилась. Битрикс24 не дает дат. Связь, которую сохранила синхронизация, имеет статус `reported`: так говорит Битрикс24, а вы ее не подтвердили. Она учитывается в каждом ответе. Когда Битрикс24 перестает ее показывать, например контакт уходит из компании, синхронизация ее завершает. Связь остается с датой окончания и никогда не удаляется. Связь, которую вы создали или подтвердили, синхронизация никогда не меняет. Если вы удалили связь, синхронизация не запишет ее снова. Чтобы новые связи сначала ждали вашей проверки, задайте настройке аккаунта `links` значение `review`. Аккаунт называется `bitrix24:` и адрес вашего портала: ```sh b24 work config set crm.bitrix24:example.bitrix24.com.links review ``` Тип компании, например `CUSTOMER`, сам по себе ничего не значит, ведь администратор может переименовать типы или добавить новые. Скажите, что значит тип, и следующая синхронизация сделает каждую компанию этого типа клиентом вашей компании, ее поставщиком или партнером: ```sh b24 work config set crm.bitrix24:example.bitrix24.com.company-types CUSTOMER=customer-of,SUPPLIER=supplier ``` Если у вебхука нет права `user` или `department`, синхронизация читает остальное и пишет в `issues`, что прочитать не удалось. Ничего из сохраненного раньше из-за этого не завершается. Без `user_basic` сотрудники приходят без адресов e-mail, поэтому сотрудник не объединяется с тем же человеком в вашей почте. Если портал не отдает ваши компании, сотрудники остаются без компании. Эти два пробела синхронизация хранит как пробелы аккаунта, которые называют ответы memo, а не в `issues`. ### Держать копию свежей [#держать-копию-свежей] `schedule` ставит таймер (пользовательский таймер systemd в Linux, агент launchd в macOS, задачу Планировщика заданий в Windows), который сам запускает `sync`: ```sh b24 work schedule command crm --every 1h -- sync b24 work schedule list # the schedule and how its last run went b24 work schedule remove crm ``` ### Спросить memo о клиенте [#спросить-memo-о-клиенте] Из связей, которые сохраняет синхронизация, отвечает `memo`. Этим командам нужна версия `memo`, в которой они есть, и она еще не вышла: ```sh memo context person:12 # a person's companies, deals and reporting lines, with what was not read memo organizations context organization:4 # a company's people, deals and open work memo deals context deal:7 --brief # a deal's people with their parts, its owner and stage ``` ## Чтение [#чтение] ```sh b24 work deals list status:open # open, won or lost b24 work deals list stage:"Quote sent" pipeline:Sales b24 work leads list --json b24 work deals show deal:12 # by the ref a list prints b24 work pipelines show Sales # its funnel: how many reached each stage b24 work stages list kind:lead # each stage with its outcome: open, won or lost b24 work people show "Anna Ivanova" # contacts and companies by id, or by the exact name ``` `deals`, `leads`, `pipelines` и `stages` — общие CRM-команды WireCat: те же слова, запрос и ответ в каждом CRM-инструменте. Сделка или лид отвечает своими `pipeline`, `stage`, `status`, `close_date` и `amount` как десятичным числом в своей `currency`; `--offline` читает то же самое. У лидов в Битрикс24 нет воронок, поэтому они стоят в одной воронке с именем `Leads`. `people` и `organizations` читают сам портал. Их `show` выдает собственные поля портала в `provider_metadata`, каждое по коду с подписью; поле-список выдает подпись своего варианта, а id варианта — как `option_id`. `b24 work fields list deals` перечисляет эти поля с их типом и вариантами, как их сохранил последний `sync`; `leads`, `people` и `organizations` работают так же. Их списки тоже фильтруют по этим полям, по коду или подписи, если портал умеет по ним фильтровать, а `--json` может их добавить: ```sh b24 work organizations list industry:IT b24 work organizations list --json=id,name,provider_metadata.UF_CRM_1745512486047 ``` Список показывает сначала самые новые: это меняют `--limit`, `--page` и, для `people` и `organizations`, `--all`. Поля, по которым список может фильтровать, перечислены в его справке, `b24 help deals list`. Телефоны и e-mail видны только у ваших клиентов, если вы не администратор Битрикс24. Ваши клиенты это контакты и компании, назначенные вам, и те, что указаны в ваших сделках и лидах. У всех остальных список показывает их без телефонов и e-mail. `people show` или `organizations show` одного не вашего клиента выдает их, но не больше 100 таких контактов и компаний в день (по UTC) на вас и ваших агентов вместе. Повторный показ того же клиента в тот же день не считается, а ваши собственные клиенты не считаются никогда. Счетчик хранится на этом компьютере, поэтому он защищает от случайности и от агента, но не от того, кто намерен забрать базу. Для этого есть права доступа самого Битрикс24. ## Запись [#запись] ```sh b24 work deals create --title "Kitchen for Example" --pipeline Sales --amount 15000 --currency EUR b24 work deals update deal:12 --amount 18000 --close-date 2026-12-24 b24 work deals move deal:12 "Contract signed" b24 work deals close deal:12 won b24 work deals delete deal:12 # asks first b24 work leads update lead:7 --field UF_CRM_SOURCE=Website b24 work people create --first-name Anna --last-name Ivanova b24 work organizations update 9 --field "Lead source=Fair" --body '{"revenue":1000}' ``` Запись сделки или лида отправляет один запрос, затем читает запись обратно в хранилище. `--stage` принимает стадию собственной воронки записи по имени или id и проверяет еще и ключ `move`; стадия успеха или провала проверяет также ключ `close`. `close` переводит запись на первую стадию успеха или провала ее воронки. `--field