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

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

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

Технічний стек: Python 3.11+, FastAPI або окремий background-service, PostgreSQL, Celery/RQ/APScheduler, requests/httpx, Pydantic, SQLAlchemy, Docker.

1. Мета

Метою задачі є створення Python-модуля / Python-сервісу для передачі документів податкової звітності через сервіс «Вчасно».

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

формування документів для податкової звітності;
перевірку структури документа;
передачу документа у «Вчасно»;
отримання статусів документа;
отримання результатів обробки;
збереження історії передачі;
обробку помилок;
можливість повторної відправки;
журналювання всіх дій.

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

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

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

створення Python API-клієнта для «Вчасно»;
створення сервісного шару для роботи з документами;
формування XML/PDF/JSON-документів;
завантаження документа у «Вчасно»;
передача метаданих документа;
отримання статусів;
отримання підписаних документів або квитанцій;
зберігання технічного журналу;
retry-механізм;
інтеграція з основною ERP / обліковою системою.

До області задачі не входить у першій версії:

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

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

Компонент	Призначення	Примітка
Вчасно.EDO API	Завантаження, підписання, статуси, скачування документів.	Використовується для документообігу.
Вчасно.Звіт	Подання звітності до податкової.	Потрібно отримати API-специфікацію від «Вчасно».
ERP / облікова система	Джерело даних для формування документів.	Наприклад K2 ERP або інша внутрішня система.
Python-сервіс	Інтеграційний шар між ERP та «Вчасно».	Реалізується в межах цього ТЗ.

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

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

API token / API key від «Вчасно»;
базовий URL API;
специфікацію endpoint-ів для подання звітності;
перелік підтримуваних типів документів;
формат метаданих документа;
правила підписання документа;
правила отримання статусів;
правила отримання квитанцій;
тестове середовище, якщо доступне;
технічний контакт з боку «Вчасно».

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

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

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

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

ERP / Accounting System
        |
        | 1. Дані для звітності
        v
Python Reporting Service
        |
        | 2. Формування XML / PDF / JSON
        v
Validation Layer
        |
        | 3. Перевірка документа
        v
Vchasno API Client
        |
        | 4. Передача у Вчасно
        v
Вчасно
        |
        | 5. Подання / підписання / обробка
        v
ДПС
        |
        | 6. Статуси / квитанції
        v
Python Reporting Service
        |
        | 7. Оновлення статусу
        v
ERP / Accounting System

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

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

7. User Story

7.1. Передача документа у Вчасно

Як користувач ERP, я хочу сформувати документ звітності та передати його у «Вчасно», щоб не завантажувати документ вручну.

7.2. Автоматичне отримання статусів

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

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 або інший підтримуваний формат.
file_content	binary / base64	Так	Вміст документа.
metadata	object	Ні	Додаткові реквізити документа.

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

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

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

8.3. Передача документа у «Вчасно»

Python-сервіс повинен мати метод для завантаження документа у «Вчасно».

Приклад логічного endpoint-а Python-сервісу:

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

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

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

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

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

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

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

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

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

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

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

Помилка передачі;
Відхилено;
Не доставлено;
Потребує повторної відправки.

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

Прийнято;
Завершено;
Очікується обробка;
Передано у Вчасно.

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

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

10. Мапінг статусів «Вчасно»

Оскільки статуси «Вчасно» можуть повертатися числовими кодами або текстовими значеннями, у Python-сервісі необхідно реалізувати мапінг.

Приклад:

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

Уточнення: фінальний мапінг статусів потрібно зробити після отримання офіційного довідника статусів від «Вчасно».

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. Передача у «Вчасно»

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

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

{
  "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
  "status": "SentToVchasno",
  "vchasno_document_id": "external-document-id",
  "message": "Document sent to Vchasno"
}

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

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

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

{
  "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
  "old_status": "SentToVchasno",
  "new_status": "WaitingForSignature",
  "vchasno_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

12. Vchasno API Client

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

Vchasno API Client — це Python-клас або пакет, який інкапсулює роботу з API «Вчасно».

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

class VchasnoClient:
    def upload_document(self, document: "DocumentPayload") -> "VchasnoDocumentResponse":
        pass

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

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

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

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

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

    def send_for_signature(self, document_id: str) -> "VchasnoDocumentResponse":
        pass

    def reject_document(self, document_id: str, reason: str) -> "VchasnoDocumentResponse":
        pass

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

class VchasnoSettings(BaseSettings):
    base_url: str
    api_key: str
    timeout_seconds: int = 30
    retry_count: int = 3
    retry_backoff_seconds: int = 5
    verify_ssl: bool = True

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

VCHASNO_BASE_URL=https://edo.vchasno.ua/api/v2
VCHASNO_API_KEY=********
VCHASNO_TIMEOUT_SECONDS=30
VCHASNO_RETRY_COUNT=3

13. Передача документа у «Вчасно»

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

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

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

def send_report_to_vchasno(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,
        metadata={
            "taxpayer_id": report.taxpayer_id,
            "report_type": report.report_type,
            "period": report.period,
        },
    )

    response = vchasno_client.upload_document(payload)

    report.vchasno_document_id = response.id
    report.status = TaxReportStatus.SENT_TO_VCHASNO
    report.sent_at = datetime.utcnow()

    audit_logger.log(
        entity_id=report.id,
        event_type="SENT_TO_VCHASNO",
        details={"vchasno_document_id": response.id},
    )

    db.commit()
    return report

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

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

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

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

Статус документа	Інтервал перевірки
SentToVchasno	кожні 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:
            vchasno_status = vchasno_client.get_document_status(
                report.vchasno_document_id
            )

            new_status = status_mapper.map_vchasno_status(vchasno_status)

            if new_status != report.status:
                tax_report_repository.update_status(report.id, new_status)
                audit_logger.log(
                    entity_id=report.id,
                    event_type="STATUS_CHANGED",
                    details={
                        "old_status": report.status,
                        "new_status": new_status,
                        "vchasno_status": vchasno_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 тощо.
status	varchar	Внутрішній статус.
vchasno_document_id	varchar	ID документа у «Вчасно».
last_sync_at	timestamp	Дата останньої синхронізації.
sent_at	timestamp	Дата передачі у «Вчасно».
accepted_at	timestamp	Дата прийняття.
rejected_at	timestamp	Дата відхилення.
error_message	text	Остання помилка.
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	Некоректні дані документа.	Не відправляти документ, показати список помилок.
VchasnoAuthError	Помилка авторизації у «Вчасно».	Зупинити відправку, повідомити адміністратора.
VchasnoApiError	API повернув помилку.	Записати відповідь API, дозволити повтор.
VchasnoTimeoutError	Перевищено час очікування.	Виконати retry.
DuplicateDocumentError	Документ вже був переданий.	Заборонити повтор без підтвердження.
FileStorageError	Неможливо прочитати або записати файл.	Зафіксувати помилку, повідомити адміністратора.
StatusMappingError	Невідомий статус від «Вчасно».	Зберегти raw-статус, позначити як Failed або Unknown.

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

VCHASNO_BASE_URL=https://edo.vchasno.ua/api/v2
VCHASNO_API_KEY=********
VCHASNO_TIMEOUT_SECONDS=30
VCHASNO_RETRY_COUNT=3
VCHASNO_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

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

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

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

20. Acceptance Criteria

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

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

20.2. Передача у «Вчасно»

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

20.3. Статуси

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

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

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

21. MVP

До MVP входить:

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

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

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

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

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

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

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

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

Етап 3. Vchasno API Client

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

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

реалізувати endpoint send-to-vchasno;
зберігати vchasno_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-документації для «Вчасно.Звіт»	Публічно доступна документація може не покривати подання звітності до ДПС.	Отримати офіційну API-специфікацію від «Вчасно».
Зміна API	Endpoint-и або формати відповіді можуть змінюватися.	Інкапсулювати API в окремому VchasnoClient.
Невідомі статуси	«Вчасно» може повертати статуси, яких немає в системі.	Зберігати raw-статус та мати UnknownStatus.
Дублювання документів	Повторна відправка може створити дубль.	Перевіряти vchasno_document_id перед відправкою.
Помилки авторизації	API key може бути неправильним або простроченим.	Додати healthcheck інтеграції та повідомлення адміністратору.
Недоступність сервісу	«Вчасно» або мережа можуть бути недоступні.	Використовувати retry та чергу задач.
Персональні дані	Документи можуть містити РНОКПП, ЄДРПОУ, фінансові дані.	Маскувати логи та обмежити доступ.

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

Який саме сервіс використовується для подання: «Вчасно.Звіт», «Вчасно.EDO» чи окрема партнерська API-інтеграція?
Чи надає «Вчасно» endpoint саме для подання звітності до ДПС?
Який формат документів передається: XML, PDF, ZIP, JSON?
Чи має Python-сервіс сам формувати XML, чи отримує готовий файл з ERP?
Чи потрібно підписувати документ до передачі у «Вчасно»?
Чи підпис виконується всередині «Вчасно»?
Які типи звітів підтримуються першими?
Чи потрібна підтримка ФОП, юридичних осіб або обох варіантів?
Чи потрібно отримувати квитанції з ДПС через «Вчасно»?
Чи є тестове середовище?
Чи є webhook-и для статусів?
Який SLA по оновленню статусів?
Де зберігати файли: локально, S3, MinIO, DMS?
Хто має доступ до API key?
Чи потрібно робити UI, чи тільки backend API?

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

tax_reporting_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/
      vchasno/
        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 створення документа працює;
документ зберігається у БД та файловому сховищі;
документ проходить валідацію;
документ передається у «Вчасно»;
зовнішній ID документа зберігається;
статус документа оновлюється;
помилки API обробляються;
retry-механізм працює;
журнал подій заповнюється;
написані unit-тести для ключових сервісів;
написані інтеграційні тести для VchasnoClient з mock API;
документація для запуску додана в README.

28. Джерела

29. Див. також

index.php?title=Категорія:Технічні завдання index.php?title=Категорія:Python index.php?title=Категорія:Вчасно index.php?title=Категорія:API index.php?title=Категорія:Податкова звітність index.php?title=Категорія:Інтеграції index.php?title=Категорія:K2 ERP