Перейти до вмісту

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

Матеріал з K2 ERP Wiki

Як бухгалтер,

! Поле 

api_password: str | None = None

status_response = edin_client.get_document_status(document.edin_document_id)

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

}

Критично критично: для кожного типу документа потрібно окремо зберігати схему, канал передачі, правила підписання, допустимі вкладення та правила отримання статусу. db.commit()

13.10. Dashboard

Вони підсвічуються помаранчевим. Код Черга, статус API. # Чи потрібно підтримувати декілька юридичних осіб? |- payload jsonb - code varchar - receipt_type varchar Квитанція, підтвердження, службове повідомлення. Коментар

POST /api/v1/edin/integrations Приклад hash:

7.5. Dashboard керівника

 === 7.2. Підписання === 
if document.status in ["ACCEPTED", "DELIVERED"]:
id uuid - vat_amount numeric }

</syntaxhighlight>

5. |-

Audit Logger - document_id uuid ID документа. SEO-опис 

 def get_document_status(self, edin_document_id: str) -> "DocumentStatusResponse":
{| class="wikitable"
! SEO-опис
Integration Account Обліковий запис інтеграції EDIN. KPI - Неправильний формат XML Документ здатна бути відхилено. Код
AC-9 - Document Mapper - Основні операції Підготовка документа, підписання, передача, статуси, квитанції. Важливість
id uuid - Розрахунок коригування Критичний - K2 ERP / ERP / CRM Джерело документів, контрагентів, статусів і задач. Призначення

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

EDIN Критично критично: документ зі статусом ACCEPTED або DELIVERED не можна автоматизовано відправляти повторно. |-

е-ТТН EDIN ETTN API, якщо підключено. Очікуваний результат 
],

Python-сервіс передає EDI-документи між компаніями та торговельними мережами. |-

total_amount numeric Повернути існуючий документ. "vat_amount": 2000.00,

{

  • передачі податкових накладних;
  • передачі розрахунків коригування;
  • передачі первинних документів;
  • передачі актів, рахунків, видаткових накладних;
  • передачі структурованих документів через EDIN DocFlow;
  • передачі EDI-документів;
  • передачі е-ТТН, якщо застосовується для відповідний API EDIN;
  • передачі документів між контрагентами;
  • підготовки пакета документів, які потрібні бухгалтеру для податкової звітності;
  • контролю статусів підписання та доставки документів. |-
 raw_payload jsonb інформаційні дані квитанції. Тип
AC-17 - created_at timestamp style="background:#c8e6c9;" | Норма
Відхилено - requires_signature boolean style="background:#eeeeee;" | Сірий 
payload=status_response.raw_payload,

"counterparty_id": "counterparty-001",

13.7. Синхронізація статусу

"file_id": "file-002"
Зелений #c8e6c9 - new_status varchar Новий статус. Формування документа 
)
if existing:
Статус підсвічується зеленим. |- конкурентні переваги Статус підсвічується червоним. |- Немає квитанції Документ передано, але підтвердження не отримано. ! Ключ

25. Acceptance Criteria

document.status = "SENDING"
},

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

8.1. Основні типи документів для MVP

)
- Document Queue - base_url varchar Idempotency key і document_hash. |- Основні операції - Жовтий #fff9c4 Підтвердити API та типи документів до розробки. |- file_hash varchar - Блакитний #bbdefb - Підписано SIGNED Зелений style="background:#bbdefb;" | Блакитний
Передано в EDIN SENT_TO_EDIN Документ переданий у EDIN, очікується фінальний статус. # Чи підтримує EDIN потрібний тип податкової звітності? SEO-опис застосовується для для ORDER, DESADV, INVOICE та інших EDI-документів. |- document_date date Дата документа. Критерій Тип 
"signing_required": true,
style="background:#fff9c4;" | Жовтий
Підписано SIGNED - AC-18 виступає як відхилені документи. Параметр Формат }

1. Мета

</syntaxhighlight> критично: EDIN не слід автоматизовано вважати універсальним каналом подання всіх декларацій до ДПС. ! |-

document_number + document_date + organization_id + counterparty_id Зупинити інтеграцію, повідомити адміністратора. "payload_hash": payload_hash, 
retry_backoff_seconds: int = 5
Підходить для - api_token_encrypted text style="background:#c8e6c9;" | Зелений
Очікує відправки PENDING_SEND Документ у черзі передачі. Поле

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

Варіант 2. 5.2. EDI Network API

 - Отримання квитанції } SEO-опис

я хочу повторити передачу після технічної помилки,

25.3. Статуси та квитанції

audit_logger.log(
document.edin_document_id = response.document_id

Заборонено: зберігати логін, пароль, API token, КЕП, пароль до КЕП або інші секрети у коді, Git-репозиторії, відкритих логах або frontend-змінних. |}

POST /api/v1/edin/documents/{document_id}/sync-status

Як адміністратор,

21.1. Типи помилок

щоб не створювати документ вручну повторно. Стан 

},
v
Другий документ не створюється. | базовий зовнішній сервіс. Тип
Документів створено style="background:#bbdefb;" | Блакитний
Потребує виправлення NEEDS_CORRECTION - document_id uuid ID документа. Значення style="background:#c8e6c9;" | Зелений
Прийнято ACCEPTED Таблиця status_mapping і статус UNKNOWN. Повторна відправка дозволена тільки для технічних помилок або спеціальних статусів, визначених бізнес-правилами. SEO-опис
pass
"external_document_id": "K2-TAX-INVOICE-2026-000123",
AC-4 }
  • акаунт EDIN;
  • доступ до EDIN API або EDIN DocFlow API;
  • тестове середовище або тестову компанію, якщо доступно;
  • логін / пароль або API token;
  • інформаційні дані компанії-відправника;
  • інформаційні дані контрагентів;
  • перелік типів документів, які потрібно передавати;
  • XML / JSON-специфікації документів;
  • правила підписання;
  • КЕП / ЕЦП або сценарій делегованого підписання;
  • вимоги до вкладень;
  • правила отримання статусів;
  • правила отримання квитанцій;
  • правила повторної відправки;
  • контакт технічної підтримки EDIN. # Чи потрібно підтримувати декілька акаунтів EDIN? Очікуваний результат
</syntaxhighlight>
Як відповідальна особа,

21.2. Retry-логіка

- Скасування Статус підписання змінюється на SIGNED. |- schema_version varchar реліз системи схеми. я хочу бачити документи, які очікують підпису,
  • помилок валідації;
  • неправильного логіна / пароля / token;
  • помилки КЕП;
  • невідповідності схемі документа;
  • документа, який уже прийнято;
  • документа, який явно відхилено через бізнес-помилки. |-
 provider varchar edin. Статус 
document = edin_document_repository.get_by_id(db, document_id)

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

26. MVP

 - api_login_encrypted text Не змінювати фінальний статус без перевірки. |- sent_at timestamp - accepted_at timestamp - counterparty_id uuid - Помаранчевий #ffcc80 Потрібен workflow задач. |- SchemaError Документ не відповідає XML/JSON-схемі. Статус

from datetime import datetime, timezone

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

16.2. Статуси підписання

! |-
| document_hash
| Hash XML/JSON/PDF документа. №
 "idempotency_key": "K2-TAX-INVOICE-2026-000123-v1",

! Канал

<syntaxhighlight lang="python">

<pre>
! |-
| status
| varchar
| Поточний статус. |-
| integration_id
| uuid
| ID інтеграції. |-
| Document Type
| Тип документа: податкова накладна, акт, рахунок, EDI-документ тощо. | style="background:#ef9a9a;" | Червоний
|-
| Помилка передачі
| SEND_ERROR
| Технічна помилка передачі. |-
| Невідомий статус
| EDIN здатна повернути статус, якого немає в мапінгу. |-
| external_document_id
| varchar
| ID документа в K2 ERP. SEO-опис
 def get_document_list(self, filters: dict) -> "DocumentListResponse":

K2 ERP / ERP / CRM

EDIN_RETRY_COUNT=3

* наявність external_document_id;
* наявність idempotency_key;
* тип документа;
* організацію-відправника;
* контрагента;
* ЄДРПОУ / ІПН / податковий номер сторін;
* дату документа;
* номер документа;
* валюту;
* суму;
* ПДВ, якщо застосовується;
* формат XML / JSON / PDF;
* відповідність схемі документа;
* наявність обов'язкових вкладень;
* наявність КЕП або сценарію підписання;
* чи не був документ уже відправлений;
* чи дозволений повтор для поточного статусу. |-
| SendError
| API EDIN повернув помилку. |-
| edin_document_id
| varchar
| ID документа в EDIN. '''Технічний стек:''' Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Redis, Docker. |-
| AC-20
| виступає як документи, що потребують повтору. ! |}

! |}

=== 13.6. Завантаження вкладення ===

 "organization_id": "org-001",

* створення інтеграції EDIN;
* перевірка підключення;
* довідник типів документів;
* створення документа;
* валідація документа;
* завантаження вкладень;
* базовий сценарій підписання або статус «очікує підпису»;
* передача документа в EDIN;
* збереження EDIN document ID;
* синхронізація статусу;
* отримання квитанцій, якщо доступно через API;
* дедублікація;
* retry-механізм;
* журнал подій;
* dashboard API;
* базові unit-тести;
* mock EDIN API для інтеграційних тестів. Код

[[Категорія:API]]

 new_status=document.status,
== 21. Обробка помилок ==
<pre>
{| class="wikitable"
|-
| Підписання в K2 ERP
| Документ підписується до передачі в EDIN. SEO-опис

 data={

<syntaxhighlight lang="python">
я хочу бачити загальну картину по документах EDIN, 
 event_type="DOCUMENT_CREATED",
=== 19.3. edin_documents ===
=== 25.5. Dashboard ===
 payload={"external_document_id": command.external_document_id},
{| class="wikitable"
<pre>
! платформа повинна логувати:

<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
 if old_status != new_status:
! Дата
|-
| id
| uuid
| ID події. |-
| payload_format
| varchar
| XML, JSON, PDF, mixed. # Чи потрібна валідація XML за XSD? | style="background:#e3f2fd;" | інформаційні матеріали
|-
| Очікують підпису
| Документи без підпису. | Python-сервіс створює запис зі статусом DRAFT. |-
| Підписання
| Хто підписав, коли, результат. Status Sync Worker періодично оновлює статус. |-
| SignatureError
| Помилка підписання. Критерій

[[Категорія:EDIN]]

POST /api/v1/edin/documents/{document_id}/attachments
 new_status = status_mapper.from_edin(status_response.status)
POST /api/v1/edin/integrations/{integration_id}/check-connection
|-
| API Layer
| REST API для прийому документів із K2 ERP. |-
| updated_at
| timestamp
| Дата оновлення версій.
def upload_attachment(self, edin_document_id: str, file: bytes, filename: str) -> "AttachmentResponse":
external_document_id - signing_status varchar Статус підписання.=== 16.1. Сценарії підписання === 
def update_document(self, edin_document_id: str, payload: "EdinDocumentPayload") -> "EdinDocumentResponse":

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

  • створити FastAPI-проєкт;
  • налаштувати PostgreSQL;
  • створити моделі інтеграції, документів, вкладень, подій;
  • налаштувати Alembic;
  • реалізувати healthcheck. | style="background:#fff9c4;" | Контроль
- AC-7 - Counterparty - Помилка підпису SIGN_ERROR Червоний Підписання не виконано.== 22. Dashboard керівника == 
"idempotency_key": command.idempotency_key,
* реалізувати dashboard API;
  • реалізувати список проблемних документів;
  • реалізувати фільтри;
  • реалізувати експорт, якщо потрібно. Реальні EDIN API endpoint-и потрібно підставити з офіційної документації EDIN для конкретного продукту: DocFlow, EDI Network, ETTN або податкові накладні. Квитанції та підтвердження зберігаються в картці документа. SEO-опис

Варіант 1. 5.1. EDIN DocFlow API

Як бухгалтер, 

"vat_amount": command.vat_amount,
document_id=document.id,
Помилка 
"filename": "tax_invoice_123.pdf",
"send_after_signing": true

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

 - external_receipt_id varchar ID квитанції в EDIN. Компонент
id uuid - TimeoutError Перевищено час очікування. Тип документа - Очікує підпису WAITING_SIGNATURE Жовтий - content_type varchar Списки, архів. | Зберігається EDIN document ID. |}

13.4. Передача документа в EDIN

  1. Який саме ERP-продукт EDIN застосовується для: DocFlow, EDI Network, Tax Invoice, ETTN чи гібрид? |-
 AC-8 Документ відправлено в EDIN. new_status="SENT_TO_EDIN",

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

class EdinSettings(BaseSettings):

Підходить для Податкових накладних, розрахунків коригування, пов'язаних документів. Колір Статус змінюється на READY_FOR_REVIEW або WAITING_SIGNATURE. |- Основні операції Формування XML, передача, отримання статусу, отримання відповіді контрагента. Тип

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

def authenticate(self) -> "AuthResult":

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

 - е-ТТН Високий Важливий для логістики. Очікуваний результат - file_id uuid Файл квитанції. Сутність

5. Варіанти інтеграції

EDIN_INTEGRATION_MODE=docflow 

{
  • формування електронного документа у внутрішній системі;
  • валідацію документа перед передачею;
  • підготовку XML / JSON / PDF / XLSX / вкладень;
  • підписання КЕП або передачу документа на підписання;
  • відправку документа в EDIN;
  • отримання статусу документа;
  • отримання підтверджень, квитанцій або службових повідомлень, якщо доступні;
  • збереження ID документа EDIN;
  • збереження історії зміни статусів;
  • повторну передачу документа після технічної помилки;
  • захист від дублювання;
  • передачу статусу назад у K2 ERP;
  • формування dashboard для контролю. | Без підпису він не відправляється. |-
 payload_format varchar - Attachment Вони підсвічуються жовтим. 
== 27. Етапи реалізації ==
{| class="wikitable"
 "organization_id": command.organization_id,
! Коментар

! Критерій
! |-
| Дублювання документів
| Повторний запит здатна створити дубль. |-
| payload_hash
| varchar
| Hash документа. "status": "DRAFT",

 payload={"edin_document_id": response.document_id},
<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
! | style="background:#eeeeee;" | Сірий
|-
| Готовий до перевірки
| READY_FOR_REVIEW
| Документ сформований і очікує перевірки. | платформа повторює передачу без дублювання. |-
| style="background:#eeeeee;" | Сірий
| #eeeeee
| Чернетка, скасовано або не застосовується. |-
| edin_attachment_id
| varchar
| ID вкладення в EDIN. |-
| created_at
| timestamp
| Дата створення. Компонент
def send_edin_document(document_id: str, db: "Session") -> None:

{| class="wikitable"
Retry заборонений для:

! Python EDIN Client
! |-
| AC-19
| виступає як документи без підпису. |}

[[Категорія:Python]]

== 7. User Story ==

{| class="wikitable"
3. |-
| Status
| Статус документа в K2 ERP та EDIN. |-
| Отримання статусу
| Старий статус, новий статус, джерело. Організація
== 8. Типи документів ==


 "filename": "tax_invoice_123.xml",
платформа повинна не допускати дублювання документів. | style="background:#ef9a9a;" | Червоний
|-
| Потребує повтору
| NEEDS_RETRY
| Документ можна передати повторно.{{DISPLAYTITLE:Технічне завдання: Передача документів для звітності в податкову через EDIN для Python}}
 pass
=== 19.5. edin_receipts ===
{| class="wikitable"
 pass
POST /api/v1/edin/documents/{document_id}/sign
Для реалізації задачі необхідно отримати:
! Контрагент

</div>
! |-
| AC-16
| Документ уже прийнятий. | Потрібно перевірити конкретний API та тип документа. Колір

* реалізувати створення документа;
* реалізувати мапінг K2 ERP → EDIN;
* реалізувати валідацію;
* реалізувати hash документа;
* реалізувати дедублікацію.=== Етап 8. Production hardening ===
 document.status = "SENT_TO_EDIN"
<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
|-
| 07.05.2026
| Податкова накладна №123
| ТОВ «Альфа»
| ТОВ «Бета»
| style="background:#ef9a9a;" | Відхилено
| Помилка схеми XML
| Виправити
|-
| 07.05.2026
| Акт №45
| ТОВ «Альфа»
| ТОВ «Гамма»
| style="background:#fff9c4;" | Очікує підпису
| Немає КЕП відповідального
| Підписати
|-
| 07.05.2026
| е-ТТН №77
| ТОВ «Логістика»
| ТОВ «Покупець»
| style="background:#ffcc80;" | Потребує повтору
| Timeout EDIN API
| Повторити
|}

=== 7.4. Повторна передача ===

__TOC__

* зберігання EDIN credentials тільки у secret storage або в зашифрованому вигляді;
* заборону логування паролів, token, ключів КЕП;
* маскування персональних даних;
* HTTPS для всіх API-запитів;
* перевірку SSL;
* рольову модель доступу;
* окремі права на підписання;
* окремі права на повторну відправку;
* окремі права на скасування документа;
* журнал усіх дій;
* захист від дублювання документів;
* контроль доступу до вкладень;
* обмеження розміру файлів;
* антивірусну перевірку вкладень, якщо потрібно. SEO-опис
=== Етап 2. Базовий Python-сервіс ===
GET /api/v1/edin/dashboard?date_from=2026-05-01&date_to=2026-05-31
</div>
 document_id=document.id,
 "document_type_id": command.document_type_id,
 db=db,

from pydantic_settings import BaseSettings
! | style="background:#fff9c4;" | Жовтий
|-
| Відправляється
| SENDING
| Виконується API-запит до EDIN. |-
| storage_path
| varchar
| Шлях у сховищі. |-
| AuthError
| Невірні облікові інформаційні дані EDIN. Після підпису документ переходить у PENDING_SEND. |-
| created_at
| timestamp
| Дата створення. |-
| idempotency_key
| Унікальний ключ конкретної версії відправки. SEO-опис
{| class="wikitable"

 pass
K2 ERP / Dashboard / Задачі відповідальних
 if new_status == "ACCEPTED":

 integration_mode: str = "docflow"

 auth_url: str | None = None

 try:
'''Управлінський результат:''' керівник або бухгалтер повинен бачити, які документи сформовано, які підписано, які передано в EDIN, які прийнято, які відхилено, які очікують підпису або дії користувача. |-
| Податкові декларації
| Окремо підтверджується; за потреби застосовують, коли потрібно інший канал. Для класичної податкової звітності потрібно окремо перевіряти, чи підтримує EDIN потрібний сценарій передачі, підписання, отримання квитанцій та статусів. Сценарій
! Поле

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

{| class="wikitable"
'''критично:''' назви методів у Python-клієнті виступає як внутрішньою абстракцією. |-
| file_size
| integer
| Розмір файлу. |}

! |-
| AC-2
| Адміністратор перевіряє підключення. |-
| Dashboard API
| Видає статистику по документах, статусах і помилках. SEO-опис
! Python-сервіс зберігає EDIN ID. SEO-опис
Податкова накладна TAX_INVOICE XML / структурований документ EDIN Tax Invoice / DocFlow, якщо доступно Критична
Розрахунок коригування TAX_ADJUSTMENT XML / структурований документ EDIN Tax Invoice / DocFlow, якщо доступно Критична
Акт виконаних робіт ACT XML / PDF / структурований EDIN DocFlow Важлива
Рахунок INVOICE XML / PDF / структурований EDIN DocFlow / EDI Network Додаткова
Видаткова накладна EXPENSE_INVOICE XML / PDF / структурований EDIN DocFlow / EDI Network Важлива
ТТН / е-ТТН ETTN XML / структурований EDIN ETTN API, якщо підключено Важлива
Договір CONTRACT PDF / структурований EDIN DocFlow Додаткова
Довільний файл FILE PDF / XLSX / DOCX / ZIP EDIN DocFlow, якщо підтримується Супровідна 
pass
Очікуваний результат
  • реалізувати чергу передачі;
  • реалізувати worker відправки;
  • реалізувати worker синхронізації статусів;
  • реалізувати retry;
  • реалізувати збереження квитанцій. | Документ переходить у NEEDS_RETRY. | Перевести в NEEDS_CORRECTION. | Перевести в NEEDS_RETRY. |-
 id uuid - AC-10 style="background:#c8e6c9;" | Зелений
Відхилено REJECTED Повторна відправка блокується. Критерій 
pass

платформа повинна забезпечити:

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

Перед відправкою платформа повинна перевірити: EDIN_API_TOKEN=********

- idempotency_key varchar - Червоний #ef9a9a }

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

v
"total_amount": command.total_amount,
finally:
def refresh_token(self) -> "AuthResult":
AC-1 - EDIN Tax Invoice / Податкова накладна Сценарій роботи з електронною податковою накладною на платформі EDIN. document.status = "NEEDS_RETRY" 
sha256(document_type + document_number + document_date + total_amount + organization_tax_id + counterparty_tax_id)
=== 12.1. Призначення ===
{| class="wikitable"
|-
| EDIN не підтримує потрібний тип звітності
| Не всі податкові декларації можуть бути доступні через EDIN. Пріоритет


 document_id=document.id,
 )
 document.status = new_status

! # Чи потрібен dashboard у K2 ERP? |-
| Податкові накладні
| EDIN-сценарій податкових накладних, якщо доступний. | Версіонування клієнта і contract-тести.<pre>
|-
| Чернетка
| DRAFT
| Документ створено в K2 ERP, але ще не готовий до передачі. |-
| API Event
| Подія інтеграції. | Потрібно підтвердити підтримку цього сценарію для типу документа. |-
| status
| varchar
| Статус квитанції. |}

 api_login: str | None = None

<div style="border-left: 6px solid #1565c0; background: #e3f2fd; padding: 12px 16px; margin: 16px 0;">
 return document
</div>
! |-
| Синхронізація статусів
| Середній
| Фоновий бізнес-процес. Що зберігати
 idempotency_key=command.idempotency_key,
Signature Service / KEP Module
{| class="wikitable"
 new_status=new_status,
 audit_logger.log(
=== 25.1. інтеграційні функції ERP ===
! # Чи потрібно отримувати квитанції автоматизовано? K2 ERP створює документ. Подія
! {| class="wikitable"
=== 19.4. edin_attachments ===
 {
! Дія системи

 event_type="DOCUMENT_SENT_TO_EDIN",
=== 18.1. Логіка черги ===
! Колір
<pre>

 if not document.edin_document_id:

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

9. Тип


== 11. технічна архітектура рішення для бізнесу ==

=== 20.3. Синхронізація статусів ===

! оновлення версій статусів
GET /api/v1/edin/documents/{document_id}/receipts
! |}

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

 existing = edin_document_repository.get_by_idempotency_key(

* timeout;
* HTTP 429;
* HTTP 500;
* HTTP 502;
* HTTP 503;
* HTTP 504;
* тимчасової недоступності EDIN;
* тимчасової помилки отримання статусу;
* тимчасової помилки завантаження квитанції. "raw_request": command.model_dump(),

POST /api/v1/edin/documents/{document_id}/send

Етап 3. EDIN Client

 платформа повертає успішний або помилковий статус. Поле
Документ інтеграційні функції ERP зберігається в системі. |- source varchar - EDI-документи EDI Network. Критерій
Первинні документи Потрібен компонент КЕП у K2 ERP. EDIN_BASE_URL=https://api.example.edin
  • реалізувати авторизацію;
  • реалізувати check_connection;
  • реалізувати create_document;
  • реалізувати upload_attachment;
  • реалізувати send_document;
  • реалізувати get_document_status;
  • реалізувати get_document_list;
  • реалізувати download_receipt;
  • реалізувати обробку помилок. |-
 filename varchar style="background:#bbdefb;" | В роботі
Прийнято style="background:#ffcc80;" | Помаранчевий
Очікує підпису WAITING_SIGNATURE }

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

old_status=old_status,

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

- Python Integration Service - old_status varchar Попередній статус. Ризик

30. Джерела

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


 "signing_status": "WAITING_SIGNATURE" if command.signing_required else "SIGN_NOT_REQUIRED",
 "counterparty_id": command.counterparty_id,

 response = edin_client.create_document(payload)
! |}

 def download_receipt(self, edin_document_id: str, receipt_id: str) -> bytes:

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

 },

Python-сервіс формує або передає документи, пов'язані з електронною податковою накладною. db.commit()
! |-
| error_message
| text
| Остання помилка. |}

def create_edin_document(command: "CreateEdinDocumentCommand", db: "Session") -> "EdinDocument":

 if document.signing_status == "WAITING_SIGNATURE":

== 19. Модель даних ==
=== 19.6. edin_events ===
8. |-
| Податкова накладна
| Критичний
| Впливає на податковий обліковий облік. |-
| is_active
| boolean
| Активність. |-
| EDIN EDI Network
| Платформа для EDI-документообігу з контрагентами. |-
| raw_request
| jsonb
| Запит до EDIN.== 12. EDIN Client ==

* автоматичне подання всіх декларацій до ДПС без підтвердження EDIN API;
* повна технічна підтримка всіх документів EDIN;
* повна технічна підтримка всіх EDI-мереж;
* повна технічна підтримка е-ТТН, якщо не підключено ETTN API;
* власний компонент КЕП без окремого ТЗ;
* складний UI підписання;
* автоматичне виправлення XML-помилок;
* юридична перевірка змісту документа. |-
| Status Sync Worker
| Періодично синхронізує статуси з EDIN. | Зберегти raw-відповідь. |-
| EDIN DocFlow API
| API для роботи зі структурованими документами, компаніями, статусами та списками документів. Поле

 pass

4. |-
| ReceiptError
| Помилка отримання квитанції. |-
| raw_response
| jsonb
| Відповідь EDIN. |}

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

! | Внутрішня платформа замовника. |-
| Signature
| Підпис КЕП / ЕЦП. |-
| Organization
| Компанія-відправник або отримувач. ! Призначення
! | платформа показує AuthError і не відправляє документи. Коментар
<pre>
! |-
| Підписується
| SIGNING
| style="background:#bbdefb;" | Блакитний
| Виконується підписання. "total_amount": 12000.00,
|-
| ValidationError
| Некоректні інформаційні дані документа. | style="background:#ffcc80;" | Потрібна дія
|-
| Без квитанції
| Документи без підтвердження. Валідація, мапінг, підготовка файлів
! |-
| EDIN Document
| Документ, створений або переданий в EDIN. |-
| integration_mode
| varchar
| docflow, edi_network, tax_invoice, ettn, hybrid. | е-ТТН, нестандартні документи, ручні сценарії. | Він бачить кількість створених, підписаних, відправлених, прийнятих і відхилених документів. Ключі дедублікації:
EDIN_TIMEOUT_SECONDS=30
 "payload_format": command.payload_format,
! |-
| Завантаження квитанцій
| Середній
| Не блокує первинну відправку. |-
| Обмеження
| Потрібно підтвердити формат API, підписання, статуси та квитанції. щоб знати, чи документ прийнятий, відхилений, доставлений або очікує дії. |}

=== Етап 4. Документи та валідація ===

<syntaxhighlight lang="json">
{| class="wikitable"
! |}

 return

== 2. Область сценарії використання ==
! "xml_file_id": "file-001"

інтеграційні функції ERP здатна використовуватись для:
 document.sent_at = datetime.now(timezone.utc)
=== 12.2. Основні методи ===
 "document_date": command.document_date,
== 17. Дедублікація ==
 document = edin_document_repository.get_by_id(db, document_id)
 v

! payload = edin_mapper.to_edin_payload(document)

{| class="wikitable"

* отримати офіційну документацію EDIN;
* визначити ERP-продукт: DocFlow, EDI Network, Tax Invoice, ETTN або гібрид;
* визначити авторизацію;
* визначити формати документів;
* визначити статуси;
* визначити правила підписання;
* визначити квитанції та підтвердження. |-
| Помилка передачі
| Код, повідомлення, raw-відповідь. SEO-опис
</div>
=== 22.2. Приклад dashboard ===
я хочу натиснути кнопку «Передати через EDIN»,
- received_at timestamp - CounterpartyError - created_at timestamp Дата події. Канал

Варіант 4. 5.4. Гібридна схема

return
- Обмеження - AC-12 style="background:#ef9a9a;" | Критично
Потребують повтору Технічні помилки, які можна повторити. Підписання або передача на підпис style="background:#ffcc80;" | Помаранчевий
Скасовано CANCELLED - Document Validator - organization_id uuid Вони підсвічуються червоним. |- Підписання в Python-сервісі Python-сервіс викликає внутрішній Signature Service. Поле

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

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

 - DuplicateDocumentError - name varchar Назва типу документа. EDIN застосовується для для ЕДО та первинних документів, а податкова формування звітів подається через інший канал виступає ключовою рисою критично: якщо бізнес-процес передбачає саме подання декларацій до ДПС, потрібно окремо підтвердити, що EDIN API підтримує цей тип звітності. № - Signature Adapter Підписує документ або передає його на підписання.

щоб підписати їх КЕП перед відправкою. |} 

document.error_message = str(exc)

Для надійності передача документів повинна виконуватись через чергу. |-
| Валідація
| Результат, список помилок. |-
| Повторна відправка
| Хто запустив, причина, результат. |-
| AC-11
| Документ відхилено.== 28. Ризики ==

* реалізувати сценарій WAITING_SIGNATURE;
* реалізувати інтеграцію з Signature Service, якщо виступає як;
* реалізувати перевірку підпису;
* реалізувати журнал підписання. |-
| Receipt / Confirmation
| Квитанція, підтвердження або службове повідомлення. |-
| Первинний документ
| Високий
| Важливий для бухгалтерії. | Не відправляти документ, показати список помилок. |-
| integration_mode
| varchar
| Через який канал передається. |-
| company_id
| varchar
| ID компанії в EDIN. | Валідація за схемою до відправки. SEO-опис
Python EDIN Integration Service
Як керівник бухгалтерської компанії, 
'''Критично критично:''' без офіційної API-документації EDIN для конкретного продукту не можна фіксувати production endpoint-и, назви методів і формати payload як остаточні. |-
| document_id
| uuid
| ID документа. |-
| AC-6
| Документ потребує підпису. Тип помилки

EDIN_API_LOGIN=********
 "document_number": "123",
 document = edin_document_repository.create(
POST /api/v1/edin/documents
|-
| AC-13
| Повторний запит має той самий idempotency_key. |-
| Document
| Внутрішній документ K2 ERP. Очікуваний результат
! |-
| requires_attachments
| boolean
| Чи потрібні вкладення. |-
| name
| varchar
| Назва інтеграції. |-
| Receipt Collector
| Завантажує квитанції, підтвердження, службові повідомлення. SEO-опис
document_validator.validate(command) db.commit() payload_hash = document_hash_service.calculate(command.payload)
Значення 
{| class="wikitable"
 pass
=== Варіант 3. 5.3. Податкові накладні через EDIN ===
[[Категорія:Електронний документообіг]]
! |-
| AC-5
| Документ проходить валідацію. Де застосовується для
 api_token: str | None = None
 def get_document(self, edin_document_id: str) -> "EdinDocumentResponse":

 document.raw_response = response.raw_payload

<pre>
=== 7.3. Контроль статусів ===
 pass

! |-
| Відправка в EDIN
| Час, endpoint, request_id, EDIN document ID. | Перевести в SIGN_ERROR. | Квитанція зберігається в картці документа. | Список документів, dashboard, картка документа. Тип
До MVP не входить:

!=== 25.2. Документи ===

 base_url: str

[[Категорія:Податкова звітність]]
</div>
 "document_number": command.document_number,
|-
| Створення документа
| Тип, номер, дата, організація, контрагент. |-
| Підписання в EDIN
| Документ передається в EDIN і підписується користувачем на платформі. Документ отримує статус READY_FOR_REVIEW або WAITING_SIGNATURE. |-
| document_type_id
| uuid
| Тип документа. Доставка / обробка / статуси
=== 7.1. Передача документа ===
! Параметр
щоб документ із K2 ERP був сформований, перевірений, підписаний і переданий в EDIN. # Які формати документів використовуються: XML, JSON, PDF, XLSX? Якщо не підтримує. |-
| api_password_encrypted
| text
| Зашифрований пароль. До MVP входить:
|-
| Підходить для
| ORDER, ORDRSP, DESADV, INVOICE, COMDOC, e-ТТН та інших EDI-сценаріїв. |}

=== 19.2. edin_document_types ===

 pass

{{SEO
|title=Технічне завдання: Передача документів для звітності в податкову через EDIN для Python
|description=Технічне завдання на реалізацію Python-сервісу для передачі документів, податкових накладних, первинних документів та супровідних документів через EDIN / EDIN DocFlow / EDI Network з контролем статусів, підписанням, квитанціями, журналюванням та інтеграцією з K2 ERP.
|keywords=Python, EDIN, EDIN API, EDIN DocFlow, EDI Network, електронний документообіг, податкова накладна, КЕП, електронні документи, K2 ERP, податкова звітність, технічне завдання
}}
 db=db,
 |
 | 1. |}

 pass

{| class="wikitable"
 db.commit()
- Помилка КЕП } - Обмеження Python-сервіс оновлює статус у K2 ERP. |- AC-15 Потрібно безпечно зберігати ключі або використовувати HSM/хмарний КЕП. |- Фіолетовий #f3e5f5 Окремий статус SIGN_ERROR і журнал підписання. Колір

я хочу бачити статус документа після відправки, 

event_type="DOCUMENT_STATUS_SYNCED",
* https://edin.ua/ Дія

def sync_edin_document_status(document_id: str, db: "Session") -> None:

20.2. Відправка документа

"document_date": "2026-05-07",
# Чи потрібно зберігати КЕП у системі? 1. Як зменшити

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

except TemporaryEdinError as exc:
pass
"currency": "UAH",
Документів за місяць 1840 інформаційні матеріали
Очікують підпису 43 Увага
Передано в EDIN 1290 В роботі
Прийнято 1218 Норма
Відхилено 12 Критично
Потребують повтору 18 Потрібна дія

Етап 1. Аналіз EDIN API

"content_type": "application/pdf", ) Метою задачі виступає як створення Python-сервісу для інтеграції з EDIN з метою передачі електронних документів, які використовуються у процесах податкового, бухгалтерського та юридично значущого документообігу. |} timeout_seconds: int = 30 Python Status Sync Worker audit_logger.log( 
"payload_format": "xml",
id uuid - конкурентні переваги - is_active boolean - EDIN Client - AC-14 - Зміна API Фоновий retry отримання квитанцій. Worker відправляє документ у EDIN. Тип документа }

31. Див. так само

Етап 6. Черга та статуси

"external_document_id": command.external_document_id,

</syntaxhighlight> Python-сервіс створює або передає структуровані документи через DocFlow API. SEO-опис 

verify_ssl: bool = True
застосовується для, якщо підключено DocFlow. HTML 
)

"attachments": [

13. API Python-сервісу

 style="background:#bbdefb;" | Блакитний
Доставлено DELIVERED Документ доставлений отримувачу або системі. # Чи потрібен UI для підписання? API EDIN / DocFlow / EDI Network 
document.status = "SEND_ERROR"
Перевести в NEEDS_CORRECTION. |- AC-3 Dashboard, проблемні документи. |} 
return existing
old_status = document.status
raise BusinessError("Document must be signed before sending")

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

Не потребує підпису SIGN_NOT_REQUIRED Сірий Документ не потребує КЕП. № 
old_status="SENDING",

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

document.error_message = str(exc)
EDIN - event_type varchar style="background:#fff9c4;" | Увага
Передано в EDIN Документи, які вже відправлені. Статус 
v
company_id: str 
except Exception as exc:
def create_document(self, payload: "EdinDocumentPayload") -> "EdinDocumentResponse":
"content_type": "application/xml",

class EdinClient: 

v
"document_type": "TAX_INVOICE",

25.4. Дедублікація та повтор

v

EDIN Client — це Python-клас або пакет, який інкапсулює роботу з EDIN API. | Черга підпису, календар задач. |-

document_number varchar Номер документа. №

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

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

document.accepted_at = datetime.now(timezone.utc)

Окремо варто відзначити який інтегрує K2 ERP або іншу облікову систему з платформою EDIN; так само реалізовано податкових накладних, первинних документів, супровідних файлів і документів, пов'язаних із податковою звітністю. |-

Довільний файл Середній Реалізується в межах цього ТЗ. EDIN_AUTH_URL=https://api.example.edin/auth
  • додати rate limiting;
  • додати моніторинг;
  • додати alerting;
  • додати dead letter queue;
  • додати резервне копіювання;
  • додати безпечне зберігання секретів. |-
 конкурентні переваги Робота зі статусами, компаніями, документами, структурованими даними. Параметр

POST /api/v1/edin/documents/{document_id}/retry

EDIN_COMPANY_ID=company-001 

def check_connection(self) -> "ConnectionStatus":

6. |-

Делеговане підписання Підписує відповідальна особа після отримання задачі. №

K2 ERP передає різні типи документів через різні API EDIN. # Які типи документів потрібно передавати в MVP? SEO-опис EDIN_API_PASSWORD=******** 

retry_count: int = 3
def send_document(self, edin_document_id: str) -> "SendDocumentResponse":

10. | Помилки валідації, retry.== 23. Безпека ==

}

Етап 5. Підписання

"file_id": "file-001"

16. Підписання КЕП

"payload": {
Тип задачі

EDIN_RETRY_BACKOFF_SECONDS=5

18. Черга передачі

19.1. edin_integrations

def cancel_document(self, edin_document_id: str, reason: str) -> "CancelDocumentResponse":

<syntaxhighlight lang="python">
Отримано з https://wiki.kyiv.ua/index.php?title=Технічне_завдання:_передача_документів_для_звітності_в_податкову_через_Edin_для_Python&oldid=987