@catalogicus-international/n8n-nodes-invoice-parser
v0.2.10
Published
Parse supplier PDF invoices into structured line items (coordinate-aware table parser)
Maintainers
Readme
@catalogicus-international/n8n-nodes-invoice-parser
Нода n8n: разбирает PDF-счёт в массив строк (наименование, код, количество, цена, сумма, НДС) и проверяет арифметику. Работает по координатам текста, а не по «плоскому» тексту — поэтому корректно читает табличные счета, где наименования переносятся по границам колонок.
Как это работает
PDF не хранит таблицу — в нём есть только глифы с координатами. Нода:
- читает каждый текстовый фрагмент с его
X/Y(pdfjs-dist); - группирует фрагменты по
Y— получает визуальные строки; - раскладывает символы по колонкам согласно
Xи границам профиля (кусок текста может пересекать границу колонок — например1 ETM9943043); - склеивает переносы наименований в предыдущую строку;
- проверяет
кол-во × цена = суммаи отдаёт предупреждения.
Установка
В Settings → Community Nodes укажите:
@catalogicus-international/n8n-nodes-invoice-parserОтдельно устанавливать PDF.js не требуется: pdfjs-dist — devDependency и встраивается
в dist вместе с воркером при сборке (scripts/bundle.mjs). Поле dependencies пустое;
n8n-workflow предоставляется самим n8n как peerDependency.
Внутри PDF.js остаются опциональные обращения к canvas для рендеринга: нода использует
извлечение текста, а не рендеринг страниц. Команда pnpm run check:package проверяет чтение
текстового PDF из npm-архива без установленных pdfjs-dist и canvas.
Пакет рассчитан на self-hosted n8n: воркер pdfjs грузится из __dirname, что не проходит
проверку Cloud-совместимости, поэтому cloud-support отключён и стоит "strict": false.
Пустое поле dependencies само по себе не означает прохождение официальной верификации n8n.
Без npm-реестра пакет можно поставить из архива: pnpm pack соберёт
catalogicus-international-n8n-nodes-invoice-parser-<версия>.tgz, его распаковывают в
~/.n8n/custom (в Docker — /home/node/.n8n/custom с N8N_CUSTOM_EXTENSIONS) и перезапускают n8n.
Разработка
Нужны Node.js 20.15+ и pnpm 12:
pnpm install
pnpm run lint
pnpm run build
pnpm testpnpm run build:watch выполняет полную сборку при изменении исходников, включая PDF.js и воркер.
pnpm run dev сначала собирает пакет, затем поднимает n8n@latest через npx с подключённым
dist и пересборкой при изменениях. Первый запуск может потребовать загрузки n8n.
Данные сервера хранятся в ~/.n8n-node-cli (можно переопределить через N8N_USER_FOLDER).
Обычный tsc --watch для этого пакета не подходит: он перезаписывает встроенный PDF.js.
Тесты работают на
синтетических строках и замоканном pdfjs; поведение на настоящих счетах проверяет регресс ниже.
После pnpm run build выполните pnpm run check:package: команда создаёт npm-архив,
распаковывает его во временную папку и читает небольшой PDF без devDependencies.
Она проверяет загрузку парсера и воркера, но не заменяет запуск ноды в n8n и регресс на счетах.
Параметры
| Параметр | Описание |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input Binary Field | поле с PDF (по умолчанию data) |
| Supplier Profile | Auto-Detect (Recommended) (определить по тексту), профили поставщиков из пакета (Электротехмонтаж, Леруа Мерлен (ЛЕ МОНЛИД), Лунда, Нормал-Вент, ТЕРЕМ, СТД «Петрович» и его макеты), Universal |
| Output | One Item per Document или One Item per Line |
| Options → Y Tolerance | допуск по вертикали для склейки строки (по умолчанию 2 pt) |
| Options → Fail on Arithmetic Mismatch | падать, если кол-во × цена ≠ сумма |
Нода поддерживает Continue On Fail: ошибка конкретного файла попадает в json.error
этого item, остальные файлы обрабатываются. Каждый выходной item связан с входным через
pairedItem.
Профиль Universal не знает колонок, поэтому lines пустой, а все текстовые строки
документа (уже собранные по координатам) приходят в unparsedRows.
Выход
{
"fileName": "2026-08-27_etm_277-02.13114.pdf",
"pages": 3,
"supplier": { "id": "etm", "title": "Электротехмонтаж" },
"lines": [
{
"num": 1,
"code": "ETM9943043",
"name": "Кабель силовой ВВГ-Пнг(А)-LS 3Х2.5ок(N,PE)-0.660 100м ТРТС",
"article": "МОНЭЛ",
"productType": "S",
"unit": "м",
"qty": 1000,
"price": 102.98,
"sum": 102980,
"total": 125635.6
}
],
"totals": { "qty": 2535, "sum": 199671.33, "vat": 43927.71, "total": 243599.04 },
"discount": 0,
"warnings": [],
"unparsedRows": []
}discount — скидка на весь документ в суммах без НДС (0, если её нет). Позиции в счёте
напечатаны до скидки, поэтому при ненулевой скидке totals меньше суммы lines[].sum
ровно на discount; повторно вычитать её из позиций не нужно.
В режиме «One Item per Line» каждый item — одна позиция без totals и discount. Если
документ со скидкой, сумма sum по таким item больше итога счёта; чтобы получить сумму
к оплате, используйте режим «One Item per Document».
Покрытие
| Поставщик | Статус |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Электротехмонтаж (счета 277/...) | профиль etm, проверено 19 из 19 счетов: число строк и суммы совпали до копейки |
| Леруа Мерлен / ЛЕ МОНЛИД | три макета: leman, leman-offer (счёт-оферта со скидкой на документ), leman-shift; 45 счетов из 46 сошлись с итогом, ещё 1 — счёт без таблицы (только сумма к оплате) |
| Лунда | профиль lunda, 52 счёта: 51 сошёлся с «Итого без НДС» до копейки, 1 — с отличающимся шаблоном (расхождение видно в warnings). В счетах 2026 года колонка «Сроки» заполнена наличием на складе («6 шт - на складе») — она служебная и в позицию не входит, ставка 22 % выводится из напечатанных итогов; фикстура lunda/main/2026-11-13_lunda_7278855.pdf |
| Нормал-Вент | профиль normalvent, 29 из 29 счетов |
| ТЕРЕМ | профили terem и terem-narrow (сдвинутый макет), 10 из 10 счетов |
| СТД «Петрович» | пять макетов: petrovich/wide, petrovich/main, petrovich/discount, petrovich/compact, petrovich/narrow; 17 счетов из 18 (выгрузка «Заказ в Excel» не счёт) |
| Прочие поставщики корпуса | 29 профилей по ИНН (корпус stabs/СЧЕТА): формы «Счёт на оплату» (1С и её варианты), счёт-договор, счёт-оферта, таблицы ИП, счёт с колонкой скидки. Итого 47 счетов от 30 поставщиков — все 47 сошлись с итогом документа до копейки |
| ООО «МЕГАПОЛИС» (аренда) | профиль megapolis: форма «Счёт на оплату» 1С без кода, количество в сутках. Границы колонок вычисляются по шапке таблицы (проверено только на этом поставщике), при нераспознанной шапке берутся запасные константы профиля; счёт № 1106-0010 сошёлся с итогом до копейки |
| Счета из выгрузки 09.11.2026 | 14 профилей по ИНН: НПД-платформы, «САТУРН ЮГ», ИП Корнеев, ИП Турдугулов, ИП Башкирова, «ИНВИЗИБЛ-ДОРС», ИП Бахарева, «БАС ИНЖИНИРИНГ ГРУПП», ИП Малиновская, «ПТК «МИРА»», ИП Дельцова, ИП Братова, «ЛЕСКРАФТ». 19 из 21 PDF разобраны без предупреждений; 2 PDF — сканы без текстового слоя |
| Счета из папки «Ошибки» (12.11.2026) | 6 профилей: delovye-linii («Деловые Линии», определение по ИНН, услуги без количества и страхование отдельной строкой), maradi («МАРАДИ», счёт-договор), mir (ООО «МиР»), alpikastroy («Альпикастройсервис»), akvadoor («АКВАДВЕРЬ», с колонкой кода), stepina (ИП Степина, артикул и скидка по строке). 6 PDF разобраны без предупреждений, позиции и итоги сошлись с документами |
| ИП Еранов (счёт Т-Банка) | профиль eranov, макет tbank-table: «Счёт на оплату» Т-Банка с колонками «Товары (работы, услуги)», «кол-во», «Ед.», «НДС», «Цена», «Сумма». Наименование нарисовано на 2 pt выше числовых значений, его перенос — ниже, поэтому у профиля yTolerance: 3. В колонке НДС напечатано «Без НДС», «Итого к оплате» равно сумме позиций; счёт № 15 от 13.11.2026 сошёлся до копейки |
| ИП Каравашкин (счёт «СберБизнеса») | профиль karavashkin, макет sber-table: «Счёт на оплату» из «СберБизнеса» с колонками «Товары (работы, услуги)», «Кол-во», «Ед. изм.», «НДС», «Цена за ед.», «Сумма». Границы колонок вычисляются по шапке: колонка цены подписана «Цена за ед.», а НДС — текстовая («Без НДС»), поэтому она объявлена в headerColumns. НДС не начисляется, «Итого к оплате» равно сумме позиций; счёт № 16 от 08.11.2026 сошёлся до копейки, фикстура suppliers/karavashkin |
| ООО «ФАКЕЛ» (Maytoni) | профиль fakel, макет maytoni-table: счёт Maytoni с артикулом, весом, объёмом, ценой, «Суммой без скидки», скидкой по строке и суммой. Скидка описана в lineDiscountColumn (цена напечатана до неё), «Сумма без скидки» — как price2, а вес, объём и «Дата прихода» — служебные колонки в raw.note; наименование нарисовано строкой выше чисел. Счёт № 448682 от 16.11.2026 (1 позиция, 6 383,00 с НДС 1 151,03) сошёлся до копейки, фикстура suppliers/fakel |
| ООО «АВТОЛЕГИОН» | профиль autolegion, макет tenzor-service: счёт оператора ЭДО «Тензор», услуга с единицей «Рейс», количество «1.000», наименование переносится четырьмя строками ниже числовой строки. «Итого:» напечатано с НДС, поэтому сумма без НДС выводится из «Всего к оплате» и «В том числе НДС». Счёт № 1950 от 12.11.2026 (1 позиция, 25 000,00, НДС 4 508,20) сошёлся до копейки, фикстура suppliers/autolegion |
| ООО «БИГ» (ИНН 2366050350) | профиль big, макет onec-standard: новое имя поставщика «БАС ИНЖИНИРИНГ ГРУПП» с тем же ИНН, но таблица — типовая форма 1С без колонки кода и без номера строкой выше. Старый макет bas-engineering эти счета не читает (0 позиций), поэтому при автоопределении из двух профилей с одним ИНН побеждает тот, чьи колонки дают сходящиеся позиции. Счета № 5071 и № 5088 сошлись до копейки, фикстура suppliers/big |
| ИП Долженко С. О. | профиль dolzhenko, макет onec-standard: типовая форма 1С без НДС («Без налога (НДС)»), три позиции по 1 шт. Счёт № 84 от 11.11.2026 на 41 905,00 сошёлся до копейки, фикстура suppliers/dolzhenko |
| ООО «АЛЬФА-ТРЕЙД» (счёт-оферта) | профиль alfa-trade, макет oferta-article-discount: форма 1С с колонками «Артикул», «Доп. инф о», «Сумма без скидки», «Скидка», «Ставка НДС» и «Сумма НДС». Наименование занимает блок строк ВЫШЕ чисел (descriptionAboveBlock) и не забирает подписи шапки; скидка по строке — lineDiscountColumn, суммы с НДС, сумма без НДС выводится из «Итого с НДС» и «В т.ч. НДС (5%)». Счёт № СС-2867: 1 позиция, 16 560,00 к оплате, фикстура suppliers/alfa-trade |
| ООО «КЛИМАТ СОЧИ» (ИНН 2366020771) | профиль klimat-sochi, макет onec-standard: типовая форма 1С без колонки кода, НДС не начисляется («Без налога (НДС)»). Границы колонок — константы, а не шапка: «Кол-во» и «Ед.» напечатаны по центру ячеек, единица «Шт» стоит левее своей подписи, и граница из шапки приклеила бы её к количеству; правая граница наименования расширена до 308 pt, иначе перенос «…СУБ-ОВиК» доходил до края колонки и слово «от» приклеивалось без пробела. Счёт № 32 от 16.11.2026: 1 позиция, 712 000,00 без НДС, фикстура suppliers/klimat-sochi |
| Darklum (счёт-оферта 9426) | нужен отдельный профиль (блочная вёрстка, не таблица) |
| ВсеИнструменты (кассовые чеки) | нужен отдельный профиль (позиции блоками) |
Всего в пакете 71 профиль; pnpm run regress проверяет 66 эталонных PDF из fixtures.
Новые профили проверены на 19 реальных PDF из выгрузки 09.11.2026, но пока без добавления этих
PDF в публичные фикстуры. счет дриада.pdf из выгрузки 16.11.2026 — не счёт, а скан подписи и
печати ИП Журавлевой О. В.: одно изображение без текстового слоя (ни одного шрифта в PDF),
разбирать в нём нечего.
Фикстуры
Новый счёт добавляется одной командой; она читает собранный парсер, проверяет позиции и итоги и только потом пишет эталон:
pnpm run build
pnpm fixture check /путь/к/счёту.pdf # разбор без записи
pnpm fixture add /путь/к/счёту.pdf # PDF + expected.json в fixtures
pnpm fixture list # покрытие корпуса
pnpm fixture report /путь/к/папке # отчёт по произвольной папке PDFПодробности и правила ревью эталона — docs/fixtures.md.
--force разрешает записать эталон с замечаниями, --replace — заменить PDF с тем же
именем, но другим содержимым; по умолчанию команда не делает ни того, ни другого.
--layout выбирает существующий каталог фикстуры или создаёт новый.
Регресс
pnpm run build && pnpm run regress -- /путь/к/pdf [эталон.json]Эталон можно собрать из уже проверенных данных: имя файла → { "lines": N, "sum": X }.
Ограничения
- Профиль
etmпривязан к текущему шаблону счетов: границы колонок в пунктах (33.5 · 47.2 · 95.3 · 229.3 · 267.1 · 274 · 291.2 · 325.5 · 366.8 · 383.9 · 425.2 · 442.3 · 456.1 · 500.8 · 548.9). Если поставщик поменяет шаблон — правитсяnodes/InvoicePdfParser/profiles.ts. - Тип товара и единица измерения приходят раздельно:
productType— буква из колонки «У» (S— складской,Z/N— заказной, в счетах шаблона «Дриада» встречаетсяR),unit— уже чистая единица (м,шт,упак). В версиях до 0.2.0 буква шла в составеunit(«S м»). - Для профилей с
pricesIncludeVat(напримерleman, Леруа Мерлен) нода сама считаетsumбез НДС, аtotalоставляет как в счёте. Ставка берётся из напечатанных итогов документа (Сумма НДС / Итого без НДС), поэтому 20 % в счетах 2025 года и 22 % в счетах 2026-го читаются одной и той же формой;vatRateпрофиля — только запасной вариант. - Сумма позиций сверяется с напечатанным итогом документа. Расхождение попадает в
warnings(с учётом допуска на построчное округление), а не проходит молча. - Позиция, повторённая на стыке страниц (тот же номер, количество, цена и сумма), считается один раз.
- У профилей с
descriptionAbove(СТД «Петрович») наименование и код нарисованы строкой выше числовой строки: такие строки придерживаются в буфере и приклеиваются к следующей позиции. - У профиля
alfa-trade(descriptionAboveBlock) наименование занимает блок из нескольких строк выше чисел: строки блока склеиваются цепочкой, пока каждая следующая отстоит не дальше обычного переноса и занята только колонкой наименования, — так подписи шапки таблицы в позицию не попадают. Перенос без дефиса, который поставщик сделал в узкой колонке («коричневы» + «й»), сохраняется пробелом: символы в наименование не додумываются. rowPattern.codeнеобязателен: у профилей без колонки кода позиция распознаётся по номеру.- У профилей с
lineDiscountColumn(ИП Степина) скидка напечатана отдельной колонкой: арифметика строки сверяется каккол-во × цена − скидка = сумма, а цена остаётся напечатанной до скидки.
Релиз
Публикация запускается командой pnpm release. Версия берётся из package.json: если она уже
есть в npm, команда сообщает о конфликте и завершается с ошибкой. Версия, changelog, коммиты,
теги и GitHub Release автоматически не создаются и не меняются.
Перед запуском явно обновите версию и changelog, закоммитьте изменения и отправьте main на
GitHub. Скрипт требует чистую рабочую копию и совпадение локального коммита с main на GitHub.
Для доступа используется GH_TOKEN / GITHUB_TOKEN или существующая авторизация Git через
credential helper; нужны права GitHub Actions на запуск workflow. GitHub CLI и npm token
не требуются.
Скрипт запускает .github/workflows/publish-npm.yml, выводит ссылку на запуск и сразу
завершается. Успех команды означает отправку запуска; результат публикации смотрите по ссылке.
Workflow публикует конкретный коммит через npm Trusted Publisher/OIDC после
lint, build, тестов, регрессии, строгого отчёта фикстур и проверки npm archive. Эти проверки
не повторяются через prepublishOnly. Ошибки отправки останавливают команду, ошибки публикации видны в Actions;
повторный workflow автоматически не запускается. Отправка тегов больше не запускает публикацию.
pnpm release --check-version только проверяет доступность версии в npm, без тестов и
публикации. При первом переходе на этот процесс изменения workflow должны попасть в main.
Лицензия
MIT, см. LICENSE.md.
