Технічне завдання: передача документів для звітності в податкову через Приват24 для Python

pass

9.; |}

docker-compose.yml

!; |- | Audit Logger | Фіксує всі дії користувачів і системи.; Очікуваний результат

11.4.; актуалізація статусу

"status": "ReadyToSend",

я хочу передати документ звітності в Приват24 без ручного завантаження,

Етап 2.; Робота з документами

|- | taxpayer_id | string | Так | РНОКПП або ЄДРПОУ платника.; Призначення

1. Отримати документ із локальної БД.; }

services/

POST /api/v1/tax-reports

audit_logger.log(
- xml
"privat24_document_id": response.id,

|- | SentToPrivat24 | кожні 5 хвилин |- | WaitingForSignature | кожні 15 хвилин |- | SentToTax | кожні 10 хвилин |- | WaitingForTaxReceipt | кожні 10 хвилин |- | Accepted / Rejected | не перевіряти |}

платформа повинна логувати:

models.py

18.1.; Змінні середовища

!; |}

Попередній логічний мапінг:

file_storage.py
def download_receipts(self, document_id: str) -> list [bytes]:

!; |- | Cancelled | Документ скасовано.; Статус документа

for report in reports:

</syntaxhighlight>

pyproject.toml

</syntaxhighlight>

file_format=report.file_format,

class Privat24Settings(BaseSettings): Як адміністратор, !; |}

!; privat24/

tax_reports.py

11.8.; Повторна відправка

щоб оперативно знаходити причину помилок інтеграції.; |- | rejected_at | timestamp | Дата відхилення.; |- | Rejected | Документ відхилено.; | Зберегти raw-статус, створити подію UnknownStatus.; Як зменшити

def cancel_document(self, document_id: str, reason: str) -> "Privat24DocumentResponse":

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

integration/
pass

requires_receipt: true

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

3.; Джерела інтеграції

def send_report_to_privat24(report_id: UUID, db: "Session") -> "TaxReport":

v
config.py

23.; Ризики

Як бухгалтер,

details={

щоб не створювати документ заново.; {

f"Report {report_id} cannot be sent from status {report.status}"

from datetime import datetime, timezone
=== 20.1.; Створення документа ===

4.; |-
| ПриватБанк
| Банк, через сервіси якого виконується передача документів.; Дія системи
Retry не застосовується для:
'''Заборонено:''' зберігати API key, client secret, токени або паролі КЕП у коді, Git-репозиторії чи відкритих логах.; |-
| old_status
| varchar
| Попередній статус.; payload = DocumentPayload(
!; |-
| report_id
| uuid
| ID документа.; |-
| AC-6
| Приват24 повертає помилку.; характеристика
 "status": "SentToPrivat24",
це Python-клас або пакет, який інкапсулює роботу з API / інтеграційним каналом Приват24 для бізнесу виступає ключовою рисою Privat24 Integration Client.; Окремо варто відзначити який формує, перевіряє, передає і контролює документи податкової звітності через інтеграцію з Приват24 для бізнесу / сервісами ПриватБанку.; характеристика

class Privat24Client:

=== 6.1.; Загальна схема ===
=== 14.1.; Фонове актуалізація ===
<pre>

!; |}

=== 11.5.; Отримання документа ===

!; Синхронізація статусів
{| class="wikitable"
}
 |
 | 7.; details={"error": str(exc)},

* Accepted;
* SentToTax;
* WaitingForTaxReceipt;
* SentToPrivat24;
* WaitingForSignature.; # Який формат документа підтримується: XML, PDF, ZIP, JSON?; |-
| Валідація
| Результат, список помилок.;<pre>

== 28.; Джерела ==

* ValidationError;
* Failed;
* Rejected;
* DeliveryError;
* NeedResend.; status_mapper.py

PRIVAT24_BASE_URL=https://api.privatbank.ua/...

* створити FastAPI-проєкт;
* налаштувати PostgreSQL;
* створити моделі tax_reports, tax_report_events, tax_report_files;
* реалізувати конфігурацію через environment variables;
* реалізувати healthcheck endpoint.;== 12. Privat24 Integration Client ==

!; |-
| sent_to_tax
| SentToTax
| Документ передано до ДПС.; |-
| Web framework
| FastAPI.; |-
| created_at
| timestamp
| Дата події.; |-
| taxpayer_name
| varchar
| Назва платника.; |-
| taxpayer_name
| string
| Так
| Назва компанії або ПІБ ФОП.; я хочу бачити журнал API-запитів і відповідей, 
 raw_status=privat24_status.raw_status,
PRIVAT24_API_KEY=********
 core/
{| class="wikitable"
document_types:
Фінальний мапінг статусів потрібно побудувати після отримання офіційного довідника статусів ПриватБанку.; Інтервал перевірки
!; |-
| AC-10
| Приват24 повертає невідомий статус.; №
!; | платформа зберігає помилку та не втрачає документ.; | платформа зберігає причину відхилення.; |-
| size_bytes
| integer
| Розмір файлу.; |}

== 6.; технічна архітектура рішення для бізнесу ==

=== 7.3.; Отримання квитанцій ===

* timeout;
* тимчасової недоступності API;
* HTTP 429;
* HTTP 500;
* HTTP 502;
* HTTP 503;
* HTTP 504.; # Який механізм авторизації застосовується: API key, OAuth, client certificate або інший варіант?; Квитанції / статуси
 if new_status != report.status:
Повторна відправка дозволена тільки для документів у статусах:
 |
 | 6.; # Де зберігати файли: локально, S3, MinIO, DMS?; Компонент
== 27. Definition of Done ==
<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
 "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",

POST /api/v1/tax-reports/{report_id}/download-receipts
=== 8.6.; Повторна відправка ===
функціональні можливості застосовують, коли потрібно для автоматизації передачі документів податкової звітності з ERP або облікової системи до Приват24 для бізнесу з подальшим поданням до податкової.; | Маскувати логи та обмежити доступ.; Тип
3.; | Зупинити відправку, повідомити адміністратора.; DATABASE_URL=postgresql+psycopg://user:password@db:5432/reports

* реалізувати завантаження квитанцій;
* реалізувати збереження PDF/XML/receipt-файлів;
* реалізувати прив'язку файлів до документа;
* реалізувати перегляд історії.; | Опційно.; # Отримати файл зі сховища.; | Реалізується в межах цього ТЗ.; # Чи Python-сервіс має сам формувати XML, чи отримує готовий XML з ERP?; |-
| Privat24ApiError
| API повернув помилку.; | Інкапсулювати API в окремому Privat24Client.; | Заборонити повтор без підтвердження.; Передача документа через API / інтеграційний канал
!; |-
| Помилка API
| HTTP-код, тіло відповіді, correlation ID.; |-
| AC-5
| API / інтеграційний канал Приват24 повертає успішну відповідь.; | платформа не створює дубль без окремого підтвердження.; №
Приклад змінних середовища:
=== Етап 1.; Базова структура Python-сервісу ===
|-
| Polling
| Періодичне опитування API Приват24.; |-
| error
| Failed
| Помилка обробки.; №

details={
download_receipts.py
merchant_id: str | None = None

12.3.; Конфігурація клієнта

Приклад тіла запиту:

- zip

20.3.; Статуси

title: "Декларація платника єдиного податку"

Етап 4.; Передача документів

}

9.; Статуси документа

<pre>
 main.py
<syntaxhighlight lang="yaml">

<syntaxhighlight lang="json">

{| class="wikitable"

Очікувана відповідь:
=== 7.2.; Отримання статусу ===
from uuid import UUID
 pass
|-
| id
| uuid
| Внутрішній ID документа.; |-
| AC-7
| Документ вже був переданий.; POST /api/v1/tax-reports/{report_id}/resend

<syntaxhighlight lang="json">

 repositories/

* створення Python API для прийому документів;
* створення клієнта інтеграції з Приват24 / ПриватБанком;
* формування XML або прийом готового XML;
* збереження документа;
* перевірка обов'язкових реквізитів;
* передача документа в Приват24;
* отримання статусів;
* отримання квитанцій;
* журнал подій;
* retry-механізм;
* захист API-ключів;
* інтеграційні функціональні можливості з ERP.;</syntaxhighlight>

* повна заміна інтерфейсу Приват24 для бізнесу;
* власна реалізація КЕП, якщо підписання виконується на стороні Приват24;
* інтеграційні функціональні можливості напряму з API ДПС;
* автоматичне актуалізація всіх XSD-схем;
* повноцінний UI для бухгалтера;
* автоматична бухгалтерська перевірка сум;
* супровід всіх типів податкової та статистичної звітності.; |-
| AC-12
| Документ відхилено.; |-
| file_name
| varchar
| Назва файлу.; "created_by": "user@example.com"
 "new_status": new_status,
!; |}

Приват24 для бізнесу

Python Tax Reporting Service
 "source_system": report.source_system,
!; |-
| Logging
| structlog або стандартний logging у JSON-форматі.; |}

 "report_type": "single_tax_declaration",

!; |}

 "taxpayer_name": report.taxpayer_name,

 - xml

1.; Мета

платформа повинна завантажувати та зберігати:

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

retry_backoff_seconds: int = 5

2.; Область сфера застосування

v

Повторна відправка не дозволена для статусів:
!; |}

 v

=== 7.4.; Повторна відправка ===

* доступ до Приват24 для бізнесу;
* інформаційні дані клієнта / компанії / ФОП;
* API key або інший механізм авторизації;
* базовий URL API;
* технічну документацію endpoint-ів;
* перелік доступних типів звітності;
* формат передачі файлів;
* формат метаданих документа;
* правила підписання документа;
* правила отримання статусів;
* правила отримання квитанцій;
* тестове середовище, якщо доступне;
* обмеження за розміром файлів;
* правила повторної відправки;
* технічний контакт з боку ПриватБанку.; Що зберігати

{| class="wikitable"

!; |}

def download_original(self, document_id: str) -> bytes:
"errors": []
report.sent_at = datetime.now(timezone.utc)

AC-11	-	Sending	Документ передається в Приват24.; Тип file_bytes = file_storage.read(report.file_path) { 2.; характеристика		-	Дублювання документів	-	SentToPrivat24	-	Webhook	} "metadata": { FILE_STORAGE_PATH=/data/tax-reports REST API для створення документа; збереження документа; базова валідація; Privat24 Integration Client; передача документа у Приват24; збереження зовнішнього ID; ручний запуск синхронізації статусу; журнал подій; базова обробка помилок.; |-	privat24_raw_status	varchar	Останній raw-статус Приват24.; ) sync_statuses.py if report.status != TaxReportStatus.READY_TO_SEND: } def get_document(self, document_id: str) -> "Privat24DocumentResponse":	; - pdf Очікувана відповідь: - DuplicateDocumentError Документ вже був переданий.; Підготувати метадані.; актуалізація статусу в ERP 7.5.; Технічний аудит README.md Dockerfile 14.2.; Приклад worker-а 15.3. tax_report_files requires_receipt: true db/ API Layer class="wikitable" "privat24_status": "waiting_signature" Логічний endpoint Python-сервісу: def sync_pending_reports() -> None: === 7.1.; Передача документа в Приват24 === !; POST /api/v1/tax-reports/{report_id}/sync-status * реалізувати створення документа; * реалізувати збереження файлу; * реалізувати валідацію; * реалізувати статуси; * реалізувати журнал подій.; |- | AC-13 | користувач системи відкриває картку документа.; allowed_formats: !; Отримати ID документа в Приват24.; |- | Передача у Приват24 | Endpoint, час, статус відповіді, зовнішній ID.; |- | Завантаження квитанції | Тип файлу, назва, дата.; |- | Недоступність сервісу | Приват24 або мережа можуть бути тимчасово недоступні.; Поле !; |- | sent_at | timestamp | Дата передачі у Приват24.; | Перевіряти privat24_document_id перед відправкою.; {| class="wikitable" PRIVAT24_CLIENT_ID=******** logging.py 6.; характеристика * квитанцію про отримання; * квитанцію про прийняття; * квитанцію про відхилення; * підписаний документ; * PDF-візуалізацію; * технічний протокол обробки, якщо доступний; * raw-відповідь Приват24.; Ризик verify_ssl: bool = True == 25.; Приклад структури Python-проєкту == == 26.; Технічні вимоги до Python == "file_format": "xml", raise InvalidStatusError( schemas.py title: "Об'єднана формування звітів" == 15.; Модель даних == <div style="border-left: 6px solid #2e7d32; background: #e8f5e9; padding: 12px 16px; margin: 16px 0;"> == 24.; Відкриті питання == == 14.; Робота зі статусами == v <pre> === 8.4.; Отримання статусів === !; # Чи є собою тестове середовище?; характеристика Задача вважається завершеною, якщо: |- | Створення документа | ID, користувач системи, дата, тип документа.; |- | FileStorageError | Неможливо прочитати або записати файл.; характеристика PRIVAT24_BASE_URL=https://api.privatbank.ua/... 1.; |} session.py наявність обов'язкових полів; коректність РНОКПП або ЄДРПОУ; коректність звітного періоду; наявність файлу; допустимий формат файлу; розмір файлу; коректність імені файлу; відповідність XML-структурі; відповідність XSD, якщо схема доступна; відсутність дубля документа; наявність налаштувань інтеграції з Приват24.; | У системі створюється запис tax_reports.; # Хто має доступ до API key?; | ключовий бізнес-канал для користувача.; Оновити статус на SentToPrivat24.; До першої версії не входить: додати Dockerfile; додати docker-compose; додати structured logging; додати metrics; додати alerting; додати rate limiting; додати security review.; |- Невідомі статуси - Failed Зафіксувати помилку, повідомити адміністратора.; "old_status": "SentToPrivat24", Мінімальний набір вхідних даних: "source_system": "K2 ERP", "privat24_document_id": "external-document-id", ) Немає відкритої API-документації для податкової звітності через Приват24 Публічні сторінки описують сервіс, але не повну API-специфікацію.; характеристика 5.; |} - Paperless / ЕДО ПриватБанку class="wikitable" ) tax_request: ERP / Accounting System entity_id=report.id, Приват24 для бізнесу Не відправляти документ, показати список помилок.; |- file_format varchar XML, PDF, ZIP тощо.; Очікуваний результат - created_at timestamp - DeliveryError Отримати офіційну технічну документацію від ПриватБанку.; Перевірити, що документ має статус ReadyToSend.; # Отримати зовнішній ID документа.; |- period varchar - period string Так Звітний період.; reports = tax_report_repository.get_reports_for_sync() }, tax_reporting_privat24_service/ === 11.1.; Створення документа === allowed_formats: {| class="wikitable" "taxpayer_id": report.taxpayer_id, api_key: str unit/ <pre> tests/ "taxpayer_name": "ФОП Іваненко Іван Іванович", PRIVAT24_API_KEY=******** '''Уточнення:''' значення статусів є собою попередніми.; |- | Privat24 Client | Python-клієнт для роботи з API / інтеграційним каналом ПриватБанку.; Компонент * Python-сервіс розгортається через Docker; * API створення документа функціонує; * документ зберігається у БД та файловому сховищі; * документ проходить валідацію; * документ передається у Приват24; * зовнішній ID документа зберігається; * статус документа оновлюється; * помилки API обробляються; * retry-механізм функціонує; * журнал подій заповнюється; * написані unit-тести для ключових сервісів; * написані інтеграційні тести для Privat24Client з mock API; * документація для запуску додана в README; * фінальні endpoint-и ПриватБанку винесені в конфігурацію.; |- | updated_at | timestamp | Дата актуалізація.; характеристика == 16.; Обробка помилок == !; | Внутрішній статус документа змінюється.; Обов'язковість !; from pydantic_settings import BaseSettings * реалізувати авторизацію; * реалізувати upload_tax_report; * реалізувати get_document_status; * реалізувати download_document; * реалізувати download_receipts; * реалізувати обробку помилок; * реалізувати retry.; |- | Status Sync Worker | Фоновий бізнес-процес для актуалізація статусів.; платформа повинна мати background worker, який періодично оновлює статуси документів.; |- | metadata | object | Ні | Додаткові реквізити для Приват24.; |- | Containers | Docker.; !; |- | Помилки авторизації | API key має змогу бути неправильним або простроченим.; |- | Зміна API | Endpoint-и або формати відповіді можуть змінюватися.; |- | Validation | Pydantic.; # Викликати Privat24 Integration Adapter.; # Який SLA по оновленню статусів?; |- | event_type | varchar | Тип події.; | Зберігати raw-статус та мати UnknownStatus.; |- | ORM | SQLAlchemy.; {| class="wikitable" audit_logger.log( !; |- | Privat24AuthError | Помилка авторизації у Приват24.; |- | document_number | string | Так | Номер документа.; audit_logger.log( == 11.; API Python-сервісу == event_type="STATUS_SYNC_FAILED", report.privat24_document_id = response.id |- | AC-1 | ERP передає інформаційні дані документа у Python-сервіс.; | Він бачить всі пов'язані файли та статуси.; |- | Receipt Loader | Завантажує квитанції та результати обробки.; |- | WaitingForTaxReceipt | Очікується квитанція або результат обробки.; |- | Polling | Періодичне опитування зовнішнього API.; Зберегти ID у локальній БД.; Поле === 8.2.; Валідація документа === [[Категорія:K2 ERP]] event_type="SENT_TO_PRIVAT24", </pre> == 21. MVP == Python-сервіс повинен мати метод для передачі документа в Приват24.; |- | document_number | varchar | Номер документа.; |} [[Категорія:Python]] # Чи надає ПриватБанк API саме для подання податкової звітності через Приват24 для бізнесу?; {| class="wikitable" щоб скоротити час підготовки та подання звітності.; |- | SentToTax | Документ передано до податкової.; |- | waiting_receipt | WaitingForTaxReceipt | Очікується квитанція.; PRIVAT24_TIMEOUT_SECONDS=30 }, Приват24 для бізнесу 8.; Спосіб pass === 13.1.; Логічний бізнес-процес === |- | AC-4 | Документ має статус ReadyToSend.; | платформа повертає список помилок валідації.; security.py * webhook-інтеграція; * інтеграційні функціональні можливості напряму з ДПС; * власний компонент КЕП; * складний UI; * автоматичне актуалізація XSD; * супровід всіх типів звітності; * автоматичне створення декларації з банківських виписок.; |- | content_type | varchar | MIME-тип.; Отримати файл зі сховища.; |- | waiting_signature | WaitingForSignature | Очікується підпис.; # Чи потрібна супровід ФОП, юридичних осіб або обох варіантів?; "message": "Document created" * помилок валідації; * неправильного API key; * відсутності прав доступу; * відхилення документа податковою; * дублювання документа; * некоректного формату файлу.; |} title: "Запит до податкової" <div style="border-left: 6px solid #1565c0; background: #e3f2fd; padding: 12px 16px; margin: 16px 0;"> report.privat24_document_id ) | | 1.; Критерій Очікувана відповідь: client.py Як бухгалтер, === 11.6.; Отримання журналу === pass health.py requires_signature: true * прийом даних звітності з ERP / облікової системи; * формування або прийом готового XML-документа; * перевірку документа перед передачею; * передачу документа через інтеграційний канал Приват24 / ПриватБанку; * отримання зовнішнього ID документа; * синхронізацію статусів; * отримання квитанцій або результатів обробки; * збереження історії передачі; * обробку помилок; * повторну відправку; * журналювання всіх технічних і бізнес-подій.; |- | Tests | pytest.; | має змогу використовуватися для суміжних документів.; |- | ReadyToSend | Документ готовий до передачі.; |- | AC-3 | Передано некоректні інформаційні дані.; single_tax_declaration: !; |- | file_path | varchar | Шлях до файлу.;== 20. Acceptance Criteria == - xml {| class="wikitable" def get_document_status(self, document_id: str) -> "Privat24StatusResponse": === 11.2.; Перевірка документа === "report_type": report.report_type, timeout_seconds: int = 30 == 10.; Мапінг статусів Приват24 == [[Категорія:Вчасно]] === 11.3.; Передача в Приват24 === STATUS_SYNC_INTERVAL_SECONDS=300 Очікувана дія: exceptions.py == 4.; Передумови == "status": "Generated", unified_report: event_repository.py - file_content_base64 string Так платформа надає можливість передачу у Приват24.; |- status varchar Внутрішній статус.; Рекомендація tax_report_repository.update_status( До MVP не входить: Етап 5.; Синхронізація статусів app/ !; |- | Migrations | Alembic.; Статус Приват24 {| class="wikitable" "old_status": old_status, |- | Draft | Документ створено, але ще не готовий до передачі.; Викликати Privat24Client.upload_tax_report().; |- | Скасування документа | Причина, користувач системи, дата.; |- | Python-сервіс | Інтеграційний шар між ERP та Приват24.; Очікуваний результат def upload_tax_report(self, document: "DocumentPayload") -> "Privat24DocumentResponse": status_sync_service.py === 16.1.; Типи помилок === Python-сервіс повинен приймати документ від ERP.; |- | AC-9 | Приват24 повертає новий статус.; Критерій validation_service.py - pdf GET /api/v1/tax-reports/{report_id}/events "period": "2026-Q1", ) ; Внутрішній статус 29.; Див.; додатково def download_signed_document(self, document_id: str) -> bytes: - error_message text У документі зберігається privat24_document_id.; |- file_name varchar Назва файлу.; # Підготувати метадані.; Пріоритет id uuid ID події.; response = privat24_client.upload_tax_report(payload) реалізувати endpoint send-to-privat24; зберігати privat24_document_id; оновлювати статуси; логувати API-взаємодію.; |- rejected Rejected - Приват24 для бізнесу - HTTP client - privat24_document_id varchar ID документа у Приват24.; Підписання / подання / обробка - ERP / облікова платформа - title varchar - Background jobs платформа завантажує квитанцію або результат обробки.; |- report_type varchar - document_date date Так Дата документа.;== 22.; Етапи реалізації == я хочу повторно відправити документ після технічної помилки, ; migrations/ api/ "taxpayer_id": "1234567890", Python-сервіс Окремий backend-сервіс або компонент, який виконує інтеграцію з Приват24.; я хочу бачити статус документа в ERP, metadata={ requires_receipt: true Етап 7.; Production hardening routes/ APP_ENV=production [[Категорія:Технічні завдання]] </div> old_status = report.status !; |- | last_sync_at | timestamp | Дата останньої синхронізації.; return report date=report.document_date, GET /api/v1/tax-reports/{report_id} <syntaxhighlight lang="python"> я хочу отримати квитанції в ERP, v платформа повинна забезпечити: report.status = TaxReportStatus.SENT_TO_PRIVAT24 |- | Python | 3.11 або вище.; # Які endpoint-и використовуються для отримання квитанцій?; | Записати відповідь API, дозволити повтор.; |- | ValidationError | Документ не пройшов перевірку.; # Чи потрібно робити UI, чи тільки backend API?; |- | document_date | date | Дата документа.; |- | report_type | string | Так | Тип звіту або документа.; Термін * реалізувати background worker; * реалізувати періодичне актуалізація статусів; * реалізувати мапінг статусів; * реалізувати обробку невідомих статусів.; |- | КЕП | Кваліфікований електронний підпис.; |- | DB | PostgreSQL.; |} </syntaxhighlight> <div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;"> Python Tax Reporting Service RECEIPT_DOWNLOAD_ENABLED=true POST /api/v1/tax-reports/{report_id}/send-to-privat24 |- | id | uuid | ID файлу.; характеристика receipt_service.py db.commit() Рекомендована періодичність: file_repository.py !;</syntaxhighlight> == 19.; Логування та аудит == "privat24_status": privat24_status.raw_status, } === 18.2.; Конфігурація типів документів === - Privat24TimeoutError - report_id uuid - file_type varchar - Персональні інформаційні дані - file_format string Так - Signed - source_system varchar - Інтеграційний компонент Приват24 як ілюстрація K2 ERP або інша платформа.; Критерій ; workers/ </syntaxhighlight> зберігання API key тільки у змінних середовища або secret storage; заборону логування API key; заборону зберігання паролів КЕП у відкритому вигляді; маскування персональних даних у технічних логах; контроль доступу до документів; контроль доступу до квитанцій; журналювання всіх операцій; HTTPS для всіх API-запитів; перевірку SSL-сертифіката; обмеження доступу до адміністративних endpoint-ів; резервне копіювання документів і квитанцій.; |- Квитанція Додати healthcheck інтеграції та повідомлення адміністратору.; |} 20.2.; Передача у Приват24 17.; Безпека ДПС title=report.title, try: 6.2.; Основні компоненти Python-сервісу ValidationError Некоректні інформаційні дані документа.; allowed_formats: ; "document_number": "DECL-2026-0001", "message": "Document sent to Privat24" Етап 6.; Квитанції та результати обробки PRIVAT24_TIMEOUT_SECONDS=30 13.; Передача документа в Приват24 7. User Story - accepted_at timestamp } requires_signature: true exceptions.py base_url: str "file_content_base64": "BASE64_XML_CONTENT", 8.1.; Створення документа storage/ uploaded SentToPrivat24 - file_path varchar Шлях до файлу у сховищі.; інформаційні дані для звітності або готовий XML file_name=report.file_name, entity_id=report.id, - Webhook - Storage Layer Зберігає документи, квитанції, статуси та логи.; Записати подію в журнал.; integrations/ https://privatbank.ua/business/tax-help https://privatbank.ua/business/elektronnyje-otchety https://privatbank.ua/business/intehratsiya https://privatbank.ua/business/paperless https://privatbank.ua/business/vse-servisy-ucheta-i-otchetnosti 8.3.; Передача документа в Приват24 Python FastAPI K2 ERP Податкова звітність Приват24 Приват24 для бізнесу ПриватБанк ДПС КЕП API інтеграція new_status=new_status, report = tax_report_repository.get_by_id(db, report_id) "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff", 13.2.; Приклад Python-логіки POST /api/v1/tax-reports/{report_id}/send-to-privat24 Метою задачі є собою створення Python-сервісу для передачі документів податкової звітності через Приват24 для бізнесу.; | Raw-статус зберігається, створюється подія UnknownStatus.; # Які endpoint-и використовуються для отримання статусів?; |- StatusMappingError - Accepted Обов'язково для MVP.; # Чи підтримуються webhook-и?; |- ДПС Державна податкова служба України.; № щоб розуміти, чи документ передано, очікує підпису, поданий у податкову, прийнятий або відхилений.; | Використовувати retry та чергу задач.; # Записати подію в журнал.; Подія 5.; Поле "raw_status": response.status, v report_id=report.id, { retry_count: int = 3 number=report.document_number, tax_report_repository.py { платформа повинна підтримувати два способи актуалізація статусів: До MVP входить: STATUS_SYNC_ENABLED=true "period": report.period, [[Категорія:API]] Як користувач системи, "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff", client_id: str | None = None entity_id=report.id, </div> ) !; характеристика except Exception as exc: !; |- | payload | jsonb | Технічні інформаційні дані події.; | Файл зберігається у файловому сховищі.; Коментар { === 20.4.; Квитанції та файли === Privat24 Integration Adapter file_content=file_bytes, } - Повторна відправка - AC-2 - created_by varchar - актуалізація статусу - accepted Accepted Документ прийнято.; Поле 11.7.; Завантаження квитанцій - signed Signed - XML Виконати retry.;=== 15.2. tax_report_events === AC-8 - WaitingForSignature Статуси документів оновлюються автономно.; Тип pass privat24_status = privat24_client.get_document_status( Головна ідея: розробити Python-сервіс.; |- API Програмний інтерфейс інтеграції.; Критерій }, 4.; Компонент 8.5.; Отримання квитанцій ; Тип 18.; конфігурація Технічний стек: Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Docker.; |- created_at timestamp - taxpayer_id varchar - new_status varchar Новий статус.; Як користувач системи ERP, Для реалізації задачі необхідно отримати від ПриватБанку або адміністратора Приват24: POST /api/v1/tax-reports/{report_id}/validate PRIVAT24_RETRY_COUNT=3 бізнесу та інтеграційних сервісів для бухгалтерських програм забезпечується через істотно: публічна відомості підтверджує наявність електронної звітності в Приват24; додатково реалізовано але фінальні API endpoint-и для автоматичної передачі звітності потрібно отримати від ПриватБанку.; # Які типи звітів підтримуються першими?; характеристика new_status = status_mapper.map_privat24_status(privat24_status) 8.; Функціональні вимоги Retry застосовується для: 12.2.; Основні методи Очікувана відповідь: <syntaxhighlight lang="json"> 15.1. tax_reports Перед передачею платформа повинна перевірити: event_type="STATUS_CHANGED", "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff", pass 7.; Внутрішній статус {{SEO PRIVAT24_CLIENT_ID=******** "document_date": "2026-04-15", "new_status": "WaitingForSignature", - Validation Layer - XSD Схема перевірки XML-документа.; Валідація та збереження документа ERP / Accounting System ; Очікуваний результат ) PRIVAT24_RETRY_BACKOFF_SECONDS=5 PRIVAT24_RETRY_BACKOFF_SECONDS=5 requires_signature: true 12.1.; Призначення <syntaxhighlight lang="python"> щоб мати підтвердження результату подання звітності.; |- Document Builder Формує XML або приймає готовий файл.; Тип помилки tax_report_service.py Потрібна технічна специфікація від ПриватБанку.; Реальні коди статусів потрібно взяти з API-документації ПриватБанку.; |- Generated Файл документа сформовано.; v