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

Головна ідея: розробити Python-сервіс, який формує, перевіряє, передає та контролює документи податкової звітності через інтеграцію з Приват24 для бізнесу / сервісами ПриватБанку.

Важливо: публічна інформація підтверджує наявність електронної звітності в Приват24 для бізнесу та інтеграційних сервісів для бухгалтерських програм, але фінальні API endpoint-и для автоматичної передачі звітності потрібно отримати від ПриватБанку.

Технічний стек: Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Docker.

1. Мета

Метою задачі є створення Python-сервісу для передачі документів податкової звітності через Приват24 для бізнесу.

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

прийом даних звітності з ERP / облікової системи;
формування або прийом готового XML-документа;
перевірку документа перед передачею;
передачу документа через інтеграційний канал Приват24 / ПриватБанку;
отримання зовнішнього ID документа;
синхронізацію статусів;
отримання квитанцій або результатів обробки;
збереження історії передачі;
обробку помилок;
повторну відправку;
журналювання всіх технічних і бізнес-подій.

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

Функціонал використовується для автоматизації передачі документів податкової звітності з ERP або облікової системи до Приват24 для бізнесу з подальшим поданням до податкової.

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

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

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

повна заміна інтерфейсу Приват24 для бізнесу;
власна реалізація КЕП, якщо підписання виконується на стороні Приват24;
інтеграція напряму з API ДПС;
автоматичне оновлення всіх XSD-схем;
повноцінний UI для бухгалтера;
автоматична бухгалтерська перевірка сум;
підтримка всіх типів податкової та статистичної звітності.

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

Компонент	Призначення	Коментар
Приват24 для бізнесу	Електронна звітність, подання звітів, робота з податковими сервісами.	Основний бізнес-канал для користувача.
Інтеграційний модуль Приват24	Обмін із бухгалтерськими програмами.	Потрібна технічна специфікація від ПриватБанку.
Paperless / ЕДО ПриватБанку	Обмін електронними документами.	Може використовуватися для суміжних документів.
Python-сервіс	Інтеграційний шар між ERP та Приват24.	Реалізується в межах цього ТЗ.
ERP / облікова система	Джерело даних для звітності.	Наприклад K2 ERP або інша система.

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

Для реалізації задачі необхідно отримати від ПриватБанку або адміністратора Приват24:

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

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

Термін	Опис
Python-сервіс	Окремий backend-сервіс або модуль, який виконує інтеграцію з Приват24.
Приват24 для бізнесу	Інтернет-банк ПриватБанку для ФОП та юридичних осіб.
ПриватБанк	Банк, через сервіси якого виконується передача документів.
ДПС	Державна податкова служба України.
XML	Формат електронного документа звітності.
XSD	Схема перевірки XML-документа.
КЕП	Кваліфікований електронний підпис.
API	Програмний інтерфейс інтеграції.
Webhook	Механізм отримання подій від зовнішньої системи.
Polling	Періодичне опитування зовнішнього API.
Квитанція	Підтвердження прийняття, відхилення або обробки звіту.

6. Архітектура рішення

6.1. Загальна схема

ERP / Accounting System
        |
        | 1. Дані для звітності або готовий XML
        v
Python Tax Reporting Service
        |
        | 2. Валідація та збереження документа
        v
Privat24 Integration Adapter
        |
        | 3. Передача документа через API / інтеграційний канал
        v
Приват24 для бізнесу
        |
        | 4. Підписання / подання / обробка
        v
ДПС
        |
        | 5. Квитанції / статуси
        v
Приват24 для бізнесу
        |
        | 6. Синхронізація статусів
        v
Python Tax Reporting Service
        |
        | 7. Оновлення статусу в ERP
        v
ERP / Accounting System

6.2. Основні компоненти Python-сервісу

Компонент	Опис
API Layer	REST API для прийому документів від ERP.
Document Builder	Формує XML або приймає готовий файл.
Validation Layer	Перевіряє реквізити, структуру та статус документа.
Privat24 Client	Python-клієнт для роботи з API / інтеграційним каналом ПриватБанку.
Status Sync Worker	Фоновий процес для оновлення статусів.
Receipt Loader	Завантажує квитанції та результати обробки.
Storage Layer	Зберігає документи, квитанції, статуси та логи.
Audit Logger	Фіксує всі дії користувачів і системи.

7. User Story

7.1. Передача документа в Приват24

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

7.2. Отримання статусу

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

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

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

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

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

7.5. Технічний аудит

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

8. Функціональні вимоги

8.1. Створення документа

Python-сервіс повинен приймати документ від ERP.

Мінімальний набір вхідних даних:

Поле	Тип	Обов'язковість	Опис
taxpayer_id	string	Так	РНОКПП або ЄДРПОУ платника.
taxpayer_name	string	Так	Назва компанії або ПІБ ФОП.
report_type	string	Так	Тип звіту або документа.
period	string	Так	Звітний період.
document_number	string	Так	Номер документа.
document_date	date	Так	Дата документа.
file_format	string	Так	XML, PDF, ZIP або інший підтримуваний формат.
file_content_base64	string	Так	Вміст документа у Base64.
metadata	object	Ні	Додаткові реквізити для Приват24.

8.2. Валідація документа

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

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

8.3. Передача документа в Приват24

Python-сервіс повинен мати метод для передачі документа в Приват24.

Логічний endpoint Python-сервісу:

POST /api/v1/tax-reports/{report_id}/send-to-privat24

Очікувана дія:

Отримати документ із локальної БД.
Перевірити статус документа.
Отримати файл зі сховища.
Підготувати метадані.
Викликати Privat24 Integration Adapter.
Отримати зовнішній ID документа.
Зберегти зовнішній ID у БД.
Оновити статус документа.
Записати подію в журнал.

8.4. Отримання статусів

Система повинна підтримувати два способи оновлення статусів:

Спосіб	Опис	Пріоритет
Polling	Періодичне опитування API Приват24.	Обов'язково для MVP.
Webhook	Отримання подій від Приват24, якщо підтримується.	Опційно.

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

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

квитанцію про отримання;
квитанцію про прийняття;
квитанцію про відхилення;
підписаний документ;
PDF-візуалізацію;
технічний протокол обробки, якщо доступний;
raw-відповідь Приват24.

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

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

ValidationError;
Failed;
Rejected;
DeliveryError;
NeedResend.

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

Accepted;
SentToTax;
WaitingForTaxReceipt;
SentToPrivat24;
WaitingForSignature.

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

Внутрішній статус	Опис
Draft	Документ створено, але ще не готовий до передачі.
Generated	Файл документа сформовано.
ValidationError	Документ не пройшов перевірку.
ReadyToSend	Документ готовий до передачі.
Sending	Документ передається в Приват24.
SentToPrivat24	Документ успішно передано в Приват24.
WaitingForSignature	Документ очікує підписання.
Signed	Документ підписано.
SentToTax	Документ передано до податкової.
WaitingForTaxReceipt	Очікується квитанція або результат обробки.
Accepted	Документ прийнято.
Rejected	Документ відхилено.
DeliveryError	Помилка доставки.
Failed	Технічна помилка.
Cancelled	Документ скасовано.

10. Мапінг статусів Приват24

Фінальний мапінг статусів потрібно побудувати після отримання офіційного довідника статусів ПриватБанку.

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

Статус Приват24	Внутрішній статус	Опис
uploaded	SentToPrivat24	Документ завантажено в Приват24.
waiting_signature	WaitingForSignature	Очікується підпис.
signed	Signed	Документ підписано.
sent_to_tax	SentToTax	Документ передано до ДПС.
waiting_receipt	WaitingForTaxReceipt	Очікується квитанція.
accepted	Accepted	Документ прийнято.
rejected	Rejected	Документ відхилено.
error	Failed	Помилка обробки.

Уточнення: значення статусів є попередніми. Реальні коди статусів потрібно взяти з API-документації ПриватБанку.

11. API Python-сервісу

11.1. Створення документа

POST /api/v1/tax-reports

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

{
  "taxpayer_id": "1234567890",
  "taxpayer_name": "ФОП Іваненко Іван Іванович",
  "report_type": "single_tax_declaration",
  "period": "2026-Q1",
  "document_number": "DECL-2026-0001",
  "document_date": "2026-04-15",
  "file_format": "xml",
  "file_content_base64": "BASE64_XML_CONTENT",
  "metadata": {
    "source_system": "K2 ERP",
    "created_by": "user@example.com"
  }
}

Очікувана відповідь:

{
  "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
  "status": "Generated",
  "message": "Document created"
}

11.2. Перевірка документа

POST /api/v1/tax-reports/{report_id}/validate

Очікувана відповідь:

{
  "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
  "status": "ReadyToSend",
  "errors": []
}

11.3. Передача в Приват24

POST /api/v1/tax-reports/{report_id}/send-to-privat24

Очікувана відповідь:

{
  "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
  "status": "SentToPrivat24",
  "privat24_document_id": "external-document-id",
  "message": "Document sent to Privat24"
}

11.4. Оновлення статусу

POST /api/v1/tax-reports/{report_id}/sync-status

Очікувана відповідь:

{
  "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
  "old_status": "SentToPrivat24",
  "new_status": "WaitingForSignature",
  "privat24_status": "waiting_signature"
}

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

GET /api/v1/tax-reports/{report_id}

11.6. Отримання журналу

GET /api/v1/tax-reports/{report_id}/events

11.7. Завантаження квитанцій

POST /api/v1/tax-reports/{report_id}/download-receipts

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

POST /api/v1/tax-reports/{report_id}/resend

12. Privat24 Integration Client

12.1. Призначення

Privat24 Integration Client — це Python-клас або пакет, який інкапсулює роботу з API / інтеграційним каналом Приват24 для бізнесу.

12.2. Основні методи

class Privat24Client:
    def upload_tax_report(self, document: "DocumentPayload") -> "Privat24DocumentResponse":
        pass

    def get_document(self, document_id: str) -> "Privat24DocumentResponse":
        pass

    def get_document_status(self, document_id: str) -> "Privat24StatusResponse":
        pass

    def download_original(self, document_id: str) -> bytes:
        pass

    def download_signed_document(self, document_id: str) -> bytes:
        pass

    def download_receipts(self, document_id: str) -> list[bytes]:
        pass

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

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

from pydantic_settings import BaseSettings


class Privat24Settings(BaseSettings):
    base_url: str
    api_key: str
    merchant_id: str | None = None
    client_id: str | None = None
    timeout_seconds: int = 30
    retry_count: int = 3
    retry_backoff_seconds: int = 5
    verify_ssl: bool = True

Приклад змінних середовища:

PRIVAT24_BASE_URL=https://api.privatbank.ua/...
PRIVAT24_API_KEY=********
PRIVAT24_CLIENT_ID=********
PRIVAT24_TIMEOUT_SECONDS=30
PRIVAT24_RETRY_COUNT=3
PRIVAT24_RETRY_BACKOFF_SECONDS=5

Заборонено: зберігати API key, client secret, токени або паролі КЕП у коді, Git-репозиторії чи відкритих логах.

13. Передача документа в Приват24

13.1. Логічний процес

1. Отримати документ з БД.
2. Перевірити, що документ має статус ReadyToSend.
3. Отримати файл зі сховища.
4. Підготувати метадані.
5. Викликати Privat24Client.upload_tax_report().
6. Отримати ID документа в Приват24.
7. Зберегти ID у локальній БД.
8. Оновити статус на SentToPrivat24.
9. Записати подію в журнал.

13.2. Приклад Python-логіки

from uuid import UUID
from datetime import datetime, timezone


def send_report_to_privat24(report_id: UUID, db: "Session") -> "TaxReport":
    report = tax_report_repository.get_by_id(db, report_id)

    if report.status != TaxReportStatus.READY_TO_SEND:
        raise InvalidStatusError(
            f"Report {report_id} cannot be sent from status {report.status}"
        )

    file_bytes = file_storage.read(report.file_path)

    payload = DocumentPayload(
        title=report.title,
        number=report.document_number,
        date=report.document_date,
        file_name=report.file_name,
        file_content=file_bytes,
        file_format=report.file_format,
        metadata={
            "taxpayer_id": report.taxpayer_id,
            "taxpayer_name": report.taxpayer_name,
            "report_type": report.report_type,
            "period": report.period,
            "source_system": report.source_system,
        },
    )

    response = privat24_client.upload_tax_report(payload)

    report.privat24_document_id = response.id
    report.status = TaxReportStatus.SENT_TO_PRIVAT24
    report.sent_at = datetime.now(timezone.utc)

    audit_logger.log(
        entity_id=report.id,
        event_type="SENT_TO_PRIVAT24",
        details={
            "privat24_document_id": response.id,
            "raw_status": response.status,
        },
    )

    db.commit()
    return report

14. Робота зі статусами

14.1. Фонове оновлення

Система повинна мати background worker, який періодично оновлює статуси документів.

Рекомендована періодичність:

Статус документа	Інтервал перевірки
SentToPrivat24	кожні 5 хвилин
WaitingForSignature	кожні 15 хвилин
SentToTax	кожні 10 хвилин
WaitingForTaxReceipt	кожні 10 хвилин
Accepted / Rejected	не перевіряти

14.2. Приклад worker-а

def sync_pending_reports() -> None:
    reports = tax_report_repository.get_reports_for_sync()

    for report in reports:
        try:
            privat24_status = privat24_client.get_document_status(
                report.privat24_document_id
            )

            new_status = status_mapper.map_privat24_status(privat24_status)

            if new_status != report.status:
                old_status = report.status

                tax_report_repository.update_status(
                    report_id=report.id,
                    new_status=new_status,
                    raw_status=privat24_status.raw_status,
                )

                audit_logger.log(
                    entity_id=report.id,
                    event_type="STATUS_CHANGED",
                    details={
                        "old_status": old_status,
                        "new_status": new_status,
                        "privat24_status": privat24_status.raw_status,
                    },
                )

        except Exception as exc:
            audit_logger.log(
                entity_id=report.id,
                event_type="STATUS_SYNC_FAILED",
                details={"error": str(exc)},
            )

15. Модель даних

15.1. tax_reports

Поле	Тип	Опис
id	uuid	Внутрішній ID документа.
taxpayer_id	varchar	РНОКПП або ЄДРПОУ.
taxpayer_name	varchar	Назва платника.
report_type	varchar	Тип звіту.
period	varchar	Звітний період.
document_number	varchar	Номер документа.
document_date	date	Дата документа.
title	varchar	Назва документа.
file_name	varchar	Назва файлу.
file_path	varchar	Шлях до файлу у сховищі.
file_format	varchar	XML, PDF, ZIP тощо.
status	varchar	Внутрішній статус.
privat24_document_id	varchar	ID документа у Приват24.
privat24_raw_status	varchar	Останній raw-статус Приват24.
last_sync_at	timestamp	Дата останньої синхронізації.
sent_at	timestamp	Дата передачі у Приват24.
accepted_at	timestamp	Дата прийняття.
rejected_at	timestamp	Дата відхилення.
error_message	text	Остання помилка.
source_system	varchar	ERP або інша система-джерело.
created_at	timestamp	Дата створення.
updated_at	timestamp	Дата оновлення.

15.2. tax_report_events

Поле	Тип	Опис
id	uuid	ID події.
report_id	uuid	ID документа.
event_type	varchar	Тип події.
old_status	varchar	Попередній статус.
new_status	varchar	Новий статус.
payload	jsonb	Технічні дані події.
created_by	varchar	Користувач або system.
created_at	timestamp	Дата події.

15.3. tax_report_files

Поле	Тип	Опис
id	uuid	ID файлу.
report_id	uuid	ID документа.
file_type	varchar	original, signed, pdf, receipt, error_protocol.
file_name	varchar	Назва файлу.
file_path	varchar	Шлях до файлу.
content_type	varchar	MIME-тип.
size_bytes	integer	Розмір файлу.
created_at	timestamp	Дата створення.

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

16.1. Типи помилок

Тип помилки	Опис	Дія системи
ValidationError	Некоректні дані документа.	Не відправляти документ, показати список помилок.
Privat24AuthError	Помилка авторизації у Приват24.	Зупинити відправку, повідомити адміністратора.
Privat24ApiError	API повернув помилку.	Записати відповідь API, дозволити повтор.
Privat24TimeoutError	Перевищено час очікування.	Виконати retry.
DuplicateDocumentError	Документ вже був переданий.	Заборонити повтор без підтвердження.
FileStorageError	Неможливо прочитати або записати файл.	Зафіксувати помилку, повідомити адміністратора.
StatusMappingError	Невідомий статус від Приват24.	Зберегти raw-статус, створити подію UnknownStatus.

16.2. Retry-логіка

Retry застосовується для:

timeout;
тимчасової недоступності API;
HTTP 429;
HTTP 500;
HTTP 502;
HTTP 503;
HTTP 504.

Retry не застосовується для:

помилок валідації;
неправильного API key;
відсутності прав доступу;
відхилення документа податковою;
дублювання документа;
некоректного формату файлу.

17. Безпека

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

зберігання API key тільки у змінних середовища або secret storage;
заборону логування API key;
заборону зберігання паролів КЕП у відкритому вигляді;
маскування персональних даних у технічних логах;
контроль доступу до документів;
контроль доступу до квитанцій;
журналювання всіх операцій;
HTTPS для всіх API-запитів;
перевірку SSL-сертифіката;
обмеження доступу до адміністративних endpoint-ів;
резервне копіювання документів і квитанцій.

18. Налаштування

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

APP_ENV=production
DATABASE_URL=postgresql+psycopg://user:password@db:5432/reports
FILE_STORAGE_PATH=/data/tax-reports

PRIVAT24_BASE_URL=https://api.privatbank.ua/...
PRIVAT24_API_KEY=********
PRIVAT24_CLIENT_ID=********
PRIVAT24_TIMEOUT_SECONDS=30
PRIVAT24_RETRY_COUNT=3
PRIVAT24_RETRY_BACKOFF_SECONDS=5

STATUS_SYNC_ENABLED=true
STATUS_SYNC_INTERVAL_SECONDS=300
RECEIPT_DOWNLOAD_ENABLED=true

18.2. Конфігурація типів документів

document_types:
  single_tax_declaration:
    title: "Декларація платника єдиного податку"
    allowed_formats:
      - xml
      - pdf
    requires_signature: true
    requires_receipt: true

  tax_request:
    title: "Запит до податкової"
    allowed_formats:
      - xml
      - pdf
    requires_signature: true
    requires_receipt: true

  unified_report:
    title: "Об'єднана звітність"
    allowed_formats:
      - xml
      - zip
    requires_signature: true
    requires_receipt: true

19. Логування та аудит

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

Подія	Що зберігати
Створення документа	ID, користувач, дата, тип документа.
Валідація	Результат, список помилок.
Передача у Приват24	Endpoint, час, статус відповіді, зовнішній ID.
Помилка API	HTTP-код, тіло відповіді, correlation ID.
Оновлення статусу	Старий статус, новий статус, raw-статус Приват24.
Завантаження квитанції	Тип файлу, назва, дата.
Повторна відправка	Причина, користувач, дата.
Скасування документа	Причина, користувач, дата.

20. Acceptance Criteria

20.1. Створення документа

№	Критерій	Очікуваний результат
AC-1	ERP передає дані документа у Python-сервіс.	У системі створюється запис tax_reports.
AC-2	Передано файл документа.	Файл зберігається у файловому сховищі.
AC-3	Передано некоректні дані.	Система повертає список помилок валідації.

20.2. Передача у Приват24

№	Критерій	Очікуваний результат
AC-4	Документ має статус ReadyToSend.	Система дозволяє передачу у Приват24.
AC-5	API / інтеграційний канал Приват24 повертає успішну відповідь.	У документі зберігається privat24_document_id.
AC-6	Приват24 повертає помилку.	Система зберігає помилку та не втрачає документ.
AC-7	Документ вже був переданий.	Система не створює дубль без окремого підтвердження.

20.3. Статуси

№	Критерій	Очікуваний результат
AC-8	Worker запускає синхронізацію.	Статуси документів оновлюються автоматично.
AC-9	Приват24 повертає новий статус.	Внутрішній статус документа змінюється.
AC-10	Приват24 повертає невідомий статус.	Raw-статус зберігається, створюється подія UnknownStatus.

20.4. Квитанції та файли

№	Критерій	Очікуваний результат
AC-11	Документ прийнято.	Система завантажує квитанцію або результат обробки.
AC-12	Документ відхилено.	Система зберігає причину відхилення.
AC-13	Користувач відкриває картку документа.	Він бачить всі пов'язані файли та статуси.

21. MVP

До MVP входить:

REST API для створення документа;
збереження документа;
базова валідація;
Privat24 Integration Client;
передача документа у Приват24;
збереження зовнішнього ID;
ручний запуск синхронізації статусу;
журнал подій;
базова обробка помилок.

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

webhook-інтеграція;
інтеграція напряму з ДПС;
власний модуль КЕП;
складний UI;
автоматичне оновлення XSD;
підтримка всіх типів звітності;
автоматичне створення декларації з банківських виписок.

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

Етап 1. Базова структура Python-сервісу

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

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

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

Етап 3. Privat24 Integration Client

реалізувати авторизацію;
реалізувати upload_tax_report;
реалізувати get_document_status;
реалізувати download_document;
реалізувати download_receipts;
реалізувати обробку помилок;
реалізувати retry.

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

реалізувати endpoint send-to-privat24;
зберігати privat24_document_id;
оновлювати статуси;
логувати API-взаємодію.

Етап 5. Синхронізація статусів

реалізувати background worker;
реалізувати періодичне оновлення статусів;
реалізувати мапінг статусів;
реалізувати обробку невідомих статусів.

Етап 6. Квитанції та результати обробки

реалізувати завантаження квитанцій;
реалізувати збереження PDF/XML/receipt-файлів;
реалізувати прив'язку файлів до документа;
реалізувати перегляд історії.

Етап 7. Production hardening

додати Dockerfile;
додати docker-compose;
додати structured logging;
додати metrics;
додати alerting;
додати rate limiting;
додати security review.

23. Ризики

Ризик	Опис	Як зменшити
Немає відкритої API-документації для податкової звітності через Приват24	Публічні сторінки описують сервіс, але не повну API-специфікацію.	Отримати офіційну технічну документацію від ПриватБанку.
Зміна API	Endpoint-и або формати відповіді можуть змінюватися.	Інкапсулювати API в окремому Privat24Client.
Невідомі статуси	Приват24 може повертати статуси, яких немає в системі.	Зберігати raw-статус та мати UnknownStatus.
Дублювання документів	Повторна відправка може створити дубль.	Перевіряти privat24_document_id перед відправкою.
Помилки авторизації	API key може бути неправильним або простроченим.	Додати healthcheck інтеграції та повідомлення адміністратору.
Недоступність сервісу	Приват24 або мережа можуть бути тимчасово недоступні.	Використовувати retry та чергу задач.
Персональні дані	Документи можуть містити РНОКПП, ЄДРПОУ, фінансові дані.	Маскувати логи та обмежити доступ.

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

Чи надає ПриватБанк API саме для подання податкової звітності через Приват24 для бізнесу?
Який механізм авторизації використовується: API key, OAuth, client certificate або інший варіант?
Який базовий URL API?
Які endpoint-и використовуються для завантаження документа?
Які endpoint-и використовуються для отримання статусів?
Які endpoint-и використовуються для отримання квитанцій?
Який формат документа підтримується: XML, PDF, ZIP, JSON?
Чи Python-сервіс має сам формувати XML, чи отримує готовий XML з ERP?
Де виконується КЕП: у Python-сервісі, у Приват24 або користувачем у веб-інтерфейсі?
Чи потрібна підтримка ФОП, юридичних осіб або обох варіантів?
Які типи звітів підтримуються першими?
Чи є тестове середовище?
Чи підтримуються webhook-и?
Який SLA по оновленню статусів?
Де зберігати файли: локально, S3, MinIO, DMS?
Хто має доступ до API key?
Чи потрібно робити UI, чи тільки backend API?

25. Приклад структури Python-проєкту

tax_reporting_privat24_service/
  app/
    main.py
    config.py
    api/
      routes/
        tax_reports.py
        health.py
    core/
      security.py
      logging.py
      exceptions.py
    db/
      session.py
      models.py
      migrations/
    services/
      tax_report_service.py
      validation_service.py
      status_sync_service.py
      receipt_service.py
    integrations/
      privat24/
        client.py
        schemas.py
        status_mapper.py
        exceptions.py
    repositories/
      tax_report_repository.py
      event_repository.py
      file_repository.py
    workers/
      sync_statuses.py
      download_receipts.py
    storage/
      file_storage.py
  tests/
    unit/
    integration/
  Dockerfile
  docker-compose.yml
  pyproject.toml
  README.md

26. Технічні вимоги до Python

Компонент	Рекомендація
Python	3.11 або вище.
Web framework	FastAPI.
HTTP client	httpx.
Validation	Pydantic.
ORM	SQLAlchemy.
DB	PostgreSQL.
Migrations	Alembic.
Background jobs	Celery, RQ або APScheduler.
Tests	pytest.
Containers	Docker.
Logging	structlog або стандартний logging у JSON-форматі.

27. Definition of Done

Задача вважається завершеною, якщо:

Python-сервіс розгортається через Docker;
API створення документа працює;
документ зберігається у БД та файловому сховищі;
документ проходить валідацію;
документ передається у Приват24;
зовнішній ID документа зберігається;
статус документа оновлюється;
помилки API обробляються;
retry-механізм працює;
журнал подій заповнюється;
написані unit-тести для ключових сервісів;
написані інтеграційні тести для Privat24Client з mock API;
документація для запуску додана в README;
фінальні endpoint-и ПриватБанку винесені в конфігурацію.

28. Джерела

29. Див. також