| id
|
uuid
|
-
|
is_active
|
boolean
|
Так
|
Ознака активності інтеграції.; Тип
|
-
|
AC-9
|
платформа зберігає помилку в журналі.; default_period_days: 3
PRIVAT24_BASE_URL=https://api.privatbank.ua/...
"sync_interval_minutes": 30,
Очікувана відповідь:
main.py
integrations/
APP_ENV=production
{| class="wikitable"
date_to=date_to,
if not integration.is_active:
</div>
!; # Зберегти або оновити рахунки в локальній БД.; # Записати результат у журнал.; |-
| counterparty_name
| string
| Назва контрагента.; Статус
!; |-
| last_successful_sync_at
| timestamp
| Дата останньої успішної синхронізації.; Призначення
<syntaxhighlight lang="json">
|
| 5.; Тип
event_type="STATEMENT_SYNC_FAILED",
!;<pre>
* реалізувати авторизацію;
* реалізувати get_accounts;
* реалізувати get_statement;
* реалізувати обробку помилок;
* реалізувати retry;
* написати mock-тести.; Передати операції в ERP, якщо увімкнено auto_export.; |-
| account_id
| uuid
| ID рахунку.; |-
| Rate limit
| API має змогу обмежувати частоту запитів.; !; Поле
щоб бухгалтерський обліковий облік залишався коректним.; |-
| bank_transaction_id
| varchar
| ID операції від банку, якщо доступний.; # Як часто потрібно оновлювати виписки?; |}
== 25.; Технічні вимоги до Python ==
=== Етап 4.; Синхронізація рахунків ===
!; |-
| Background jobs
| Celery, RQ або APScheduler.; |-
| created_at
| timestamp
| Дата створення.; |-
| AuthError
| Помилка авторизації.; |-
| ExportedToERP
| Операцію передано в ERP.; Тип
"integration_id": "f4d2758e-9a97-4e64-80fb-443b9b864b01",
!; |-
| Дедублікація
| Кількість пропущених операцій.; Записати результат у журнал.; |-
| bank_mfo
| varchar
| МФО банку.; |-
| status
| varchar
| Результат.; # Які рахунки потрібно синхронізувати?;<syntaxhighlight lang="json">
* створення платежів;
* підписання платіжних доручень;
* відправка платежів у банк;
* валютний контроль;
* бухгалтерське проведення операцій;
* автоматичне рознесення оплат по рахунках;
* UI для повного банківського клієнта;
* інтеграційні функціональні можливості з картками фізичних осіб, якщо задача стосується лише бізнес-рахунків.; |}
== 14.; Модель даних ==
PRIVAT24_CLIENT_ID=********
client_id: str | None = None
|-
| id
| uuid
| ID події.; Оновити last_successful_sync_at.; | Позначити як Duplicate або пропустити.; |}
!; Нормалізувати операції.; |-
| SyncFailed
| Синхронізацію завершено з помилкою.; |-
| integration_id
| uuid
| ID інтеграції.; |}
FILE_STORAGE_PATH=/data/bank-statements
платформа повинна не допускати дублювання операцій.; |-
| Containers
| Docker.; №
=== 9.1.; Статуси синхронізації ===
1.; |-
| api_key_encrypted
| text
| Зашифрований API key.; |-
| account_number
| string
| IBAN або номер рахунку.; "message": "Integration created"
* 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
!; |-
| Migrations
| Alembic.; !; Поле
=== 10.2.; Перевірка підключення ===
account_number: str,
|-
| AC-13
| Увімкнено ERP export.; характеристика
|-
| NotConfigured
| інтеграційні функціональні можливості ще не налаштована.; date_from = account.last_successful_sync_at.date() \
=== 6.2.; Основні компоненти Python-сервісу ===
!; # Raw reference / bank reference, якщо доступний.; |-
| Duplicate
| операційна дія визначена як дубль.; характеристика
{| class="wikitable"
security.py
=== 17.1.; Змінні середовища ===
2.; |}
<pre>
!; | Зберегти операцію та дозволити повторний експорт.;
"message": "Connection successful"
README.md
24.; Приклад структури Python-проєкту
| ;== 21.; Етапи реалізації ==
Логічний endpoint Python-сервісу:
- зберігання API key тільки у змінних середовища або secret storage;
- шифрування API key у БД;
- заборону логування API key;
- маскування номерів рахунків у технічних логах за потреби;
- маскування персональних даних контрагентів у логах;
- контроль доступу до виписок;
- журналювання всіх операцій синхронізації;
- HTTPS для всіх API-запитів;
- перевірку SSL-сертифіката;
- обмеження доступу до адміністративних endpoint-ів;
- резервне копіювання виписок і журналів.; |-
|
Приват24 для бізнесу
|
-
|
ErpExportError
|
-
|
integration_id
|
uuid
|
Реалізувати кілька рівнів дедублікації.; |}
7.4.; Контроль помилок
class Privat24Settings(BaseSettings):
- timeout;
- тимчасової недоступності API;
- HTTP 429;
- HTTP 500;
- HTTP 502;
- HTTP 503;
- HTTP 504;
- тимчасових мережевих помилок.; |-
|
AC-8
|
платформа зберігає нові операції в bank_transactions.; Критерій
14.4. bank_sync_events
Python Bank Statement Service
Як користувач системи ERP,
date_from=date_from,
- document_number
STATEMENT_SYNC_INTERVAL_SECONDS=1800
3.; Джерела інтеграції
</syntaxhighlight>
- currency
|
; Термін
8.2.; Отримання списку рахунківv
| -
|
Виписка
|
-
|
unique_key
|
varchar
|
Унікальний ключ для дедублікації.; # Нормалізувати операції.; характеристика
|
-
|
Background Worker
|
Реалізується в межах цього ТЗ.; "date_from": "2026-05-01",
13.1.; Рекомендований режим
retry_backoff_seconds: int = 5
try:
Dockerfile
"date_to": "2026-05-07",
щоб не завантажувати виписки вручну з Приват24.; |}
- account_number
}
if account.last_successful_sync_at else date_to
date_to = date.today()
{
raise IntegrationDisabledError("Privat24 integration is disabled")
|-
| AC-4
| Запущено sync-accounts.; | Отримати credentials і технічні конфігурація в кабінеті клієнта.; Отримання raw-виписки
hash_fields:
"id": "f4d2758e-9a97-4e64-80fb-443b9b864b01",
|
| 3.; |-
| DB
| PostgreSQL.; Фінальні endpoint-и, формат авторизації та доступні поля виписки потрібно підтвердити в API-налаштуваннях конкретного клієнта ПриватБанку.; |-
| payload
| jsonb
| Технічні інформаційні дані події.;=== 8.5.; Нормалізація операцій ===
},
{| class="wikitable"
== 2.; Область сфера застосування ==
5.; |-
| Posted
| Операцію проведено в обліку.; |}
{| class="wikitable"
</pre>
PRIVAT24_RETRY_COUNT=3
unit/
"status": "Active",
платформа повинна логувати:
|-
| Privat24AuthError
| Помилка авторизації.; ) -> "Privat24StatementResponse":
!; |-
| balance_after
| decimal
| Залишок після операції, якщо доступний.; |-
| counterparty_account
| varchar
| Рахунок контрагента.; | Інкапсулювати API в окремому Privat24Client.; |-
| company_id
| varchar
| ID компанії в ERP.; Записати результат у журнал.; |-
| company_id
| varchar
| ID компанії в ERP.; №
функціональні можливості застосовують, коли потрібно для автоматизації імпорту банківських операцій з Приват24 для бізнесу в ERP або бухгалтерську систему.; |-
| Архівний період
| вручну
| Завантаження історичних виписок за вибраний період.; |-
| base_url
| string
| Так
| Базова адреса API.; |-
| account_id
| uuid
| Внутрішній ID рахунку.; Перевірити, що інтеграційні функціональні можливості активна.; # Який базовий URL API для конкретного клієнта?; характеристика
provider: privat24_business
bank_integration_repository.py
"duplicates": duplicates,
До першої версії не входить:
duplicates += 1
!; |}
}
<syntaxhighlight lang="python">
routes/
<pre>
"base_url": "https://api.privatbank.ua/...",
!; |-
| operation_date
| date
| Дата операції.; |}
ERP_EXPORT_ENABLED=true
)
account.integration_id,
Validation & Deduplication Layer
date_to: date,
Приклад тіла запиту:
|-
| AC-1
| Адміністратор створює інтеграцію з Приват24.; Тип
from uuid import UUID
10.7.; Отримання журналу синхронізації
"account_id": "a5f0e82b-efb6-4f3a-8e08-4abefbb58c45",
Retry застосовується для:
- Виконати запит до API Приват24.; Зберегти нові операції.; Отримати рахунок з БД.; Критерій
integration_id=account.integration_id,
bank_statement_sync:
7.5.; Передача в ERP
pass
4.; |-
|
amount
|
decimal
|
Сума операції.; v
health.py
Privat24 Integration Client
for account in accounts:
| ; Очікуваний результат
|
| Неповна API-документація
|
Частина параметрів Автоклієнта має змогу бути доступна тільки після підключення в Приват24 для бізнесу.; характеристика
|
У системі створюється запис bank_integrations.; |-
|
Успішна синхронізація
|
-
|
last_check_at
|
timestamp
|
Дата останньої перевірки підключення.; Тип синхронізації
statement_sync_service.py
19.1.; конфігурація інтеграції
9.; Статуси інтеграції та операцій
8.; "provider": "privat24_business",
{
ERP / Accounting System
|
|
-
|
date_to
|
date
|
платформа повертає успішний або помилковий результат.; |}
щоб оперативно імпортувати банківські операції в ERP.; |-
|
AC-7
|
-
|
Secrets
|
Vault, Doppler, AWS Secrets Manager або аналог.; Компонент
"company_id": "company-001",
</syntaxhighlight>
Очікувана відповідь:
10.1.; Створення інтеграції
|
| AC-10
|
Worker запущено.; характеристика
|
| integration_name
|
string
|
Так
|
-
|
Active
|
Виконати retry.; |-
|
DuplicateTransactionError
|
-
|
raw_payload
|
jsonb
|
Raw-відповідь банку.; характеристика
db/
for raw_operation in response.operations:
{{SEO
|title=Технічне завдання: Отримання банківських виписок з Приват24 для Python
|description=Технічне завдання на реалізацію Python-сервісу для автоматичного отримання банківських виписок з Приват24 для бізнесу через інтеграцію Автоклієнт / API ПриватБанку.
|keywords=Python, Приват24, Приват24 для бізнесу, ПриватБанк, банківська виписка, Автоклієнт, API, інтеграція, FastAPI, технічне завдання
}}
transaction_normalizer.py
<pre>
except Exception as exc:
Приклад тіла запиту:
"date_to": str(date_to),
== 6.; технічна архітектура рішення для бізнесу ==
== 17.; конфігурація ==
app/
self,
=== 11.3.; Конфігурація клієнта ===
bank_transactions.py
"date_to": "2026-05-07",
</div>
1.; |-
| Помилка API
| HTTP-код, тіло відповіді, correlation ID.; | платформа показує AuthError і не запускає синхронізацію.; |-
| Персональні інформаційні дані
| Виписки містять фінансові та персональні інформаційні дані.; Дія системи
class Privat24Client:
7.; # Який механізм авторизації застосовується?; |-
| status
| varchar
| Статус операції.; |}
bank_integrations.py
</pre>
<pre>
платформа повинна дозволяти зберігати конфігурація підключення до Приват24.; # Зберегти raw-відповідь.; Тип
v
POST /api/v1/bank-integrations/{integration_id}/check-connection
платформа повинна підтримувати передачу операцій в ERP.; |-
| account_id
| uuid
| ID рахунку.; |-
| payment_purpose
| text
| Призначення платежу.; # Чи потрібно реалізувати ручний експорт CSV / JSON?; # Виконати запит до API Приват24.; # Який алгоритм дедублікації вважати основним?; Поле
erp_export_service.py
=== 19.2.; Отримання рахунків ===
До MVP не входить:
!; |}
STATEMENT_SYNC_ENABLED=true
# Який саме канал застосовується: Автоклієнт, Відкрита виписка або інший API ПриватБанку?; |-
| Polling
| Періодичне опитування API для отримання нових операцій.;== 4.; Передумови ==
POST /api/v1/bank-accounts/{account_id}/export-to-erp
== 13.; Автоматична синхронізація ==
Для реалізації задачі необхідно отримати:
{| class="wikitable"
imported += 1
!; №
* Python-сервіс розгортається через Docker;
* API створення інтеграції функціонує;
* API key зберігається безпечно;
* check-connection функціонує;
* список рахунків отримується або зберігається вручну;
* виписка за період отримується;
* raw-відповідь зберігається;
* операції нормалізуються;
* дедублікація функціонує;
* операції зберігаються в БД;
* автоматична синхронізація функціонує;
* помилки API обробляються;
* retry-механізм функціонує;
* журнал подій заповнюється;
* написані unit-тести для ключових сервісів;
* написані інтеграційні тести для Privat24Client з mock API;
* документація для запуску додана в README;
* фінальні endpoint-и Приват24 винесені в конфігурацію.; Поле
GET /api/v1/bank-accounts/{account_id}/transactions?date_from=2026-05-01&date_to=2026-05-07
=== 7.2.; Автоматична синхронізація ===
== 1.; Мета ==
Очікувана відповідь:
raw_operation=raw_operation,
{{DISPLAYTITLE:Технічне завдання: Отримання банківських виписок з Приват24 для Python}}
{| class="wikitable"
=== 10.6.; Експорт операцій в ERP ===
== 27.; Джерела ==
я хочу, щоб платформа автономно отримувала нові банківські операції,
== 18.; Логування та аудит ==
"force": false
PRIVAT24_RETRY_COUNT=3
== 19. Acceptance Criteria ==
PRIVAT24_COMPANY_ID=company-001
schemas.py
) -> "Privat24TransactionResponse":
)
!; |-
| Web framework
| FastAPI.; |-
| created_at
| timestamp
| Дата події.; |-
| Validation
| Pydantic.; |-
| Синхронізація рахунків
| Кількість створених і оновлених рахунків.; характеристика
self,
=== 7.1.; Отримання виписки вручну ===
mode: push
operation.unique_key,
bank_account_repository.py
[[Категорія:Python]]
5.; Критерій
=== 19.5.; Передача в ERP ===
account_sync_service.py
'''Технічний стек:''' Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Docker.; |-
| privat24_client_id
| string
| Ні
| Ідентифікатор клієнта, якщо застосовується.; db.commit()
"duplicates": 3,
migrations/
3.; |-
| Matched
| Операцію зіставлено з документом в ERP.; |-
| company_id
| string
| Так
| Ідентифікатор компанії / ФОП у локальній системі.; | Операції отримують статус ExportFailed.; Викликати Privat24Client.get_statement().; платформа повинна мати background worker для автоматичного отримання нових операцій.;=== Етап 5.; Синхронізація виписок ===
logging.py
"date_from": "2026-05-01",
* створення Python API для керування інтеграцією;
* створення клієнта інтеграції з Приват24 / Автоклієнтом;
* отримання виписок за рахунками;
* отримання виписок за період;
* збереження raw-відповідей банку;
* нормалізація операцій;
* дедублікація операцій;
* фонове актуалізація виписок;
* журнал синхронізації;
* retry-механізм;
* експорт даних у ERP.; | платформа отримує та зберігає рахунки.; |-
| raw_payload
| jsonb
| Оригінальна відповідь банку.; |-
| base_url
| varchar
| Базова адреса API.; |}
POST /api/v1/bank-integrations/{integration_id}/sync-accounts
db,
PRIVAT24_API_KEY=********
GET /api/v1/bank-integrations/{integration_id}/sync-events
|
| id
|
uuid
|
-
|
account_number
|
varchar
|
IBAN або номер рахунку.; db: "Session",
=== 19.3.; Отримання виписки ===
!; # Комбінація: рахунок + дата + сума + номер документа + призначення платежу.; |-
| Попередній день
| 1 раз на день
| Контрольна синхронізація для операцій, які могли з'явитися із затримкою.; Приклад змінних середовища:
щоб оперативно знаходити та виправляти проблеми.; |-
| updated_at
| timestamp
| Дата актуалізація.; PRIVAT24_COMPANY_ID=company-001
PostgreSQL / File Storage
<pre>
Рекомендований алгоритм:
[[Категорія:Технічні завдання]]
"date_to": "2026-05-07",
integration_id=integration.id,
account = bank_account_repository.get_by_id(db, account_id)
bank_accounts.py
=== 8.7.; Передача операцій в ERP ===
Raw-операція Приват24 повинна бути перетворена у внутрішню модель.; |-
| Deduplication Service
| Перевіряє, чи операційна дія вже була імпортована.; # Чи потрібно передавати операції в ERP автономно?; PRIVAT24_CLIENT_ID=********
|-
| AC-6
| користувач системи запускає sync-statement за період.; |-
| direction
| varchar
| debit або credit.; |-
| ERP
| платформа, у яку передаються банківські операції.; №
- amount
duplicates=duplicates,
=== 7.3.; Дедублікація операцій ===
!; if transaction_repository.exists_by_unique_key(
integration = bank_integration_repository.get_by_id(
!; Поле
models.py
=== 11.1.; Призначення ===
)
date_to=date_to,
я хочу бачити отримані банківські операції в ERP,
|
; Компонент
Мінімальний набір полів операції:
Див.; 28.; додатково
7. User Story
Задача вважається завершеною, якщо:
Етап 3.; Privat24 Integration Client
POST /api/v1/bank-integrations
{
Як бухгалтер,
</syntaxhighlight>
|
| Поточний день
|
кожні 15–30 хвилин
|
-
|
HTTP client
|
httpx.; # Зберегти нові операції.;== 15.; Обробка помилок ==
"status": "Active",
я хочу запустити отримання виписки за вибраним рахунком і періодом,
payload={"error": str(exc)},
|
| Python-сервіс
|
Окремий backend-сервіс або компонент для отримання виписок з Приват24.;
PRIVAT24_TIMEOUT_SECONDS=30
{| class="wikitable"
[[Категорія:API]]
account_id=account.id,
continue
{| class="wikitable"
<syntaxhighlight lang="json">
=== 9.2.; Статуси банківських операцій ===
tests/
PRIVAT24_API_KEY=********
"force": false
date_from: date,
Етап 8.; Production hardening
8.; Функціональні вимоги
я хочу, щоб повторна синхронізація не створювала дублікати операцій,
</syntaxhighlight>
=== 8.1.; конфігурація інтеграції ===
'''істотно:''' ключовий сценарій інтеграції для бізнес-рахунків — через сервіс «інтеграційні функціональні можливості / Автоклієнт» у Приват24 для бізнесу.; |-
| Дедублікація
| Виявлення та пропуск операцій, які вже були імпортовані.; Режим
Очікувана дія:
!; # Які поля операції обов'язкові для ERP?; Що зберігати
duplicates = 0
storage/
}
{| class="wikitable"
"date_from": str(date_from),
!; |-
| Затримка операцій
| Деякі операції можуть з'являтися у виписці із затримкою.; company_id: str | None = None
* реалізувати створення інтеграції;
* реалізувати зберігання credentials;
* реалізувати шифрування API key;
* реалізувати check-connection;
* реалізувати журнал налаштувань.;<pre>
!; Нормалізація операцій
repositories/
core/
|
| 4.; |-
| is_active
| boolean
| Ознака активності.; Запитати виписку з останньої дати до поточної дати.; характеристика
Приват24 для бізнесу / Автоклієнт
Пріоритетні ключі дедублікації:
платформа повинна забезпечити:
account.last_successful_sync_at = datetime.utcnow()
Як адміністратор,
sync_previous_day_daily: true
!; | Операції отримують статус ExportedToERP.; |-
| ORM
| SQLAlchemy.; Оновити дату останньої синхронізації.; |-
| Manual export
| користувач системи експортує виписку у CSV / JSON / XML.; Зберегти raw-відповідь банку.; |-
| error_count
| integer
| Кількість помилок.; # Отримати raw-виписку.; |-
| SyncSuccess
| Синхронізацію завершено успішно.; Обов'язковість
9.; |-
| operation_date
| date
| Дата операції.; exceptions.py
* створення платежів;
* підписання платежів;
* webhook-інтеграція;
* складний UI;
* автоматичне рознесення оплат;
* супровід всіх банків;
* валютний контроль;
* прогнозування платежів.; # Хто має доступ до API key?; | ключовий рекомендований сценарій для бізнес-рахунків.; |-
| Помилки авторизації
| API key має змогу бути неправильним або зміненим.; |-
| інтеграційні функціональні можливості / Автоклієнт
| API-канал для автоматизації отримання виписки та надсилання платежів.; | як ілюстрація K2 ERP або інша облікова платформа.; |-
| exported_to_erp_at
| timestamp
| Дата передачі в ERP.; |-
| AC-12
| Синхронізація завершилась помилкою.; |-
| imported_count
| integer
| Кількість імпортованих операцій.; |-
| balance_after
| numeric
| Залишок після операції.; |-
| date_from
| date
| Початок періоду.; | Помилка записується в bank_sync_events.; 6.; date_from=date_from,
"date_from": "2026-05-01",
<div style="border-left: 6px solid #2e7d32; background: #e8f5e9; padding: 12px 16px; margin: 16px 0;">
!; |-
| created_at
| timestamp
| Дата створення.; |-
| document_number
| varchar
| Номер документа.; |-
| Logging
| structlog або стандартний logging у JSON-форматі.; }
* додати Dockerfile;
* додати docker-compose;
* додати structured logging;
* додати metrics;
* додати alerting;
* додати rate limiting;
* додати security review.; |-
| client_id
| varchar
| ID клієнта, якщо застосовується.; |-
| payment_purpose
| text
| Призначення платежу.; |-
| is_active
| boolean
| Чи синхронізується рахунок.; |-
| Автоклієнт
| Інтеграційний сервіс Приват24 для бізнесу для роботи з виписками та платежами.; Критерій
account_id: UUID,
strategy: bank_id_or_hash
account_id=account.id,
raw_statement_storage.py
<pre>
transaction_repository.create(db, operation)
</div>
!; |-
| Помилка експорту
| Текст помилки, ID операції, дата.; API виписок
=== Етап 1.; Базова структура Python-сервісу ===
=== 13.2.; Приклад worker-а ===
|
| 2.; def get_accounts(self) -> list ["Privat24Account"]:
{| class="wikitable"
!; |-
| Транзакція
| Окрема банківська операційна дія у виписці.; |-
| counterparty_name
| varchar
| Контрагент.; bank_transaction_repository.py
!; |-
| last_successful_sync_at
| timestamp
| Дата останньої успішної синхронізації.; Знайти всі активні інтеграції.; Логічний endpoint Python-сервісу:
"api_key": "SECRET_VALUE",
=== 19.4.; Автоматична синхронізація ===
{| class="wikitable"
== 26. Definition of Done ==
pass
=== 14.1. bank_integrations ===
pyproject.toml
=== 11.2.; Основні методи ===
<pre>
!; sync_statement(
|-
| transaction_id
| string
| Унікальний ID операції з банку або сформований hash.; | Додати backoff і контроль інтервалів.; |-
| Pull
| ERP самостійно забирає операції через API Python-сервісу.; |-
| currency
| string
| Валюта операції.; | платформа отримує виписку з Приват24.; | Зупинити синхронізацію, повідомити адміністратора.; enabled: true
{| class="wikitable"
sync_event_repository.create(
deduplication:
}
export_to_erp:
7.; |-
| document_number
| string
| Номер платіжного документа.; | У ньому підключається сервіс інтеграції.; Рекомендація
date_from=date_from,
"imported": imported,
deduplication_service.py
v
2.; |-
|
Transaction Normalizer
|
Перетворює raw-операції банку у внутрішній формат.; # Перевірити коректність періоду.; sync_current_day: true
- реалізувати export-to-erp;
- реалізувати статуси експорту;
- обробити помилки ERP;
- додати повторний експорт.; Як зменшити
}
11.; | платформа оновлює його інформаційні дані, а не створює дубль.; |-
|
AccountAccessError
|
-
|
imported_at
|
timestamp
|
-
|
integration_name
|
varchar
|
-
|
AC-2
|
-
|
Privat24RateLimitError
|
Перевищено ліміт запитів.; Очікуваний результат
services/
DATABASE_URL=postgresql+psycopg://user:password@db:5432/bank_statements
def get_statement(
config.py
sha256(account_number + operation_date + amount + currency + document_number + payment_purpose)
<pre>
"accounts_updated": 1
=== 8.3.; Отримання виписки за період ===
payload=response.raw_payload,
date_from: date,
timeout_seconds: int = 30
4.; Тип помилки
=== 8.6.; Дедублікація ===
|-
| Python
| 3.11 або вище.;<syntaxhighlight lang="python">
* неправильного API key;
* відсутності доступу до рахунку;
* некоректного періоду;
* помилок валідації налаштувань;
* операцій, які вже імпортовані.; |}
<pre>
{
"integration_id": "f4d2758e-9a97-4e64-80fb-443b9b864b01",
</pre>
- operation_date
sync_event_repository.create(
!; |-
| counterparty_code
| varchar
| ЄДРПОУ / РНОКПП контрагента.; |-
| currency
| varchar
| Валюта рахунку.; характеристика
account_id=account.id,
}
!; |-
| event_type
| varchar
| Тип події.; # Чи потрібен UI, чи тільки backend API?; Очікувана відповідь:
* реалізувати background worker;
* реалізувати періодичне актуалізація виписок;
* реалізувати контроль останньої успішної синхронізації;
* реалізувати повторну синхронізацію після помилки.; |-
| sync_interval_minutes
| integer
| Так
| Інтервал автоматичної синхронізації.; Для кожної інтеграції знайти активні рахунки.; !; |-
| Відкрита виписка
| Сервіс доступу до виписок за вибраними рахунками.; | Вимкнути рахунок або повідомити адміністратора.; |-
| AC-11
| Синхронізація успішна.; До області задачі входить:
|-
| API Layer
| REST API для керування інтеграцією та запуску синхронізації.; | має змогу використовуватись як альтернативний або додатковий сценарій.; бізнесу забезпечується через '''Головна ідея:''' розробити Python-сервіс.;=== 8.4.; Автоматична синхронізація ===
[[Категорія:Інтеграції]]
"imported": 42,
db,
== 12.; Отримання виписки ==
payload={
date_to: date,
=== Етап 2.; конфігурація інтеграції ===
account_number=account.account_number,
base_url: str
Як бухгалтер,
[[Категорія:Приват24]]
PRIVAT24_TIMEOUT_SECONDS=30
"errors": 0
{| class="wikitable"
</pre>
Як бухгалтер,
=== 15.1.; Типи помилок ===
<pre>
Privat24 Integration Client — це Python-клас або пакет, який інкапсулює роботу з API Приват24 / Автоклієнта.; |-
| updated_at
| timestamp
| Дата актуалізація.; client.py
Retry не застосовується для:
{| class="wikitable"
PRIVAT24_RETRY_BACKOFF_SECONDS=5
{
=== 12.1.; Логічний бізнес-процес ===
response = privat24_client.get_statement(
[[Категорія:Банківські виписки]]
{| class="wikitable"
|-
| Створення інтеграції
| ID, користувач системи, дата, provider.; |-
| Imported
| Операцію імпортовано з банку.; Передача в ERP
</pre>
{| class="wikitable"
!; # Нормалізувати рахунки.; характеристика
pass
* доступ до Приват24 для бізнесу;
* доступ до потрібної компанії / ФОП;
* підключений сервіс «інтеграційні функціональні можливості / Автоклієнт»;
* API credentials для Автоклієнта;
* перелік рахунків, за якими потрібно отримувати виписки;
* валюту рахунків;
* правила доступу користувачів;
* базовий URL API;
* формат авторизації;
* формат відповіді API;
* правила обмеження запитів;
* тестовий доступ або тестовий рахунок, якщо доступний.; |-
| Privat24TimeoutError
| Перевищено час очікування.; |}
from datetime import date
Сервіс повинен забезпечити:
db=db,
== 20. MVP ==
privat24_statement_service/
verify_ssl: bool = True
session.py
) -> "StatementSyncResult":
== 23.; Відкриті питання ==
6.; |-
| Ignored
| Операцію пропущено за правилом.; |-
| value_date
| date
| Дата валютування, якщо доступна.; |-
| Tests
| pytest.; | Зберегти raw-відповідь і помилку.; |-
| AC-5
| Рахунок уже існує.; |-
| StatementParseError
| Неможливо розібрати відповідь банку.; |}
</pre>
{
db=db,
# Унікальний ID операції від банку.; | Оновлюється last_successful_sync_at.; платформа повинна дозволяти отримати виписку за конкретним рахунком та періодом.; Критерій
=== 12.2.; Приклад Python-логіки ===
account=account,
from pydantic_settings import BaseSettings
errors=0,
POST /api/v1/bank-integrations/{integration_id}/sync-accounts
10.3.; Синхронізація рахунків
|
Маскувати логи, шифрувати secrets, обмежити доступ.; |-
|
AC-15
|
-
|
ERP / бухгалтерська платформа
|
-
|
Privat24ApiError
|
API повернув помилку.; # Записати результат у журнал.; # Виконати дедублікацію.; account_id=account.id,
)
|
-
|
AC-3
|
-
|
Audit Logger
|
-
|
Зміна API
|
-
|
counterparty_code
|
string
|
ЄДРПОУ / РНОКПП контрагента, якщо доступно.; Подія
sync_event_repository.py
<syntaxhighlight lang="python">
11. Privat24 Integration Client
def sync_statement(
PRIVAT24_BASE_URL=https://api.privatbank.ua/...
exceptions.py
)
Окремо варто відзначити який автономно отримує банківські виписки з Приват24; додатково реалізовано зберігає операції, виконує дедублікацію і передає інформаційні дані в ERP / бухгалтерську систему.; Інтервал
6.1.; Загальна схема
|
| id
|
uuid
|
-
|
direction
|
string
|
debit або credit.; Очікуваний результат
docker-compose.yml
|
|
|
|
|
