Як перевірити статус рахунку в KSeF після надсилання?

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

Статуси 100 і 150 є перехідними, 200 означає успіх рахунку, а статуси помилок потребують прочитання деталей перед будь-яким повторним надсиланням. Не плутайте технічно успішну відповідь HTTP зі статусом рахунку в даних документа.

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

Після надсилання XML перевірте статус того самого рахунку або сесії, не надсилайте автоматично другу версію, при статусі 200 збережіть номер KSeF і UPO, а при помилці прочитайте код, опис і деталі відповіді перед наступним рішенням.

Рахунок надіслано до KSeF, але невідомо, чи його вже прийнято, чи він ще обробляється, чи його відхилено. Цей посібник проводить через рішення після надсилання - від перехідного статусу до номера KSeF, UPO або діагностики помилки.

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

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

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

В інтерактивній сесії можна відстежувати один документ, переданий у межах сесії. У пакетній сесії або при багатьох рахунках треба додатково перевірити, скільки документів пройшли правильно, скільки відхилено і які статуси мають окремі рахунки.

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

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

Нижче таблиця як практична карта рішень. Вона не замінює повну документацію API, але допомагає уникнути найчастіших помилок після надсилання XML.

Якщо статус рахунку 100 або 150, базова реакція - подальший контроль того самого надсилання. Не повідомляйте всередині компанії, що рахунок уже прийнято, але й не вважайте його автоматично відхиленим.

Якщо статус рахунку 200, переходьте до номера KSeF, дати прийняття і UPO. Це етап упорядкування підтверджень, а не пошуку причини помилки.

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

Не трактуйте статус сесії як автоматичне підтвердження успіху кожного документа. Сесія і рахунки мають окремі рівні контролю. Особливо в пакетах треба перевірити лічильники правильно і неправильно оброблених рахунків та список документів у сесії.

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

Відсутність UPO не є самостійною діагностикою. При статусах 100 і 150 UPO ще не є цільовою точкою, бо рахунок не має фінального результату.

При статусі 200 перевірте номер KSeF, створене посилання для UPO, строк дії посилання та інструмент, через який документ надіслано. Посилання для завантаження UPO є елементом статусної відповіді і може потребувати повторної перевірки статусу, якщо посилання втратило чинність.

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

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

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

Докладну процедуру діагностики знайдете в посібнику Рахунок відхилено KSeF.

У користувацькому процесі почніть з правильного суб’єкта. Виберіть правильний NIP продавця або контекст компанії, бо статус, прочитаний в іншому суб’єкті, не пояснить реальне надсилання.

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

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

В API-інтеграції статус перевіряють поетапно. Спочатку встановлюють сесію, потім документи в сесії, і лише після успіху конкретного рахунку переходять до UPO. UPO не замінює статус, а є наступним кроком після підтвердженого успіху.

Типові контрольні шляхи охоплюють список сесій, деталі конкретної сесії, список рахунків у сесії, деталі конкретного рахунку та список відхилених рахунків.

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

У KSeFGPT статус після надсилання має бути зрозумілим для людини, яка не хоче аналізувати сиру відповідь API. Після обробки надсилання застосунок допомагає побачити, чи документ передано до KSeF, який він має статус, чи доступний номер KSeF і чи для цього документа доступне UPO.

Це важливе розрізнення: KSeFGPT упорядковує статуси і підтвердження для рахунків, надісланих через цей застосунок. Не слід припускати, що інструмент завантажить UPO для кожного рахунку, який колись був надісланий іншим ERP або іншою інтеграцією. У такому випадку шукайте підтвердження в системі, яка виконала надсилання, в Aplikacja Podatnika KSeF або у власній API-інтеграції.

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

Найчастіші помилки виникають не через один складний код, а через змішування рівнів: HTTP, сесія, рахунок, референційний номер, номер KSeF і UPO.

Що означає статус 100 у KSeF? - Статус 100 означає, що рахунок прийнято до подальшої обробки. Це ще не фінальний успіх і не відхилення. Перевіряйте той самий рахунок або ту саму сесію, не надсилайте документ повторно.

Що означає статус 150 у KSeF? - Статус 150 означає, що обробка триває. На цьому етапі ще не шукайте UPO як фінальне підтвердження і не вважайте документ відхиленим.

Чи означає статус 200, що я маю номер KSeF? - Статус рахунку 200 означає успішну обробку рахунку. Тоді перевірте номер KSeF, дату прийняття і шлях до UPO. Не плутайте це з технічно успішною відповіддю HTTP від кінцевої точки API.

Чи означає статус сесії 200 успіх усіх рахунків? - Ні, так спрощувати не варто. Статус сесії потрібно читати разом зі списком рахунків, статусами документів і лічильниками правильних та неправильних рахунків. Якщо рахунків багато, контролюйте кожен документ окремо.

Чи відсутність UPO означає відхилення? - Не завжди. Відсутність UPO може означати обробку, неправильний контекст NIP, прострочене посилання, пошук у неправильній сесії, обмеження інструмента або відхилення. Спочатку перевірте статус і номер KSeF.

Чи референційний номер є номером KSeF? - Ні. Референційний номер ідентифікує технічну операцію, сесію або рахунок у сесії. Номер KSeF ідентифікує рахунок, прийнятий системою, і доступний лише після успіху документа.

Чи можна надіслати рахунок повторно, якщо статус не змінюється? - Не надсилайте автоматично другу версію лише тому, що статус залишається перехідним. Спочатку перевірте ту саму сесію, той самий рахунок, референційний номер і можливі дані дубліката.

Як перевірити відхилені рахунки в сесії? - В API-інтеграції перевірте список рахунків у сесії та кінцеву точку для відхилених рахунків. У користувацькому застосунку шукайте вид помилок, статус документа і деталі відповіді, а не лише повідомлення після натискання надсилання.

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

Якщо потрібен повний процес, почніть з Надсилання рахунків до KSeF. Після статусу успіху перейдіть до UPO в KSeF. Коли підтвердження не видно, скористайтеся посібником Немає UPO в KSeF. При помилці документа перейдіть до Рахунок відхилено KSeF.