Planday → Excel, Power BI и Claude

У Timesheet Report в Planday — того самого, где есть отработанные часы и стоимость персонала за смену, — нет отдельной конечной точки API. Большинство узнают об этом на горьком опыте, подключив Power Query не к тому ресурсу и получив ровно 50 строк.

Этот проект решает обе проблемы:

1. Транслятор, который собирает настоящий Timesheet Report из трёх конечных точек, которые Planday никогда не объединяет, и отдаёт его в Excel или Power BI в виде живого потока данных.

2. MCP-сервер, покрывающий весь API Planday — все 125 операций, — так что вы можете задавать вопросы на простом английском: «Сколько нам в июле стоило привлечение агентского персонала, по отделам?»

Лицензия MIT. Работает на вашей собственной инфраструктуре. Ваши учётные данные Planday никогда её не покидают.

Пока не проверено на реальном портале. Всё здесь работает на реалистичном образцовом портале, а клиент API сгенерирован из опубликованных спецификаций самого Planday, но на настоящие данные его ещё никто не направлял. Если это про вас, сначала прочтите TESTING.md — там объясняется, как сверить результаты с собственным отчётом Planday, и честно сказано, где скорее всего могут быть ошибки. Команда pnpm doctor проверяет каждый слой и отличает настоящую ошибку от проблемы с настройкой.

Просто хотите, чтобы оно работало?

→ SETUP.md — это пошаговая инструкция, написанная для того, кто составляет график, а не для разработчика. Около 20 минут, без программирования, бесплатно.

После развёртывания достаточно открыть его в браузере — вы увидите вот что: страница показывает, что настроено, запускает реальное тестовое извлечение данных и генерирует для вас фрагмент Power Query с уже подставленным вашим URL:

Остальная часть этого файла — для разработчиков.

Требования: Node 20 или новее, и больше ничего. pnpm соответствует lockfile, но и npm install работает нормально.

Всё, что описано ниже, работает на реалистичных образцовых данных. Учётные данные Planday не нужны, чтобы увидеть его в работе — это самый быстрый способ решить, делает ли он то, что вам нужно.

pnpm install && pnpm dummy      # or: npm install && npm run dummy

Planday timesheet  mode=dummy  2026-06-01 -> 2026-07-26

department                  shifts   worked h        cost   cost/h
------------------------------------------------------------------
Events                         160     1137.5   £21398.45    18.81
Kitchen                        167     1159.8   £21169.29    18.25
Front of House                 166     1116.1   £20793.30    18.63
Housekeeping                   133      942.6   £18243.15    19.35
------------------------------------------------------------------
TOTAL                          626     4356.1   £81604.19    18.73

rows: 626   cost source: payroll   portal: Harbour Group
edge cases -> orphan punch-clock: 1, open shifts: 1, no cost attached: 30, edited after approval: 22

626 rows - well past the 50-record cap that catches most people out.

Две вещи, на которых спотыкаются все

1. Конечной точки Timesheet Report не существует

https://openapi.planday.com/api/absence и подобные ему адреса — это страницы документации, а не конечные точки API. Ошибка лёгкая и очень распространённая. Absence в Planday — это учёт отпусков и переработок, к табелям он отношения не имеет.

Timesheet Report — это объединение трёх конечных точек:

Плюс hr/departments, hr/employees, hr/employeegroups и scheduling/shifttypes, чтобы превращать идентификаторы в названия. Это объединение находится в src/timesheet/transform.ts.

2. Ограничение в 50 записей

Списочные конечные точки Planday в собственной спецификации объявляют limit с maximum: 50. Увеличение значения ни к чему не приводит — сервер молча игнорирует вас. Единственный путь — зациклить offset, пока не будут получены все записи из paging.total.

Полезный нюанс: три указанных выше отчётных конечных точки вообще не используют пагинацию. Это массовые вызовы по диапазону дат. Так что на правильных конечных точках проблема 50 записей по большей части исчезает — она затрагивает лишь небольшие справочные таблицы.

Также стоит знать

Каждый запрос к Planday требует два заголовка, а не один:

Authorization: Bearer <access token>
X-ClientId: <client id>

Если пропустить X-ClientId, вы получите 401, который выглядит точно так же, как при неверном токене. Кроме того, access-токены истекают через час, поэтому любому запланированному процессу нужно их обновлять. Это главным образом и делает реализацию на чистом Power Query неприятной, и именно поэтому существует описанный ниже мост.

Related MCP server: TimeChimp MCP Server

Как перенести это в Excel или Power BI

Есть два варианта. Они подходят для разных бюджетов, и оба включены.

Вариант A — сервис-мост (рекомендуется)

Небольшой сервис находится между Planday и Excel. Он берёт на себя OAuth, почасовое обновление токена и всю пагинацию, так что Power Query сводится к одному вызову Web.Contents.

cp .env.example .env      # set BRIDGE_KEY
pnpm bridge

Откройте http://localhost:8787 — это страница настройки: она показывает, что настроено, запускает тестовое извлечение данных и выдаёт вам фрагмент Power Query с уже вставленным вашим URL.

Эта конечная точка передаёт ставки и оклады, поэтому она защищена аутентификацией с самого первого коммита: общий секрет передаётся в заголовке x-bridge-key. Он решительно отвергает любые операции записи независимо от настроек: URL, который может обновлять электронная таблица, ни при каких условиях не должен менять действующий график.

Вариант B — вообще без сервера

powerquery/Timesheet-direct.pq обращается к Planday напрямую из Power Query, в том числе используя цикл смещения List.Generate, который решает проблему 50 записей. Медленнее и заново проходит аутентификацию при каждом обновлении, но запуск ничего не стоит.

MCP-сервер

19 инструментов, покрывающих все 125 операций Planday.

pnpm mcp        # stdio; .mcp.json already registers it for Claude Code

Для Claude Desktop добавьте это в claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\\Claude\\):

{
  "mcpServers": {
    "planday": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/planday-bridge", "tsx", "apps/mcp/index.ts"],
      "env": {
        "PLANDAY_CLIENT_ID": "your-client-id",
        "PLANDAY_REFRESH_TOKEN": "your-refresh-token",
        "PLANDAY_WRITE_TIER": "read"
      }
    }
  }
}

Чтобы работать с образцовым порталом, полностью удалите оба значения Planday.

Регистрация 125 отдельных инструментов перегрузила бы большинство MCP-клиентов и потратила бы десятки тысяч контекстных токенов на описания, прежде чем был бы задан хотя бы один вопрос. Поэтому покрытие полное, а регистрация — многоуровневая:

Универсальный доступ — 3 инструмента, все 125 операций

• planday_search_operations — поиск любой конечной точки по ключевому слову

• planday_describe_operation — её полная сигнатура и форма ответа

• planday_call — вызов с проверкой по спецификации и обработкой пагинации

Всё, что умеет Planday, доступно отсюда, включая конечные точки, о которых ещё никто не подумал.

Отобранные операции чтения — 12 инструментов для типовых задач: отделы, сотрудники, группы сотрудников, типы смен, должности, смены, отметки прихода/ухода, записи об отсутствиях, расчётная ведомость, время и стоимость, история составления графика, плюс planday_whoami.

Составные операции — 4 инструмента, которые делают то, что сырой API не может сделать за один вызов: planday_get_timesheet (тройное объединение), planday_summarise_staff_cost, planday_export_timesheet_csv, planday_explain_columns.

Почему он может отвечать на вопросы, а не просто возвращать данные

Восемь недель портала среднего размера — это более тысячи строк. Если передать их модели в виде сырого JSON, её контекст исчерпывается и это провоцирует арифметические ошибки. Поэтому агрегация выполняется на стороне сервера: planday_summarise_staff_cost группирует по отделу, сотруднику, группе сотрудников, типу смены, дню, неделе, источнику затрат или признаку «агентский персонал против собственного» и возвращает с десяток строк. Большие выгрузки возвращаются в виде пути к файлу, а не инлайна.

Безопасность операций записи

62 из 125 операций изменяют данные — включая удаление смен и отделов, а также отметку прихода и ухода сотрудников. Они доступны для обнаружения, но их выполнение регулируется:

Ничего не скрыто — но LLM, направленная на живой портал составления графиков, не получит кнопку удаления случайно.

Переход на реальные данные

Для всего описанного выше учётные данные Planday не нужны. Когда понадобятся реальные данные:

1. В Planday: Settings → Integrations → API Access → Create App. Отметьте области доступа, перечисленные в SETUP.md, нажмите Authorise и скопируйте Client ID и Refresh Token. Отмечайте как можно меньше областей, без которых можно обойтись — см. SECURITY.md.

2. Поместите их в .env как PLANDAY_CLIENT_ID и PLANDAY_REFRESH_TOKEN.

3. pnpm doctor

pnpm doctor идёт дальше: проверяет окружение, конфигурацию, подключение, каждую область доступа Planday по отдельности, а затем реальную сборку отчёта, так что вы точно увидите, какой слой даёт сбой. В его выводе нет учётных данных и сведений о сотрудниках, поэтому им можно безопасно делиться. Planday разграничивает доступ к каждой области отдельно, поэтому даже совершенно валидному токену всё ещё может быть отказано в расчётной ведомости; в этом случае отчёт упрощается до «время и стоимость», а затем до часов без стоимости, но не падает.

Изменений в коде не требуется. Образцовый и реальный режимы работают по одному и тому же пути кода.

Planday предлагает 30-дневную бесплатную пробную версию с доступом к API и по запросу выдаёт демонстрационный портал для разработчиков — удобно для проверки интеграции, не затрагивая действующий график.

Как обеспечивается корректность

Весь клиент сгенерирован из собственных спецификаций OpenAPI Planday, которые находятся в репозитории в specs/. Написанные вручную обёртки над конечными точками разошлись бы с реальностью в тот же момент, как Planday выпустил бы изменение; сгенерированные же пересоздаются за секунды.

pnpm gen     # 125 operations, 294 schemas. Asserts no duplicate ids, no unresolved refs.
pnpm test    # 32 tests
pnpm doctor  # diagnose a live connection, layer by layer

Тест покрытия вызывает каждую из 125 операций и проверяет каждый ответ по схеме этой операции. Именно это превращает «весь API доступен» из заявления в проверенный факт. И если Planday добавит конечную точку, она будет покрыта автоматически — без списка, который нужно не забыть обновить.

test/deploy.test.ts собирает реальную бессерверную точку входа с помощью esbuild и прогоняет маршруты, потому что многие вещи проходят под tsx, но ломаются после сборки.

Остальные тесты фиксируют правила объединения на примерах, которые ломают собственноручно сделанное объединение в Power Query: отметка прихода/ухода без идентификатора смены, смена, переходящая через полночь, пара, в которой окончание раньше начала, вычет неоплачиваемого перерыва, сотрудник с месячным окладом, у которого есть часы, но нет стоимости, неназначенная открытая смена и смена, отредактированная после её утверждения. Образцовый портал намеренно содержит все эти случаи.

Адаптация

Агентский персонал и контрактное замещение. В Planday нет полноценного понятия агентского персонала, поэтому проект определяет его по названию группы сотрудников или типа смены. Если в вашем портале это помечается иначе, измените AGENCY_RULE в src/timesheet/transform.ts. Это одно регулярное выражение.

Названия колонок. src/timesheet/columns.ts — единственный источник истины. Заголовок CSV, маршрут /columns, MCP-инструмент explain_columns и сгенерированный powerquery/Timesheet.pq — всё формируется из него, поэтому переименование колонки там обновляет всё. После этого выполните pnpm gen.

Валюта и локаль. Берутся из того, что Planday сообщает для вашего портала.

Другие данные Planday. Табель рабочего времени — просто наиболее проработанный пример. Каждая из 125 операций уже доступна через planday_call и маршрут /api/ — балансы отсутствий, выручка, ставки оплаты, отметки прихода и ухода, история сотрудников. Если вам нужен ещё один отчёт, устроенный так же, как табель, — src/timesheet/ это образец для копирования.

Безопасность

Прочтите SECURITY.md перед развёртыванием. Если коротко: refresh-токен открывает доступ к данным о заработной плате и не истекает сам по себе, ничего нигде не хранится, операции записи по умолчанию отклоняются, и существует приватный канал для сообщений об уязвимостях.

Участие в разработке

Приветствуются issues и pull requests. Если Planday изменит свой API: заново скачайте спецификации в specs/, запустите pnpm gen, и diff покажет вам, что именно изменилось.

Работаете над этим с ИИ-агентом для написания кода? AGENTS.md написан именно для этого — в нём собраны доменные знания и неочевидные ловушки, повторное обнаружение которых обходится дорого.