Перейти до вмісту

Технічне завдання: Передача звітності з K2 ERP до Електронного кабінету ДПС

Матеріал з K2 ERP Wiki Ukraine — База знань з автоматизації та санкцій в Україні

SEO title: Технічне завдання: Передача звітності з K2 ERP до Електронного кабінету ДПС SEO description: Технічне завдання на реалізацію ручного та автоматизованого сценарію передачі податкової звітності з K2 ERP до Електронного кабінету ДПС України. SEO keywords: K2 ERP, K2 Cloud ERP, ДПС, електронний кабінет, податкова звітність, API ДПС, КЕП, XML, квитанції, технічне завдання Alternative to:


Технічне завдання: Передача звітності з K2 ERP до Електронного кабінету ДПС

Головна ідея: реалізувати в K2 ERP два варіанти подання звітності до ДПС: ручний експорт XML для подальшого подання користувачем та автоматизовану передачу через API Електронного кабінету ДПС.

Важливо: автоматизований сценарій потребує формування XML за актуальними XSD-схемами ДПС, підписання КЕП, шифрування, передачі через API та обробки квитанцій.

1. Мета

Метою задачі є розробка механізму передачі податкової звітності з K2 ERP до Електронного кабінету ДПС України.

Система повинна підтримувати два сценарії:

№ Сценарій Опис
1 Ручний K2 ERP формує XML-файл звітності, користувач завантажує його та самостійно подає через Електронний кабінет ДПС або інше офіційне ПЗ.
2 Автоматизований K2 ERP формує XML, підписує КЕП, шифрує, передає через API ДПС та отримує квитанції.

2. Область застосування

Функціонал використовується для підготовки та передачі податкової звітності з K2 ERP.

До області задачі входить:

  • формування XML-документів звітності;
  • перевірка XML перед поданням;
  • експорт XML для ручного подання;
  • завантаження квитанцій вручну;
  • підписання XML за допомогою КЕП;
  • шифрування XML;
  • передача звітності через API ДПС;
  • отримання квитанцій;
  • ведення статусів звіту;
  • журналювання дій користувачів та системи.

До першої версії може не входити:

  • повна підтримка всіх форм звітності;
  • автоматичне оновлення всіх XSD-схем;
  • підтримка всіх КНЕДП;
  • підтримка всіх варіантів хмарного КЕП;
  • повноцінний податковий календар.

3. Передумови

Для реалізації задачі необхідно мати:

  • довідник платників податків у K2 ERP;
  • реквізити ФОП або юридичної особи;
  • код контролюючого органу ДПС;
  • актуальні форми звітності;
  • XSD-схеми для відповідних форм;
  • правила іменування XML-файлів;
  • механізм роботи з КЕП;
  • актуальні сертифікати ДПС для шифрування;
  • доступ до API Електронного кабінету ДПС.

4. Терміни та скорочення

Термін Опис
K2 ERP ERP-система, з якої формується та передається звітність.
ДПС Державна податкова служба України.
Електронний кабінет Офіційний електронний сервіс ДПС для платників податків.
XML Формат електронного документа звітності.
XSD Схема перевірки структури XML-документа.
КЕП Кваліфікований електронний підпис.
Квитанція №1 Підтвердження отримання документа контролюючим органом.
Квитанція №2 Фінальний результат обробки звітності: прийнято або не прийнято.
API Програмний інтерфейс для автоматизованого обміну з ДПС.

5. Ролі користувачів

Роль Опис Основні права
Адміністратор Налаштовує інтеграцію та доступи. Налаштування API, сертифікатів, ролей, журналів.
Бухгалтер Формує та подає звітність. Створення звіту, перевірка, експорт, підписання, відправка.
Керівник Підписує звітність. Перегляд, підписання, контроль статусів.
ФОП Самостійно формує та подає власну звітність. Формування, підписання, подання, перегляд квитанцій.
Аудитор Перевіряє історію дій. Перегляд звітів, квитанцій, журналів.

6. User Story

6.1. Ручне подання звітності

Як бухгалтер або ФОП, я хочу сформувати XML-файл звітності в K2 ERP, щоб завантажити його та самостійно подати через Електронний кабінет ДПС.

6.2. Автоматизоване подання звітності

Як бухгалтер або ФОП, я хочу передати звітність до ДПС напряму з K2 ERP, щоб не виконувати ручний експорт, підписання та завантаження звіту в кабінет ДПС.

6.3. Отримання квитанцій

Як користувач K2 ERP, я хочу бачити квитанції ДПС безпосередньо в картці звіту, щоб контролювати, чи прийнята звітність.

6.4. Контроль помилок

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

7. Загальний бізнес-процес

K2 ERP
  |
  |-- Формування звітних даних
  |
  |-- Генерація XML
  |
  |-- Перевірка XML / XSD
  |
  |-- Сценарій 1: ручний експорт
  |       |
  |       |-- Користувач завантажує XML
  |       |-- Користувач подає XML через кабінет ДПС
  |       |-- Користувач завантажує квитанції в K2 ERP
  |
  |-- Сценарій 2: автоматизована передача
          |
          |-- Підписання КЕП
          |-- Шифрування
          |-- Передача через API ДПС
          |-- Отримання квитанцій
          |-- Оновлення статусу

8. Функціональні блоки

8.1. Довідник платника податків

У системі має бути довідник платника податків.

Мінімальний набір полів:

Поле Тип Обов'язковість Опис
Тип платника Довідник Так ФОП або юридична особа.
Податковий номер Рядок Так РНОКПП або ЄДРПОУ.
Назва / ПІБ Рядок Так Найменування юридичної особи або ПІБ ФОП.
Код ДПС Рядок Так Код контролюючого органу.
Система оподаткування Довідник Так Єдиний податок, загальна система, ПДВ тощо.
Група платника Довідник Ні Для ФОП на єдиному податку.
Відповідальна особа Користувач Ні Користувач, відповідальний за подання звітності.

8.2. Картка звіту

У K2 ERP має бути створена картка звіту.

Картка звіту повинна містити:

  • тип звіту;
  • звітний період;
  • платника;
  • контролюючий орган;
  • дату створення;
  • автора;
  • поточний статус;
  • XML-файл;
  • підписаний файл;
  • зашифрований файл;
  • квитанцію №1;
  • квитанцію №2;
  • журнал дій;
  • повідомлення про помилки.

8.3. Формування XML

Система повинна формувати XML-документ на основі:

  • даних платника;
  • даних обліку в K2 ERP;
  • вибраного звітного періоду;
  • вибраної форми звітності;
  • актуальної структури XML;
  • правил ДПС щодо іменування файлів.

8.4. Перевірка XML

Перед експортом або відправкою система повинна виконати перевірку:

Перевірка Опис
Обов'язкові поля Перевірити, що всі обов'язкові реквізити заповнені.
Податковий номер Перевірити формат РНОКПП або ЄДРПОУ.
Код ДПС Перевірити наявність контролюючого органу.
Період Перевірити коректність звітного періоду.
XML-структура Перевірити наявність потрібних тегів.
XSD Перевірити відповідність XML актуальній XSD-схемі.
Ім'я файлу Перевірити відповідність правилам ДПС.

9. Сценарій 1: ручне подання

9.1. Опис

Ручний сценарій призначений для випадків, коли K2 ERP формує XML, але не передає його напряму до ДПС.

Користувач самостійно подає файл через Електронний кабінет ДПС або інше офіційне ПЗ.

9.2. Послідовність дій

  1. Користувач відкриває розділ звітності.
  2. Створює новий звіт.
  3. Обирає тип звіту.
  4. Обирає звітний період.
  5. Натискає Сформувати XML.
  6. Система формує XML.
  7. Користувач натискає Перевірити.
  8. Система перевіряє XML.
  9. Користувач натискає Експортувати XML.
  10. Система завантажує XML-файл.
  11. Користувач подає файл через Електронний кабінет ДПС.
  12. Користувач отримує квитанції.
  13. Користувач завантажує квитанції в K2 ERP.
  14. Система оновлює статус звіту.

9.3. Кнопки інтерфейсу

Кнопка Опис
Створити звіт Створює нову картку звіту.
Сформувати XML Генерує XML-файл.
Перевірити Запускає перевірку XML.
Експортувати XML Завантажує XML-файл користувачу.
Завантажити квитанцію Додає квитанцію до картки звіту.
Позначити як подано вручну Змінює статус документа після ручного подання.

9.4. Статуси ручного сценарію

Статус Опис
Чернетка Звіт створено, але XML ще не сформовано.
XML сформовано XML-файл створено.
XML перевірено XML пройшов внутрішню перевірку.
Експортовано Користувач завантажив XML.
Подано вручну Користувач підтвердив ручне подання.
Квитанція №1 отримана До звіту додано першу квитанцію.
Прийнято Отримано позитивну квитанцію №2.
Не прийнято Отримано негативну квитанцію.
Потребує виправлення Звіт містить помилки.

10. Сценарій 2: автоматизоване подання через API

10.1. Опис

Автоматизований сценарій призначений для передачі звітності до ДПС без ручного завантаження XML у кабінет.

У цьому сценарії K2 ERP виконує:

  • формування XML;
  • перевірку XML;
  • підписання КЕП;
  • шифрування;
  • формування Base64;
  • передачу через API;
  • отримання квитанцій;
  • оновлення статусів.

10.2. Послідовність дій

  1. Користувач створює звіт.
  2. Система формує XML.
  3. Система перевіряє XML.
  4. Користувач обирає КЕП.
  5. Система підписує XML.
  6. Система шифрує XML для ДПС.
  7. Система формує Base64-контейнер.
  8. Система надсилає звіт через API ДПС.
  9. Система отримує відповідь API.
  10. Система зберігає ідентифікатор документа.
  11. Система запитує квитанції.
  12. Система оновлює статус звіту.

10.3. Endpoint для відправки одного звіту

POST https://cabinet.tax.gov.ua/cabinet/public/api/exchange/report

Тип запиту:

Content-Type: application/json

Логічна структура тіла запиту:

[
  {
    "fname": "назва_файлу_згідно_правил_ДПС.xml",
    "contentBase64": "BASE64_ПІДПИСАНИЙ_ТА_ЗАШИФРОВАНИЙ_XML"
  }
]

10.4. Endpoint для пакетного подання

POST https://cabinet.tax.gov.ua/cabinet/public/api/exchange/reportzip

Логічна структура тіла запиту:

{
  "zipBase64": "BASE64_АРХІВ_ЗІ_ЗВІТАМИ"
}

10.5. Endpoint для отримання квитанцій

POST https://cabinet.tax.gov.ua/cabinet/public/api/exchange/kvt_by_id

Логічна структура тіла запиту:

{
  "encryptedId": "ІДЕНТИФІКАТОР_ДОКУМЕНТА"
}

10.6. Статуси автоматизованого сценарію

Статус Опис
Чернетка Звіт створено.
XML сформовано XML-документ створено.
XML перевірено XML пройшов перевірку.
Підписано XML підписано КЕП.
Зашифровано XML зашифровано для ДПС.
Готово до відправки Сформовано Base64-контейнер.
Передано до ДПС Запит до API успішно виконано.
Очікується квитанція №1 Система очікує первинну квитанцію.
Квитанція №1 отримана ДПС підтвердила отримання документа.
Очікується квитанція №2 Система очікує фінальну квитанцію.
Прийнято Звіт прийнято ДПС.
Не прийнято Звіт відхилено ДПС.
Помилка API Виникла помилка під час API-обміну.
Помилка КЕП Виникла помилка підписання.
Помилка шифрування Виникла помилка шифрування.

11. Вимоги до КЕП

11.1. Загальні вимоги

Система повинна підтримувати підписання XML-документів за допомогою КЕП.

Мінімальні вимоги:

  • вибір ключа користувачем;
  • введення пароля до ключа;
  • перевірка строку дії сертифіката;
  • перевірка належності сертифіката платнику;
  • підписання XML;
  • збереження інформації про підписанта;
  • журналювання факту підписання.

11.2. Типи підписантів

Тип платника Підписанти
ФОП КЕП ФОП.
Юридична особа КЕП директора, бухгалтера, печатки — залежно від вимог форми.

11.3. Зберігання пароля

Заборонено: зберігати пароль КЕП у відкритому вигляді.

За замовчуванням пароль КЕП має вводитися користувачем під час підписання.

12. Вимоги до шифрування

Після підписання XML має бути зашифрований для передачі до ДПС.

Система повинна:

  • використовувати актуальні сертифікати ДПС;
  • перевіряти строк дії сертифікатів;
  • шифрувати підписаний XML;
  • формувати транспортний контейнер;
  • кодувати результат у Base64;
  • зберігати дату та результат шифрування.

13. Журналювання

Усі дії зі звітністю повинні записуватися в журнал.

Подія Дані журналу
Створення звіту Користувач, дата, тип звіту, період.
Формування XML Дата, форма, версія, результат.
Перевірка XML Результат, список помилок.
Експорт XML Користувач, дата, назва файлу.
Підписання Підписант, сертифікат, дата.
Шифрування Дата, сертифікат ДПС, результат.
Відправка API Endpoint, HTTP-код, час відповіді.
Отримання квитанції Тип квитанції, дата, статус.
Помилка Етап, код, опис, користувач.

14. Обробка помилок

14.1. Помилки даних

Приклади:

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

14.2. Помилки XML

Приклади:

  • XML не відповідає XSD;
  • відсутній обов'язковий тег;
  • неправильна структура XML;
  • неправильне ім'я файлу;
  • використовується застаріла форма звіту.

14.3. Помилки КЕП

Приклади:

  • ключ не знайдено;
  • неправильний пароль;
  • сертифікат прострочено;
  • сертифікат не відповідає платнику;
  • користувач не має права підпису.

14.4. Помилки API

Приклади:

Код / тип Опис
401 Неавторизований запит.
403 Доступ заборонено.
404 Endpoint або ресурс не знайдено.
500 Внутрішня помилка сервера.
Timeout Перевищено час очікування відповіді.
No receipt Квитанція ще не сформована.

15. Налаштування інтеграції

15.1. Налаштування API

Параметр Опис
API URL Базова адреса API ДПС.
Режим роботи Ручний або автоматизований.
Таймаут Час очікування відповіді API.
Кількість повторів Максимальна кількість повторних спроб.
Інтервал опитування Періодичність перевірки квитанцій.
Логування Рівень деталізації журналу.
Сертифікати ДПС Джерело актуальних сертифікатів.

15.2. Налаштування КЕП

Параметр Опис
Тип КЕП Файловий або хмарний.
Шлях до ключа Для файлового КЕП.
КНЕДП Надавач електронних довірчих послуг.
Пароль Вводиться користувачем.
Зберігання пароля Заборонено за замовчуванням.
Перевірка сертифіката Обов'язкова перед підписанням.

16. Нефункціональні вимоги

16.1. Безпека

Система повинна забезпечити:

  • розмежування прав доступу;
  • заборону зберігання паролів КЕП у відкритому вигляді;
  • маскування чутливих даних у логах;
  • захист XML-файлів;
  • захист квитанцій;
  • аудит операцій із КЕП;
  • контроль доступу до налаштувань API;
  • резервне копіювання звітів та квитанцій.

16.2. Надійність

Система повинна:

  • зберігати проміжні стани обробки;
  • не втрачати XML після помилки API;
  • дозволяти повторну відправку;
  • не дублювати звіт без підтвердження користувача;
  • фіксувати всі помилки в журналі.

16.3. Масштабованість

Система повинна дозволяти:

  • додавання нових форм звітності;
  • оновлення XSD-схем;
  • додавання нових сценаріїв підписання;
  • розширення списку API-методів;
  • підтримку пакетної передачі.

17. Acceptance Criteria

17.1. Ручний сценарій

№ Критерій Очікуваний результат
AC-1 Користувач створює звіт У системі створюється картка звіту.
AC-2 Користувач формує XML Система створює XML-файл.
AC-3 Користувач перевіряє XML Система показує результат перевірки.
AC-4 Користувач експортує XML XML-файл завантажується на комп'ютер.
AC-5 Користувач додає квитанцію Квитанція зберігається в картці звіту.
AC-6 Користувач фіксує результат подання Статус звіту змінюється на відповідний.

17.2. Автоматизований сценарій

№ Критерій Очікуваний результат
AC-7 Система формує XML XML створено відповідно до форми звітності.
AC-8 Система перевіряє XML XML проходить XSD-перевірку.
AC-9 Система підписує XML XML підписано КЕП.
AC-10 Система шифрує XML XML зашифровано для ДПС.
AC-11 Система формує Base64 Підготовлено тіло запиту для API.
AC-12 Система відправляє звіт API ДПС приймає запит.
AC-13 Система отримує квитанції Квитанції збережено в картці звіту.
AC-14 Система оновлює статус Статус відповідає результату обробки ДПС.
AC-15 Система журналює дії Усі етапи записані в журнал.

18. MVP

До MVP входить:

  • довідник платника;
  • картка звіту;
  • формування XML;
  • базова перевірка XML;
  • експорт XML;
  • ручне завантаження квитанцій;
  • статуси ручного сценарію;
  • журнал дій.

До MVP не входить:

  • автоматичне підписання КЕП;
  • автоматичне шифрування;
  • передача через API;
  • автоматичне отримання квитанцій;
  • пакетне подання.

19. Етапи реалізації

Етап 1. Ручний сценарій

  • створити довідник платника;
  • створити картку звіту;
  • реалізувати формування XML;
  • реалізувати перевірку XML;
  • реалізувати експорт XML;
  • реалізувати завантаження квитанцій;
  • реалізувати ручні статуси;
  • реалізувати журнал дій.

Етап 2. Напівавтоматичний сценарій

  • додати модуль КЕП;
  • реалізувати підписання XML;
  • реалізувати шифрування XML;
  • формувати Base64-контейнер;
  • дозволити експорт підписаного та зашифрованого документа.

Етап 3. Повна API-інтеграція

  • реалізувати відправку одного звіту через API;
  • реалізувати пакетну відправку;
  • реалізувати отримання квитанцій;
  • реалізувати автоматичне оновлення статусів;
  • додати повторні спроби;
  • додати моніторинг помилок;
  • додати адміністративну панель інтеграції.

20. Ризики

Ризик Опис Як зменшити
Зміна форм звітності ДПС може оновлювати форми та XSD. Передбачити механізм оновлення схем.
Помилки КЕП Можливі проблеми з ключами, паролями, сертифікатами. Додати перевірку сертифікатів до підписання.
Недоступність API API ДПС може бути тимчасово недоступним. Додати повторні спроби та журнал помилок.
Негативна квитанція Звіт може бути не прийнятий. Показувати текст помилки та дозволяти повторне формування.
Некоректне шифрування Документ може бути відхилений через неправильний контейнер. Використовувати актуальні сертифікати ДПС.

21. Відкриті питання

  1. Які форми звітності підтримуються першими?
  2. Чи потрібна підтримка тільки ФОП, чи також юридичних осіб?
  3. Чи є в K2 ERP існуючий модуль КЕП?
  4. Чи потрібна підтримка хмарного КЕП?
  5. Чи потрібно реалізовувати пакетне подання?
  6. Де зберігати XML та квитанції: БД, файлове сховище або DMS?
  7. Хто відповідає за оновлення форм і XSD?
  8. Хто відповідає за оновлення сертифікатів ДПС?
  9. Чи потрібен тестовий режим?
  10. Чи потрібно робити окрему роль для податкового консультанта?

22. Джерела

23. Див. також

Отримано з https://wiki.erp.kyiv.ua/index.php?title=Технічне_завдання:_Передача_звітності_з_K2_ERP_до_Електронного_кабінету_ДПС&oldid=960