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

{{DISPLAYTITLE:Технічне завдання: Отримання банківських виписок з Приват24 для Python}}

{{SEO
|title=Технічне завдання: Отримання банківських виписок з Приват24 для Python
|description=Технічне завдання на реалізацію Python-сервісу для автоматичного отримання банківських виписок з Приват24 для бізнесу через інтеграцію Автоклієнт / API ПриватБанку.
|keywords=Python, Приват24, Приват24 для бізнесу, ПриватБанк, банківська виписка, Автоклієнт, API, інтеграція, FastAPI, технічне завдання
}}

<div style="border-left: 6px solid #2e7d32; background: #e8f5e9; padding: 12px 16px; margin: 16px 0;">
'''Головна ідея:''' розробити Python-сервіс, який автоматично отримує банківські виписки з Приват24 для бізнесу, зберігає операції, виконує дедублікацію та передає дані в ERP / бухгалтерську систему.
</div>

<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
'''Важливо:''' основний сценарій інтеграції для бізнес-рахунків — через сервіс «Інтеграція / Автоклієнт» у Приват24 для бізнесу. Фінальні endpoint-и, формат авторизації та доступні поля виписки потрібно підтвердити в API-налаштуваннях конкретного клієнта ПриватБанку.
</div>

<div style="border-left: 6px solid #1565c0; background: #e3f2fd; padding: 12px 16px; margin: 16px 0;">
'''Технічний стек:''' Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Docker.
</div>

__TOC__

== 1. Мета ==

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

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

* підключення до API Приват24 / Автоклієнта;
* отримання списку доступних рахунків;
* отримання банківських операцій за рахунками;
* отримання виписки за період;
* регулярну синхронізацію виписок;
* збереження операцій у локальній БД;
* дедублікацію банківських транзакцій;
* обробку помилок API;
* ведення журналу синхронізації;
* передачу виписок в ERP / бухгалтерську систему.

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

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

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

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

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

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

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

{| class="wikitable"
! Компонент
! Призначення
! Коментар
|-
| Приват24 для бізнесу
| Основний кабінет клієнта для роботи з бізнес-рахунками.
| У ньому підключається сервіс інтеграції.
|-
| Інтеграція / Автоклієнт
| API-канал для автоматизації отримання виписки та надсилання платежів.
| Основний рекомендований сценарій для бізнес-рахунків.
|-
| Відкрита виписка
| Сервіс доступу до виписок за вибраними рахунками.
| Може використовуватись як альтернативний або додатковий сценарій.
|-
| Python-сервіс
| Інтеграційний шар між Приват24 та ERP.
| Реалізується в межах цього ТЗ.
|-
| ERP / бухгалтерська система
| Система-отримувач банківських операцій.
| Наприклад K2 ERP або інша облікова система.
|}

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

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

* доступ до Приват24 для бізнесу;
* доступ до потрібної компанії / ФОП;
* підключений сервіс «Інтеграція / Автоклієнт»;
* API credentials для Автоклієнта;
* перелік рахунків, за якими потрібно отримувати виписки;
* валюту рахунків;
* правила доступу користувачів;
* базовий URL API;
* формат авторизації;
* формат відповіді API;
* правила обмеження запитів;
* тестовий доступ або тестовий рахунок, якщо доступний.

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

{| class="wikitable"
! Термін
! Опис
|-
| Python-сервіс
| Окремий backend-сервіс або модуль для отримання виписок з Приват24.
|-
| Приват24 для бізнесу
| Інтернет-банк ПриватБанку для ФОП та юридичних осіб.
|-
| Автоклієнт
| Інтеграційний сервіс Приват24 для бізнесу для роботи з виписками та платежами.
|-
| Виписка
| Перелік банківських операцій за рахунком за певний період.
|-
| Транзакція
| Окрема банківська операція у виписці.
|-
| Polling
| Періодичне опитування API для отримання нових операцій.
|-
| Webhook
| Механізм отримання подій від зовнішньої системи, якщо підтримується.
|-
| Дедублікація
| Виявлення та пропуск операцій, які вже були імпортовані.
|-
| ERP
| Система, у яку передаються банківські операції.
|}

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

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

<pre>
Приват24 для бізнесу / Автоклієнт
        |
        | 1. API виписок
        v
Privat24 Integration Client
        |
        | 2. Отримання raw-виписки
        v
Python Bank Statement Service
        |
        | 3. Нормалізація операцій
        v
Validation & Deduplication Layer
        |
        | 4. Збереження в БД
        v
PostgreSQL / File Storage
        |
        | 5. Передача в ERP
        v
ERP / Accounting System
</pre>

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

{| class="wikitable"
! Компонент
! Опис
|-
| API Layer
| REST API для керування інтеграцією та запуску синхронізації.
|-
| Privat24 Client
| Python-клієнт для роботи з API Приват24 / Автоклієнта.
|-
| Account Sync Service
| Отримує та оновлює список рахунків.
|-
| Statement Sync Service
| Отримує банківські виписки за рахунками.
|-
| Transaction Normalizer
| Перетворює raw-операції банку у внутрішній формат.
|-
| Deduplication Service
| Перевіряє, чи операція вже була імпортована.
|-
| ERP Export Service
| Передає нормалізовані операції в ERP.
|-
| Audit Logger
| Фіксує всі запити, відповіді, помилки та результати синхронізації.
|-
| Background Worker
| Виконує регулярну синхронізацію за розкладом.
|}

== 7. User Story ==

=== 7.1. Отримання виписки вручну ===

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

=== 7.2. Автоматична синхронізація ===

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

=== 7.3. Дедублікація операцій ===

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

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

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

=== 7.5. Передача в ERP ===

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

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

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

Система повинна дозволяти зберігати налаштування підключення до Приват24.

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

{| class="wikitable"
! Поле
! Тип
! Обов'язковість
! Опис
|-
| integration_name
| string
| Так
| Назва інтеграції.
|-
| company_id
| string
| Так
| Ідентифікатор компанії / ФОП у локальній системі.
|-
| privat24_client_id
| string
| Ні
| Ідентифікатор клієнта, якщо використовується.
|-
| api_key
| secret
| Так
| Ключ або токен доступу до API.
|-
| base_url
| string
| Так
| Базова адреса API.
|-
| is_active
| boolean
| Так
| Ознака активності інтеграції.
|-
| sync_interval_minutes
| integer
| Так
| Інтервал автоматичної синхронізації.
|-
| default_date_from
| date
| Ні
| Дата початку первинного імпорту.
|}

=== 8.2. Отримання списку рахунків ===

Система повинна мати можливість отримати або зберегти перелік рахунків, за якими імпортується виписка.

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

<pre>
POST /api/v1/bank-integrations/{integration_id}/sync-accounts
</pre>

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

# Виконати запит до API Приват24.
# Отримати список доступних рахунків.
# Нормалізувати рахунки.
# Зберегти або оновити рахунки в локальній БД.
# Записати результат у журнал.

=== 8.3. Отримання виписки за період ===

Система повинна дозволяти отримати виписку за конкретним рахунком та періодом.

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

<pre>
POST /api/v1/bank-accounts/{account_id}/sync-statement
</pre>

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

<syntaxhighlight lang="json">
{
  "date_from": "2026-05-01",
  "date_to": "2026-05-07",
  "force": false
}
</syntaxhighlight>

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

# Перевірити доступ до рахунку.
# Перевірити коректність періоду.
# Виконати запит до API Приват24.
# Отримати raw-виписку.
# Зберегти raw-відповідь.
# Нормалізувати операції.
# Виконати дедублікацію.
# Зберегти нові операції.
# Передати операції в ERP, якщо увімкнено експорт.
# Записати результат у журнал.

=== 8.4. Автоматична синхронізація ===

Система повинна мати background worker для автоматичного отримання нових операцій.

Рекомендований алгоритм:

<pre>
1. Знайти всі активні інтеграції.
2. Для кожної інтеграції знайти активні рахунки.
3. Для кожного рахунку визначити дату останньої успішної синхронізації.
4. Запитати виписку з останньої дати до поточної дати.
5. Зберегти нові операції.
6. Оновити last_successful_sync_at.
7. Записати результат у журнал.
</pre>

=== 8.5. Нормалізація операцій ===

Raw-операція Приват24 повинна бути перетворена у внутрішню модель.

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

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| transaction_id
| string
| Унікальний ID операції з банку або сформований hash.
|-
| account_id
| uuid
| Внутрішній ID рахунку.
|-
| account_number
| string
| IBAN або номер рахунку.
|-
| operation_date
| date
| Дата операції.
|-
| value_date
| date
| Дата валютування, якщо доступна.
|-
| amount
| decimal
| Сума операції.
|-
| currency
| string
| Валюта операції.
|-
| direction
| string
| debit або credit.
|-
| balance_after
| decimal
| Залишок після операції, якщо доступний.
|-
| counterparty_name
| string
| Назва контрагента.
|-
| counterparty_account
| string
| Рахунок контрагента.
|-
| counterparty_code
| string
| ЄДРПОУ / РНОКПП контрагента, якщо доступно.
|-
| payment_purpose
| text
| Призначення платежу.
|-
| document_number
| string
| Номер платіжного документа.
|-
| raw_payload
| jsonb
| Оригінальна відповідь банку.
|}

=== 8.6. Дедублікація ===

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

Пріоритетні ключі дедублікації:

# Унікальний ID операції від банку.
# Комбінація: рахунок + дата + сума + номер документа + призначення платежу.
# Hash від нормалізованих ключових полів.
# Raw reference / bank reference, якщо доступний.

Приклад hash-ключа:

<pre>
sha256(account_number + operation_date + amount + currency + document_number + payment_purpose)
</pre>

=== 8.7. Передача операцій в ERP ===

Система повинна підтримувати передачу операцій в ERP.

Режими передачі:

{| class="wikitable"
! Режим
! Опис
|-
| Push
| Python-сервіс сам передає операції в ERP після синхронізації.
|-
| Pull
| ERP самостійно забирає операції через API Python-сервісу.
|-
| Manual export
| Користувач експортує виписку у CSV / JSON / XML.
|}

== 9. Статуси інтеграції та операцій ==

=== 9.1. Статуси синхронізації ===

{| class="wikitable"
! Статус
! Опис
|-
| NotConfigured
| Інтеграція ще не налаштована.
|-
| Active
| Інтеграція активна.
|-
| Disabled
| Інтеграція вимкнена.
|-
| AuthError
| Помилка авторизації.
|-
| Syncing
| Виконується синхронізація.
|-
| SyncSuccess
| Синхронізацію завершено успішно.
|-
| SyncFailed
| Синхронізацію завершено з помилкою.
|}

=== 9.2. Статуси банківських операцій ===

{| class="wikitable"
! Статус
! Опис
|-
| Imported
| Операцію імпортовано з банку.
|-
| Duplicate
| Операція визначена як дубль.
|-
| ExportedToERP
| Операцію передано в ERP.
|-
| ExportFailed
| Помилка передачі в ERP.
|-
| Ignored
| Операцію пропущено за правилом.
|-
| Matched
| Операцію зіставлено з документом в ERP.
|-
| Posted
| Операцію проведено в обліку.
|}

== 10. API Python-сервісу ==

=== 10.1. Створення інтеграції ===

<pre>
POST /api/v1/bank-integrations
</pre>

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

<syntaxhighlight lang="json">
{
  "integration_name": "Privat24 Main Company",
  "company_id": "company-001",
  "provider": "privat24_business",
  "base_url": "https://api.privatbank.ua/...",
  "api_key": "SECRET_VALUE",
  "sync_interval_minutes": 30,
  "is_active": true
}
</syntaxhighlight>

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

<syntaxhighlight lang="json">
{
  "id": "f4d2758e-9a97-4e64-80fb-443b9b864b01",
  "status": "Active",
  "message": "Integration created"
}
</syntaxhighlight>

=== 10.2. Перевірка підключення ===

<pre>
POST /api/v1/bank-integrations/{integration_id}/check-connection
</pre>

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

<syntaxhighlight lang="json">
{
  "integration_id": "f4d2758e-9a97-4e64-80fb-443b9b864b01",
  "status": "Active",
  "message": "Connection successful"
}
</syntaxhighlight>

=== 10.3. Синхронізація рахунків ===

<pre>
POST /api/v1/bank-integrations/{integration_id}/sync-accounts
</pre>

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

<syntaxhighlight lang="json">
{
  "integration_id": "f4d2758e-9a97-4e64-80fb-443b9b864b01",
  "accounts_created": 2,
  "accounts_updated": 1
}
</syntaxhighlight>

=== 10.4. Синхронізація виписки ===

<pre>
POST /api/v1/bank-accounts/{account_id}/sync-statement
</pre>

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

<syntaxhighlight lang="json">
{
  "date_from": "2026-05-01",
  "date_to": "2026-05-07",
  "force": false
}
</syntaxhighlight>

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

<syntaxhighlight lang="json">
{
  "account_id": "a5f0e82b-efb6-4f3a-8e08-4abefbb58c45",
  "date_from": "2026-05-01",
  "date_to": "2026-05-07",
  "imported": 42,
  "duplicates": 3,
  "errors": 0
}
</syntaxhighlight>

=== 10.5. Отримання списку операцій ===

<pre>
GET /api/v1/bank-accounts/{account_id}/transactions?date_from=2026-05-01&date_to=2026-05-07
</pre>

=== 10.6. Експорт операцій в ERP ===

<pre>
POST /api/v1/bank-accounts/{account_id}/export-to-erp
</pre>

=== 10.7. Отримання журналу синхронізації ===

<pre>
GET /api/v1/bank-integrations/{integration_id}/sync-events
</pre>

== 11. Privat24 Integration Client ==

=== 11.1. Призначення ===

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

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

<syntaxhighlight lang="python">
class Privat24Client:
    def check_connection(self) -> "Privat24ConnectionResponse":
        pass

    def get_accounts(self) -> list["Privat24Account"]:
        pass

    def get_statement(
        self,
        account_number: str,
        date_from: date,
        date_to: date,
    ) -> "Privat24StatementResponse":
        pass

    def get_transaction_details(
        self,
        transaction_id: str,
    ) -> "Privat24TransactionResponse":
        pass
</syntaxhighlight>

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

<syntaxhighlight lang="python">
from pydantic_settings import BaseSettings


class Privat24Settings(BaseSettings):
    base_url: str
    api_key: str
    client_id: str | None = None
    company_id: str | None = None
    timeout_seconds: int = 30
    retry_count: int = 3
    retry_backoff_seconds: int = 5
    verify_ssl: bool = True
</syntaxhighlight>

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

<pre>
PRIVAT24_BASE_URL=https://api.privatbank.ua/...
PRIVAT24_API_KEY=********
PRIVAT24_CLIENT_ID=********
PRIVAT24_COMPANY_ID=company-001
PRIVAT24_TIMEOUT_SECONDS=30
PRIVAT24_RETRY_COUNT=3
PRIVAT24_RETRY_BACKOFF_SECONDS=5
</pre>

<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
'''Заборонено:''' зберігати API key, client secret, токени або банківські credentials у коді, Git-репозиторії чи відкритих логах.
</div>

== 12. Отримання виписки ==

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

<pre>
1. Отримати рахунок з БД.
2. Перевірити, що інтеграція активна.
3. Визначити період синхронізації.
4. Викликати Privat24Client.get_statement().
5. Зберегти raw-відповідь банку.
6. Нормалізувати операції.
7. Виконати дедублікацію.
8. Зберегти нові операції.
9. Передати операції в ERP, якщо увімкнено auto_export.
10. Оновити дату останньої синхронізації.
11. Записати результат у журнал.
</pre>

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

<syntaxhighlight lang="python">
from datetime import date
from uuid import UUID


def sync_statement(
    account_id: UUID,
    date_from: date,
    date_to: date,
    db: "Session",
) -> "StatementSyncResult":
    account = bank_account_repository.get_by_id(db, account_id)
    integration = bank_integration_repository.get_by_id(
        db,
        account.integration_id,
    )

    if not integration.is_active:
        raise IntegrationDisabledError("Privat24 integration is disabled")

    response = privat24_client.get_statement(
        account_number=account.account_number,
        date_from=date_from,
        date_to=date_to,
    )

    raw_statement_repository.save(
        db=db,
        account_id=account.id,
        date_from=date_from,
        date_to=date_to,
        payload=response.raw_payload,
    )

    imported = 0
    duplicates = 0

    for raw_operation in response.operations:
        operation = transaction_normalizer.normalize(
            account=account,
            raw_operation=raw_operation,
        )

        if transaction_repository.exists_by_unique_key(
            db,
            operation.unique_key,
        ):
            duplicates += 1
            continue

        transaction_repository.create(db, operation)
        imported += 1

    account.last_successful_sync_at = datetime.utcnow()

    sync_event_repository.create(
        db=db,
        integration_id=integration.id,
        account_id=account.id,
        event_type="STATEMENT_SYNC_SUCCESS",
        payload={
            "date_from": str(date_from),
            "date_to": str(date_to),
            "imported": imported,
            "duplicates": duplicates,
        },
    )

    db.commit()

    return StatementSyncResult(
        imported=imported,
        duplicates=duplicates,
        errors=0,
    )
</syntaxhighlight>

== 13. Автоматична синхронізація ==

=== 13.1. Рекомендований режим ===

Для бізнес-рахунків рекомендовано виконувати синхронізацію:

{| class="wikitable"
! Тип синхронізації
! Інтервал
! Опис
|-
| Поточний день
| кожні 15–30 хвилин
| Отримання нових операцій за поточний день.
|-
| Попередній день
| 1 раз на день
| Контрольна синхронізація для операцій, які могли з'явитися із затримкою.
|-
| Архівний період
| вручну
| Завантаження історичних виписок за вибраний період.
|}

=== 13.2. Приклад worker-а ===

<syntaxhighlight lang="python">
from datetime import date, timedelta


def sync_all_active_accounts() -> None:
    accounts = bank_account_repository.get_active_accounts()

    for account in accounts:
        try:
            date_to = date.today()
            date_from = account.last_successful_sync_at.date() \
                if account.last_successful_sync_at else date_to

            sync_statement(
                account_id=account.id,
                date_from=date_from,
                date_to=date_to,
                db=session_factory(),
            )

        except Exception as exc:
            sync_event_repository.create(
                db=session_factory(),
                integration_id=account.integration_id,
                account_id=account.id,
                event_type="STATEMENT_SYNC_FAILED",
                payload={"error": str(exc)},
            )
</syntaxhighlight>

== 14. Модель даних ==

=== 14.1. bank_integrations ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| Внутрішній ID інтеграції.
|-
| provider
| varchar
| privat24_business.
|-
| integration_name
| varchar
| Назва інтеграції.
|-
| company_id
| varchar
| ID компанії в ERP.
|-
| base_url
| varchar
| Базова адреса API.
|-
| api_key_encrypted
| text
| Зашифрований API key.
|-
| client_id
| varchar
| ID клієнта, якщо використовується.
|-
| is_active
| boolean
| Ознака активності.
|-
| sync_interval_minutes
| integer
| Інтервал синхронізації.
|-
| last_check_at
| timestamp
| Дата останньої перевірки підключення.
|-
| last_successful_sync_at
| timestamp
| Дата останньої успішної синхронізації.
|-
| created_at
| timestamp
| Дата створення.
|-
| updated_at
| timestamp
| Дата оновлення.
|}

=== 14.2. bank_accounts ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| Внутрішній ID рахунку.
|-
| integration_id
| uuid
| ID інтеграції.
|-
| company_id
| varchar
| ID компанії в ERP.
|-
| account_number
| varchar
| IBAN або номер рахунку.
|-
| account_name
| varchar
| Назва рахунку.
|-
| currency
| varchar
| Валюта рахунку.
|-
| bank_mfo
| varchar
| МФО банку.
|-
| is_active
| boolean
| Чи синхронізується рахунок.
|-
| last_successful_sync_at
| timestamp
| Дата останньої успішної синхронізації.
|-
| created_at
| timestamp
| Дата створення.
|-
| updated_at
| timestamp
| Дата оновлення.
|}

=== 14.3. bank_transactions ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| Внутрішній ID операції.
|-
| account_id
| uuid
| ID рахунку.
|-
| unique_key
| varchar
| Унікальний ключ для дедублікації.
|-
| bank_transaction_id
| varchar
| ID операції від банку, якщо доступний.
|-
| operation_date
| date
| Дата операції.
|-
| value_date
| date
| Дата валютування.
|-
| amount
| numeric
| Сума операції.
|-
| currency
| varchar
| Валюта.
|-
| direction
| varchar
| debit або credit.
|-
| balance_after
| numeric
| Залишок після операції.
|-
| counterparty_name
| varchar
| Контрагент.
|-
| counterparty_account
| varchar
| Рахунок контрагента.
|-
| counterparty_code
| varchar
| ЄДРПОУ / РНОКПП контрагента.
|-
| payment_purpose
| text
| Призначення платежу.
|-
| document_number
| varchar
| Номер документа.
|-
| status
| varchar
| Статус операції.
|-
| raw_payload
| jsonb
| Raw-відповідь банку.
|-
| imported_at
| timestamp
| Дата імпорту.
|-
| exported_to_erp_at
| timestamp
| Дата передачі в ERP.
|}

=== 14.4. bank_sync_events ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID події.
|-
| integration_id
| uuid
| ID інтеграції.
|-
| account_id
| uuid
| ID рахунку.
|-
| event_type
| varchar
| Тип події.
|-
| status
| varchar
| Результат.
|-
| date_from
| date
| Початок періоду.
|-
| date_to
| date
| Кінець періоду.
|-
| imported_count
| integer
| Кількість імпортованих операцій.
|-
| duplicate_count
| integer
| Кількість дублів.
|-
| error_count
| integer
| Кількість помилок.
|-
| payload
| jsonb
| Технічні дані події.
|-
| created_at
| timestamp
| Дата події.
|}

== 15. Обробка помилок ==

=== 15.1. Типи помилок ===

{| class="wikitable"
! Тип помилки
! Опис
! Дія системи
|-
| Privat24AuthError
| Помилка авторизації.
| Зупинити синхронізацію, повідомити адміністратора.
|-
| Privat24ApiError
| API повернув помилку.
| Записати відповідь API, дозволити повтор.
|-
| Privat24TimeoutError
| Перевищено час очікування.
| Виконати retry.
|-
| Privat24RateLimitError
| Перевищено ліміт запитів.
| Збільшити інтервал повтору.
|-
| AccountAccessError
| Немає доступу до рахунку.
| Вимкнути рахунок або повідомити адміністратора.
|-
| StatementParseError
| Неможливо розібрати відповідь банку.
| Зберегти raw-відповідь і помилку.
|-
| DuplicateTransactionError
| Операція вже існує.
| Позначити як Duplicate або пропустити.
|-
| ErpExportError
| Помилка передачі в ERP.
| Зберегти операцію та дозволити повторний експорт.
|}

=== 15.2. Retry-логіка ===

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

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

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

* неправильного API key;
* відсутності доступу до рахунку;
* некоректного періоду;
* помилок валідації налаштувань;
* операцій, які вже імпортовані.

== 16. Безпека ==

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

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

== 17. Налаштування ==

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

<pre>
APP_ENV=production
DATABASE_URL=postgresql+psycopg://user:password@db:5432/bank_statements
FILE_STORAGE_PATH=/data/bank-statements

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

STATEMENT_SYNC_ENABLED=true
STATEMENT_SYNC_INTERVAL_SECONDS=1800
ERP_EXPORT_ENABLED=true
</pre>

=== 17.2. Конфігурація синхронізації ===

<syntaxhighlight lang="yaml">
bank_statement_sync:
  provider: privat24_business
  default_period_days: 3
  sync_current_day: true
  sync_previous_day_daily: true
  deduplication:
    strategy: bank_id_or_hash
    hash_fields:
      - account_number
      - operation_date
      - amount
      - currency
      - document_number
      - payment_purpose
  export_to_erp:
    enabled: true
    mode: push
</syntaxhighlight>

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

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

{| class="wikitable"
! Подія
! Що зберігати
|-
| Створення інтеграції
| ID, користувач, дата, provider.
|-
| Перевірка підключення
| Результат, дата, технічний статус.
|-
| Синхронізація рахунків
| Кількість створених і оновлених рахунків.
|-
| Запит виписки
| Рахунок, період, час запиту.
|-
| Успішна синхронізація
| Кількість імпортованих операцій і дублів.
|-
| Помилка API
| HTTP-код, тіло відповіді, correlation ID.
|-
| Дедублікація
| Кількість пропущених операцій.
|-
| Експорт в ERP
| Кількість переданих операцій, результат.
|-
| Помилка експорту
| Текст помилки, ID операції, дата.
|}

== 19. Acceptance Criteria ==

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

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-1
| Адміністратор створює інтеграцію з Приват24.
| У системі створюється запис bank_integrations.
|-
| AC-2
| Адміністратор перевіряє підключення.
| Система повертає успішний або помилковий результат.
|-
| AC-3
| API key неправильний.
| Система показує AuthError і не запускає синхронізацію.
|}

=== 19.2. Отримання рахунків ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-4
| Запущено sync-accounts.
| Система отримує та зберігає рахунки.
|-
| AC-5
| Рахунок уже існує.
| Система оновлює його дані, а не створює дубль.
|}

=== 19.3. Отримання виписки ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-6
| Користувач запускає sync-statement за період.
| Система отримує виписку з Приват24.
|-
| AC-7
| У виписці є нові операції.
| Система зберігає нові операції в bank_transactions.
|-
| AC-8
| У виписці є вже імпортовані операції.
| Система не створює дублікати.
|-
| AC-9
| API Приват24 повертає помилку.
| Система зберігає помилку в журналі.
|}

=== 19.4. Автоматична синхронізація ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-10
| Worker запущено.
| Система автоматично синхронізує активні рахунки.
|-
| AC-11
| Синхронізація успішна.
| Оновлюється last_successful_sync_at.
|-
| AC-12
| Синхронізація завершилась помилкою.
| Помилка записується в bank_sync_events.
|}

=== 19.5. Передача в ERP ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-13
| Увімкнено ERP export.
| Нові операції передаються в ERP.
|-
| AC-14
| ERP повертає успіх.
| Операції отримують статус ExportedToERP.
|-
| AC-15
| ERP повертає помилку.
| Операції отримують статус ExportFailed.
|}

== 20. MVP ==

До MVP входить:

* REST API для створення інтеграції;
* збереження API credentials;
* перевірка підключення;
* отримання списку рахунків;
* отримання виписки за період;
* збереження raw-відповіді;
* нормалізація операцій;
* дедублікація;
* збереження операцій у PostgreSQL;
* ручний запуск синхронізації;
* журнал подій;
* базова обробка помилок.

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

* створення платежів;
* підписання платежів;
* webhook-інтеграція;
* складний UI;
* автоматичне рознесення оплат;
* підтримка всіх банків;
* валютний контроль;
* прогнозування платежів.

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

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

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

=== Етап 2. Налаштування інтеграції ===

* реалізувати створення інтеграції;
* реалізувати зберігання credentials;
* реалізувати шифрування API key;
* реалізувати check-connection;
* реалізувати журнал налаштувань.

=== Етап 3. Privat24 Integration Client ===

* реалізувати авторизацію;
* реалізувати get_accounts;
* реалізувати get_statement;
* реалізувати обробку помилок;
* реалізувати retry;
* написати mock-тести.

=== Етап 4. Синхронізація рахунків ===

* реалізувати sync-accounts;
* зберігати рахунки;
* оновлювати існуючі рахунки;
* дозволити активувати / деактивувати рахунки.

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

* реалізувати sync-statement;
* зберігати raw-відповіді;
* нормалізувати операції;
* реалізувати дедублікацію;
* зберігати операції.

=== Етап 6. Автоматична синхронізація ===

* реалізувати background worker;
* реалізувати періодичне оновлення виписок;
* реалізувати контроль останньої успішної синхронізації;
* реалізувати повторну синхронізацію після помилки.

=== Етап 7. Передача в ERP ===

* реалізувати export-to-erp;
* реалізувати статуси експорту;
* обробити помилки ERP;
* додати повторний експорт.

=== Етап 8. Production hardening ===

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

== 22. Ризики ==

{| class="wikitable"
! Ризик
! Опис
! Як зменшити
|-
| Неповна API-документація
| Частина параметрів Автоклієнта може бути доступна тільки після підключення в Приват24 для бізнесу.
| Отримати credentials і технічні налаштування в кабінеті клієнта.
|-
| Зміна API
| Формат відповіді або endpoint-и можуть змінюватися.
| Інкапсулювати API в окремому Privat24Client.
|-
| Дублювання операцій
| Повторна синхронізація може створити дублікати.
| Реалізувати кілька рівнів дедублікації.
|-
| Затримка операцій
| Деякі операції можуть з'являтися у виписці із затримкою.
| Щодня повторно синхронізувати попередній день.
|-
| Помилки авторизації
| API key може бути неправильним або зміненим.
| Додати check-connection і сповіщення адміністратора.
|-
| Rate limit
| API може обмежувати частоту запитів.
| Додати backoff і контроль інтервалів.
|-
| Персональні дані
| Виписки містять фінансові та персональні дані.
| Маскувати логи, шифрувати secrets, обмежити доступ.
|}

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

# Який саме канал використовується: Автоклієнт, Відкрита виписка або інший API ПриватБанку?
# Який базовий URL API для конкретного клієнта?
# Який механізм авторизації використовується?
# Які рахунки потрібно синхронізувати?
# Чи потрібна підтримка ФОП, юридичних осіб або обох варіантів?
# Чи потрібна підтримка валютних рахунків?
# Який максимальний історичний період потрібно імпортувати?
# Як часто потрібно оновлювати виписки?
# Чи потрібно передавати операції в ERP автоматично?
# Чи потрібно реалізувати ручний експорт CSV / JSON?
# Які поля операції обов'язкові для ERP?
# Який алгоритм дедублікації вважати основним?
# Чи потрібно зберігати raw-відповіді банку?
# Хто має доступ до API key?
# Чи потрібен UI, чи тільки backend API?

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

<pre>
privat24_statement_service/
  app/
    main.py
    config.py
    api/
      routes/
        bank_integrations.py
        bank_accounts.py
        bank_transactions.py
        health.py
    core/
      security.py
      logging.py
      exceptions.py
    db/
      session.py
      models.py
      migrations/
    services/
      account_sync_service.py
      statement_sync_service.py
      transaction_normalizer.py
      deduplication_service.py
      erp_export_service.py
    integrations/
      privat24/
        client.py
        schemas.py
        exceptions.py
    repositories/
      bank_integration_repository.py
      bank_account_repository.py
      bank_transaction_repository.py
      sync_event_repository.py
    workers/
      sync_statements.py
    storage/
      raw_statement_storage.py
  tests/
    unit/
    integration/
  Dockerfile
  docker-compose.yml
  pyproject.toml
  README.md
</pre>

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

{| class="wikitable"
! Компонент
! Рекомендація
|-
| 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-форматі.
|-
| Secrets
| Vault, Doppler, AWS Secrets Manager або аналог.
|}

== 26. Definition of Done ==

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

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

== 27. Джерела ==

* https://privatbank.ua/business/intehratsiya
* https://privatbank.ua/business/openstatement
* https://api.privatbank.ua/
* https://privatbank.ua/business/app-pryvat24
* https://privatbank.ua/business/vse-servisy-ucheta-i-otchetnosti

== 28. Див. також ==

* [[Python]]
* [[FastAPI]]
* [[K2 ERP]]
* [[Приват24]]
* [[Приват24 для бізнесу]]
* [[ПриватБанк]]
* [[Автоклієнт]]
* [[Банківська виписка]]
* [[API інтеграція]]
* [[ERP]]

[[Категорія:Технічні завдання]]
[[Категорія:Python]]
[[Категорія:Приват24]]
[[Категорія:ПриватБанк]]
[[Категорія:API]]
[[Категорія:Банківські виписки]]
[[Категорія:Інтеграції]]
[[Категорія:K2 ERP]]