Medoc REST API

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

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

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

Загальний опис

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

У відкритих матеріалах M.E.Doc REST API описується як схема роботи з документами у три основні кроки: створити документ, підписати та відправити, отримати стан обробки документа.

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

Для чого потрібен Medoc REST API

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

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

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

Основні можливості

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

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

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

Типові документи для інтеграції

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

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

Типова архітектура інтеграції

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

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

У такій схемі ERP є джерелом бізнес-даних, а M.E.Doc відповідає за юридично значущий електронний документообіг, підписання, відправлення та отримання квитанцій.

Інтеграційний акцент: ERP не повинна просто «скидати файл» у M.E.Doc. Бажано зберігати повний зв’язок між документом ERP і документом M.E.Doc: ідентифікатор, статус, дату відправлення, квитанції, помилки та історію змін.

Типовий сценарій роботи

Типовий процес роботи через 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;
порт доступу;
користувача або технічний обліковий запис;
права доступу;
параметри безпеки;
доступ до потрібних організацій;
доступ до потрібних документів;
доступ до підписання;
доступ до відправлення;
журнал дій інтеграційного користувача.

Рекомендація: для інтеграції краще використовувати окремий технічний обліковий запис із мінімально необхідними правами, а не обліковий запис бухгалтера або адміністратора.

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

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

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

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

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

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

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

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

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

Не плутати: передавання документа в M.E.Doc і його підписання — це різні етапи. Документ може бути створений у M.E.Doc, але ще не підписаний і не відправлений.

Відправлення документа

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

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

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

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

Отримання статусів

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

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

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

Для облікової системи: статуси з M.E.Doc потрібно повертати в ERP, щоб користувач бачив реальний стан документа без відкриття M.E.Doc вручну.

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

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

В 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;
журнал технічного обміну;
обробку помилок;
повторну відправку після виправлення.

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

Типовий сценарій у 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.

Рекомендація: інтеграційний модуль має зберігати повну технічну відповідь M.E.Doc, а не лише короткий статус. Це допомагає швидше знаходити причину помилки та підтримувати користувачів.

Безпека інтеграції

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

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

Переваги інтеграції

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

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

Обмеження та ризики

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

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

Не плутати: Medoc REST API — це інтерфейс для інтеграції, а не окремий сервіс електронної звітності. Без налаштованого M.E.Doc, ліцензії, доступів і сертифікатів інтеграція не працюватиме повноцінно.

Висновок

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

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

Джерела

Див. також

ЕДО

ДПС

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

SAF-T UA

Е-ТТН

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

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

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

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