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

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

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

details={ 

retry_backoff_seconds: int = 5

} 

- pdf


Можливість саме подання податкової звітності до ДПС через ПТАХ потрібно підтвердити в офіційній API-документації або договорі з постачальником. Записати подію в журнал. ptah/

8.3. Передача документа в ПТАХ

- zip

Мінімальний набір вхідних даних: </syntaxhighlight> Python Tax Reporting Service 

event_type="SIGNED_IN_PTAH",
def download_signed_document(self, document_id: str) -> bytes:

! # Чи підтримує ПТАХ сценарій подання податкової звітності до ДПС? # Чи Python-сервіс має сам формувати XML, чи отримує готовий XML з ERP? SEO-опис 

status_sync_service.py

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

exceptions.py

11.8. Отримання журналу

щоб оперативно знаходити причину помилок інтеграції. Поле

PTAH_CLIENT_ID=******** 

"new_status": "WaitingForSignature",

я хочу отримати квитанції або результати обробки в ERP,

29. Джерела

15.1. Фонове оновлення версій

docker-compose.yml
Очікувана відповідь: PTAH_API_KEY=******** services/ "ptah_status": ptah_status.raw_status, 5. | Raw-статус зберігається, створюється подія UnknownStatus. | Повторити пізніше, повідомити адміністратора. |-
AC-9 - taxpayer_name varchar Назва платника. Компонент

PTAH_CLIENT_SECRET=********

  • створення Python API для прийому документів;
  • створення клієнта інтеграції з API.ПТАХ;
  • формування XML або прийом готового XML;
  • збереження документа;
  • перевірка обов'язкових реквізитів;
  • передача документа в ПТАХ;
  • запуск підписання / відправки через ПТАХ, якщо підтримується API;
  • отримання статусів;
  • отримання квитанцій або результатів обробки;
  • журнал подій;
  • retry-механізм;
  • захист API-ключів і службових доступів;
  • інтеграційні функції ERP з ERP. |-
 sent_to_receiver_at timestamp Зафіксувати помилку, повідомити адміністратора. | платформа не створює дубль без окремого підтвердження. Отримати ID документа в ПТАХ. |- ДПС - DeliveryError - КЕП Кваліфікований електронний підпис. Валідація та збереження документа

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

7.6. Технічний аудит

 - Зміна API - API.ПТАХ Інтеграційний API для роботи з документами. Синхронізація статусів 
entity_id=report.id,
Зупинити відправку, повідомити адміністратора. |- last_sync_at timestamp як приклад K2 ERP або інша платформа. allowed_formats: 
unit/

21.4. Статуси

</syntaxhighlight> 1. } 

app/

21.3. Підписання та відправка

"period": "2026-Q1",

def sign_and_send_report(report_id: UUID, db: "Session") -> "TaxReport": Для реалізації задачі необхідно отримати: def sync_pending_reports() -> None: 9. Підписання / відправка / обробка

2. |-
Передача в ПТАХ Endpoint, час, статус відповіді, зовнішній ID. SEO-опис

28. Definition of Done

"file_content_base64": "BASE64_XML_CONTENT",

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

"old_status": "SentToPtah",
Компонент 
"ptah_document_id": response.id,

=== 8.4. Підписання документа ===
== 10. Мапінг статусів ПТАХ ==
До MVP не входить:
</pre>
 payload = DocumentPayload(

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

! |-
| оновлення версій статусу
| Старий статус, новий статус, raw-статус ПТАХ. # Чи підтримуються webhook-и? | Статус документа змінюється на Signed. sync_statuses.py
PTAH_CLIENT_SECRET=********

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

 pass
! |-
| period
| string
| Так
| Звітний період. |-
| accepted
| Accepted
| Документ прийнято. |-
| report_id
| uuid
| ID документа. Записати подію в журнал. До MVP входить:

 f"Report {report_id} cannot be signed from status {report.status}"

 "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
 core/
=== 14.3. Приклад Python-логіки ===

<pre>

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

 tax_reports.py
== 14. Підписання та відправка через ПТАХ ==
 v
! |-
| Web framework
| FastAPI. |-
| Validation
| Pydantic. # Які endpoint-и використовуються для отримання статусів? Як адміністратор, 

 TaxReportStatus.CREATED_IN_PTAH,
GET /api/v1/tax-reports/{report_id}
PTAH_BASE_URL=https://api.ptah.example

я хочу бачити статус документа в ERP, 

 )

 try:
== 8. Функціональні вимоги ==
 "source_system": report.source_system,
== 2. Область сценарії використання ==
POST /api/v1/tax-reports/{report_id}/send-to-ptah
! |-
| Generated
| Файл документа сформовано. Коментар

* Accepted;
* Sent;
* WaitingForReceipt;
* SentToPtah;
* WaitingForSignature. |-
| AC-5
| API.ПТАХ повертає успішну відповідь. |-
| Webhook
| Механізм отримання подій від зовнішньої системи. | Опційно. |-
| created_at
| timestamp
| Дата події. |}

tax_report_repository.py

<pre>
 file_name=report.file_name,
|-
| AC-4
| Документ має статус ReadyToSend. |-
| Rejected
| Документ відхилено. Подія
 client_id: str | None = None
 "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
! |-
| file_name
| varchar
| Назва файлу. |-
| Receipt Loader
| Завантажує квитанції та результати обробки. |-
| updated_at
| timestamp
| Дата оновлення версій. |-
| Ручне підписання
| користувач системи підписує документ у веб-інтерфейсі або клієнті ПТАХ. # Які типи звітів підтримуються першими? |-
| FileStorageError
| Неможливо прочитати або записати файл. |-
| DB
| PostgreSQL. | Файл зберігається у файловому сховищі. |-
| Sending
| Документ передається в ПТАХ. |-
| content_type
| varchar
| MIME-тип. | Внутрішній статус документа змінюється. |-
| Помилки КЕП
| Можливі проблеми з ключами, паролями або сертифікатами. №
5. Підготувати метадані. document_types:
я хочу бачити журнал API-запитів і відповідей, 
 title: "Об'єднана формування звітів"

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

PTAH_COMPANY_CODE=12345678

 "message": "Document sent to Ptah"
</syntaxhighlight>
Retry застосовується для:
|-
| SentToPtah
| кожні 5 хвилин
|-
| CreatedInPtah
| кожні 5 хвилин
|-
| WaitingForSignature
| кожні 15 хвилин
|-
| Sent
| кожні 10 хвилин
|-
| SentToTax
| кожні 10 хвилин
|-
| WaitingForReceipt
| кожні 10 хвилин
|-
| ReceiptReceived
| кожні 30 хвилин або не перевіряти
|-
| Accepted / Rejected
| не перевіряти
|}

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

 if not report.ptah_document_id:
=== 7.3. Отримання статусу ===
{| class="wikitable"

 requires_signature: true
 entity_id=report.id,
! |-
| Failed
| Технічна помилка. Поле
POST /api/v1/tax-reports

 pass
! |-
| status
| varchar
| Внутрішній статус.=== 21.5. Квитанції та файли ===

Перед передачею платформа повинна перевірити:

 send_response = ptah_client.send_document(report.ptah_document_id)

{

 report.status = TaxReportStatus.SIGNED
<pre>
 raise InvalidStatusError("Report is not created in Ptah")
tax_reporting_ptah_service/
 main.py
|-
| taxpayer_id
| string
| Так
| РНОКПП або ЄДРПОУ платника. Перевірити, що документ не був відправлений раніше. |-
| source_system
| varchar
| ERP або інша система-джерело. 4. |-
| Audit Logger
| Фіксує всі дії користувачів і системи. |-
| Неповна або закрита API-документація
| Частина методів здатна бути доступна лише за договором або в окремому тарифі. # Хто має доступ до API key? # Які endpoint-и використовуються для створення документа? |-
| report_type
| string
| Так
| Тип звіту або документа. SEO-опис
DATABASE_URL=postgresql+psycopg://user:password@db:5432/reports
from pydantic_settings import BaseSettings
|-
| Python
| 3.11 або вище. "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
== 1. Мета ==
 def cancel_document(self, document_id: str, reason: str) -> "PtahDocumentResponse":

щоб не виконувати ці дії вручну, якщо це підтримується API. |-

SentToPtah Документ успішно передано в ПТАХ. № 
}
details={"error": str(exc)},
- file_content_base64 string Так - file_format varchar XML, PDF, ZIP тощо. Отримати файл зі сховища. "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",

19.1. Змінні середовища

Приклад тіла запиту: 

report.sent_to_receiver_at = datetime.now(timezone.utc)
sign_response = ptah_client.sign_document(report.ptah_document_id)
event_type="SENT_TO_PTAH",
"raw_status": response.status,
signing_service.py
- file_format string Так XML, PDF, ZIP або інший підтримуваний формат. Квитанції / статуси

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

Інкапсулювати API в окремому PtahClient. |} 

</syntaxhighlight>
PTAH_BASE_URL=https://api.ptah.example

v
AC-12 Worker запускає синхронізацію.== 24. Ризики == }

16.3. tax_report_files

PTAH_COMPANY_CODE=12345678

  • timeout;
  • тимчасової недоступності API.ПТАХ;
  • HTTP 429;
  • HTTP 500;
  • HTTP 502;
  • HTTP 503;
  • HTTP 504;
  • тимчасових мережевих помилок. # Чи виступає як тестове середовище? # Перевірити статус документа. Призначення
return report
  • прийом даних звітності з ERP / облікової системи;
  • формування або прийом готового XML-документа;
  • перевірку документа перед передачею;
  • передачу документа в ПТАХ;
  • запуск підписання документа, якщо це підтримується API;
  • запуск відправки документа, якщо це підтримується API;
  • отримання зовнішнього ID документа;
  • синхронізацію статусів;
  • отримання квитанцій або результатів обробки;
  • збереження історії передачі;
  • обробку помилок;
  • повторну відправку;
  • журналювання всіх технічних і бізнес-подій. |-
 new_status varchar базовий режим, якщо підтримується API. | Використовувати retry та чергу задач. |- size_bytes integer Розмір файлу. SEO-опис

Технічний стек: Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Docker. | Отримати офіційну API-документацію та підтвердження від постачальника.== 19. конфігурація == 

pass
number=report.document_number,

 raise InvalidStatusError(
 "taxpayer_name": report.taxpayer_name,
=== 12.1. Призначення ===
3. |-
| Validation Layer
| Перевіряє реквізити, структуру та статус документа. |-
| Tests
| pytest. Перевірити, що документ має статус ReadyToSend.</pre>
! |-
| report_type
| varchar
| Тип звіту. "errors": []

* webhook-інтеграція;
* інтеграційні функції ERP напряму з ДПС;
* власний компонент КЕП;
* складний UI;
* автоматичне оновлення версій XSD;
* технічна підтримка всіх типів звітності;
* автоматичне створення декларацій з бухгалтерських даних. |-
| AC-7
| Документ вже був переданий. Запустити очікування квитанцій. | Потрібна офіційна API-документація та доступ.</pre>
 db.commit()
=== Етап 8. Production hardening ===
{| class="wikitable"
 requires_receipt: true
Очікувана відповідь:
 )
! # Записати подію в журнал. }

 report.ptah_document_id = response.id
<syntaxhighlight lang="json">
 security.py
{| class="wikitable"
|-
| Непідтверджений сценарій подання звітності до ДПС
| Публічно API.ПТАХ описаний як API для ЕДО, але сценарій податкової звітності потрібно підтвердити. оновлення версій статусу в ERP
<syntaxhighlight lang="json">
== 3. Джерела інтеграції ==
=== 8.7. Отримання квитанцій ===

! # Оновити статус документа. * помилок валідації;
* неправильного API key;
* відсутності прав доступу;
* відхилення документа отримувачем;
* дублювання документа;
* некоректного формату файлу;
* помилки КЕП через неправильний пароль. # Де виконується КЕП: у Python-сервісі, у ПТАХ або користувачем у веб-інтерфейсі? |-
| Logging
| structlog або стандартний logging у JSON-форматі. |-
| Підписання в Python-сервісі
| Python-сервіс підписує документ до передачі в ПТАХ. |-
| document_number
| varchar
| Номер документа. |-
| Status Sync Worker
| Фоновий бізнес-процес для оновлення версій статусів. | платформа дає можливість ініціювати підписання, якщо це підтримується API. | Зберегти raw-статус, створити подію UnknownStatus. |-
| file_name
| varchar
| Назва файлу. |-
| period
| varchar
| Звітний період. |-
| ValidationError
| Некоректні інформаційні дані документа. |-
| Ptah Client
| Python-клієнт для роботи з API.ПТАХ. ! Поле
=== 15.2. Приклад worker-а ===

щоб не створювати документ заново. )

* реалізувати завантаження квитанцій;
* реалізувати збереження PDF/XML/receipt-файлів;
* реалізувати прив'язку файлів до документа;
* реалізувати перегляд історії. {

 pass

 vat_declaration:
== 27. Технічні вимоги до Python ==
=== 11.2. Перевірка документа ===
=== 12.2. Основні методи ===
|-
| Polling
| Періодичне опитування API.ПТАХ. |-
| document_number
| string
| Так
| Номер документа. SEO-опис
 report = tax_report_repository.get_by_id(db, report_id)
!=== 11.3. Передача в ПТАХ ===
 new_status = status_mapper.map_ptah_status(ptah_status)
Тип

ПТАХ

- StatusMappingError - ДПС } 
requires_signature: true

integration/
  • Python-сервіс розгортається через Docker;
  • API створення документа функціонує;
  • документ зберігається у БД та файловому сховищі;
  • документ проходить валідацію;
  • документ передається в ПТАХ;
  • зовнішній ID документа зберігається;
  • статус документа оновлюється;
  • помилки API обробляються;
  • retry-механізм функціонує;
  • журнал подій заповнюється;
  • написані unit-тести для ключових сервісів;
  • написані інтеграційні тести для PtahClient з mock API;
  • документація для запуску додана в README;
  • фінальні endpoint-и ПТАХ винесені в конфігурацію;
  • отримано підтвердження сценарію подання звітності до ДПС через ПТАХ або зафіксовано альтернативний сценарій. |-
 Storage Layer Зберігає документи, квитанції, статуси та логи. Записати подію в журнал. інформаційні дані для звітності або готовий XML 
event_repository.py

STATUS_SYNC_INTERVAL_SECONDS=300

2. SEO-опис 
base_url: str

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

audit_logger.log(
"created_by": "user@example.com"
pass
title=report.title,
pass

Етап 3. Ptah Integration Client

pass
)
Draft - receipt_received ReceiptReceived } 
}:

v
  • квитанцію про отримання;
  • квитанцію про прийняття;
  • квитанцію про відхилення;
  • підписаний документ;
  • PDF-візуалізацію, якщо доступна;
  • технічний протокол обробки, якщо доступний;
  • raw-відповідь ПТАХ. Передача документа через API.ПТАХ

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

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

У документі зберігається ptah_document_id. |- Дублювання документів - Скасування документа - metadata object Ні - Accepted - document_date date Так Дата документа. ERP / Accounting System 
tax_request:

2. |-

Помилка API - HTTP client Заборонити повтор без підтвердження. Отримати результат підписання. Як бухгалтер,
  • реалізувати endpoint send-to-ptah;
  • зберігати ptah_document_id;
  • оновлювати статуси;
  • логувати API-взаємодію. |-
 DuplicateDocumentError - Завантаження квитанції - ReceiptReceived - AC-17 - AC-3 Передано некоректні інформаційні дані. Режим 
tests/
raise InvalidStatusError(

ERP / Accounting System 

v

from datetime import datetime, timezone

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

 "source_system": "K2 ERP", 
single_tax_declaration:

щоб скоротити час підготовки та подання документів. |-

waiting_signature WaitingForSignature - SentToTax } 

<div style="border-left: 6px solid #2e7d32; background: #e8f5e9; padding: 12px 16px; margin: 16px 0;">

* REST API для створення документа;
* збереження документа;
* базова валідація;
* Ptah Integration Client;
* передача документа в ПТАХ;
* збереження зовнішнього ID;
* ручний запуск синхронізації статусу;
* журнал подій;
* базова обробка помилок. | Виконати retry. | Відображати зрозумілу помилку та дозволяти повторне підписання. Статус ПТАХ
! платформа повинна підтримувати один із режимів:

=== 11.6. оновлення версій статусу ===

 validation_service.py
POST /api/v1/tax-reports/{report_id}/send
 def download_receipts(self, document_id: str) -> list [bytes]:

 TaxReportStatus.WAITING_FOR_SIGNATURE,

 f"Report {report_id} cannot be sent from status {report.status}"
4. ! Очікуваний результат

=== 8.5. Відправка документа ===
2. | Основна платформа для передачі документів. Інтервал перевірки

=== 17.2. Retry-логіка ===
 - xml
! # Чи потрібно робити UI, чи тільки backend API? |}

<syntaxhighlight lang="json">

Python Tax Reporting Service
{| class="wikitable"
 "ptah_document_id": "external-document-id",
=== Етап 1. Базова структура Python-сервісу ===
|-
| AC-8
| Документ створено в ПТАХ. |-
| Підписання
| Результат, дата, raw-відповідь ПТАХ. # Який базовий URL API? |-
| PtahTimeoutError
| Перевищено час очікування. |}

 - xml

PTAH_API_KEY=********
 requires_receipt: true
 def sign_document(self, document_id: str) -> "PtahDocumentResponse":
</syntaxhighlight>
|-
| AC-15
| Документ прийнято. Поле

 )
<syntaxhighlight lang="python">
 )
 if new_status != report.status:

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

<pre>
<pre>
 download_receipts.py
 v
Повторна відправка дозволена тільки для документів у статусах:
POST /api/v1/tax-reports/{report_id}/resend
== Див. 30. так само ==
GET /api/v1/tax-reports/{report_id}/events
=== 6.2. Основні компоненти Python-сервісу ===
 def download_original(self, document_id: str) -> bytes:
[[Категорія:Податкова звітність]]
я хочу передати документ звітності в ПТАХ без ручного імпорту, 
 "status": "ReadyToSend",
 },
== 7. User Story ==

 "old_status": old_status,

 api_key: str | None = None
! # Які endpoint-и використовуються для отримання квитанцій? |-
| created_at
| timestamp
| Дата створення. |-
| old_status
| varchar
| Попередній статус. # Чи потрібна технічна підтримка ФОП, юридичних осіб або обох варіантів? # Отримати зовнішній ID документа в ПТАХ. | платформа дає можливість передачу в ПТАХ. |-
| ПТАХ
| Платформа електронного документообігу. # Який формат документа підтримується: XML, PDF, ZIP, JSON? )

* реалізувати background worker;
* реалізувати періодичне оновлення версій статусів;
* реалізувати мапінг статусів;
* реалізувати обробку невідомих статусів. POST /api/v1/tax-reports/{report_id}/send-to-ptah

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

 file_content=file_bytes,
 except Exception as exc:
 unified_report:

</syntaxhighlight>

</div>

 "period": report.period,

<pre>

STATUS_SYNC_ENABLED=true
! | платформа зберігає помилку та не втрачає документ. До першої версії не входить:

* реалізувати створення документа;
* реалізувати збереження файлу;
* реалізувати валідацію;
* реалізувати статуси;
* реалізувати журнал подій.
 details={"raw_status": sign_response.status},
 "status": "Sent",
'''Головна ідея:''' розробити Python-сервіс, який формує, перевіряє, передає та контролює документи звітності через інтеграцію з платформою ПТАХ / API.ПТАХ.<syntaxhighlight lang="json">

* реалізувати авторизацію;
* реалізувати upload_tax_report;
* реалізувати create_document;
* реалізувати get_document_status;
* реалізувати download_document;
* реалізувати download_receipts;
* реалізувати обробку помилок;
* реалізувати retry. Оновити статус на SentToPtah. |-
| Polling
| Періодичне опитування зовнішнього API. |}

=== 14.1. Логічний бізнес-процес підписання ===

! Реальні коди статусів потрібно взяти з API-документації ПТАХ. |-
| signed
| Signed
| Документ підписано. Критерій

</div>
=== 8.2. Валідація документа ===
 models.py

7. tax_report_repository.update_status(

__TOC__
class PtahClient:
=== 11.9. Завантаження квитанцій ===
 "file_format": "xml",
|-
| ПТАХ
| Платформа електронного документообігу та обміну юридично значущими документами. report.status = TaxReportStatus.SENT
 tax_report_service.py
<syntaxhighlight lang="json">
 retry_count: int = 3
! SEO-опис
{| class="wikitable"
 if report.status != TaxReportStatus.READY_TO_SEND:

це Python-клас або пакет, який інкапсулює роботу з API виступає ключовою рисою Ptah Integration Client.ПТАХ. | У системі створюється запис tax_reports. "status": "SentToPtah",

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

! PTAH_RETRY_BACKOFF_SECONDS=5

 - xml

* створити FastAPI-проєкт;
* налаштувати PostgreSQL;
* створити моделі tax_reports, tax_report_events, tax_report_files;
* реалізувати конфігурацію через environment variables;
* реалізувати healthcheck endpoint. | Статус документа змінюється на Sent. # Отримати файл зі сховища. |-
| rejected_at
| timestamp
| Дата відхилення. |-
| AC-13
| ПТАХ повертає новий статус. До області задачі входить:

* додати Dockerfile;
* додати docker-compose;
* додати structured logging;
* додати metrics;
* додати alerting;
* додати rate limiting;
* додати security review. |-
| API
| Програмний інтерфейс інтеграції. |}

class PtahSettings(BaseSettings):

 file_format=report.file_format,

Попередній логічний мапінг:
 "message": "Document signed via Ptah"
 |
 | 1. Очікуваний результат
 "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff",
Очікувана відповідь:
PTAH_TIMEOUT_SECONDS=30
 report.status = TaxReportStatus.SENT_TO_PTAH
 "report_type": "single_tax_declaration",
{
 receipt_service.py
 ptah_status = ptah_client.get_document_status(
{| class="wikitable"
=== Етап 7. Квитанції та результати обробки ===
{| class="wikitable"
PTAH_RETRY_COUNT=3
=== 7.2. Підписання та відправка ===
 allowed_formats:
 audit_logger.log(
 event_type="STATUS_SYNC_FAILED",
4. |-
| Помилки авторизації
| Доступ до API здатна бути неправильним або простроченим. Дія системи
{| class="wikitable"
платформа повинна підтримувати два способи оновлення версій статусів:

== 12. Ptah Integration Client ==
<syntaxhighlight lang="python">

 details={
}

{
== 13. Передача документа в ПТАХ ==

 README.md
 event_type="STATUS_CHANGED",

! Оновити статус на Signed або Failed. електронного документообігу: створення забезпечується через '''критично:''' API.ПТАХ публічно описується як API; так само реалізовано підписання, відправка та отримання документів. |-
| PtahApiError
| API повернув помилку. return report
POST /api/v1/tax-reports/{report_id}/download-receipts

[[Категорія:Інтеграції]]

 v

=== 7.4. Отримання квитанцій ===
 repositories/
Очікувана дія:
|-
| Створення документа
| ID, користувач системи, дата, тип документа. №
! |-
| ValidationError
| Документ не пройшов перевірку. "message": "Document created"

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

 )

{| class="wikitable"
Ptah Integration Adapter
 "status": "Generated",

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

ПТАХ
== 5. Терміни та скорочення ==
! # Записати подію в журнал. |-
| WaitingForSignature
| Документ очікує підписання.=== 7.1. Передача документа в ПТАХ ===

* реалізувати sign endpoint;
* реалізувати send endpoint;
* обробити помилки КЕП;
* обробити помилки відправки;
* фіксувати всі етапи в журналі. |-
| rejected
| Rejected
| Документ відхилено. |-
| SignatureError
| Помилка підписання документа. |-
| AC-11
| Відправка виконана успішно. |-
| report_id
| uuid
| ID документа. Оновити статус на Sent або Failed. |-
| XML
| Формат електронного документа звітності. |-
| sent_at
| timestamp
| Дата передачі в ПТАХ. |
 | 5. Викликати PtahClient.upload_tax_report(). |-
| CreatedInPtah
| Документ створено в ПТАХ. # Які endpoint-и використовуються для відправки? |-
| ptah_raw_status
| varchar
| Останній raw-статус ПТАХ. |-
| AC-10
| Документ підписано. | платформа завантажує квитанцію або результат обробки. |-
| Sent
| Документ відправлено отримувачу. Термін
=== 11.1. Створення документа ===


 metadata={
! | Опційно. |-
| Повторна відправка
| Причина, користувач системи, дата. Внутрішній статус
 allowed_formats:

=== 11.7. Отримання документа ===

 "taxpayer_id": report.taxpayer_id,
 title: "Декларація з ПДВ"


 integrations/
 client.py

status_mapper.py

Retry не застосовується для: 

old_status = report.status
file_storage.py

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

for report in reports:
date=report.document_date,

</syntaxhighlight> </syntaxhighlight> POST /api/v1/tax-reports/{report_id}/sign

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

def send_document(self, document_id: str) -> "PtahDocumentResponse":
verify_ssl: bool = True
- error_message text - Signed - Невідомі статуси - uploaded SentToPtah - API.ПТАХ - created_by varchar Статуси документів оновлюються автоматизовано. |- XSD - Квитанція - AC-16 Документ відхилено. SEO-опис 
audit_logger.log(

Заборонено: зберігати API key, client secret, токени або паролі КЕП у коді, Git-репозиторії чи відкритих логах. |-

Валідація - created_at timestamp Дата створення. Dockerfile

3. |-

ERP / облікова платформа - Недоступність ПТАХ Платформа або мережа можуть бути тимчасово недоступні. SEO-опис

}

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

PTAH_RETRY_COUNT=3

API Layer REST API для прийому документів від ERP. 
"ptah_status": "waiting_signature"
Додати healthcheck інтеграції та повідомлення адміністратору. |- Python-сервіс - AC-2 Передано файл документа. Компонент 
audit_logger.log(
  • зберігання API key тільки у змінних середовища або secret storage;
  • заборону логування API key;
  • заборону зберігання паролів КЕП у відкритому вигляді;
  • маскування персональних даних у технічних логах;
  • контроль доступу до документів;
  • контроль доступу до квитанцій;
  • журналювання всіх операцій;
  • HTTPS для API-запитів;
  • перевірку SSL-сертифіката;
  • обмеження доступу до адміністративних endpoint-ів;
  • резервне копіювання документів і квитанцій. v

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

accepted_at timestamp Дата прийняття.

# Отримати документ із локальної БД. |-
| Webhook
| Отримання подій від ПТАХ, якщо підтримується. |-
| WaitingForReceipt
| Очікується квитанція або результат обробки. | Зберегти помилку, дозволити повторне підписання. Статус документа
{

{| class="wikitable"
[[Категорія:Технічні завдання]]
 "message": "Document sent via Ptah"

== 21. Acceptance Criteria ==

{| class="wikitable"

Як користувач системи, 
 file_bytes = file_storage.read(report.file_path)
6. Тип
=== 11.4. Підписання документа ===

<syntaxhighlight lang="python">
 title: "Декларація платника єдиного податку"

Якщо API.ПТАХ підтримує відповідний метод, Python-сервіс повинен ініціювати відправку документа отримувачу. Очікуваний результат
ДПС або інший отримувач
 report_id=report.id,
=== 16.2. tax_report_events ===
 def create_document(self, document: "DocumentPayload") -> "PtahDocumentResponse":

}
 )
! |-
| Cancelled
| Документ скасовано. Критерій
APP_ENV=production

=== 8.1. Створення документа ===
def send_report_to_ptah(report_id: UUID, db: "Session") -> "TaxReport":
 logging.py
! Що зберігати
<div style="border-left: 6px solid #1565c0; background: #e3f2fd; padding: 12px 16px; margin: 16px 0;">
Логічний endpoint Python-сервісу:
'''Уточнення:''' значення статусів виступає як попередніми. №
 pyproject.toml

 storage/

{| class="wikitable"
6. SEO-опис
! |-
| ORM
| SQLAlchemy. # Оновити статус на Sent. | Маскувати логи та обмежити доступ. |}

<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">

{{DISPLAYTITLE:Технічне завдання: Передача документів для звітності в податкову через ПТАХ для Python}}

! |-
| document_date
| date
| Дата документа. company_code: str | None = None
! Ризик

 health.py

 audit_logger.log(
! Пріоритет
== 25. Відкриті питання ==
 routes/
=== Етап 2. Робота з документами ===
[[Категорія:K2 ERP]]

3. |-
| PtahUnavailableError
| Платформа ПТАХ недоступна. | Отримати офіційну документацію та тестовий доступ. |}

 file_repository.py

 details={"raw_status": send_response.status},

 "taxpayer_id": "1234567890",

</div>
 def upload_tax_report(self, document: "DocumentPayload") -> "PtahDocumentResponse":
! # Перевірити, що документ підписано або готовий до підписання. |-
| AC-6
| API.ПТАХ повертає помилку. |-
| sent
| Sent
| Документ відправлено.== 20. Логування та аудит ==

{| class="wikitable"

! |}

 requires_receipt: true

=== Етап 6. Синхронізація статусів ===
 client_secret: str | None = None

title: "Запит до податкової"
id uuid Сценарій передачі через ПТАХ потрібно підтвердити окремо. Очікуваний результат 
def get_document_status(self, document_id: str) -> "PtahStatusResponse":

Як користувач системи ERP, Приклад змінних середовища:

id uuid }

</syntaxhighlight>

№

Очікувана відповідь: 1. Перевірити, що документ створено в ПТАХ. |}

Спосіб
Підписання в ПТАХ - AC-14 class="wikitable"

} PTAH_RETRY_BACKOFF_SECONDS=5

Критерій

PTAH_TIMEOUT_SECONDS=30

created CreatedInPtah Документ створено в ПТАХ. 
"new_status": new_status,

</syntaxhighlight> 

api/

{

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

id uuid Внутрішній ID документа. Внутрішній статус

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

платформа повинна логувати:

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

Логічний endpoint Python-сервісу: функції ERP застосовують, коли потрібно для автоматизації передачі документів звітності з ERP або облікової системи до ПТАХ. |-

Background jobs Резервний режим. "metadata": { 
pass
  • ValidationError;
  • Failed;
  • Rejected;
  • DeliveryError;
  • NeedResend. # Який SLA по оновленню статусів? |-
 title varchar - event_type varchar Тип події. SEO-опис 
db/

щоб мати підтвердження результату передачі документа. Критерій 

entity_id=report.id,
  • наявність обов'язкових полів;
  • коректність РНОКПП або ЄДРПОУ;
  • коректність звітного періоду;
  • наявність файлу;
  • допустимий формат файлу;
  • розмір файлу;
  • коректність імені файлу;
  • відповідність XML-структурі;
  • відповідність XSD, якщо схема доступна;
  • відсутність дубля документа;
  • наявність налаштувань інтеграції з ПТАХ. | Не відправляти документ, показати список помилок. |-
 payload jsonb - sent_to_tax_at timestamp платформа дає можливість відправку документа. Обов'язковість 
migrations/

Фінальний мапінг статусів потрібно побудувати після отримання офіційного довідника статусів API.ПТАХ. Викликати метод підписання ПТАХ, якщо він доступний. Як зменшити 

session.py

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

PTAH_CLIENT_ID=******** 

"document_number": "DECL-2026-0001",

Python-сервіс повинен мати метод для передачі документа в ПТАХ. Зберегти ID у локальній БД. Критерій

платформа зберігає причину відхилення. |- Containers - taxpayer_name string Так Назва компанії або ПІБ ФОП. Тип 
{| class="wikitable"
</div>
Python-сервіс повинен приймати документ від ERP. | Обов'язково для MVP.== 22. MVP ==

TaxReportStatus.SENT_TO_PTAH,

</syntaxhighlight>

19.2. Конфігурація типів документів

я хочу ініціювати підписання та відправку документа через ПТАХ,

Він бачить всі пов'язані файли та статуси. raw_status=ptah_status.raw_status,

<syntaxhighlight lang="python"> 

<pre>
|-
| Python-сервіс
| Окремий backend-сервіс або компонент, який виконує інтеграцію з ПТАХ.

1. |}

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

if report.status not in {

POST /api/v1/tax-reports/{report_id}/validate

Як бухгалтер, SEO title: Технічне завдання: Передача документів для звітності в податкову через ПТАХ для Python

SEO keywords: Python, ПТАХ, API.ПТАХ, електронна звітність, податкова звітність, ДПС, API, XML, КЕП, електронний документообіг, технічне завдання 

</noinclude>
 {{SEO
Шаблон для службового SEO-опису сторінки.

}}


14.2. Логічний бізнес-процес відправки

from uuid import UUID

  1. Перевірити, що документ створено в ПТАХ. # Які endpoint-и використовуються для підписання? |-
 waiting_receipt WaitingForReceipt - PtahAuthError - Персональні інформаційні дані - file_path varchar платформа повертає список помилок валідації. | Реалізується в межах цього ТЗ.=== 8.6. Отримання статусів === 
"taxpayer_name": "ФОП Іваненко Іван Іванович",
requires_signature: true }, requires_signature: true

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

<syntaxhighlight lang="json">
Задача вважається завершеною, якщо:

 - zip

 allowed_formats:

 event_type="SENT_VIA_PTAH",

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

 },



 db.commit()
 workers/
платформа повинна мати background worker, який періодично оновлює статуси документів. |}


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

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

* доступ до платформи ПТАХ;
* активований доступ до API.ПТАХ;
* базовий URL API;
* спосіб авторизації;
* API key / token / client credentials;
* технічну документацію endpoint-ів;
* перелік доступних типів документів;
* підтвердження функції ERP передачі звітності до ДПС через ПТАХ;
* формат передачі файлів;
* формат метаданих документа;
* правила створення документа в ПТАХ;
* правила підписання документа;
* правила відправки документа;
* правила отримання статусів;
* правила отримання квитанцій;
* тестове середовище, якщо доступне;
* технічний контакт з боку постачальника ПТАХ. |-
error Failed Помилка обробки. Рекомендація schemas.py report.ptah_document_id

18. Безпека

AC-1 ERP передає інформаційні дані документа у Python-сервіс. Очікуваний результат "id": "9ddaa913-03a3-4e11-a90a-582adf8a05ff", 
 requires_receipt: true
{ class="wikitable" response = ptah_client.upload_tax_report(payload) - pdf
"document_date": "2026-04-15",
- Document Builder Формує XML або приймає готовий файл.=== 13.1. Логічний бізнес-процес === * повна заміна інтерфейсу ПТАХ; * власна реалізація подання напряму до API ДПС; * власна реалізація КЕП, якщо підписання виконується на стороні ПТАХ; * автоматичне оновлення версій всіх XSD-схем; * повноцінний UI для бухгалтера; * автоматична бухгалтерська перевірка сум; * технічна підтримка всіх типів податкової, статистичної та фінансової звітності. |- ptah_document_id varchar ID документа у ПТАХ. Тип entity_id=report.id, "report_type": report.report_type,

21.2. Передача в ПТАХ

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

5. Отримати документ з БД. Пріоритет FILE_STORAGE_PATH=/data/tax-reports exceptions.py <syntaxhighlight lang="json"> RECEIPT_DOWNLOAD_ENABLED=true pass pass entity_id=report.id, timeout_seconds: int = 30 POST /api/v1/tax-reports/{report_id}/sync-status report = tax_report_repository.get_by_id(db, report_id) new_status=new_status, - xml "status": "Signed",

16.1. tax_reports

config.py 		} reports = tax_report_repository.get_reports_for_sync() # Який саме ERP-продукт застосовується для: ПТАХ, API.ПТАХ або інтеграційні функції ERP через інший ERP-продукт Linkos Group? | Перевіряти ptah_document_id перед відправкою. | Зберігати raw-статус та мати UnknownStatus. |- Відправка - Migrations Alembic.== 17. Обробка помилок == - taxpayer_id varchar - file_type varchar - ReadyToSend - sent_to_tax SentToTax }

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

report.sent_at = datetime.now(timezone.utc) 		Записати відповідь API, дозволити повтор. |- file_path varchar } ) 8. SEO-опис
Отримано з https://wiki.kyiv.ua/index.php?title=Технічне_завдання:_передача_документів_для_звітності_в_податкову_через_Птах_для_Python&oldid=977