# Как собирать чеки и авансовые отчёты сотрудников в чате

> Сценарий Пачки. Сотрудник отправляет чек боту «Расходы», карточка расхода приходит в беседу «Расходы сотрудников», бухгалтер принимает её кнопкой. В конце месяца бот собирает авансовые отчёты и отправляет их на подписание.

> Это Markdown-версия страницы https://pachca.com/scenarios/avansovye-otchety для ИИ-агентов. Методы API, которые здесь названы, описаны в https://dev.pachca.com/llms.txt — открой его, прежде чем вызывать API. Остальные сценарии — в https://pachca.com/llms.txt.

## Что получится

1. Сотрудник пишет боту `/start`. Бот отвечает кнопкой «Добавить расход» и открывает форму с чеком.
2. Карточка расхода приходит в беседу «Расходы сотрудников» с кнопками «Принять» и «Уточнить».
3. Бот пишет сотруднику в личку, что расход принят и с какой зарплатой придёт компенсация.
4. В последний рабочий день месяца обработчик собирает принятые расходы по сотрудникам в отчёты из docx-шаблона и кладёт файлы в тред.

Форму, карточку и отчёты делает обработчик событий бота. Есть три варианта:

- А. Без обработчика: чеки в беседу по шаблону. Формы и кнопок нет.
- Б. Без кода через n8n.
- В. Свой код: форма, отчёты, отправка в КЭДО, реестр выплат в 1С.

## Что нужно до начала

- Доступ к Пачке от имени администратора или владельца пространства со скоупами `chats:create`, `chat_members:write`, `group_tags:read`, `group_tags:write`, `bots:write`, `messages:create`, `pins:write`. Для шагов настройки и проверки нужны ещё `search:users`, `messages:read`. Вход описан в правилах ниже.
- Для варианта Б — n8n с узлом Пачки: https://pachca.com/help-center/integrations/avtomatizacii-v-pachke-s-pomoshchyu-n8n
- docx-шаблон авансового отчёта, согласованный с бухгалтером.

## Если ты ИИ-агент: правила работы

### Кто что делает

- Всё, для чего в инструкции назван метод API, делаешь ты. Не проси пользователя создать беседу, бота или сообщение руками.
- Пользователя проси только о входе в Пачку и о том, что есть в разделе «Попроси пользователя сделать руками».
- Если терминала у тебя нет, скажи об этом сразу и не делай вид, что настроил. Проведи пользователя по шагам для человека со страницы сценария и помоги с шаблоном или кодом обработчика.

### Как говорить с пользователем

- Пользователь не разработчик. Пиши коротко и простыми словами. Не называй методы API, скоупы, коды ответов, `id` и профили CLI. Вместо «скоупы» говори «права», вместо «обработчик» — «программа, которая отвечает за бота».
- О своих проверках не рассказывай. В сообщении только три вещи: что уже готово, что нужно от пользователя, что ты сделаешь дальше.
- Не спрашивай то, что можешь узнать сам через API или что легко поменять позже. Возьми значение из инструкции и назови его.
- Тексты сообщений бота бери из инструкции или напиши сам и продолжай. Покажи их в итоговом сообщении и предложи поменять. Подтверждения не жди.
- Вопросы из раздела «Спроси у пользователя» задавай теми же словами.

### Первое сообщение пользователю

Оно состоит из трёх частей. Первые две вместе занимают не больше пяти строк.

1. Что получится: одна-две строки.
2. Что ты создашь сам: беседа, бот, сообщения с названиями из инструкции. То, что зависит от выбора пользователя, называй условно: «если выберете бота, создам ещё…».
3. «От вас нужно»: вход в Пачку, если его ещё нет, и вопросы из раздела «Спроси у пользователя». Если сценарию или одному из вариантов нужен n8n, здесь же спроси, есть ли он у пользователя, и сразу попроси доступ словами из раздела «n8n» ниже: «если n8n есть, пришлите…».

Если часть результата появится только после ручного шага пользователя, скажи об этом одной строкой: «вопросы ретро по расписанию настроите сами, я подскажу как».

Ответ пользователя на вопросы — это согласие с планом. После него настраивай сразу, второго подтверждения не проси.

### Доступ к Пачке

- Токен выпускать и присылать в чат не нужно. Перед первым сообщением проверь вход: `npx -y @pachca/cli@latest auth status`. Если входа нет, попроси пользователя выполнить в своём терминале `npx -y @pachca/cli@latest auth login`. CLI покажет код, пользователь введёт его в браузере и подтвердит доступ. Пиши команды с `@latest`: без него может запуститься старая версия CLI из кэша, она вместо входа через браузер просит вставить токен.
- Права такого входа равны правам роли пользователя. Сам сверь их со скоупами из раздела «Что нужно до начала»: скоупы показывает `npx -y @pachca/cli@latest api GET /oauth/token/info`. Если прав не хватает, скажи простыми словами, чего ты не сможешь сделать, например «не смогу отправлять сообщения». Путей два: добавить это право токену в Пачке, в разделе «Автоматизации» → «API», или войти заново под владельцем или администратором пространства.
- Если `auth status` показывает `scopes: null`, это не значит, что прав нет: смотри `GET /oauth/token/info`. Для проверок из этих правил нужны ещё `search:chats`, `bots:read` и `profile:read`.
- Когда пользователь говорит «я», это владелец входа. Его `id` и ник отдаёт `GET /profile`.
- API вызывай через `npx -y @pachca/cli@latest api <МЕТОД> <путь> -o json`. Команду пиши целиком в каждом вызове, в переменную оболочки её не клади.
- Параметры запроса передавай как `--query ключ=значение`, например `--query query=Закупки`. Параметр без ключа CLI молча отбрасывает и возвращает весь список: легко решить, что нужная беседа уже есть.
- Тело запроса передавай через `--data` или `--input`. Почти у каждого метода записи тело обёрнуто в объект: `chat` у `POST /chats`, `message` у `POST /messages`, `task` у `POST /tasks`, `group_tag` у `POST /group_tags`, `user` у `PUT /users/{id}`, `webhook` у ботов. Обёртку показывает `--describe`, путь в нём пиши с `{id}`, а не с числом. Без обёртки `POST /chats` создаст беседу, но молча не добавит участников.
- Токены и адреса входящих вебхуков ботов в чат не выводи. Токен бота показывают один раз, при создании: сохрани его в файл.

### n8n

- Если n8n у пользователя нет, скажи, что его берут в облаке n8n Cloud или ставят на свой сервер, и дай ссылку на установку узлов Пачки: https://dev.pachca.com/guides/n8n/setup.md. Как ставить n8n, эта инструкция не описывает. Если в ней есть вариант без n8n, предложи начать с него, а к боту вернуться, когда n8n появится.
- Если n8n есть, попроси доступ к нему этими словами: «Пришлите адрес вашего n8n: ссылку, по которой вы открываете его в браузере. Ключ в чат не присылайте. В n8n откройте Settings → n8n API → Create an API key и скопируйте ключ. Сразу после этого выполните в терминале команду ниже как есть, вписывать в неё ничего не нужно. Она сохранит скопированный ключ в файл, на экране ничего не появится. Потом напишите мне „ключ сохранил“». Команда для macOS: `pbpaste > ~/n8n-key.txt`. Для другой системы подбери свою.
- Всё, что собираешь в n8n, делай на официальных узлах Пачки `n8n-nodes-pachca`. Узел `HTTP Request` для вызовов API Пачки не бери.

### Настройка

- Методы API бери из https://dev.pachca.com/llms.txt, на память не полагайся. Схему метода показывает команда `npx -y @pachca/cli@latest api <МЕТОД> <путь> --describe`.
- Порядок вызовов и разбор ошибок для чатов, ботов и форм есть в скиллах Пачки: `npx skills add pachca/openapi`. Ставь их, когда понадобятся, пользователя об этом не спрашивай.
- Перед созданием проверь, нет ли уже такой беседы и такого бота: `GET /search/chats`, `GET /bots`. Если есть, спроси, настраивать их или создать новые.
- `POST /group_tags` создаёт пустой тег. Сотруднику его назначает `PUT /users/{id}` с `list_tags`, нужен скоуп `users:update`. Поле заменяет набор тегов целиком: сначала прочитай текущие теги сотрудника через `GET /users/{id}` и передай их вместе с новым. Пока в теге никого нет, его упоминание никого не уведомит.
- Если метод ответил ошибкой, остановись и скажи пользователю простыми словами, что не получилось и что нужно, чтобы продолжить.
- Сообщения, которые публикуешь сам или которые отправляет бот, должны легко читаться с экрана, без перебора с отступами и выделением. Заголовок выдели жирным, текст под ним начинай со следующей строки. Связный текст пиши одним абзацем. Правила и шаги ставь нумерованными строками одна под другой и отдели их от вступления одной пустой строкой. Больше пустых строк в коротком сообщении не нужно. В карточке подписи полей выдели жирным, поля ставь строка под строкой. Жирным выделяй только заголовок и подписи полей. Списков и таблиц в разметке Пачки нет: цифры в начале строк остаются обычным текстом. Образец:

  ```text
  **Правила ретро**
  В последний день спринта сюда приходит сообщение с вопросами. Отвечаем в треде под ним.

  1. Каждый пункт пишем отдельным сообщением.
  2. Ставим 👍 тому, что важно обсудить.
  3. Итоги ведущий пишет одним сообщением и закрепляет его.
  ```
- Закрепление через API не проверить: его подтверждает только успешный ответ `POST /messages/{id}/pin`.
- Если для проверки бота ты отправлял в беседу служебные сообщения, например `/start`, удали их: `DELETE /messages/{id}`. Сообщения с правилами и шаблонами не удаляй.
- В конце напиши, что создано, что осталось сделать пользователю руками и как проверить, что сценарий работает.
- Откатить настройку: `DELETE /bots/{id}` удаляет бота, `PUT /chats/{id}/archive` отправляет беседу в архив.

## Как настроить сценарий вместе с пользователем

### 1. Спроси у пользователя

Задай эти вопросы этими словами:

1. Как сотрудники будут сдавать чеки? Сообщением по шаблону в беседе: заработает сразу. Или через форму у бота «Расходы», который сам соберёт отчёты за месяц: для него нужен n8n. У вас есть n8n? Если нет или не уверены, начнём с простого варианта, а бота добавим потом.
2. Кто бухгалтер, который принимает чеки? Напишите имя.
3. Кто из руководителей должен видеть расходы? Добавлю их в беседу «Расходы сотрудников».
4. В какой срок и в каком виде сотрудники сдают чеки? Это попадёт в правила беседы.

Сам проверь, есть ли в пространстве тег «Бухгалтерия». Для бота понадобится docx-шаблон авансового отчёта: попроси его, когда дойдёшь до обработчика.

### 2. Сделай сам через API Пачки: беседа и тег

Эти шаги нужны во всех вариантах.

1. Найди `id` бухгалтера и руководителей: `GET /search/users` или `GET /users`.
2. Найди тег «Бухгалтерия»: `GET /group_tags` с `names`.
3. Если тега нет, создай тег «Бухгалтерия» с теми, кто принимает чеки: `POST /group_tags`. Схему метода проверь через `--describe`. Упоминание @Бухгалтерия в треде расхода дойдёт до всех них.
4. Создай беседу: `POST /chats` с `name: "Расходы сотрудников"`, `member_ids` и `id` тега в `group_tag_ids`. Сохрани `id` беседы для обработчика. Если беседа уже есть, добавь в неё тег: `POST /chats/{id}/group_tags` с `group_tag_ids`.

### 3. Вариант А: чеки по шаблону

1. Опубликуй шаблон чека: `POST /messages` в беседу с текстом:

```
Чек: фото
Что оплатили: такси до клиента, встреча с «Северным ветром»
Сумма: 1 240 ₽
Дата: 24.09.2026
```

2. Закрепи шаблон: `POST /messages/{id}/pin`.
3. Предложи опубликовать правила: `POST /messages`. Чек присылают в день покупки. Бухгалтер ставит ✅, когда принял, вопросы задаёт в треде через @упоминание. Раз в месяц бухгалтер собирает авансовые отчёты руками.
4. Спроси пользователя, создать ли бота «Расходы» сейчас. Если да, выполни шаги 1–2 раздела 4.

### 4. Варианты Б и В: сделай сам через API Пачки

1. Создай бота: `POST /bots` с `name: "Расходы"`, ником на `_bot`, `trigger_on: "commands"`, `commands: ["/start"]` и `events: ["message_new", "button_click"]`. Не ставь `single_chat: true`: бот работает в нескольких чатах. Из ответа сохрани `id` бота и `access_token`: токен показывают один раз, он нужен обработчику.
2. Добавь бота в беседу: `POST /chats/{id}/members` с `id` бота в `member_ids`.
3. Когда у обработчика есть адрес, пропиши его в исходящий вебхук: `PUT /bots/{id}` с `outgoing_url` личным токеном или `PUT /bot/webhook` токеном бота. Для n8n это Production URL первого воркфлоу.
4. Предложи опубликовать правила из раздела «Правила для команды»: `POST /messages`.

### 5. Обработчик: спецификация

- События: команда `/start` и нажатие кнопок.
- На `/start` бот отвечает кнопкой «Добавить расход». Кнопка открывает форму через `POST /views/open` с `trigger_id` из события нажатия.
- Поля формы: «Что оплатили», «Сумма», «Дата», «Категория», «Чек». Для чека подходит блок `file_input`.
- Карточка в беседе «Расходы сотрудников»: сумма, дата и фото чека, кнопки «Принять» и «Уточнить». Чек загружается через API файлов Пачки: https://dev.pachca.com/api/file-uploads.md
- «Принять»: расход записывается в таблицу, бот пишет сотруднику в личку, что расход принят и с какой зарплатой придёт компенсация.
- «Уточнить»: бухгалтер задаёт вопрос сотруднику в треде карточки.
- Отчёт: второй процесс по расписанию в последний рабочий день месяца собирает принятые расходы по сотрудникам, заполняет docx-шаблон и кладёт файлы в тред.

Вариант Б: возьми за образец воркфлоу бота отпусков https://pachca.com/blog/avtomatizaciya-pachka-n8n-zayavki-na-otpusk. Замени поля формы и кнопки на перечисленные выше. Второй воркфлоу запускает Schedule Trigger.

Вариант В: обработчик пишет разработчик или ИИ-ассистент по этой спецификации. Туда же добавляют отправку отчётов в КЭДО и реестр выплат в 1С.

### Обработчик в n8n

Собери обработчик на узлах Пачки `n8n-nodes-pachca` второй версии. Они должны стоять в n8n пользователя: https://dev.pachca.com/guides/n8n/setup.md

Готовый рабочий воркфлоу с формой, кнопками и ответами в тред: https://pachca.com/scenarios-agent/propusk-bot-n8n.json. Возьми его за основу и замени под свой сценарий поля формы, кнопки, тексты и ветки. В файле стоят заглушки: `CHAT_ID`, `MANAGERS`, `CREDENTIAL_ID` и `NEW-UUID`. Имена параметров узлов бери из него и из списка ниже. В примерах на dev.pachca.com часть имён другая, по ним воркфлоу не соберётся.

Из чего собирать:

- `Pachca Trigger` принимает события бота. В воркфлоу он один: у бота один адрес вебхука. Параметр `event` принимает одно значение, поставь `*`, это все события. `webhookSetup` поставь `manual`: адрес боту ты пропишешь сам. Узлу нужен свой `webhookId`, новый UUID.
- Узел `Code` после триггера разбирает событие и выбирает ветку. Новое сообщение: `type: "message"`, `event: "new"`, текст в `content`. Нажатие кнопки: `type: "button"`, значение кнопки в `data`, рядом `trigger_id` и `message_id`. Отправка формы: `type: "view"`, `event: "submit"`, `callback_id` формы, значения полей в `data` по именам полей. Кто действовал, показывает `user_id`. Поля событий: https://dev.pachca.com/guides/webhook/events.md
- `Switch` делит события по ветке из узла `Code`.
- Форма: узел `Pachca`, `resource: "form"`, `operation: "create"`. Заголовок в `formTitle`, `triggerId` из события нажатия кнопки, он действует три секунды. `formBuilderMode: "json"`, поля в `formBlocks` JSON-строкой. `callbackId`, `submitText` и `closeText` лежат внутри `additionalFields`. Типы блоков: https://dev.pachca.com/guides/forms/blocks.md
- Сообщение: `resource: "message"`, `operation: "create"`, `entityType` и `entityId`, текст в `content`. В беседу пишут с `entityType: "discussion"`, сотруднику в личные сообщения — с `entityType: "user"` и его `user_id` в `entityId`. В образце кнопка после `/start` уходит в беседу: если по сценарию бот отвечает в личке, поменяй это. Кнопки: `buttonLayout: "raw_json"` и `rawJsonButtons` JSON-строкой. Это массив строк, в каждой строке массив кнопок с `text` и `data`. Сотрудника упоминай как `<@user_id>`.
- Ответ в тред под сообщением. Сначала `resource: "thread"`, `operation: "create"` с `threadMessageId`: это `message_id` сообщения, под которым нужен тред. Узел вернёт `id` треда. Затем сообщение с `entityType: "thread"` и этим `id` в `entityId`.
- Нажатие кнопки внутри треда приносит `chat_id` треда, а для ответа нужен `id` треда. Клади `id` треда в `data` кнопок, которые публикуешь в треде.
- Если нажимать кнопку вправе не все, сравни `user_id` из события со списком из описания обработчика и на чужое нажатие ничего не отправляй.

- Участники беседы: `resource: "member"`, `operation: "getAll"`, беседа в параметре `id`, `returnAll: true`, `simplify: false`. Бот сам есть в этом списке с признаком `bot`: отфильтруй его.
- Расписание запускает узел `Schedule Trigger` с правилом `cronExpression`.

Образец ничего не хранит: всё, что нужно для ответа, лежит в `data` кнопок, это действие и `id` автора. Если сценарию нужно помнить немного данных, например счётчик номеров заявок или кто уже ответил, бери статические данные воркфлоу: `$getWorkflowStaticData('global')` в узле `Code`. Они сохраняются только при запусках включённого воркфлоу, при ручном запуске в редакторе не сохраняются. Назови это решение пользователю в итоговом сообщении. Расписание переговорок, реестры и всё, что должно пережить пересоздание воркфлоу, храни во внешней таблице: её выбери вместе с пользователем.

Порядок работы:

1. Собери файл воркфлоу. Оставь в нём только `name`, `nodes`, `connections` и `settings`: остальные поля n8n через API не примет. Проверь, что JSON валиден, а имена узлов в `connections` и в выражениях совпадают с именами в `nodes`.
2. Получи адрес n8n и ключ API, как сказано в правилах выше. Запросы к API n8n идут с заголовком `X-N8N-API-KEY`.
3. Создай в n8n Credential для Пачки: `POST /api/v1/credentials` с `type: "pachcaApi"`. В `data` положи `accessToken` с токеном бота и `baseUrl` со значением `https://api.pachca.com/api/shared/v1`. Остальные обязательные поля покажет `GET /api/v1/credentials/schema/pachcaApi`. Если среди них есть `allowedHttpRequestDomains`, поставь `all`. Впиши `id` и имя этого Credential во все узлы Пачки в файле.
4. Загрузи воркфлоу: `POST /api/v1/workflows`. Включи его: `POST /api/v1/workflows/{id}/activate`.
5. Пропиши боту адрес вебхука: `PUT /bots/{id}` с `outgoing_url`. Адрес собирается так: адрес n8n, затем `/webhook/`, `webhookId` узла `Pachca Trigger` и `/webhook`.
6. Чтобы проверить запуск по расписанию, не дожидаясь срока, временно поставь расписание на ближайшую минуту, дождись запуска и верни как было.
7. Если ключа API n8n нет или шаг не прошёл, отдай файл пользователю. Он вставит его содержимое в новый воркфлоу, создаст Credential с токеном бота, выберет его во всех узлах Пачки и включит воркфлоу. Попроси Production URL узла `Pachca Trigger` и пропиши его боту сам.

### 6. Попроси пользователя сделать руками

- Сделать бота «Расходы» публичным: в настройках бота включить переключатель «Публичный». Через API это не задаётся.
- Если создать тег через API не вышло: в беседе открыть Участники → табличный вид → иконку тега и создать тег «Бухгалтерия» с теми, кто принимает чеки.
- Загрузить воркфлоу в n8n и включить их, если у тебя нет доступа к n8n.

### 7. Проверь

1. Попроси пользователя написать боту `/start`. Бот должен ответить кнопкой «Добавить расход».
2. Попроси заполнить форму и отправить. Убедись, что карточка появилась в беседе: `GET /messages` по беседе «Расходы сотрудников».
3. Попроси нажать «Принять». Ответ бота в личке сотрудника подтверждает пользователь: личную переписку с ботом твой токен не видит.

## Правила для команды

Чек отправляется в день покупки. Бухгалтер принимает или уточняет в течение дня, вопросы задаёт в треде через @упоминание. Что не принято до 25-го числа, уходит в отчёт за следующий месяц. Сроки и требования берут из учётной политики компании.

## Что сценарий не умеет

- Подписывают авансовые отчёты в КЭДО. В Пачке виден только статус.
- Шаблон отчёта и лимиты по категориям сверяют с бухгалтером до запуска.

## Если не работает

- Бот не отвечает на `/start`. В исходящем вебхуке не отмечены «Новые сообщения» или обработчик выключен. В n8n нужен Production URL, Test URL не подойдёт.
- Кнопка не открывает форму, «Принять» не срабатывает. В исходящем вебхуке не отмечено «Нажатие кнопок»: проверь `button_click` в `events` бота.
- Чек не прикрепляется к карточке. Обработчик передал только имя файла и не загрузил файл через API файлов: https://dev.pachca.com/api/file-uploads.md

## Ссылки

- Страница сценария с демо и инструкцией для человека: https://pachca.com/scenarios/avansovye-otchety
- Воркфлоу бота отпусков: https://pachca.com/blog/avtomatizaciya-pachka-n8n-zayavki-na-otpusk
- n8n в Пачке: https://pachca.com/help-center/integrations/avtomatizacii-v-pachke-s-pomoshchyu-n8n
- Формы: https://pachca.com/help-center/integrations/formy
- Кнопки в чат-ботах: https://pachca.com/help-center/integrations/knopki-v-chat-botah
- Исходящие вебхуки: https://pachca.com/help-center/integrations/ishodyashchie-webhook-kak-nastroit
- Теги для разработчиков: https://dev.pachca.com/guides/tags.md
- Формы для разработчиков: https://dev.pachca.com/guides/forms/overview.md
- Исходящие вебхуки и типы событий: https://dev.pachca.com/guides/webhook/events.md