KSeF: как подключить систему продаж через токен и API

С 2026 года Национальная система электронных фактур перестаёт быть опцией. Это руководство шаг за шагом показывает, как технически подключить систему продаж к KSeF: выбрать метод аутентификации (токен или сертификат), соединиться с API 2.0, выставить фактуру в структуре FA(3) и всё протестировать в тестовой среде, прежде чем запустить продакшн.

От чего зависит срок и что, собственно, нужно подключить

Чтобы подключить систему продаж к KSeF, вам нужны три вещи одновременно: метод аутентификации (авторизационный токен или сертификат KSeF), интеграция с API KSeF 2.0 и генерация фактур в структуре FA(3) в формате XML. Это и есть полный ответ на вопрос «как это подключить» — остальная часть статьи раскладывает каждый из этих элементов на составляющие.

Но сначала — срок, ведь именно от него зависит, когда всё должно быть готово. С 1 февраля 2026 года действует целевая версия системы: единственной принимаемой структурой фактуры является FA(3), а единственным работающим интерфейсом — API KSeF 2.0. Более старые FA(2) и API 1.0 выводятся из эксплуатации. Что важно для каждого продавца: обязанность принимать фактуры в KSeF касается всех налогоплательщиков уже с февраля 2026 — даже если сами выставлять вы обязаны только с апреля.

Пороги и даты приводим ориентировочно — прежде чем планировать внедрение, проверьте их в актуальном законе и на ksef.podatki.gov.pl. Если вы только разбираетесь в теме с деловой стороны, начните с нашего обзора KSeF 2026 для продавцов e-commerce, а здесь сосредоточьтесь на технической стороне.

Аутентификация: токен, сертификат KSeF или печать

Прежде чем система что-либо отправит, она должна доказать KSeF, что действует от имени вашей компании. Здесь работают три связанных понятия: аутентификация (кто вы), авторизация (какие у вас права) и ключ для автоматизации (чем вы подписываете последующие запросы к API). Порядок жёсткий: владелец компании сначала входит «сильным» методом, назначает права, и только потом генерирует токен или сертификат для интеграции.

Этим «сильным» методом первого входа является Profil Zaufany, квалифицированная электронная подпись (физическое лицо, по PESEL/NIP) или квалифицированная электронная печать (организация, по NIP). Весь этот процесс обслуживает Модуль сертификатов и прав (MCU), запущенный 1 ноября 2025 года.

Права назначаются отдельно для разных действий — обычно разделяют право на выставление фактур, на их просмотр и приём, а также на управление правами (административная роль). Интеграции системы продаж нужно право на выставление и приём, привязанное к субъекту или лицу, от имени которого вы сгенерируете токен или сертификат. Определите заранее, кто в компании является владельцем этой конфигурации — именно он разблокирует и заблокирует доступ, когда вы смените поставщика программного обеспечения.

Авторизационный токен KSeF

Это самый удобный метод для интеграции «система к системе». Токен вы генерируете один раз (после аутентификации сильным методом), а затем он служит для подписи последующих запросов к API — без обращения к подписи или сертификату каждый раз. Две вещи, о которых нужно помнить: токены из KSeF 1.0 не работают в KSeF 2.0 (нужно сгенерировать новый), а сами токены 2.0 теряют силу 31 декабря 2026 года. С 1 января 2027 их заменяют сертификаты KSeF. Поэтому относитесь к токену как к переходному решению — и как к секрету: держите вне репозитория кода, ротируйте и ограничивайте доступ.

Сертификат KSeF (тип 1 и тип 2)

Сертификаты KSeF доступны из MCU с 1 ноября 2025 года, действительны максимум 2 года и продлеваются. Это не квалифицированный сертификат в понимании eIDAS, но он признаётся внутри KSeF. Существует в двух типах: тип 1 выполняет функцию аутентификации (как подпись/печать при обращении к API), а тип 2 служит для цифровой подписи QR-кодов на фактурах, выставляемых в офлайн-режиме. Это целевое решение — если вы строите интеграцию на годы, стоит сразу опереть её на сертификат тип 1, а не на истекающий токен.

Печать, квалифицированная подпись и Profil Zaufany

Эти методы служат в основном для первого входа и назначения прав. Квалифицированная электронная печать аутентифицирует всю организацию (по NIP), а не конкретное лицо — удобно для компании, в которой интеграцию сопровождают несколько человек. Profil Zaufany — самый простой путь для индивидуального предпринимателя.

Структура FA(3): что меняется по сравнению с FA(2)

С 1 февраля 2026 единственной обязательной структурой фактуры является FA(3). Если ваша система сегодня генерирует XML в FA(2), нужно обновить маппинг. Важнейшие отличия:

• Бинарные вложения — к фактуре можно приложить, например, акт приёмки или спецификацию (в FA(2) это было невозможно).
• Новая роль «работник» в узле Podmiot3.
• Уточнённые поля сроков оплаты — больше точности при рассроченных и множественных сроках.
• Расширенные лимиты символов в названиях товаров и услуг (поле P_7).
• Поддержка JST (органов местного самоуправления) и групп НДС — новые сценарии по субъектам.

Ключевое правило: сгенерированный XML должен точно 1:1 соответствовать схеме XSD, опубликованной Министерством финансов. Малейшее несоответствие означает отклонение фактуры, а отклонённая фактура не получает номер KSeF — то есть с точки зрения системы не существует. Поэтому не «склеивайте» XML вручную: используйте библиотеку или слой маппинга данных заказа на структуру и валидируйте локально относительно XSD перед отправкой. Актуальную XSD FA(3), спецификацию OpenAPI (Swagger), руководство интегратора, а также готовые SDK (Java, .NET) и примеры кода вы скачаете с ksef.podatki.gov.pl. Отдельный, частый в e-commerce случай — фактуры к заказам с marketplace и чеков — мы описываем в тексте KSeF и продажи на Allegro.

На практике больше всего отклонений возникает не из-за экзотических полей, а из-за основ: ошибочный или отсутствующий NIP покупателя, ставка НДС, не соответствующая позиции, неверный формат даты или суммы, которые не сходятся до копейки. Позаботьтесь также о корректирующих и авансовых фактурах — в FA(3) у них свои правила, а в e-commerce они появляются при возвратах и предоплатах. Смапьте эти случаи сразу, вместо того чтобы добавлять их потом «на продакшене».

Тестовая среда KSeF 2.0 — тестируйте, прежде чем запускать продакшн

Министерство финансов предоставляет три среды. Здоровый сценарий такой: сначала тестовая (разработка), потом предпродакшн (приёмка), в конце продакшн. Не начинайте с продакшна — там фактуры имеют реальные юридические последствия.

В тестовой среде можно использовать самоподписанные (self-signed) сертификаты и сгенерировать токен без «настоящих» документов, а тестовые действия не влияют на права и производственные сертификаты. Если у вас пока нет собственной интеграции, для ручной проверки подойдёт бесплатное приложение Aplikacja Podatnika KSeF 2.0 от MF, у которого также есть тестовая версия (выпущена осенью 2025). Адреса приводим ориентировочно — всегда подтверждайте их на ksef.podatki.gov.pl, потому что детали сред иногда обновляются.

Шаг за шагом: подключение системы через API

Приведённая ниже последовательность предполагает, что у вас уже есть система продаж, которая знает данные заказов и покупателей. Задача интеграции — перевести эти данные на язык KSeF и получить подтверждение. Пройдите шаги по порядку — пропуск прав или локальной валидации — самая частая причина «застревания» на первой отправке.

1. Наведите порядок в правах в MCU. Владелец входит сильным методом (печать / подпись / Profil Zaufany) и назначает права — например, на выставление и приём фактур — нужным лицам и субъектам. Без этого ни токен, ни сертификат не сработают.
2. Сгенерируйте ключ для автоматизации. В MCU создайте авторизационный токен или сертификат KSeF тип 1. Сохраните секрет в безопасном месте (менеджер секретов, переменные окружения), никогда в коде.
3. Скачайте материалы для интеграции. Спецификация OpenAPI, схемы XSD для FA(3), SDK и руководство интегратора находятся на ksef.podatki.gov.pl.
4. Настройте тестовую среду. Задайте базовый URL на тестовый адрес и реализуйте поток challenge → подпись → токен: система получает вызов (challenge), подписывает его и в обмен получает доступ к сессии.
5. Откройте сессию в нужном режиме. Интерактивная сессия — это отдельные фактуры с немедленной валидацией (документ до ок. 1 МБ). Пакетная (batch) сессия — это набор из множества фактур, отправляемый как ZIP-архив, разбитый на части — хороша для больших объёмов, типичных для e-commerce.
6. Отправьте фактуру FA(3). Смапьте данные заказа на XML FA(3), провалидируйте локально относительно XSD, а затем отправьте в открытой сессии.
7. Получите номер KSeF и UPO. После успешной валидации система присваивает номер KSeF (35 символов), возвращаемый в UPO — официальном подтверждении приёма. Запрашивайте статус (ориентировочно: 150 = в процессе, 200 = принято) и сохраняйте номер KSeF и UPO при заказе.
8. Обработайте ошибки и повторы. Отклонённая фактура не имеет номера KSeF — исправьте XML и отправьте заново. Постройте очередь повторов и лог ответов, чтобы ничего не пропало при временных сбоях.
9. Перейдите на демо, потом на продакшн. Повторите тесты в предпродакшн-среде, а после соответствующего срока (1 февраля или 1 апреля 2026) переключите конфигурацию на продакшн.

Если вы хотите, чтобы фактура создавалась сама после смены статуса заказа (например, «оплачено» или «отправлено»), рассматривайте подключение к KSeF как часть более широкой автоматизации заказов — иначе вы добавите команде ручной работы, вместо того чтобы её убавить.

Режимы работы: онлайн, offline24 и аварийный

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

• Онлайн (основной) — фактура попадает в KSeF сразу, номер KSeF вы получаете немедленно.
• Offline24 — вы выставляете фактуру без подключения (префикс OFF, два QR-кода, второй подписан сертификатом продавца) и передаёте её в KSeF не позднее следующего рабочего дня.
• Аварийный — запускается официальным сообщением MF во время сбоя системы; фактуры вы досылаете в окне до 7 рабочих дней с момента окончания сбоя (сроки ориентировочные — проверьте при внедрении).

Практический вывод: заранее предусмотрите поддержку офлайн-режима в коде, чтобы сбой на стороне KSeF не остановил выставление фактур и отгрузки в магазине.

Сопровождение интеграции: что запланировать на перспективу

Подключение к KSeF — это не разовый проект, а элемент, который нужно сопровождать. Запланируйте заранее несколько вещей. Во-первых — ротацию секретов: токен истекает в конце 2026 года, а сертификат действует до двух лет, поэтому вам нужен календарь продлений, чтобы интеграция не встала в один день. Во-вторых — мониторинг статусов: каждая отправка должна завершаться подтверждённым номером KSeF, а всё, что застряло «в процессе» или было отклонено, должно попадать в видимый список для обработки. В-третьих — логи и архивацию: храните отправленный XML, номер KSeF и UPO, потому что это ваше доказательство выставления в случае проверки. В-четвёртых — среду для регрессии: когда MF обновит схему или API, проверьте изменение в тестовой среде, прежде чем оно затронет продакшн.

Самые частые ошибки при подключении (чек-лист)

• Использование старого токена из KSeF 1.0 — не сработает в 2.0, сгенерируйте новый.
• Ручное склеивание XML вместо маппинга — мелкая ошибка означает отклонение и отсутствие номера KSeF.
• Тесты сразу на продакшене — начните с тестовой среды.
• Отсутствие назначенных прав в MCU перед генерацией токена.
• Отношение к токену как к постоянному решению — помните об истечении 31.12.2026 и переходе на сертификат.
• Несохранение номера KSeF и UPO при заказе — это ваше доказательство выставления.
• Игнорирование обязанности приёма — касается всех уже с февраля 2026.
• Отсутствие плана на сбой и офлайн-режим.

Для магазина, продающего на нескольких каналах, самое трудное — не само API, а его связка с остальным потоком: заказ с Allegro или Shopify, корректные данные покупателя, правильная ставка НДС и выставление FA(3) в нужный момент. Инструменты класса multichannel — в том числе готовящийся Nimo — со временем должны брать этот поток на себя, чтобы продавцу не приходилось сопровождать собственную интеграцию с KSeF; как должна выглядеть такая обработка фактур KSeF, мы описываем отдельно. Независимо от выбора инструмента правило одно и то же: протестируйте всё в тестовой среде, прежде чем фактуры начнут иметь юридические последствия.

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

Нужен ли мне сертификат или достаточно токена?

До конца 2026 года авторизационного токена достаточно для автоматизации через API. С 1 января 2027 токены истекают, и их заменяют сертификаты KSeF, поэтому интеграцию, строящуюся на годы, стоит сразу опереть на сертификат тип 1.

Чем отличается FA(3) от FA(2)?

FA(3) — единственная обязательная структура с 1 февраля 2026. Она добавляет, среди прочего, бинарные вложения и роль «работник», уточняет поля сроков оплаты и расширяет лимиты символов. Фактура должна точно соответствовать схеме XSD MF, иначе будет отклонена.

Где тестировать интеграцию?

Начните в тестовой среде KSeF 2.0 (ориентировочно api-test.ksef.mf.gov.pl и приложение ap-test.ksef.mf.gov.pl), а потом перейдите на предпродакшн (демо). Тестовые действия не влияют на производственные данные. Актуальные адреса подтвердите на ksef.podatki.gov.pl.

Что такое номер KSeF и UPO?

Номер KSeF — это уникальный идентификатор (35 символов), присваиваемый после успешной валидации — он подтверждает, что фактура находится в обороте. UPO — это официальное подтверждение приёма, в котором возвращается этот номер. Оба сохраняйте при заказе как доказательство выставления.

С какого момента я обязан выставлять фактуры в KSeF?

Крупнейшие (оборот брутто свыше 200 млн злотых в 2024 г.) — с 1 февраля 2026, остальные предприниматели — с 1 апреля 2026, а самые мелкие выставители — с 1 января 2027. Приём фактур в KSeF обязателен для всех уже с февраля 2026.