Перегляд вихідного коду сторінки Накладення електронного підпису за допомогою Дія в Python

{{DISPLAYTITLE:Технічне завдання: Накладення електронного підпису за допомогою Дія.Підпис у Python}}

{{SEO
|title=Технічне завдання: Накладення електронного підпису за допомогою Дія.Підпис у Python
|description=Технічне завдання на реалізацію Python-сервісу для інтеграції з Дія.Підпис: підписання документів, авторизація, QR/deep link, статуси, callback, p7s, перевірка підпису, журналювання, dashboard та безпека.
|keywords=Python, Дія.Підпис, Diia.Signature, КЕП, електронний підпис, підписання документів, FastAPI, K2 ERP, callback, p7s, електронний документообіг
}}


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

<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
'''Критично важливо:''' система не повинна вважати документ підписаним тільки після відкриття QR-коду або переходу в застосунок Дія. Документ вважається підписаним лише після отримання підтвердженого результату підписання, збереження підпису та успішної перевірки цілісності.
</div>

<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
'''Важливо:''' точні endpoint-и, формат callback, формат підписаного контейнера, параметри deep link / QR та правила взаємодії потрібно брати з офіційної документації Дії, яку надають після підключення партнера.
</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, Redis, Docker, S3-compatible file storage.
</div>

<div style="border-left: 6px solid #6a1b9a; background: #f3e5f5; padding: 12px 16px; margin: 16px 0;">
'''Управлінський результат:''' відповідальна особа повинна бачити, які документи очікують підпису, які підписані, які відхилені, які прострочені, які мають помилки callback, які потребують повтору або ручної перевірки.
</div>

__TOC__

== 1. Мета ==

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

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

* створення заявки на підписання документа;
* підготовку документа до підпису;
* розрахунок hash документа, якщо це вимагається інтеграцією;
* створення сесії підписання;
* генерацію QR-коду або deep link для переходу в застосунок Дія;
* відображення користувачу статусу підписання;
* отримання callback / webhook від Дії;
* отримання результату підписання;
* збереження підпису;
* збереження підписаного документа або контейнера;
* перевірку підпису;
* перевірку цілісності документа;
* оновлення статусу документа в K2 ERP або іншій системі;
* журналювання всіх подій;
* контроль помилок;
* dashboard для відповідальних осіб.

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

Інтеграція може використовуватись для:

* договорів;
* актів виконаних робіт;
* рахунків;
* заяв;
* анкет;
* кадрових документів;
* первинних документів;
* документів ЕДО;
* документів K2 ERP;
* документів, які формуються в CRM;
* авторизації користувача через Дія.Підпис;
* підтвердження дії користувача в системі.

== 3. Що таке Дія.Підпис у межах інтеграції ==

Дія.Підпис у межах цього ТЗ розглядається як зовнішній сервіс, який дозволяє користувачу підтвердити свою дію та накласти електронний підпис через застосунок Дія.

{| class="wikitable"
! Параметр
! Опис
|-
| Тип сервісу
| Електронний підпис через застосунок Дія.
|-
| Основний сценарій
| Користувач відкриває QR/deep link, підтверджує підписання в застосунку, система отримує результат.
|-
| Результат
| Підпис, підписаний контейнер або дані підписання згідно з API Дії.
|-
| Формат результату
| Уточнюється за офіційною документацією Дії. Для багатьох КЕП-сценаріїв типовим є окремий файл підпису або контейнер.
|-
| Кінцева система
| K2 ERP / CRM / документообіг / сайт / мобільний застосунок.
|}

<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
'''Критично важливо:''' Дія.Підпис не повинен підміняти внутрішню систему зберігання документів. Python-сервіс повинен сам зберігати документ, підпис, статус, аудит і результат перевірки.
</div>

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

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

* партнерський доступ до інтеграції Дії;
* офіційну документацію Дія.Підпис;
* тестове середовище, якщо доступне;
* client_id або аналогічний ідентифікатор партнера;
* client_secret або інший секрет доступу;
* сертифікати, якщо вони потрібні для взаємодії;
* endpoint-и API Дії;
* callback URL, який буде приймати результат;
* правила формування QR/deep link;
* правила формування запиту на підпис;
* допустимі формати документів;
* максимальний розмір документа;
* правила зберігання результату підписання;
* правила перевірки підпису;
* контакт технічної підтримки Дії.

<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
'''Критично важливо:''' без офіційної документації партнера Дії не можна фіксувати production endpoint-и, назви параметрів і формат callback як остаточні.
</div>

== 5. Основні сценарії інтеграції ==

=== 5.1. Підписання одного документа ===

Користувач відкриває документ у K2 ERP або на сайті, натискає кнопку «Підписати через Дія.Підпис».

Система:

* створює запис документа;
* створює сесію підписання;
* генерує QR/deep link;
* показує QR користувачу;
* очікує callback;
* отримує результат;
* зберігає підпис;
* перевіряє підпис;
* змінює статус документа на SIGNED.

=== 5.2. Підписання пакета документів ===

Користувач підписує декілька документів за один бізнес-процес.

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

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

=== 5.3. Підписання документа клієнтом ===

Клієнт отримує посилання на документ.

Система:

* відкриває сторінку підписання;
* показує коротку інформацію про документ;
* показує QR/deep link;
* клієнт підтверджує підписання в Дії;
* система отримує результат;
* документ стає підписаним клієнтом.

=== 5.4. Підписання документа співробітником ===

Співробітник компанії підписує внутрішній документ.

Система:

* створює задачу на підпис;
* показує її у списку задач;
* контролює строк підписання;
* нагадує про прострочення;
* зберігає аудит дій.

=== 5.5. Авторизація через Дія.Підпис ===

Дія.Підпис може використовуватись не тільки для документа, а й для авторизації або підтвердження дії.

Система:

* створює authorization session;
* показує QR/deep link;
* отримує підтвердження;
* ідентифікує користувача згідно з дозволеним обсягом даних;
* створює або оновлює сесію користувача.

== 6. Основні сутності ==

{| class="wikitable"
! Сутність
! Опис
|-
| Signature Integration
| Налаштування підключення до Дія.Підпис.
|-
| Document
| Документ, який потрібно підписати.
|-
| Document Version
| Версія документа, яка передана на підпис.
|-
| Signature Request
| Заявка на підписання.
|-
| Signature Session
| Сесія взаємодії з Дією.
|-
| Signer
| Підписант.
|-
| Callback Event
| Подія, отримана від Дії.
|-
| Signature File
| Файл підпису або підписаний контейнер.
|-
| Verification Result
| Результат перевірки підпису.
|-
| Audit Event
| Подія журналу.
|}

== 7. User Story ==

=== 7.1. Користувач підписує документ ===

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

=== 7.2. Менеджер контролює підписання ===

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

=== 7.3. Адміністратор перевіряє помилки ===

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

=== 7.4. Керівник бачить dashboard ===

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

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

{| class="wikitable"
! Статус
! Код
! Опис
! Колір
|-
| Чернетка
| DRAFT
| Документ створений, але ще не готовий до підпису.
| style="background:#eeeeee;" | Сірий
|-
| Готовий до підпису
| READY_TO_SIGN
| Документ перевірено і можна створювати заявку.
| style="background:#bbdefb;" | Блакитний
|-
| Очікує підпису
| WAITING_SIGNATURE
| Користувачу створено QR/deep link.
| style="background:#fff9c4;" | Жовтий
|-
| Підписується
| SIGNING
| Користувач відкрив процес підписання.
| style="background:#bbdefb;" | Блакитний
|-
| Підписано
| SIGNED
| Підпис успішно отримано і збережено.
| style="background:#c8e6c9;" | Зелений
|-
| Підпис перевірено
| VERIFIED
| Підпис пройшов перевірку.
| style="background:#c8e6c9;" | Зелений
|-
| Відхилено користувачем
| DECLINED_BY_USER
| Користувач не підтвердив підписання.
| style="background:#ffcc80;" | Помаранчевий
|-
| Прострочено
| EXPIRED
| Строк сесії підписання минув.
| style="background:#ffcc80;" | Помаранчевий
|-
| Помилка підписання
| SIGN_ERROR
| Помилка під час підписання.
| style="background:#ef9a9a;" | Червоний
|-
| Помилка перевірки
| VERIFY_ERROR
| Підпис отримано, але перевірка не пройдена.
| style="background:#ef9a9a;" | Червоний
|-
| Ручна перевірка
| MANUAL_REVIEW
| Потрібна перевірка адміністратором.
| style="background:#f3e5f5;" | Фіолетовий
|}

== 9. Статуси сесії підписання ==

{| class="wikitable"
! Статус
! Код
! Опис
! Колір
|-
| Створюється
| CREATING
| Система створює сесію підписання.
| style="background:#bbdefb;" | Блакитний
|-
| Активна
| ACTIVE
| QR/deep link доступний користувачу.
| style="background:#fff9c4;" | Жовтий
|-
| Очікує callback
| WAITING_CALLBACK
| Користувач перейшов у Дію, система очікує результат.
| style="background:#fff9c4;" | Жовтий
|-
| Завершена
| COMPLETED
| Сесія завершена успішно.
| style="background:#c8e6c9;" | Зелений
|-
| Відхилена
| DECLINED
| Користувач відхилив дію.
| style="background:#ffcc80;" | Помаранчевий
|-
| Прострочена
| EXPIRED
| Сесія не завершена у строк.
| style="background:#ffcc80;" | Помаранчевий
|-
| Помилка
| ERROR
| Технічна помилка.
| style="background:#ef9a9a;" | Червоний
|}

== 10. Єдина логіка кольорів ==

{| class="wikitable"
! Колір
! HTML
! Значення
! Де використовується
|-
| style="background:#c8e6c9;" | Зелений
| #c8e6c9
| Успішно: підписано, перевірено, завершено.
| Dashboard, список документів, картка документа.
|-
| style="background:#bbdefb;" | Блакитний
| #bbdefb
| Операція виконується.
| Створення сесії, підписання.
|-
| style="background:#fff9c4;" | Жовтий
| #fff9c4
| Очікування дії користувача або callback.
| Очікує підпису, активна сесія.
|-
| style="background:#ffcc80;" | Помаранчевий
| #ffcc80
| Потрібна дія або є ризик.
| Відхилено, прострочено.
|-
| style="background:#ef9a9a;" | Червоний
| #ef9a9a
| Помилка або негативний результат.
| Помилка підписання, помилка перевірки.
|-
| style="background:#f3e5f5;" | Фіолетовий
| #f3e5f5
| Ручна перевірка або нестандартний сценарій.
| MANUAL_REVIEW.
|-
| style="background:#eeeeee;" | Сірий
| #eeeeee
| Чернетка або архів.
| DRAFT, archived.
|}

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

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

<pre>
K2 ERP / CRM / Website
        |
        | 1. Документ на підпис
        v
Python Diia.Sign Integration Service
        |
        | 2. Валідація, hash, створення сесії
        v
Diia Adapter
        |
        | 3. API Дії / QR / deep link
        v
Застосунок Дія
        |
        | 4. Користувач підтверджує підписання
        v
Callback URL Python-сервісу
        |
        | 5. Результат підписання
        v
Signature Storage + Verification Service
        |
        | 6. Збереження, перевірка, статус
        v
K2 ERP / Dashboard / Документообіг
</pre>

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

{| class="wikitable"
! Компонент
! Опис
|-
| API Layer
| REST API для створення заявок на підпис.
|-
| Document Service
| Робота з документами та версіями.
|-
| Signature Request Service
| Створення заявки на підписання.
|-
| Diia Client
| Python-клієнт для API Дії.
|-
| QR / Deep Link Service
| Генерація посилання або QR.
|-
| Callback Controller
| Прийом callback від Дії.
|-
| Signature Storage
| Зберігання підпису, контейнера, документа.
|-
| Verification Service
| Перевірка підпису та цілісності.
|-
| Status Sync Service
| Оновлення статусів у K2 ERP.
|-
| Audit Logger
| Журнал подій, callback-ів, помилок.
|-
| Dashboard API
| Дані для керівника та відповідальних осіб.
|}

== 12. Diia Client ==

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

Diia Client — це Python-клас або пакет, який інкапсулює роботу з API Дія.Підпис.

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

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

    def authenticate(self) -> "AuthResult":
        pass

    def create_signature_session(self, payload: "CreateSignatureSessionPayload") -> "SignatureSessionResponse":
        pass

    def get_signature_session_status(self, session_id: str) -> "SignatureSessionStatusResponse":
        pass

    def get_signature_result(self, session_id: str) -> "SignatureResultResponse":
        pass

    def cancel_signature_session(self, session_id: str) -> "CancelSignatureSessionResponse":
        pass
</syntaxhighlight>

<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
'''Важливо:''' назви методів у Python-клієнті є внутрішньою абстракцією. Реальні endpoint-и і payload потрібно взяти з офіційної документації Дії для партнера.
</div>

== 13. Конфігурація ==

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


class DiiaSignatureSettings(BaseSettings):
    base_url: str
    client_id: str
    client_secret: str
    callback_url: str
    redirect_url: str | None = None
    timeout_seconds: int = 30
    retry_count: int = 3
    retry_backoff_seconds: int = 5
    verify_ssl: bool = True
    session_ttl_minutes: int = 15
    max_document_size_mb: int = 10
</syntaxhighlight>

Приклад `.env`:

<pre>
DIIA_SIGNATURE_BASE_URL=https://partner-api.example.diia
DIIA_SIGNATURE_CLIENT_ID=********
DIIA_SIGNATURE_CLIENT_SECRET=********
DIIA_SIGNATURE_CALLBACK_URL=https://example.com/api/v1/diia-signature/callback
DIIA_SIGNATURE_REDIRECT_URL=https://example.com/signature/result
DIIA_SIGNATURE_TIMEOUT_SECONDS=30
DIIA_SIGNATURE_RETRY_COUNT=3
DIIA_SIGNATURE_SESSION_TTL_MINUTES=15
DIIA_SIGNATURE_MAX_DOCUMENT_SIZE_MB=10
</pre>

<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
'''Заборонено:''' зберігати client_secret, приватні ключі, токени, callback secrets або інші секрети у коді, Git-репозиторії, frontend-змінних або відкритих логах.
</div>

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

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

<pre>
POST /api/v1/diia-signature/integrations
</pre>

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

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

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

<pre>
POST /api/v1/diia-signature/documents
</pre>

=== 14.4. Створення заявки на підпис ===

<pre>
POST /api/v1/diia-signature/documents/{document_id}/signature-requests
</pre>

=== 14.5. Отримання QR/deep link ===

<pre>
GET /api/v1/diia-signature/signature-requests/{request_id}/link
</pre>

=== 14.6. Отримання статусу заявки ===

<pre>
GET /api/v1/diia-signature/signature-requests/{request_id}/status
</pre>

=== 14.7. Callback від Дії ===

<pre>
POST /api/v1/diia-signature/callback
</pre>

=== 14.8. Завантаження підписаного документа ===

<pre>
GET /api/v1/diia-signature/documents/{document_id}/signed-file
</pre>

=== 14.9. Завантаження файлу підпису ===

<pre>
GET /api/v1/diia-signature/documents/{document_id}/signature-file
</pre>

=== 14.10. Перевірка підпису ===

<pre>
POST /api/v1/diia-signature/documents/{document_id}/verify
</pre>

=== 14.11. Dashboard ===

<pre>
GET /api/v1/diia-signature/dashboard?date_from=2026-05-01&date_to=2026-05-31
</pre>

== 15. Приклад запиту на створення заявки на підпис ==

<syntaxhighlight lang="json">
{
  "external_document_id": "K2-DOC-2026-000123",
  "idempotency_key": "K2-DOC-2026-000123-sign-v1",
  "document_type": "CONTRACT",
  "document_name": "Договір поставки №123",
  "document_number": "123",
  "document_date": "2026-05-07",
  "file_id": "file-001",
  "file_name": "contract_123.pdf",
  "file_mime_type": "application/pdf",
  "signer": {
    "external_signer_id": "CLIENT-001",
    "full_name": "Іван Петренко",
    "phone": "+380671112233",
    "email": "client@example.com",
    "tax_id": "1234567890"
  },
  "callback_context": {
    "k2_entity": "contract",
    "k2_entity_id": "contract-001"
  },
  "expires_at": "2026-05-07T14:30:00+03:00"
}
</syntaxhighlight>

== 16. Валідація документа перед підписом ==

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

* наявність external_document_id;
* наявність idempotency_key;
* наявність файлу документа;
* файл доступний у сховищі;
* файл не порожній;
* розмір файлу не перевищує ліміт;
* MIME type дозволений;
* документ не був змінений після створення заявки;
* hash документа збережений;
* підписант визначений;
* строк підписання не минув;
* документ ще не підписаний цим підписантом;
* бізнес-процес дозволяє підписання;
* користувач має право ініціювати підписання.

<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
'''Критично важливо:''' якщо документ змінено після створення заявки на підпис, попередня заявка повинна бути скасована або переведена в статус INVALIDATED. Не можна підписувати старий hash для нової версії документа.
</div>

== 17. Hash документа і версії ==

Для кожного документа потрібно зберігати:

{| class="wikitable"
! Поле
! Опис
|-
| document_version_id
| ID версії документа.
|-
| file_hash_sha256
| Hash файлу.
|-
| file_size
| Розмір файлу.
|-
| mime_type
| MIME type.
|-
| created_at
| Дата створення версії.
|-
| created_by
| Хто створив версію.
|}

Приклад hash:

<pre>
sha256(file_bytes)
</pre>

== 18. Callback від Дії ==

Callback endpoint повинен:

* приймати тільки HTTPS-запити;
* перевіряти підпис або секрет callback, якщо передбачено API;
* перевіряти session_id;
* перевіряти request_id;
* перевіряти idempotency callback;
* зберігати raw payload;
* оновлювати статус сесії;
* зберігати файл підпису або посилання на результат;
* запускати перевірку підпису;
* повертати коректний HTTP status.

<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
'''Критично важливо:''' callback повинен бути ідемпотентним. Якщо Дія або мережа повторно надішле той самий callback, система не повинна дублювати підпис або повторно змінювати фінальний статус некоректно.
</div>

== 19. Перевірка підпису ==

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

Перевіряється:

* цілісність документа;
* відповідність підпису конкретній версії документа;
* валідність підпису;
* валідність сертифіката;
* дані підписанта;
* час підписання;
* статус відкликання сертифіката, якщо доступно;
* чи відповідає підписант очікуваному користувачу;
* чи не минув строк сесії;
* чи не змінювався документ після підпису.

Можливі результати:

{| class="wikitable"
! Результат
! Код
! Опис
! Колір
|-
| Валідний
| VALID
| Підпис пройшов перевірку.
| style="background:#c8e6c9;" | Зелений
|-
| Невалідний
| INVALID
| Підпис не пройшов перевірку.
| style="background:#ef9a9a;" | Червоний
|-
| Не той документ
| HASH_MISMATCH
| Hash документа не збігається.
| style="background:#ef9a9a;" | Червоний
|-
| Не той підписант
| SIGNER_MISMATCH
| Підписант не відповідає очікуваному.
| style="background:#ef9a9a;" | Червоний
|-
| Потребує ручної перевірки
| MANUAL_REVIEW
| Неможливо автоматично визначити результат.
| style="background:#f3e5f5;" | Фіолетовий
|}

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

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

Ключі дедублікації:

{| class="wikitable"
! Ключ
! Призначення
|-
| external_document_id
| ID документа в K2 ERP.
|-
| document_version_id
| Версія документа.
|-
| signer_id
| Підписант.
|-
| idempotency_key
| Унікальний ключ заявки.
|-
| diia_session_id
| ID сесії в Дії.
|-
| callback_event_id
| ID callback-події, якщо надається.
|-
| file_hash_sha256
| Hash документа.
|}

== 21. Черга обробки ==

=== 21.1. Логіка черги ===

<pre>
1. K2 ERP створює документ.
2. Користувач натискає «Підписати через Дія».
3. Python-сервіс перевіряє документ.
4. Створюється signature_request.
5. Створюється signature_session.
6. Користувачу показується QR/deep link.
7. Callback Controller приймає результат.
8. Signature Storage зберігає підпис.
9. Verification Service перевіряє підпис.
10. K2 ERP отримує фінальний статус.
</pre>

=== 21.2. Пріоритети задач ===

{| class="wikitable"
! Задача
! Пріоритет
! Коментар
|-
| Прийом callback
| Критичний
| Не можна втрачати результат підписання.
|-
| Збереження підпису
| Критичний
| Юридично значущий результат.
|-
| Перевірка підпису
| Високий
| Потрібна для фінального статусу.
|-
| Створення сесії
| Високий
| Основний сценарій користувача.
|-
| Оновлення dashboard
| Середній
| Контроль.
|-
| Нагадування про прострочення
| Низький
| Фоновий процес.
|}

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

=== 22.1. diia_signature_integrations ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID інтеграції.
|-
| provider
| varchar
| diia_signature.
|-
| name
| varchar
| Назва інтеграції.
|-
| base_url
| varchar
| URL API.
|-
| client_id
| varchar
| ID партнера.
|-
| client_secret_encrypted
| text
| Зашифрований секрет.
|-
| callback_url
| varchar
| Callback URL.
|-
| redirect_url
| varchar
| URL повернення користувача.
|-
| is_active
| boolean
| Активність.
|-
| created_at
| timestamp
| Дата створення.
|-
| updated_at
| timestamp
| Дата оновлення.
|}

=== 22.2. sign_documents ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID документа.
|-
| external_document_id
| varchar
| ID документа в K2 ERP.
|-
| document_type
| varchar
| CONTRACT, ACT, APPLICATION тощо.
|-
| document_name
| varchar
| Назва документа.
|-
| document_number
| varchar
| Номер документа.
|-
| document_date
| date
| Дата документа.
|-
| current_version_id
| uuid
| Поточна версія.
|-
| status
| varchar
| Статус документа.
|-
| created_at
| timestamp
| Дата створення.
|}

=== 22.3. sign_document_versions ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID версії.
|-
| document_id
| uuid
| ID документа.
|-
| file_id
| uuid
| Файл документа.
|-
| file_name
| varchar
| Назва файлу.
|-
| mime_type
| varchar
| MIME type.
|-
| file_size
| integer
| Розмір файлу.
|-
| file_hash_sha256
| varchar
| Hash файлу.
|-
| version_number
| integer
| Номер версії.
|-
| created_at
| timestamp
| Дата створення.
|}

=== 22.4. signature_requests ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID заявки.
|-
| document_id
| uuid
| Документ.
|-
| document_version_id
| uuid
| Версія документа.
|-
| signer_id
| uuid
| Підписант.
|-
| idempotency_key
| varchar
| Ключ дедублікації.
|-
| status
| varchar
| Статус заявки.
|-
| expires_at
| timestamp
| Строк дії.
|-
| created_by
| uuid
| Хто створив заявку.
|-
| created_at
| timestamp
| Дата створення.
|}

=== 22.5. signature_sessions ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID сесії.
|-
| signature_request_id
| uuid
| Заявка.
|-
| diia_session_id
| varchar
| ID сесії в Дії.
|-
| qr_payload
| text
| Дані QR, якщо зберігаються.
|-
| deep_link
| text
| Deep link.
|-
| status
| varchar
| Статус сесії.
|-
| raw_request
| jsonb
| Запит до Дії.
|-
| raw_response
| jsonb
| Відповідь Дії.
|-
| created_at
| timestamp
| Дата створення.
|-
| expires_at
| timestamp
| Дата завершення.
|}

=== 22.6. signature_files ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID файлу підпису.
|-
| signature_request_id
| uuid
| Заявка.
|-
| file_id
| uuid
| Файл у сховищі.
|-
| file_type
| varchar
| signature, signed_container, signed_pdf.
|-
| file_hash_sha256
| varchar
| Hash файлу.
|-
| created_at
| timestamp
| Дата створення.
|}

=== 22.7. signature_verifications ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID перевірки.
|-
| signature_request_id
| uuid
| Заявка.
|-
| result
| varchar
| VALID, INVALID, HASH_MISMATCH тощо.
|-
| signer_name
| varchar
| ПІБ підписанта з сертифіката.
|-
| signer_identifier
| varchar
| Ідентифікатор підписанта, якщо доступний.
|-
| signed_at
| timestamp
| Час підписання.
|-
| certificate_info
| jsonb
| Дані сертифіката.
|-
| raw_result
| jsonb
| Повний результат перевірки.
|-
| created_at
| timestamp
| Дата перевірки.
|}

=== 22.8. signature_events ===

{| class="wikitable"
! Поле
! Тип
! Опис
|-
| id
| uuid
| ID події.
|-
| entity_type
| varchar
| document, request, session, callback, verification.
|-
| entity_id
| uuid
| ID сутності.
|-
| event_type
| varchar
| Тип події.
|-
| old_status
| varchar
| Попередній статус.
|-
| new_status
| varchar
| Новий статус.
|-
| source
| varchar
| K2_ERP, PYTHON_SERVICE, DIIA, USER.
|-
| payload
| jsonb
| Технічні дані.
|-
| created_at
| timestamp
| Дата події.
|}

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

=== 23.1. Створення заявки на підпис ===

<syntaxhighlight lang="python">
from hashlib import sha256
from datetime import datetime, timezone


def create_signature_request(command: "CreateSignatureRequestCommand", db: "Session") -> "SignatureRequest":
    existing = signature_request_repository.get_by_idempotency_key(
        db=db,
        idempotency_key=command.idempotency_key,
    )

    if existing:
        return existing

    document = document_repository.get_by_external_id(
        db=db,
        external_document_id=command.external_document_id,
    )

    signature_validator.validate_document_for_signing(document, command)

    request = signature_request_repository.create(
        db=db,
        data={
            "document_id": document.id,
            "document_version_id": document.current_version_id,
            "signer_id": command.signer_id,
            "idempotency_key": command.idempotency_key,
            "status": "CREATING",
            "expires_at": command.expires_at,
        },
    )

    signature_queue.enqueue(
        task_name="create_diia_signature_session",
        payload={"signature_request_id": str(request.id)},
    )

    audit_logger.log(
        entity_type="signature_request",
        entity_id=request.id,
        event_type="SIGNATURE_REQUEST_CREATED",
        new_status="CREATING",
        payload={"external_document_id": command.external_document_id},
    )

    db.commit()
    return request
</syntaxhighlight>

=== 23.2. Створення сесії Дія.Підпис ===

<syntaxhighlight lang="python">
async def create_diia_signature_session(signature_request_id: str, db: "Session") -> None:
    request = signature_request_repository.get_by_id(db, signature_request_id)
    document_version = document_version_repository.get_by_id(db, request.document_version_id)

    try:
        payload = diia_mapper.to_signature_session_payload(
            request=request,
            document_version=document_version,
        )

        response = await diia_client.create_signature_session(payload)

        session = signature_session_repository.create(
            db=db,
            data={
                "signature_request_id": request.id,
                "diia_session_id": response.session_id,
                "qr_payload": response.qr_payload,
                "deep_link": response.deep_link,
                "status": "ACTIVE",
                "raw_request": payload,
                "raw_response": response.raw_payload,
                "expires_at": response.expires_at,
            },
        )

        request.status = "WAITING_SIGNATURE"

        audit_logger.log(
            entity_type="signature_session",
            entity_id=session.id,
            event_type="DIIA_SIGNATURE_SESSION_CREATED",
            new_status="ACTIVE",
            payload={"diia_session_id": response.session_id},
        )

    except Exception as exc:
        request.status = "SIGN_ERROR"
        audit_logger.log(
            entity_type="signature_request",
            entity_id=request.id,
            event_type="DIIA_SIGNATURE_SESSION_ERROR",
            new_status="SIGN_ERROR",
            payload={"error": str(exc)},
        )

    finally:
        db.commit()
</syntaxhighlight>

=== 23.3. Callback controller ===

<syntaxhighlight lang="python">
from fastapi import APIRouter, Request, HTTPException

router = APIRouter()


@router.post("/api/v1/diia-signature/callback")
async def diia_signature_callback(request: Request):
    payload = await request.json()

    # Перевірка callback signature / secret залежить від офіційної документації Дії.
    if not callback_security_service.is_valid(request, payload):
        raise HTTPException(status_code=401, detail="Invalid callback signature")

    callback_id = callback_service.get_callback_id(payload)

    if callback_repository.exists(callback_id):
        return {"status": "already_processed"}

    callback_event = callback_repository.create_raw_event(payload)

    signature_session = signature_session_repository.get_by_diia_session_id(
        diia_session_id=payload["session_id"],
    )

    if not signature_session:
        callback_event.status = "UNKNOWN_SESSION"
        return {"status": "unknown_session"}

    callback_processor.process_signature_result(
        signature_session=signature_session,
        payload=payload,
    )

    return {"status": "ok"}
</syntaxhighlight>

=== 23.4. Обробка результату підписання ===

<syntaxhighlight lang="python">
def process_signature_result(signature_session: "SignatureSession", payload: dict) -> None:
    request = signature_session.signature_request

    if payload.get("status") == "declined":
        signature_session.status = "DECLINED"
        request.status = "DECLINED_BY_USER"
        return

    if payload.get("status") != "signed":
        signature_session.status = "ERROR"
        request.status = "SIGN_ERROR"
        return

    signature_file = signature_storage.save_signature_result(
        signature_request_id=request.id,
        payload=payload,
    )

    signature_session.status = "COMPLETED"
    request.status = "SIGNED"

    verification_queue.enqueue(
        task_name="verify_signature",
        payload={
            "signature_request_id": str(request.id),
            "signature_file_id": str(signature_file.id),
        },
    )
</syntaxhighlight>

=== 23.5. Перевірка підпису ===

<syntaxhighlight lang="python">
def verify_signature(signature_request_id: str, signature_file_id: str, db: "Session") -> None:
    request = signature_request_repository.get_by_id(db, signature_request_id)
    document_version = document_version_repository.get_by_id(db, request.document_version_id)
    signature_file = signature_file_repository.get_by_id(db, signature_file_id)

    try:
        result = signature_verifier.verify(
            document_file_id=document_version.file_id,
            signature_file_id=signature_file.file_id,
            expected_hash=document_version.file_hash_sha256,
        )

        verification = signature_verification_repository.create(
            db=db,
            data={
                "signature_request_id": request.id,
                "result": result.code,
                "signer_name": result.signer_name,
                "signer_identifier": result.signer_identifier,
                "signed_at": result.signed_at,
                "certificate_info": result.certificate_info,
                "raw_result": result.raw,
            },
        )

        if result.code == "VALID":
            request.status = "VERIFIED"
            request.document.status = "VERIFIED"
        else:
            request.status = "VERIFY_ERROR"

    except Exception as exc:
        request.status = "MANUAL_REVIEW"
        audit_logger.log(
            entity_type="signature_request",
            entity_id=request.id,
            event_type="SIGNATURE_VERIFY_EXCEPTION",
            new_status="MANUAL_REVIEW",
            payload={"error": str(exc)},
        )

    finally:
        db.commit()
</syntaxhighlight>

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

{| class="wikitable"
! Тип помилки
! Опис
! Дія системи
|-
| ValidationError
| Документ або підписант невалідний.
| Не створювати сесію.
|-
| AuthError
| Невірні credentials Дії.
| Зупинити інтеграцію і повідомити адміністратора.
|-
| DocumentChangedError
| Документ змінено після заявки.
| Скасувати заявку або створити нову.
|-
| FileTooLargeError
| Документ перевищує ліміт.
| Показати користувачу помилку.
|-
| SessionExpiredError
| Сесія підписання прострочена.
| Статус EXPIRED, дозволити створити нову.
|-
| CallbackValidationError
| Callback не пройшов перевірку.
| Відхилити callback і записати подію.
|-
| SignatureResultError
| Не вдалося отримати результат підпису.
| Перевести в SIGN_ERROR або NEEDS_RETRY.
|-
| VerificationError
| Підпис не пройшов перевірку.
| Статус VERIFY_ERROR.
|-
| SignerMismatchError
| Підписант не відповідає очікуваному.
| Статус MANUAL_REVIEW або VERIFY_ERROR.
|-
| TimeoutError
| API недоступне або timeout.
| Retry, якщо безпечно.
|}

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

Retry дозволений для:

* timeout;
* HTTP 429;
* HTTP 500;
* HTTP 502;
* HTTP 503;
* HTTP 504;
* тимчасової помилки створення сесії;
* тимчасової помилки отримання статусу;
* тимчасової помилки перевірки підпису;
* повторного callback з тим самим callback_id.

Retry заборонений для:

* невалідного документа;
* документа, який змінився;
* простроченої сесії;
* відхилення користувачем;
* невірного callback signature;
* невідповідності підписанта;
* вже фінального статусу VERIFIED.

== 26. Dashboard керівника ==

=== 26.1. Основні KPI ===

{| class="wikitable"
! KPI
! Опис
! Колір
|-
| Документів створено
| Загальна кількість документів.
| style="background:#e3f2fd;" | Інформація
|-
| Очікують підпису
| Документи з активною сесією.
| style="background:#fff9c4;" | Увага
|-
| Підписано
| Підпис отримано.
| style="background:#c8e6c9;" | Норма
|-
| Перевірено
| Підпис пройшов перевірку.
| style="background:#c8e6c9;" | Норма
|-
| Відхилено
| Користувач відмовився.
| style="background:#ffcc80;" | Потрібна дія
|-
| Прострочено
| Сесія не завершена вчасно.
| style="background:#ffcc80;" | Потрібна дія
|-
| Помилки
| Помилки підписання або callback.
| style="background:#ef9a9a;" | Критично
|-
| Ручна перевірка
| Потрібне втручання адміністратора.
| style="background:#f3e5f5;" | Контроль
|}

=== 26.2. Приклад dashboard ===

{| class="wikitable"
! Показник
! Значення
! Стан
|-
| Документів за день
| 184
| style="background:#e3f2fd;" | Інформація
|-
| Очікують підпису
| 32
| style="background:#fff9c4;" | Увага
|-
| Підписано
| 128
| style="background:#c8e6c9;" | Норма
|-
| Перевірено
| 126
| style="background:#c8e6c9;" | Норма
|-
| Відхилено
| 8
| style="background:#ffcc80;" | Потрібна дія
|-
| Прострочено
| 10
| style="background:#ffcc80;" | Потрібна дія
|-
| Помилки callback
| 3
| style="background:#ef9a9a;" | Критично
|-
| Ручна перевірка
| 2
| style="background:#f3e5f5;" | Контроль
|}

=== 26.3. Проблемні документи ===

{| class="wikitable"
! Дата
! Документ
! Підписант
! Статус
! Причина
! Дія
|-
| 07.05.2026
| Договір №123
| Іван Петренко
| style="background:#ffcc80;" | Прострочено
| Користувач не завершив підписання
| Створити нову заявку
|-
| 07.05.2026
| Акт №45
| Олена Сидоренко
| style="background:#ef9a9a;" | Помилка перевірки
| Hash документа не збігається
| Ручна перевірка
|-
| 07.05.2026
| Заява №77
| ТОВ «Альфа»
| style="background:#f3e5f5;" | Ручна перевірка
| Неможливо автоматично визначити підписанта
| Перевірити сертифікат
|}

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

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

* HTTPS для всіх endpoint-ів;
* перевірку SSL;
* зберігання секретів тільки в secret storage;
* шифрування файлів підпису;
* шифрування документів або контроль доступу до них;
* обмеження доступу до callback endpoint;
* перевірку callback signature / secret;
* ідемпотентність callback;
* журнал усіх дій;
* маскування персональних даних у логах;
* контроль доступу до документів;
* окремі права на створення заявки;
* окремі права на повторне підписання;
* окремі права на ручну перевірку;
* заборону підписання зміненої версії документа.

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

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

{| class="wikitable"
! Подія
! Що зберігати
|-
| Створення документа
| Тип, номер, версія, hash.
|-
| Створення заявки
| Підписант, строк дії, ініціатор.
|-
| Створення сесії Дія
| diia_session_id, статус, expires_at.
|-
| Відкриття QR/deep link
| request_id, час.
|-
| Callback
| callback_id, raw payload, статус перевірки.
|-
| Отримання підпису
| file_id, hash підпису, час.
|-
| Перевірка підпису
| результат, підписант, сертифікат.
|-
| Помилка
| код, повідомлення, stack trace без секретів.
|-
| Ручна перевірка
| хто перевірив, рішення, коментар.
|}

== 29. Acceptance Criteria ==

=== 29.1. Інтеграція ===

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

=== 29.2. Документ ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-4
| Документ валідний.
| Система створює заявку на підпис.
|-
| AC-5
| Документ перевищує ліміт розміру.
| Заявка не створюється.
|-
| AC-6
| Документ змінено після створення заявки.
| Попередня заявка стає INVALIDATED або скасовується.
|}

=== 29.3. Підписання ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-7
| Користувач натискає «Підписати через Дія».
| Система показує QR/deep link.
|-
| AC-8
| Користувач підписує документ.
| Система отримує callback і зберігає підпис.
|-
| AC-9
| Користувач відхиляє підписання.
| Статус стає DECLINED_BY_USER.
|-
| AC-10
| Сесія прострочена.
| Статус стає EXPIRED.
|}

=== 29.4. Перевірка ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-11
| Підпис валідний.
| Статус стає VERIFIED.
|-
| AC-12
| Hash документа не збігається.
| Статус стає VERIFY_ERROR.
|-
| AC-13
| Підписант не відповідає очікуваному.
| Статус стає MANUAL_REVIEW або VERIFY_ERROR.
|}

=== 29.5. Callback ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-14
| Callback має правильний підпис/секрет.
| Система приймає callback.
|-
| AC-15
| Callback повторився.
| Система не дублює результат.
|-
| AC-16
| Callback невалідний.
| Система повертає помилку і записує подію.
|}

=== 29.6. Dashboard ===

{| class="wikitable"
! №
! Критерій
! Очікуваний результат
|-
| AC-17
| Керівник відкриває dashboard.
| Він бачить документи, підписи, помилки, прострочення.
|-
| AC-18
| Є помилки підписання.
| Вони підсвічуються червоним.
|-
| AC-19
| Є прострочені заявки.
| Вони підсвічуються помаранчевим.
|-
| AC-20
| Є документи на ручній перевірці.
| Вони підсвічуються фіолетовим.
|}

== 30. MVP ==

До MVP входить:

* створення інтеграції Дія.Підпис;
* перевірка підключення;
* створення документа;
* збереження версії документа;
* розрахунок hash;
* створення заявки на підпис;
* створення сесії підписання;
* QR/deep link;
* callback endpoint;
* збереження результату підписання;
* базова перевірка підпису;
* статуси документа;
* журнал подій;
* dashboard API;
* retry для технічних помилок;
* ідемпотентність callback;
* unit-тести;
* mock Diia client.

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

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

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

=== Етап 1. Аналіз інтеграції Дія.Підпис ===

* отримати партнерську документацію;
* отримати тестові credentials;
* погодити callback URL;
* перевірити тестовий сценарій;
* визначити формат результату підписання;
* визначити правила перевірки підпису.

=== Етап 2. Базовий Python-сервіс ===

* створити FastAPI-проєкт;
* налаштувати PostgreSQL;
* створити моделі документів, заявок, сесій, підписів;
* налаштувати Alembic;
* реалізувати healthcheck.

=== Етап 3. Diia Client ===

* реалізувати authenticate;
* реалізувати create_signature_session;
* реалізувати get_signature_session_status;
* реалізувати get_signature_result;
* реалізувати обробку помилок.

=== Етап 4. Документи ===

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

=== Етап 5. Callback та підпис ===

* реалізувати callback endpoint;
* реалізувати перевірку callback;
* реалізувати збереження результату;
* реалізувати ідемпотентність;
* реалізувати raw event storage.

=== Етап 6. Перевірка підпису ===

* реалізувати Verification Service;
* реалізувати статуси перевірки;
* реалізувати ручну перевірку;
* реалізувати журнал перевірок.

=== Етап 7. Dashboard та аудит ===

* реалізувати dashboard API;
* реалізувати список проблемних документів;
* реалізувати фільтри;
* реалізувати експорт, якщо потрібно.

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

* додати rate limiting;
* додати alerting;
* додати dead letter queue;
* додати backup файлів;
* додати моніторинг callback;
* додати безпечне зберігання секретів.

== 32. Ризики ==

{| class="wikitable"
! Ризик
! Опис
! Як зменшити
|-
| Немає партнерського доступу
| Без доступу неможливо реалізувати production інтеграцію.
| Отримати доступ до старту розробки.
|-
| Документ змінено після заявки
| Можна підписати неактуальну версію.
| Версіонування і hash документа.
|-
| Callback втрачено
| Система не дізнається про результат.
| Callback retry, polling статусу, журнал raw events.
|-
| Дублювання callback
| Може повторно змінити статус.
| Ідемпотентність callback.
|-
| Невідомий формат підпису
| Неможливо зберегти/перевірити результат.
| Уточнити формат за документацією Дії.
|-
| Невідповідність підписанта
| Документ підписала не та особа.
| Перевірка даних сертифіката.
|-
| Помилка перевірки
| Підпис отримано, але не підтверджено.
| MANUAL_REVIEW і аудит.
|-
| Прострочені сесії
| Користувач не завершив підписання.
| TTL, нагадування, повторна заявка.
|}

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

# Чи вже є партнерський доступ до Дія.Підпис?
# Який точний формат результату підписання: p7s, ASIC, PDF з підписом або інший?
# Чи потрібно підписувати PDF, XML, DOCX або будь-який файл?
# Який максимальний розмір документа?
# Чи потрібне пакетне підписання?
# Чи потрібна авторизація через Дія.Підпис?
# Чи потрібно підписувати документи клієнтами, співробітниками або обома?
# Чи потрібно перевіряти РНОКПП / ЄДРПОУ підписанта?
# Чи потрібна інтеграція з K2 ERP?
# Чи потрібно зберігати підписані документи в архіві довгострокового зберігання?
# Чи потрібен UI для підписанта?
# Чи потрібні email/SMS-нагадування?
# Який строк дії сесії підписання?
# Який callback security mechanism надає Дія?
# Чи потрібна інтеграція з ЕДО-системами після підписання?

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

* Офіційна сторінка інтеграції Дії.
* Офіційна сторінка Дія.Підпис для партнерів.
* Офіційний FAQ Дія.Підпис.
* Офіційний сервіс КЕП Дії.
* Партнерська API-документація Дії, яка надається після підключення.
* Документація K2 ERP щодо документів і бізнес-процесів.

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

* [[Python]]
* [[FastAPI]]
* [[K2 ERP]]
* [[Дія]]
* [[Дія.Підпис]]
* [[Diia.Signature]]
* [[КЕП]]
* [[Електронний підпис]]
* [[Електронний документообіг]]
* [[Callback]]
* [[Webhook]]
* [[p7s]]
* [[Підписання документів]]
* [[API інтеграція]]

[[Категорія:Технічні завдання]]
[[Категорія:Python]]
[[Категорія:Дія]]
[[Категорія:Дія.Підпис]]
[[Категорія:КЕП]]
[[Категорія:Електронний документообіг]]
[[Категорія:API]]
[[Категорія:K2 ERP]]
[[Категорія:Інтеграції]]