Накладення електронного підпису за допомогою Дія в Python
payload=payload,
request = signature_session.signature_request
{| class="wikitable"
audit_logger.log(
1.; |-
| client_secret_encrypted
| text
| Зашифрований секрет.; |-
| Signature File
| Файл підпису або підписаний контейнер.; '''Критично істотно:''' якщо документ змінено після створення заявки на підпис, попередня заявка повинна бути скасована або переведена в статус INVALIDATED.; | Callback retry, polling статусу, журнал raw events.; |-
| signed_at
| timestamp
| Час підписання.; | style="background:#ffcc80;" | Помаранчевий
|-
| Помилка
| ERROR
| Технічна помилка.; K2 ERP отримує фінальний статус.; Поле
!; Diia Adapter
callback_url: str
я хочу бачити callback-и, помилки API та технічний журнал,
== 2.; Область сфера застосування ==
return request
"k2_entity_id": "contract-001"
retry_backoff_seconds: int = 5
except Exception as exc:
<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
client_id: str
db=db,
if payload.get("status") != "signed":
{| class="wikitable"
'''Головна ідея:''' розробити Python-сервіс, який надає можливість користувачам підписувати документи за допомогою '''Дія.Підпис''' із подальшим збереженням підписаного документа, файлу підпису, статусу підписання, журналу дій і результату перевірки підпису.; | style="background:#ef9a9a;" | Червоний
|-
| Не той документ
| HASH_MISMATCH
| Hash документа не збігається.; pass
db=db,
entity_id=request.id,
<syntaxhighlight lang="python">
"document_number": "123",
"deep_link": response.deep_link,
v
!; |-
| entity_id
| uuid
| ID сутності.; | Попередня заявка стає INVALIDATED або скасовується.; | Він бачить документи, підписи, помилки, прострочення.; |-
| Document Service
| Робота з документами та версіями.; |-
| ключовий сценарій
| користувач системи відкриває QR/deep link, підтверджує підписання в застосунку, платформа отримує результат.; |-
| Callback
| callback_id, raw payload, статус перевірки.; |-
| Отримання підпису
| file_id, hash підпису, час.; |-
| status
| varchar
| Статус заявки.; | платформа повертає помилку і записує подію.; {| class="wikitable"
* реалізувати завантаження документа;
* реалізувати версіонування;
* реалізувати hash;
* реалізувати валідацію;
* реалізувати дедублікацію.; # Який точний формат результату підписання: p7s, ASIC, PDF з підписом або інший?; |-
| Callback Event
| Подія, отримана від Дії.; Дата
|
| 4.; KPI
document_version = document_version_repository.get_by_id(db, request.document_version_id)
!; Показник
)
!;</pre>
request.status = "VERIFIED"
{| class="wikitable"
!; HTML
result = signature_verifier.verify(
=== 23.2.; Створення сесії Дія.Підпис ===
!; |-
| document_number
| varchar
| Номер документа.; |-
| created_at
| timestamp
| Дата створення.; Signature Storage зберігає підпис.; * Офіційна сторінка Дія.Підпис для партнерів.; document_version = document_version_repository.get_by_id(db, request.document_version_id)
платформа повинна логувати:
Перед створенням заявки платформа повинна перевірити:
[[Категорія:Python]]
!; Для багатьох КЕП-сценаріїв типовим є собою окремий файл підпису або контейнер.; |-
| raw_request
| jsonb
| Запит до Дії.; # Чи потрібно підписувати PDF, XML, DOCX або будь-який файл?; # Чи потрібна авторизація через Дія.Підпис?;== 26.; Dashboard керівника ==
DIIA_SIGNATURE_CLIENT_SECRET=********
"raw_response": response.raw_payload,
=== 14.1.; Створення інтеграції ===
{| class="wikitable"
== 31.; Етапи реалізації ==
!; |-
| SessionExpiredError
| Сесія підписання прострочена.; Поле
def create_signature_session(self, payload: "CreateSignatureSessionPayload") -> "SignatureSessionResponse":
!; Очікуваний результат
== 24.; Обробка помилок ==
entity_type="signature_request",
if callback_repository.exists(callback_id):
{| class="wikitable"
* створення заявки на підписання документа;
* підготовку документа до підпису;
* розрахунок hash документа, якщо це вимагається інтеграцією;
* створення сесії підписання;
* генерацію QR-коду або deep link для переходу в застосунок Дія;
* відображення користувачу статусу підписання;
* отримання callback / webhook від Дії;
* отримання результату підписання;
* збереження підпису;
* збереження підписаного документа або контейнера;
* перевірку підпису;
* перевірку цілісності документа;
* актуалізація статусу документа в K2 ERP або іншій системі;
* журналювання всіх подій;
* контроль помилок;
* dashboard для відповідальних осіб.; Причина
|-
| Прийом callback
| Критичний
| Не можна втрачати результат підписання.; Тип
"raw_request": payload,
{| class="wikitable"
POST /api/v1/diia-signature/documents/{document_id}/signature-requests
{{SEO
|title=Технічне завдання: Накладення електронного підпису за допомогою Дія.Підпис у Python
|description=Технічне завдання на реалізацію Python-сервісу для інтеграції з Дія.Підпис: підписання документів, авторизація, QR/deep link, статуси, callback, p7s, перевірка підпису, журналювання, dashboard та безпека.
|keywords=Python, Дія.Підпис, Diia.Signature, КЕП, електронний підпис, підписання документів, FastAPI, K2 ERP, callback, p7s, електронний документообіг
}}
"document_date": "2026-05-07",
5.; Результат
</pre>
"signer_id": command.signer_id,
</pre>
payload={"external_document_id": command.external_document_id},
{| class="wikitable"
щоб оперативно знаходити причини невдалого підписання.; Пріоритет
{| class="wikitable"
payload={"signature_request_id": str(request.id)},
17.; Hash документа і версії
7.3.; Адміністратор перевіряє помилки
Для кожного документа потрібно зберігати: Ключі дедублікації:
request.status = "SIGN_ERROR"
def verify_signature(signature_request_id: str, signature_file_id: str, db: "Session") -> None:
db.commit()
| style="background:#eeeeee;" | Сірий | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Готовий до підпису | READY_TO_SIGN | - | expires_at | timestamp | Дата завершення.; Очікуваний результат
13.; Конфігурація"signature_request_id": request.id, signature_session=signature_session,
щоб підписати документ без завантаження ключів у систему.; |-
| AuthError
| Невірні credentials Дії.;[[Категорія:K2 ERP]]
Після отримання результату підписання платформа повинна виконати перевірку.; |-
| is_active
| boolean
| Активність.; | style="background:#ef9a9a;" | Червоний
|-
| Потребує ручної перевірки
| MANUAL_REVIEW
| Неможливо автономно визначити результат.; |-
| AC-6
| Документ змінено після створення заявки.; Поле
K2 ERP / CRM / Website
!;<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
* Офіційна сторінка інтеграції Дії.; характеристика
== 34.; Джерела ==
{| class="wikitable"
=== 7.2.; Менеджер контролює підписання ===
=== 14.4.; Створення заявки на підпис ===
raise HTTPException(status_code=401, detail="Invalid callback signature")
"raw_result": result.raw,
=== Етап 6.; Перевірка підпису ===
=== 14.8.; Завантаження підписаного документа ===
користувач системи відкриває документ у K2 ERP або на сайті, натискає кнопку «Підписати через Дія.Підпис».; |}
<pre>
!; request.status = "DECLINED_BY_USER"
"certificate_info": result.certificate_info,
== 27.; Безпека ==
finally:
!; request=request,
"signature_request_id": request.id,
external_document_id=command.external_document_id,
* створити пакет документів;
* перевірити всі документи;
* передати пакет на підписання, якщо це підтримується;
* отримати результат по кожному документу;
* показати частково підписані або помилкові документи;
* не втратити статус окремого документа.; Verification Service перевіряє підпис.;== 23.; Приклад Python-логіки ==
</pre>
client_secret: str
document_version=document_version,
from pydantic_settings import BaseSettings
|-
| Немає партнерського доступу
| Без доступу неможливо реалізувати production інтеграцію.; | Помилка підписання, помилка перевірки.; |-
| qr_payload
| text
| інформаційні дані QR, якщо зберігаються.; |-
| AC-8
| користувач системи підписує документ.; * створення інтеграції Дія.Підпис;
* перевірка підключення;
* створення документа;
* збереження версії документа;
* розрахунок hash;
* створення заявки на підпис;
* створення сесії підписання;
* QR/deep link;
* callback endpoint;
* збереження результату підписання;
* базова перевірка підпису;
* статуси документа;
* журнал подій;
* dashboard API;
* retry для технічних помилок;
* ідемпотентність callback;
* unit-тести;
* mock Diia client.; характеристика
verification_queue.enqueue(
"diia_session_id": response.session_id,
{| class="wikitable"
платформа:
!; # Який строк дії сесії підписання?; |-
| idempotency_key
| Унікальний ключ заявки.; | Статус стає VERIFY_ERROR.; |-
| current_version_id
| uuid
| Поточна реліз.; Signature Storage + Verification Service
"idempotency_key": command.idempotency_key,
== 15.; Приклад запиту на створення заявки на підпис ==
* створює authorization session;
* показує QR/deep link;
* отримує підтвердження;
* ідентифікує користувача згідно з дозволеним обсягом даних;
* створює або оновлює сесію користувача.; API Дії / QR / deep link
<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
!; | Статус стає DECLINED_BY_USER.; # Чи потрібні email/SMS-нагадування?; |-
| Відкриття QR/deep link
| request_id, час.; | Статус стає VERIFIED.; !; | Не створювати сесію.; | Вони підсвічуються фіолетовим.; |-
| FileTooLargeError
| Документ перевищує ліміт.; Очікуваний результат
session_ttl_minutes: int = 15
=== 14.5.; Отримання QR/deep link ===
!; |-
| style="background:#eeeeee;" | Сірий
| #eeeeee
| Чернетка або архів.; | DRAFT, archived.; |-
| entity_type
| varchar
| document, request, session, callback, verification.; |-
| idempotency_key
| varchar
| Ключ дедублікації.; | Уточнити формат за документацією Дії.; Призначення
До MVP не входить:
)
)
Callback URL Python-сервісу
<pre>
{| class="wikitable"
base_url: str |
- | Створення сесії | Високий | ключовий сценарій користувача.; Дія системи
Співробітник компанії підписує внутрішній документ.; | платформа повертає успішний або помилковий статус.; | style="background:#c8e6c9;" | Зелений | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Відхилено користувачем | DECLINED_BY_USER | - | callback_event_id | ID callback-події, якщо надається.; характеристика | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Валідний | VALID | Зупинити інтеграцію і повідомити адміністратора.; |}
Етап 7.; Dashboard та аудитfrom hashlib import sha256
|
Verification Service | class="wikitable"
entity_type="signature_request", користувач системи підписує декілька документів за один бізнес-процес.; callback_id = callback_service.get_callback_id(payload) щоб контролювати електронний документообіг.; !; |- |
Signature Session | - | created_at | timestamp | - | file_id | uuid | style="background:#ef9a9a;" | Критично | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Ручна перевірка | Показати користувачу помилку.; характеристика
"signed_at": result.signed_at, request.status = "SIGNED" |- | id | uuid | ID інтеграції.; |} ) До MVP входить: <pre>
Diia Client — це Python-клас або пакет, який інкапсулює роботу з API Дія.Підпис.; |-
|