Коди помилок KSeF

Огляд

Коли KSeF відмовляється прийняти запит, він повертає числовий код помилки — коротке позначення на кшталт 21115 або 21901. Один і той самий код означає одну й ту саму причину незалежно від того, якою програмою ви користуєтесь: власним порталом KSeF, Biurko чи будь-яким іншим сервісом. Тому код зручніше гуглити й обговорювати з підтримкою, ніж довільний текст повідомлення, який кожна програма формулює по-своєму.

Ця сторінка групує коди за змістом — окремо проблеми входу, окремо прав доступу, окремо помилки в самому документі — і для кожного пояснює, що сталося, коли так буває і що з цим робити. Знайдіть свій код за номером або погляньте на групу, до якої він належить.

Авторизація і сесія

Ця група — про сам процес підключення до KSeF: токени, сертифікат і сесію, яку він відкриває. Здебільшого причина в тому, що з'єднання застаріло, зайняте або було розірвано не так, як очікував KSeF.

21100 — невірний токен авторизації

KSeF не визнав токен, яким програма намагається підтвердити з'єднання: він або спотворений, або виданий для іншого середовища (наприклад, тестового замість робочого). Найчастіше це наслідок неправильно скопійованого значення чи плутанини між середовищами KSeF. Перевірте, що використовується токен саме того середовища, з яким ви працюєте, і спробуйте підключення заново.

21115 — сертифікат відхилено

Це найпоширеніша і водночас найменш очевидна помилка з усього списку, тож варто розібрати її детальніше. KSeF відмовляється прийняти сертифікат, яким програма намагається авторизуватися, і причина може бути однією з трьох:

• Сертифікат не зареєстрований у KSeF. Його потрібно спершу додати через портал KSeF (розділ управління автентифікацією), інакше система його просто не впізнає.
• NIP у сертифікаті не збігається з NIP компанії, від імені якої йде запит. Так буває, коли сертифікат випущений на іншу фірму або підписаний не тим ключем, з яким пов'язана поточна компанія.
• Для цього сертифіката вже відкрита інша активна сесія KSeF. KSeF не дозволяє відкрити другу сесію тим самим сертифікатом, поки перша не закрита чи не закінчилася.

Що робити: перевірте в порталі KSeF, що сертифікат зареєстрований і належить правильному NIP, і переконайтесь, що жодна інша програма чи вкладка зараз не тримає активну сесію з тим самим сертифікатом. Якщо сумніваєтесь, яка саме з трьох причин ваша, — почніть з найпростішої перевірки: чи не залишилась відкритою стара сесія деінде.

21175 — виклик KSeF закінчився

При підключенні KSeF надсилає програмі короткочасний "виклик" (challenge), який потрібно підписати протягом обмеженого часу. Якщо це вікно пропущено — через паузу, повільне з'єднання чи очікування підпису сертифіката, — виклик втрачає чинність. Рішення просте: почніть підключення заново, не розтягуючи процес підпису.

21177 — сесія вже відкрита для цього сертифіката

KSeF дозволяє лише одну активну сесію на сертифікат одночасно. Якщо попереднє з'єднання не було коректно закрито (наприклад, програма аварійно завершилась або вкладку закрили без виходу), KSeF усе ще вважає ту сесію живою і не відкриває нову. Варіанти:

• зачекати, поки попередня сесія завершиться сама за таймаутом;
• або явно від'єднати старе з'єднання (якщо є доступ до нього) і підключитися знову.

21178 — сесія не існує або закрита

Програма намагається щось зробити (наприклад, надіслати рахунок) із сесією, якої KSeF уже не знає: вона закінчилася за часом, була закрита вручну або ніколи не відкривалась успішно. Треба просто відкрити нову сесію — стару відновити не можна.

21179 — перевищено ліміт відкритих сесій

KSeF обмежує кількість одночасно відкритих сесій. Якщо ліміт вичерпано — зазвичай через накопичені, але не закриті попередні з'єднання, — нову сесію відкрити не вдасться. Найчастіше допомагає просто зачекати кілька хвилин, поки старі сесії закінчаться за таймаутом, і повторити спробу.

21401 — токен сесії недійсний або закінчився

На відміну від 21100 (токен авторизації для входу), тут ідеться про токен уже відкритої сесії, яким підписуються запити всередині неї. Він міг закінчитися за часом або бути виданий для сесії, яка вже завершилась. Рішення — підключитися заново: перший вхід видасть нову сесію з новим токеном.

21402 — токен сесії відкликано

Токен сесії було скасовано — найчастіше тому, що сесію закрили вручну (наприклад, через портал KSeF або натиснувши "від'єднати" в програмі), поки він ще використовувався десь ще. Продовжувати роботу зі скасованим токеном не можна; потрібне нове підключення.

21404 — особа в токені не відповідає ініціатору сесії

Токен, яким підписано запит, виданий на іншу особу чи інший сертифікат, ніж той, що відкривав сесію. Зазвичай це ознака переплутаних облікових даних між кількома підключеннями чи середовищами, а не разова випадковість. Перевірте, що для сесії й для підпису запитів усередині неї використовується один і той самий сертифікат.

Права доступу

Ці коди означають, що з'єднання з KSeF відкрито успішно, але у вашого сертифіката чи облікового запису бракує конкретного дозволу для дії, яку ви намагаєтесь виконати.

21330 — немає права виставляти рахунок від імені продавця

Щоб надсилати рахунки до KSeF від імені компанії, потрібне явне право "виставлення рахунків", надане в порталі KSeF цьому сертифікату чи особі. Без нього запит на надсилання відхиляється незалежно від того, наскільки коректний сам документ. Перевірте перелік прав у порталі KSeF (розділ управління доступом для компанії) або зверніться до адміністратора компанії, який може їх надати.

21331 — немає права читати рахунки для цього NIP

Аналогічно попередньому, але для читання: у сертифіката немає дозволу переглядати рахунки компанії з указаним NIP. Це трапляється, коли сертифікат зареєстрований на іншу компанію або йому не надали право на перегляд, а лише на виставлення. Виправляється так само — наданням потрібного права в порталі KSeF.

Перевірка структури документа

Ці коди повертає перевірка самого файлу рахунка ще до того, як KSeF розглядає його зміст по суті. Причина завжди в тому, як сформовано XML-документ, а не в бізнес-логіці операції.

21301 — рахунок не пройшов XSD-валідацію

Файл рахунка не відповідає офіційній XML-схемі (XSD), яку вимагає KSeF: пропущений обов'язковий елемент, неправильний порядок полів або невірний тип значення. Це загальна помилка структури — вона не вказує на конкретне поле, а сигналізує, що документ у цілому невалідний. Потрібно перевірити структуру XML відповідно до чинної схеми FA(3) чи іншої актуальної версії.

21302 — невірний формат номера рахунку

Номер рахунка не відповідає формату, який очікує KSeF (наприклад, містить недопустимі символи або перевищує допустиму довжину). Перевірте, за яким шаблоном формується номер, і приведіть його у відповідність до вимог схеми.

21303 — відсутнє обов'язкове поле

В документі не заповнене одне з полів, обов'язкових за схемою KSeF. Найчастіше причина — неповні дані контрагента чи позиції рахунка ще на етапі формування документа в програмі, до відправлення. Перевірте, чи всі обов'язкові реквізити (дані продавця й покупця, дати, позиції) заповнені перед надсиланням.

21304 — невірний NIP покупця або продавця

Значення NIP у документі не відповідає формату (наприклад, невірна кількість цифр чи контрольна сума) або не заповнене там, де це обов'язково. Перевірте правильність NIP обох сторін операції в даних рахунка.

21305 — невірна дата виставлення

Дата виставлення рахунка не відповідає вимогам KSeF — наприклад, вона в майбутньому, у неприпустимо форматованому вигляді, чи випадає поза допустимим періодом для відправлення. Перевірте дату документа перед повторним надсиланням.

21306 — невірні значення ставок ПДВ

Вказана ставка ПДВ не входить до переліку значень, які дозволяє схема KSeF (наприклад, помилка в числі або невідповідність типу операції). Звірте застосовану ставку з переліком чинних ставок ПДВ і типом товару чи послуги.

21307 — невірний код валюти

Код валюти в документі не відповідає стандарту, який очікує KSeF (тризначний код ISO, наприклад PLN чи EUR). Найчастіше причина — одруківка в коді або використання застарілого позначення.

21308 — відсутня хоча б одна позиція на рахунку

Документ не містить жодного рядка товарів чи послуг, хоча KSeF вимагає щонайменше одну позицію в кожному рахунку. Перевірте, що список позицій рахунка не порожній перед відправленням.

21309 — невірний курс валюти

Якщо рахунок виставлено у валюті, відмінній від злотого, документ має містити курс перерахунку, і цей курс має відповідати вимогам схеми (додатне число в очікуваному форматі). Помилка виникає, коли курс відсутній там, де обов'язковий, або вказаний у невірному вигляді.

21310 — контрольна сума рахунку (HashFA) не збігається

Кожен документ несе власну контрольну суму (хеш HashFA), яку KSeF перераховує і звіряє із зазначеною в файлі. Розбіжність означає, що вміст документа змінили після обчислення хешу — навіть незначне редагування XML після підпису призводить до цієї помилки. Документ потрібно сформувати й підписати заново, без ручних правок файлу між цими кроками.

Логіка документа

Ці коди повертаються тоді, коли зі структурою файлу все гаразд, але сама операція суперечить стану, який KSeF уже знає про цей рахунок чи його номер.

21501 — рахунок з таким номером уже надіслано

KSeF уже отримав і зареєстрував рахунок із таким самим номером раніше — повторне надсилання того самого документа неможливе. Якщо це не помилкова повторна відправка, а потреба щось виправити — на це є не повторне надсилання, а корегувальний документ.

21502 — номер KSeF не існує в системі

Запит посилається на номер KSeF, якого система не знає: він або невірно вказаний, або належить середовищу, відмінному від того, з яким зараз працює програма (наприклад, тестовому замість робочого). Перевірте номер і середовище запиту.

21503 — коригований рахунок не існує в KSeF

Ви намагаєтеся подати корегувальний документ до оригінального рахунка, якого KSeF не знаходить за вказаним номером KSeF. Найчастіша причина — помилка в номері оригіналу або спроба скоригувати рахунок, який ще не був успішно прийнятий системою раніше. Перевірте номер KSeF оригінального документа.

21504 — рахунок уже скориговано до нуля

Оригінальний рахунок уже має корекцію, яка звела його суму до нуля, — а такий документ вважається закритим і подальших корекцій не приймає. Якщо потрібна ще одна зміна, варто перевірити історію корекцій цього рахунка: ймовірно, її вже зробили раніше.

Недоступність і аварії

Ці три коди не пов'язані з конкретним документом чи правом доступу — вони описують стан самого KSeF як сервісу.

21900 — KSeF тимчасово недоступний

Сервіс KSeF на короткий час не відповідає — це разовий збій на боці державної системи, а не помилка у вашому запиті чи документі. У Biurko такі відправлення стають в чергу і повторюються автоматично, тому додаткових дій зазвичай не потрібно: варто лише зачекати.

21901 — активний аварійний режим KSeF

KSeF офіційно перейшов в аварійний режим — тоді закон дозволяє виставляти рахунки офлайн і досилати їх до системи вже після відновлення роботи сервісу. Строк досилання залежить від того, який режим оголошено:

• у режимі offline24 рахунок треба надіслати до KSeF не пізніше наступного робочого дня після дня виставлення (назва режиму не означає «протягом 24 годин»);
• у аварійному режимі, оголошеному повідомленням Міністерства фінансів, на надсилання дається 7 робочих днів від моменту закінчення аварії.

Поки триває аварійний режим, самé виставлення рахунка не блокується — обмежена лише його передача до KSeF, і про цей крок подбає програма, коли сервіс відновиться.

21999 — неочікувана помилка KSeF

Це загальний код на випадок, коли KSeF повернув відмову, яка не підпадає під жодну відому категорію. Тут немає універсальної інструкції з виправлення: якщо помилка повторюється, варто звернутися до адміністратора чи в підтримку з деталями запиту, який її спричинив.

Чого в цьому списку немає

Цей перелік охоплює 28 кодів, які розпізнає й окремо обробляє Biurko. KSeF може повернути й інший код, якого тут немає, — у такому разі варто орієнтуватися на текст повідомлення, яке прийшло разом із кодом, і за потреби звертатися до служби підтримки KSeF або адміністратора компанії. Список на цій сторінці буде поповнюватися в міру появи нових кодів у практиці.