Перегляд вихідного коду сторінки Medoc REST API

'''Medoc REST API''' — це інтерфейс інтеграції M.E.Doc з обліковими, ERP, CRM та іншими інформаційними системами. Він використовується для автоматизації роботи з електронними документами: створення, передавання в M.E.Doc, підписання, відправлення контрагентам або контролюючим органам, а також отримання статусів обробки.

M.E.Doc описує REST API як інструмент для інтеграції з ERP та обліковими системами, зокрема для роботи з первинними документами, регламентованою звітністю та електронним документообігом.<div style="background:#e8f4ff; border-left:5px solid #1e88e5; padding:12px; margin:12px 0;">
'''Важливо:''' Medoc REST API не замінює сам M.E.Doc. API використовується як інтеграційний шар між зовнішньою системою та M.E.Doc, а підписання, відправлення, обробка квитанцій і юридично значущий документообіг виконуються через інфраструктуру M.E.Doc.
</div>

== Загальний опис ==
Medoc REST API дозволяє зовнішній системі взаємодіяти з M.E.Doc без ручного дублювання документів. Наприклад, ERP-система може сформувати рахунок, акт, видаткову накладну, податкову накладну або інший документ, передати його в M.E.Doc через API, а потім отримати статус підписання, відправлення або обробки.

У відкритих матеріалах M.E.Doc REST API описується як схема роботи з документами у три основні кроки: створити документ, підписати та відправити, отримати стан обробки документа.<div style="background:#fff8e1; border-left:5px solid #f9a825; padding:12px; margin:12px 0;">
'''Зверніть увагу:''' для коректної роботи з методами M.E.Doc REST API зазвичай потрібна відповідна ліцензія на інтеграцію з обліковими системами, налаштований серверний контур M.E.Doc, доступи, сертифікати електронного підпису та правильна мережева конфігурація.
</div>

== Для чого потрібен Medoc REST API ==
Medoc REST API потрібен для автоматизації електронного документообігу між ERP-системою та M.E.Doc.

Основні задачі інтеграції:

* створення електронних документів у M.E.Doc з ERP;
* передавання первинних документів;
* передавання регламентованої звітності;
* передавання податкових накладних;
* передавання розрахунків коригування;
* підписання документів електронним підписом;
* відправлення документів контрагентам;
* відправлення документів до контролюючих органів;
* отримання статусів документів;
* отримання квитанцій;
* отримання інформації про помилки;
* зменшення ручного введення;
* синхронізація стану документів між ERP та M.E.Doc.

== Основні можливості ==
Medoc REST API може використовуватися для таких операцій:

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

<div style="background:#e8f5e9; border-left:5px solid #43a047; padding:12px; margin:12px 0;">
'''Практичне застосування:''' Medoc REST API корисний для компаній, які вже ведуть документи в ERP або обліковій системі й хочуть автоматично передавати їх у M.E.Doc для підписання, відправлення та контролю статусів.
</div>

== Типові документи для інтеграції ==
Через інтеграцію з M.E.Doc можуть передаватися різні типи документів:

* рахунки;
* акти виконаних робіт;
* видаткові накладні;
* товарно-транспортні накладні;
* договори;
* додаткові угоди;
* податкові накладні;
* розрахунки коригування;
* декларації;
* регламентована звітність;
* звітність з ПДВ;
* звітність з ЄСВ;
* інші документи електронного документообігу.

== Типова архітектура інтеграції ==
Типова архітектура інтеграції може включати:

* ERP або облікову систему;
* модуль інтеграції з M.E.Doc;
* Medoc REST API;
* сервер M.E.Doc;
* базу документів M.E.Doc;
* електронні підписи;
* канали обміну з контрагентами;
* канали обміну з ДПС або іншими контролюючими органами;
* журнал технічного обміну.

У такій схемі ERP є джерелом бізнес-даних, а M.E.Doc відповідає за юридично значущий електронний документообіг, підписання, відправлення та отримання квитанцій.<div style="background:#f3e5f5; border-left:5px solid #8e24aa; padding:12px; margin:12px 0;">
'''Інтеграційний акцент:''' ERP не повинна просто «скидати файл» у M.E.Doc. Бажано зберігати повний зв’язок між документом ERP і документом M.E.Doc: ідентифікатор, статус, дату відправлення, квитанції, помилки та історію змін.
</div>

== Типовий сценарій роботи ==
Типовий процес роботи через Medoc REST API може виглядати так:

# Користувач створює документ у ERP.
# ERP перевіряє реквізити документа.
# Модуль інтеграції формує структуру документа або XML.
# Документ передається в M.E.Doc через REST API.
# M.E.Doc створює документ у своїй базі.
# Документ підписується електронним підписом.
# Документ відправляється контрагенту або до контролюючого органу.
# M.E.Doc отримує статус або квитанцію.
# ERP через API запитує стан документа.
# Статус, квитанція або помилка зберігається в ERP.

== Авторизація і доступ ==
Для роботи з Medoc REST API потрібно налаштувати доступ до інтеграційного сервісу. Конкретний спосіб авторизації залежить від версії M.E.Doc, налаштувань серверної частини, ліцензії та документації API.

У типовому проєкті потрібно визначити:

* адресу API;
* порт доступу;
* користувача або технічний обліковий запис;
* права доступу;
* параметри безпеки;
* доступ до потрібних організацій;
* доступ до потрібних документів;
* доступ до підписання;
* доступ до відправлення;
* журнал дій інтеграційного користувача.

<div style="background:#fff3e0; border-left:5px solid #fb8c00; padding:12px; margin:12px 0;">
'''Рекомендація:''' для інтеграції краще використовувати окремий технічний обліковий запис із мінімально необхідними правами, а не обліковий запис бухгалтера або адміністратора.
</div>

== Створення документа ==
Створення документа через REST API зазвичай передбачає передавання даних з ERP до M.E.Doc.

ERP може передавати:

* тип документа;
* дату документа;
* номер документа;
* організацію;
* контрагента;
* реквізити сторін;
* табличну частину;
* суми;
* податкові ставки;
* валюту;
* коментар;
* пов’язані документи;
* XML-файл;
* вкладення або PDF за потреби.

Після створення документа M.E.Doc може повернути ідентифікатор, за яким ERP надалі відстежує стан документа.

== Підписання документа ==
Підписання документа виконується електронним підписом. Залежно від налаштувань M.E.Doc підписання може виконуватися користувачем вручну або в межах автоматизованого сценарію.

У бізнес-процесі важливо контролювати:

* хто має право підпису;
* яким сертифікатом підписується документ;
* чи дійсний сертифікат;
* чи потрібна печатка підприємства;
* чи потрібні декілька підписів;
* чи зберігається інформація про підписанта;
* чи повертається статус підписання в ERP.

<div style="background:#ffebee; border-left:5px solid #e53935; padding:12px; margin:12px 0;">
'''Не плутати:''' передавання документа в M.E.Doc і його підписання — це різні етапи. Документ може бути створений у M.E.Doc, але ще не підписаний і не відправлений.
</div>

== Відправлення документа ==
Після створення та підписання документ може бути відправлений контрагенту або контролюючому органу.

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

* первинних документів контрагенту;
* податкових накладних;
* розрахунків коригування;
* регламентованої звітності;
* інших документів, підтримуваних M.E.Doc.

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

== Отримання статусів ==
Один із ключових елементів інтеграції — отримання статусів документа з M.E.Doc.

Типові статуси можуть бути такими:

* створено;
* передано в M.E.Doc;
* очікує підпису;
* підписано;
* відправлено;
* доставлено;
* отримано контрагентом;
* підписано контрагентом;
* відхилено;
* прийнято контролюючим органом;
* не прийнято;
* очікує квитанцію;
* помилка відправлення;
* помилка підпису;
* помилка обробки.

<div style="background:#e0f2f1; border-left:5px solid #00897b; padding:12px; margin:12px 0;">
'''Для облікової системи:''' статуси з M.E.Doc потрібно повертати в ERP, щоб користувач бачив реальний стан документа без відкриття M.E.Doc вручну.
</div>

== Отримання квитанцій ==
Для звітності, податкових накладних і розрахунків коригування важливо отримувати квитанції.

В ERP бажано зберігати:

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

== Робота з довідниками ==
У новіших оновленнях M.E.Doc REST API додавалися методи для отримання довідників і редакцій документів. Це може бути корисно для синхронізації даних між ERP і M.E.Doc.

Через довідники можуть використовуватися:

* типи документів;
* статуси;
* контрагенти;
* організації;
* коди;
* службові класифікатори;
* шаблони або редакції документів.

== Інтеграція з K2 ERP ==
У системі K2 ERP Medoc REST API може використовуватися як інтеграційний модуль для електронного документообігу, звітності та податкових документів.

Типова реалізація може включати:

* налаштування підключення до M.E.Doc;
* вибір організації;
* зіставлення типів документів K2 ERP і M.E.Doc;
* формування XML або структури документа;
* передавання документа в M.E.Doc;
* запуск підписання;
* запуск відправлення;
* отримання статусів;
* отримання квитанцій;
* зберігання ідентифікатора документа M.E.Doc;
* журнал технічного обміну;
* обробку помилок;
* повторну відправку після виправлення.

<div style="background:#ede7f6; border-left:5px solid #5e35b1; padding:12px; margin:12px 0;">
'''Для K2 ERP:''' Medoc REST API бажано реалізовувати як окремий модуль інтеграції. Він має приймати документи з ERP, передавати їх у M.E.Doc, контролювати статуси, отримувати квитанції та повертати результат у картку документа.
</div>

== Типовий сценарій у K2 ERP ==
Типовий процес роботи K2 ERP з Medoc REST API може виглядати так:

# Користувач створює документ у K2 ERP.
# Документ проходить перевірку реквізитів.
# Користувач натискає «Передати в M.E.Doc».
# K2 ERP формує XML або інший потрібний формат.
# Модуль інтеграції викликає Medoc REST API.
# M.E.Doc створює документ.
# K2 ERP зберігає ідентифікатор документа M.E.Doc.
# Документ підписується і відправляється.
# K2 ERP періодично запитує статус документа.
# Після отримання квитанції статус оновлюється в K2 ERP.
# Квитанція або повідомлення зберігається у картці документа.

== Дані, які бажано зберігати в ERP ==
Для якісної інтеграції з M.E.Doc в ERP бажано зберігати:

* тип документа;
* номер документа;
* дату документа;
* контрагента;
* організацію;
* суму;
* валюту;
* статус документа в ERP;
* статус документа в M.E.Doc;
* ідентифікатор документа M.E.Doc;
* дату передавання;
* дату підписання;
* дату відправлення;
* дату отримання квитанції;
* файл XML;
* файл PDF за потреби;
* файл квитанції;
* текст помилки;
* користувача, який ініціював обмін;
* журнал API-запитів;
* кількість спроб передавання;
* зв’язок із первинним документом.

== Можливі помилки під час інтеграції ==
Під час роботи з Medoc REST API можуть виникати такі помилки:

* API недоступний;
* неправильна адреса або порт;
* відсутня ліцензія на інтеграцію;
* неправильні права користувача;
* документ має неправильний формат;
* відсутній обов’язковий реквізит;
* не знайдено організацію;
* не знайдено контрагента;
* документ уже існує;
* помилка підписання;
* сертифікат підпису прострочений;
* помилка відправлення;
* квитанція не отримана;
* статус не оновився;
* невідповідність типу документа;
* помилка мережі;
* помилка сервера M.E.Doc.

<div style="background:#fff3e0; border-left:5px solid #fb8c00; padding:12px; margin:12px 0;">
'''Рекомендація:''' інтеграційний модуль має зберігати повну технічну відповідь M.E.Doc, а не лише короткий статус. Це допомагає швидше знаходити причину помилки та підтримувати користувачів.
</div>

== Безпека інтеграції ==
Для безпечної роботи Medoc REST API потрібно контролювати:

* права інтеграційного користувача;
* доступ до API;
* мережеві обмеження;
* доступ до електронних підписів;
* строк дії сертифікатів;
* журнал дій;
* журнал API-запитів;
* шифрування з’єднання;
* резервне копіювання документів;
* доступ до квитанцій;
* зберігання технічних логів;
* блокування зайвих облікових записів.

== Переваги інтеграції ==
Інтеграція з Medoc REST API дає такі переваги:

* менше ручного введення;
* менше дублювання документів;
* швидше передавання документів у M.E.Doc;
* контроль статусів у ERP;
* зберігання квитанцій в обліковій системі;
* прозорий журнал обміну;
* швидше виправлення помилок;
* автоматизація документообігу;
* централізований контроль документів;
* зв’язок електронного документа з первинним документом ERP.

== Обмеження та ризики ==
Під час впровадження потрібно враховувати:

* потребу в ліцензії на інтеграцію;
* залежність від версії M.E.Doc;
* потребу в налаштуванні серверної частини;
* потребу в електронних підписах;
* потребу в якісній підготовці XML або структури документа;
* можливі зміни API після оновлень;
* потребу в тестовому середовищі;
* потребу в журналі обміну;
* потребу в підтримці користувачів;
* залежність від доступності M.E.Doc і каналів обміну.

<div style="background:#ffebee; border-left:5px solid #e53935; padding:12px; margin:12px 0;">
'''Не плутати:''' Medoc REST API — це інтерфейс для інтеграції, а не окремий сервіс електронної звітності. Без налаштованого M.E.Doc, ліцензії, доступів і сертифікатів інтеграція не працюватиме повноцінно.
</div>

== Висновок ==
Medoc REST API — це інструмент для інтеграції M.E.Doc з ERP, CRM та обліковими системами. Він дозволяє автоматизувати створення документів, передавання в M.E.Doc, підписання, відправлення, отримання статусів і квитанцій.

Для K2 ERP інтеграцію з Medoc REST API доцільно реалізовувати як окремий модуль, який пов’язує документи ERP із документами M.E.Doc, контролює обмін, зберігає технічні відповіді, статуси, квитанції та забезпечує прозорий документообіг між системами.

== Джерела ==

* [https://medoc.ua/page/integrationapi Medoc API — інтеграція з ERP]
* [https://medoc.ua/faq/opis-metodv-web-api Опис методів M.E.Doc Web API]
* [https://medoc.ua/files/uploads/b23038aa9d2ded4cc42f43945076ac0d.pdf Документація M.E.Doc REST API]
* [https://medoc.ua/ M.E.Doc]
* [https://sys2biz.com.ua/news/onovlennya-m-e-doc-versiya-11-02-177/ Оновлення M.E.Doc REST API]

== Див. також ==
[[ЕДО]]

[[ДПС]]

[[Розрахунок коригування]]

[[SAF-T UA]]

[[Е-ТТН]]

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

[[Технічне завдання: Передача звітності з K2 ERP до Електронного кабінету ДПС]]

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

[[Уніфіковане накладання електронного підпису різних сервісних центрів України]]