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

API K2 ERP

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

PATCH /api/v1/orders/{id}/status Приклади: K2 ERP має змогу надсилати webhooks у зовнішні системи.; * order.created;

  • order.updated;
  • order.cancelled;
  • payment.paid;
  • payment.refunded;
  • product.updated;
  • inventory.changed;
  • fiscal.receipt.created;
  • fiscal.receipt.failed;
  • shipment.created;
  • shipment.delivered;
  • edo.document.signed;
  • edo.document.rejected.;== Sandbox ==

Під час роботи з API K2 ERP можуть виникати такі помилки: GET /api/v1/orders/by-external-id/{externalId} 

price
  • отримати список товарів;
  • отримати товар за ID;
  • отримати товар за SKU;
  • створити товар;
  • оновити товар;
  • отримати характеристики;
  • отримати фото;
  • отримати статус публікації;
  • отримати категорії.; Основні задачі API:

API K2 ERP має змогу забезпечувати такі функціональні можливості:

  • ПРРО;
  • SAF-T UA;
  • електронна формування звітів;
  • податкові накладні;
  • розрахунки коригування;
  • запити до електронного кабінету;
  • контроль строків звітності;
  • отримання квитанцій.;</syntaxhighlight>Для деяких інтеграцій додатково можуть використовуватися:

GET /api/v1/products/{id} 

name
  • LiqPay;
  • інтернет-еквайринг;
  • банківські платежі;
  • оплата карткою;
  • післяплата;
  • переказ на рахунок.; * GET;
  • POST;
  • PUT;
  • PATCH;
  • DELETE.; "message": "Замовлення з таким externalId вже існує",

REST API

Це потрібно для: 

"phone": "+380501112233",

Приклади:

Фіскальні чеки

K2 ERP має змогу містити багато функціональних модулів: продажі та реалізація, закупівельна діяльність, складський облік, виробництво, зарплата, основні засоби, бухгалтерський обліковий облік, електронний документообіг, інтеграції з банками, ДПС, ЕДО, РРО, ПРРО, маркетплейсами, інтернет-магазинами та логістичними сервісами.; API має перевіряти вхідні інформаційні дані до виконання бізнес-операції.; Типові операції: Можливі операції: GET /api/v1/counterparties

Джерела

GET /api/v1/edo/documents/{id}/status

Incremental synchronization

Безпека: журнал API потрібен для діагностики, але в ньому не можна зберігати паролі, private keys, access tokens, повні реквізити карток, ключі електронного підпису або зайві персональні інформаційні дані.; # API передає документ у компонент ЕДО.; як ілюстрація:

Доставка

Асинхронно можуть оброблятися: </syntaxhighlight> 

status

Для облікової системи: фіскальний чек має бути пов’язаний із замовленням, оплатою, касиром, зміною, складом, клієнтом і документом продажу.; # Покупець оформлює замовлення.;</syntaxhighlight>Версіонування потрібне для: 

},

Medoc REST API

</syntaxhighlight> GET /api/v1/counterparties/{id}

  • автоматизацію обміну даними;
  • менше ручного введення;
  • менше дублювання документів;
  • швидше створення інтеграцій;
  • централізований доступ до даних ERP;
  • контроль прав доступу;
  • зв’язок зовнішніх систем із бізнес-логікою ERP;
  • прозорий журнал обміну;
  • підтримку інтернет-магазинів;
  • підтримку маркетплейсів;
  • підтримку оплат;
  • підтримку фіскалізації;
  • підтримку ЕДО;
  • можливість створення мобільних застосунків;
  • можливість побудови B2B і B2C-порталів.; "jobId": "job_12345",

Можливі операції:

API K2 ERP має змогу використовуватися для інтеграцій із ДПС або сервісами, які передають інформаційні дані до ДПС.; GET /api/v1/shipments/{id} Можливі операції:

Ціни

API для ПРРО і РРО

}

Він має змогу виконувати:

  • отримання довідників;
  • створення документів;
  • актуалізація статусів документів;
  • отримання залишків;
  • синхронізація товарів;
  • синхронізація цін;
  • отримання замовлень;
  • передавання замовлень;
  • обробка оплат;
  • передавання даних для фіскалізації;
  • отримання фіскальних чеків;
  • інтеграційні функціональні можливості з інтернет-магазинами;
  • інтеграційні функціональні можливості з маркетплейсами;
  • інтеграційні функціональні можливості з банками;
  • інтеграційні функціональні можливості з ЕДО;
  • інтеграційні функціональні можливості з ДПС;
  • інтеграційні функціональні можливості з логістикою;
  • робота з мобільними застосунками;
  • обмін даними між модулями K2 ERP.; * OpenAPI Specification
  • REST API Tutorial
  • GraphQL
  • Introduction to JSON Web Tokens
  • OAuth 2.0
  • HTTP response status codes — MDN
"code": "ORDER_ALREADY_EXISTS",

POST /api/v1/products

Gradle 

}

"status": "new"
Приклади:
API доставки застосовується для роботи з логістикою.; Це надає можливість перевіряти права доступу, статуси документів, обов’язкові поля, залишки, проводки, податки та інші правила.; # Покупцю надсилається електронний чек.; Типовий сценарій інтеграції інтернет-магазину з API K2 ERP має змогу виглядати так:
 name

 "details": {
 "externalId": "SHOPIFY-10025"
X-RateLimit-Reset: 1715179200
POST /api/v1/payments/liqpay/callback
<div style="background:#e8f5e9; border-left:5px solid #43a047; padding:12px; margin:12px 0;">

* товарів;
* замовлень;
* документів;
* платежів;
* журналів;
* залишків;
* подій;
* контрагентів.; POST /api/v1/payments
== API для ЕДО ==
Типові операції:

Контрагенти

API компаній має змогу використовуватися для отримання списку юридичних осіб або організацій, доступних користувачу чи інтеграційному сервісу.;=== Webhooks ===

Для безпечної роботи API потрібно контролювати: POST /api/v1/fiscal/shifts/close

Для K2 ERP: API-документація має бути частиною продукту.; GET /api/v1/products GET /api/v1/inventory/{sku} 

{

Filtering і sorting

</syntaxhighlight>

POST /api/v1/orders/{id}/cancel Рекомендація: для інтернет-магазинів і маркетплейсів API має повертати не бухгалтерський залишок, а доступний до продажу залишок: фактична кількість мінус резерви та інші блокування.; # K2 ERP створює замовлення клієнта.;СОТА 

}

API K2 ERP — це технічний інтерфейс для інтеграції K2 ERP із зовнішніми системами, модулями, сайтами, мобільними застосунками, платіжними сервісами, маркетплейсами, інтернет-магазинами, ПРРО, ЕДО, ДПС, банками та логістичними платформами.; query { 

version: 1.0.0

Типовий сценарій інтеграції з ЕДО має змогу виглядати так:

  • HTTPS;
  • автентифікацію;
  • авторизацію;
  • ролі;
  • права доступу;
  • IP allowlist;
  • rate limiting;
  • audit log;
  • secrets management;
  • token rotation;
  • захист від SQL injection;
  • захист від XSS для web-інтерфейсів;
  • валідацію вхідних даних;
  • CORS;
  • CSRF для браузерних сценаріїв;
  • журнал доступів;
  • контроль персональних даних.; це програмний інтерфейс; додатково реалізовано модулів, сервісів, сайтів, мобільних застосунків, інтеграційних конекторів та внутрішніх компонентів із системою K2 ERP виступає ключовою рисою взаємодії зовнішніх систем забезпечується через API K2 ERP.; # ПРРО повертає фіскальний номер.; Зверніть увагу: API K2 ERP має працювати не напряму з таблицями бази даних, а через бізнес-логіку системи.;

</syntaxhighlight>OpenAPI корисний для:

</syntaxhighlight> GET /api/v1/products?page=1&pageSize=100

  • Shopify;
  • Magento;
  • Wix;
  • OpenCart;
  • Tilda Commerce;
  • власний сайт;
  • мобільний застосунок;
  • B2B-портал;
  • B2C-портал.;== Типовий сценарій інтеграції з ЕДО ==

GET /api/v1/products/changes?updatedAfter=2026-05-08T00:00:00Z API K2 ERP має змогу використовуватися для роботи з банківськими даними.; "externalId": "SHOPIFY-10025",

Залишки

sku
phone

Типовий сценарій фіскалізації через API

GET /api/v1/orders?cursor=eyJpZCI6MTIzfQ

OpenAPI

GET /api/v1/fiscal/receipts/{id}

Обробка помилок

ДПС

Основним форматом для API K2 ERP має змогу бути JSON.; Це спрощує інтеграцію та підтримку зовнішніх систем.; Приклади версіонування:

GET /api/v1/products

Приклад:
== API для логістики ==
API має змогу бути реалізоване як REST API, GraphQL API, WebSocket API, RPC-інтерфейс, webhook-механізм або внутрішній сервісний інтерфейс між модулями.; "error": {
GET /api/v1/products/by-sku/{sku}

* генерації документації;
* генерації клієнтів;
* тестування API;
* контрактного тестування;
* контролю змін;
* роботи frontend і backend команд.; До основних переваг API K2 ERP можна віднести:
Можливі операції:
API K2 ERP має змогу використовуватися для інтеграції з інтернет-магазинами:

 "price": 450.00
 }

* API Gateway;
* компонент авторизації;
* бізнес-сервіси;
* сервіс довідників;
* сервіс документів;
* сервіс залишків;
* сервіс оплат;
* сервіс фіскалізації;
* сервіс інтеграцій;
* журнал обміну;
* систему черг;
* базу даних;
* компонент моніторингу;
* механізм webhooks;
* механізм rate limiting;
* механізм аудиту.; PATCH /api/v1/products/{id}
GET /api/v1/orders?status=paid&createdFrom=2026-05-01

* потребу в якісній документації;
* потребу в стабільному версіонуванні;
* потребу в захисті токенів;
* потребу в логуванні без секретів;
* ризик перевантаження API;
* ризик дублювання документів;
* ризик некоректної фіскалізації;
* ризик неправильного актуалізація цін;
* ризик неправильних залишків;
* потребу в ідемпотентності;
* потребу в моніторингу;
* потребу в sandbox;
* потребу в тестах;
* потребу в підтримці сумісності.; customer {
</div>
Якісне API K2 ERP має підтримувати авторизацію, версіонування, REST або GraphQL endpoint-и, webhooks, ідемпотентність, журнал обміну, зрозумілі помилки, документацію OpenAPI, sandbox, моніторинг, rate limiting і безпечне зберігання секретів.; API K2 ERP має змогу взаємодіяти з сервісами електронного документообігу.; GET /api/v1/companies
Приклади endpoint-ів:<syntaxhighlight lang="text">
Типовий сценарій фіскалізації має змогу виглядати так:

</syntaxhighlight>

  • створено замовлення;
  • змінено статус оплати;
  • фіскальний чек створено;
  • товар оновлено;
  • залишок змінився;
  • документ підписано в ЕДО;
  • замовлення відправлено;
  • отримано банківську виписку.; Приклад:

API K2 ERP потрібне для інтеграції ERP з іншими системами та автоматизації бізнес-процесів.; /api/v2/orders K2 Модуль Shopify

POST /api/v1/orders

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

FREDO

API залишків застосовується для отримання доступної кількості товарів на складах.; Можливі операції:

Приклад:
* Prom;
* Rozetka;
* Hotline;
* інші торгові майданчики.;== API для платіжних сервісів ==
[[YouTrack]]
}
}
Варто контролювати:
Для K2 ERP API є собою основою інтеграційної архітектури: воно надає можливість будувати модулі Shopify, Magento, Wix, Prom, LiqPay, ПРРО, ЕДО, SAF-T UA, е-ТТН, банківські й логістичні інтеграції без ручного дублювання даних.; API K2 ERP має мати механізм автентифікації та авторизації.;[[DevOps]]
POST /api/v1/payments/{id}/refund

<div style="background:#ffebee; border-left:5px solid #e53935; padding:12px; margin:12px 0;">

* доступність API;
* середній час відповіді;
* кількість запитів;
* кількість помилок;
* error rate;
* кількість 401 і 403;
* кількість 429;
* кількість 500;
* повільні endpoint-и;
* стан черг;
* статус зовнішніх інтеграцій;
* помилки webhooks;
* невдалі фіскалізації;
* невдалі платежі.; Можливі операції:
== API для інтернет-магазинів ==

 "status": "queued"

* створити замовлення;
* отримати замовлення;
* змінити статус;
* додати оплату;
* додати доставку;
* скасувати замовлення;
* створити повернення;
* отримати історію змін.; Він надає можливість формально описати endpoint-и, параметри, схеми даних, відповіді, помилки й авторизацію.; # Оператор повертає статус.; # Після підписання зберігається підписаний файл.; * отримати залишок за товаром;
* отримати залишки за складом;
* отримати доступний залишок;
* отримати резерви;
* отримати залишки для каналу продажів;
* оновити зовнішню систему після складського руху.; # Статус замовлення оновлюється.;== Документація API ==

API K2 ERP потрібне для того, щоб ці модулі могли взаємодіяти із зовнішніми системами без ручного дублювання даних.;[[K2 Модуль Magento]]
POST /api/v1/fiscal/refunds
Типовий обмін:
GET /api/v1/orders/changes?sinceToken=abc123
'''REST API''' — це найпоширеніший варіант API для ERP-інтеграцій.;[[РРО]]
=== ЕДО ===
 }
POST /api/v1/fiscal/receipts

== Основні функціональні можливості ==
Приклади endpoint-ів:<syntaxhighlight lang="text">

[[Edin]]

* створити фіскальний чек;
* створити чек повернення;
* отримати статус чека;
* отримати фіскальний номер;
* отримати посилання на чек;
* відкрити зміну;
* закрити зміну;
* сформувати Z-звіт.; Це захищає систему від дублювання при повторному запиті.; * паролі;
* хеші паролів;
* private keys;
* ключі електронного підпису;
* access tokens;
* refresh tokens;
* production connection strings;
* повні інформаційні дані платіжних карток;
* зайві персональні інформаційні дані;
* внутрішні технічні секрети;
* системні журнали без фільтрації;
* фінансові інформаційні дані без прав доступу.;== Rate limiting ==
[[ЕДО]]
Типовий обмін:
== переважні аспекти API K2 ERP ==
POST /api/v1/edo/documents
== Для чого потрібне API K2 ERP ==
== Idempotency ==
'''API Gateway''' має змогу бути вхідною точкою для API K2 ERP.; '''Безпека:''' API token, private key, client secret і access token не можна зберігати у відкритому коді, логах, публічних файлах, wiki-сторінках або повідомленнях.; # ERP створює відвантаження.; "eventId": "evt_100001",
POST /api/v1/edo/documents/{id}/send

Для якісної роботи API в K2 ERP бажано зберігати:

* тестування інтеграцій;
* перевірки авторизації;
* перевірки форматів;
* навчання партнерів;
* тестування webhooks;
* перевірки помилок;
* тестування фіскалізації в тестовому режимі;
* перевірки обробки повторних запитів.; # Магазин отримує ціни.;== Обмеження та ризики ==
Документація повинна містити:
}
== Черги і асинхронна обробка ==
 id
 summary: Create order
Або cursor-based pagination:
{
[[SAF-T UA]]
Типові HTTP-коди:
Приклад:<syntaxhighlight lang="text">
Можливі операції:
'''GraphQL API''' має змогу використовуватися тоді, коли клієнту потрібно гнучко отримувати лише потрібні поля, об’єднувати кілька типів даних в одному запиті або будувати складні інтерфейси.; Retry потрібен, якщо:
API K2 ERP має змогу приймати події від платіжних сервісів або передавати платіжні запити.; # Інтернет-магазин отримує товари з K2 ERP.; # Документ проходить внутрішню перевірку.;[[TeamCity]]

* створити платіж;
* отримати callback;
* перевірити підпис;
* оновити статус оплати;
* створити документ оплати;
* запустити фіскалізацію;
* створити повернення.; # За потреби виконується фіскалізація.; {
У журналі можна зберігати:
[[LiqPay]]
[[K2 Модуль Wix]]
 number
'''OpenAPI''' — це формат опису REST API.; # API оновлює статус документа в K2 ERP.; Приклади REST endpoint-ів:<syntaxhighlight lang="text">
Приклад GraphQL-запиту:<syntaxhighlight lang="graphql">

* integration ID;
* назву інтеграції;
* тип інтеграції;
* користувача або service account;
* права доступу;
* API token у захищеному вигляді;
* дату створення токена;
* дату останнього використання;
* статус інтеграції;
* request ID;
* correlation ID;
* external ID об’єкта;
* internal ID об’єкта;
* статус синхронізації;
* останню дату синхронізації;
* текст помилки;
* технічну відповідь;
* кількість повторних спроб.; Без зрозумілої документації інтеграції стають залежними від усних пояснень, ручних тестів і технічної підтримки.; {
== Див.; додатково ==

* неправильний token;
* token прострочений;
* немає прав доступу;
* неправильний формат JSON;
* відсутнє обов’язкове поле;
* некоректний SKU;
* контрагент не знайдений;
* товар не знайдений;
* складський облік не знайдений;
* замовлення вже існує;
* недостатній залишок;
* неправильний статус документа;
* оплата вже проведена;
* чек уже фіскалізований;
* помилка зовнішнього сервісу;
* timeout;
* дублювання webhook;
* перевищено rate limit;
* API-версія застаріла;
* помилка бізнес-правила.; '201':
Приклад:<syntaxhighlight lang="text">

</div>

* дату і час запиту;
* endpoint;
* HTTP-метод;
* користувача або сервіс;
* IP-адресу;
* request ID;
* correlation ID;
* статус відповіді;
* час виконання;
* текст помилки;
* ідентифікатор об’єкта;
* напрям інтеграції;
* кількість повторних спроб.; API цін застосовується для синхронізації прайсів з інтернет-магазинами, маркетплейсами, мобільними застосунками або B2B-порталами.; Для великих списків API має підтримувати пагінацію.;
Або через заголовок:
PATCH /api/v1/shipments/{id}/tracking
== інформаційні дані, які бажано зберігати для інтеграції ==
API K2 ERP має змогу використовуватися для інтеграції з маркетплейсами:
 "customer": {
Можливі операції:
 "status": "paid"
Документацію можна оформити через:
 "sku": "SKU-001",
Це надає можливість інтеграціям не завантажувати всі інформаційні дані щоразу, а отримувати лише потрібні зміни.; Якщо зовнішня платформа створює документ через API, він має проходити ті самі перевірки, що й документ, створений користувачем у K2 ERP.; Можливі операції:

GET /api/v1/companies/{id} IDE GET /api/v1/edo/documents/{id} 

"event": "order.created",
Приклад заголовка:
{

== інформаційні дані, які не можна відкривати через API ==
 post:

 items {

* створити оплату;
* отримати статус оплати;
* прив’язати платіж до замовлення;
* обробити callback;
* створити повернення;
* отримати історію платежів;
* виконати звірку оплат.;<div style="background:#e8f5e9; border-left:5px solid #43a047; padding:12px; margin:12px 0;">
 "externalId": "SHOPIFY-10025",

Можливі операції:

* Нова пошта;
* Укрпошта;
* Мурашина логістика;
* кур’єрські служби;
* внутрішня доставка;
* е-ТТН.; POST /api/v1/shipments
API електронного документообігу має змогу використовуватися для інтеграції з M.E.Doc, EDIN, СОТА, FREDO або іншими сервісами.; '''Рекомендація:''' усі API-операції, які створюють гроші, документи, чеки або складські рухи, мають підтримувати ідемпотентність.; * зовнішній сервіс тимчасово недоступний;
* стався timeout;
* виникла мережева помилка;
* endpoint повернув 503;
* webhook не доставлено;
* фіскальний сервер не відповів.;== Авторизація і автентифікація ==

* XML;
* CSV;
* XLSX;
* YAML;
* multipart/form-data;
* binary files;
* ZIP-архіви;
* підписані файли.; API K2 ERP має повертати зрозумілі помилки.; Принцип мінімально необхідного доступу важливий для безпеки ERP, персональних даних, платежів і фіскальних операцій.; GET /api/v1/products/{id}/prices

* OpenAPI / Swagger;
* Postman Collection;
* Markdown;
* MediaWiki;
* Redoc;
* Developer Portal.; API замовлень застосовується для створення та актуалізація замовлень клієнтів.; # K2 ERP перевіряє оплату.; Вони мають зберігатися в захищених сховищах.; * базовий URL;
* версію API;
* спосіб авторизації;
* список endpoint-ів;
* приклади запитів;
* приклади відповідей;
* моделі даних;
* помилки;
* rate limits;
* webhooks;
* правила ідемпотентності;
* changelog;
* sandbox-оточення;
* contact support;
* приклади інтеграції.; /api/v1/orders:
Можливі варіанти:

 "items": [
'''Не плутати:''' API — це не обхід бізнес-правил ERP.; # компонент ЕДО надсилає документ оператору.;<div style="background:#fff8e1; border-left:5px solid #f9a825; padding:12px; margin:12px 0;">
Приклад:<syntaxhighlight lang="text">

== API для банків ==
Приклад замовлення:<syntaxhighlight lang="json">

</div>

* отримати список контрагентів;
* створити контрагента;
* оновити контактні інформаційні дані;
* знайти контрагента за ЄДРПОУ;
* знайти контрагента за ІПН;
* знайти клієнта за телефоном;
* знайти клієнта за email.; paths:

* маршрутизацію запитів;
* авторизацію;
* rate limiting;
* логування;
* перевірку токенів;
* балансування навантаження;
* трансформацію запитів;
* кешування;
* контроль версій;
* захист від некоректних запитів.; # У картці документа зберігається історичний розвиток обміну.; # Платіжний сервіс надсилає callback про оплату.;[[Git]]

API має підтримувати фільтрацію та сортування.; Приклад webhook-повідомлення:<syntaxhighlight lang="json">

[[Модуль Prom]]

* обов’язкові поля;
* формат телефону;
* формат email;
* валюту;
* кількість;
* ціну;
* SKU;
* наявність товару;
* контрагента;
* складський облік;
* статус документа;
* форму оплати;
* податкові ставки;
* права користувача;
* дублювання externalId.;== Можливі помилки під час інтеграції ==

* M.E.Doc;
* EDIN;
* СОТА;
* FREDO;
* Вчасно;
* інші оператори ЕДО.; * підтримки старих інтеграцій;
* безпечного розвитку API;
* поступового переходу клієнтів;
* тестування нових endpoint-ів;
* документування змін;
* контролю сумісності.; # Сайт передає замовлення в K2 ERP.; Приклад:<syntaxhighlight lang="text">

* отримати ціну товару;
* отримати ціни за типом цін;
* оновити ціну;
* отримати акційну ціну;
* отримати валюту ціни;
* отримати історію зміни ціни.; * товарів;
* залишків;
* цін;
* замовлень;
* контрагентів;
* документів;
* статусів.; GET /api/v1/orders/{id}
</div>
Через API не можна безконтрольно відкривати:
Перевіряти потрібно:
/api/v1/orders
'''істотно:''' API K2 ERP — це не окремий компонент обліку, а технічний інтерфейс доступу до функцій і даних ERP.; Для інтеграцій потрібно підтримувати повторну обробку помилок.; Це особливо істотно для:

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

</syntaxhighlight>Це корисно для:

Приклад відповіді:

Dead letter queue потрібна для повідомлень, які не вдалося обробити після кількох спроб.; API K2 ERP має змогу працювати з логістичними сервісами.; '''Webhooks''' — це механізм, за якого K2 ERP або зовнішня платформа надсилає повідомлення про подію.; Приклад відповіді з помилкою:<syntaxhighlight lang="json">
[[M.E.Doc.ЕДО]]
У такій архітектурі зовнішня платформа не функціонує напряму з базою даних K2 ERP, а звертається до API, яке перевіряє запит і виконує бізнес-операцію.; # платформа резервує товар.;
description: Order created
  1. У K2 ERP створюється документ.; API оплат застосовується для зв’язку з LiqPay, банками, еквайрингом, касами та внутрішніми документами оплати.; POST /api/v1/payments

Компанії

Замовлення

Sandbox — це тестове середовище API, у якому інтеграції можуть перевірятися без впливу на production-дані.; "orderId": "12345", Рекомендація: API має повертати машинозчитуваний код помилки і зрозуміле повідомлення для розробника.;== Загальний характеристика ==

  • синхронізація товарів;
  • актуалізація цін;
  • актуалізація залишків;
  • отримання замовлень;
  • передавання статусів;
  • передавання ТТН;
  • фіскалізація;
  • обробка повернень.; "quantity": 2,

ПРРО

GET /api/v1/inventory?warehouseId=1 GET /api/v1/products?updatedFrom=2026-05-01T00:00:00Z

Webhooks API K2 ERP

Incremental synchronization — це синхронізація тільки тих даних, які змінилися після певного часу або версії.; }

  • створити ТТН;
  • отримати статус доставки;
  • отримати вартість доставки;
  • отримати відділення;
  • передати tracking number;
  • створити е-ТТН;
  • отримати підтвердження доставки.; Через API зовнішні системи можуть читати, створювати або оновлювати інформаційні дані відповідно до прав доступу та бізнес-правил.;== API Gateway ==
  • створити документ;
  • відправити документ;
  • отримати статус;
  • отримати підписаний файл;
  • отримати квитанцію;
  • обробити відмову;
  • синхронізувати вхідні документи.; API K2 ERP застосовують, коли потрібно для автоматизації обміну даними: створення документів, отримання довідників, синхронізації товарів, клієнтів, замовлень, оплат, залишків, бухгалтерських операцій, статусів, інтеграційних подій і результатів обробки.; API має повертати не лише статус, а й фіскальний номер та технічну відповідь.; POST /api/v1/fiscal/shifts/open

Idempotency — це властивість API-запиту, за якої повторне виконання того самого запиту не створює дублікати.; # API створює фіскальний чек.;

API для ДПС

  1. Зовнішній сайт створює замовлення.; GET /api/v1/orders/{id}

Monitoring API

Rate limiting обмежує кількість запитів до API за певний період часу.;
  • ERP передає товари;
  • ERP передає ціни;
  • ERP передає залишки;
  • магазин передає замовлення;
  • магазин передає оплату;
  • ERP передає статус;
  • ERP передає tracking number;
  • ERP виконує фіскалізацію;
  • ERP передає чек або посилання на чек.;== Валідація даних ==
Приклади endpoint-ів:
GET /api/v1/prices?priceType=shopify

* login і password;
* access token;
* refresh token;
* API key;
* OAuth2;
* JWT;
* service account;
* client credentials;
* IP allowlist;
* mTLS для критичних інтеграцій.; Можливі напрями:
 responses:
 "method": "liqpay",
[[Е-ТТН]]
POST /api/v1/orders
== Pagination ==
== Висновок ==
Accept: application/vnd.k2erp.v1+json
X-RateLimit-Limit: 1000
'''Практичне сфера застосування:''' для великих каталогів товарів краще використовувати синхронізацію змін, а не щоразу вивантажувати весь каталог в цілому.;== Безпека API K2 ERP ==
Під час впровадження API потрібно враховувати:
  • відкрити зміну;
  • закрити зміну;
  • створити чек;
  • створити чек повернення;
  • отримати статус чека;
  • отримати фіскальний номер;
  • створити Z-звіт;
  • зберегти відповідь ДПС;
  • надіслати електронний чек покупцю.; # Магазин надсилає замовлення в K2 ERP через API.; API товарів застосовується для отримання і синхронізації номенклатури.; * хто виконує запит;
  • до якої компанії є собою доступ;
  • які модулі доступні;
  • які документи можна читати;
  • які документи можна створювати;
  • які поля можна змінювати;
  • чи дозволено виконувати фіскалізацію;
  • чи дозволено працювати з оплатами;
  • чи дозволено бачити персональні інформаційні дані.; API фіскалізації застосовується для створення чеків через ПРРО або РРО.; # Магазин показує покупцю статус замовлення.; # Магазин отримує залишки.; * створити електронний документ;
  • відправити документ;
  • отримати статус;
  • отримати квитанцію;
  • отримати підписаний файл;
  • обробити відхилення;
  • зберегти технічну відповідь.; інформаційні дані передаються через HTTP-запити, а об’єкти зазвичай представлені у форматі JSON.; Типові операції:

openapi: 3.0.3

</syntaxhighlight>

  • масовий експорт товарів;
  • масове актуалізація залишків;
  • фіскалізація після оплати;
  • передавання документів в ЕДО;
  • формування SAF-T UA;
  • імпорт великих файлів;
  • синхронізація маркетплейсів;
  • відправлення webhooks;
  • повторна обробка помилок.;</syntaxhighlight>

Практичне сфера застосування: REST API комфортно використовувати для запитів і команд, а webhooks — для швидкого повідомлення про події без постійного опитування системи.; "createdAt": "2026-05-08T12:30:00Z", POST /api/v1/counterparties Типові операції: 

}

</syntaxhighlight>

Типова технічна архітектура API K2 ERP має змогу включати:

API K2 ERP має мати документацію.;== API для маркетплейсів == }

У K2 ERP бажано зберігати журнал API-запитів.; # K2 ERP зберігає чек.; "data": {

технічна архітектура API K2 ERP

Типовий сценарій інтеграції інтернет-магазину

quantity

Приклади: API K2 ERP потрібно моніторити.; # Після оплати сайт або платіжний сервіс надсилає подію.; # ERP передає tracking number у магазин.; # K2 ERP створює документ оплати.; Довгі або ризиковані операції краще передавати в чергу.; GET /api/v1/products/{id}

Авторизація має визначати:

  • 200 — успішний запит;
  • 201 — створено;
  • 400 — помилка валідації;
  • 401 — не авторизовано;
  • 403 — немає прав доступу;
  • 404 — об’єкт не знайдено;
  • 409 — конфлікт або дублювання;
  • 422 — бізнес-правило не виконано;
  • 429 — перевищено ліміт запитів;
  • 500 — внутрішня помилка сервера;
  • 503 — сервіс тимчасово недоступний.; X-RateLimit-Remaining: 850

Типові події:

API контрагентів застосовується для роботи з клієнтами, постачальниками, перевізниками, партнерами та іншими учасниками обліку.;=== GraphQL API ===

  • створити доставку;
  • прив’язати ТТН до замовлення;
  • отримати статус доставки;
  • оновити tracking number;
  • отримати інформаційні дані перевізника;
  • створити е-ТТН;
  • отримати історію доставки.;== Типи API ==
  • авторизацію користувачів і сервісів;
  • роботу з access token;
  • роботу з API keys;
  • отримання списку компаній;
  • отримання довідника контрагентів;
  • отримання довідника товарів;
  • отримання цін;
  • отримання залишків;
  • створення замовлення клієнта;
  • створення документа продажу;
  • створення документа закупівельна діяльність;
  • створення оплати;
  • створення повернення;
  • створення складського руху;
  • створення фіскального чека;
  • отримання статусу документа;
  • отримання історії змін;
  • обробку webhooks;
  • журналювання інтеграційних операцій;
  • контроль помилок і повторних запитів.;== Формат даних ==
}

</syntaxhighlight>Пагінація потрібна для:

  • отримати банківські виписки;
  • імпортувати платежі;
  • зіставити платіж із замовленням;
  • створити платіжне доручення;
  • отримати статус платежу;
  • виконати звірку;
  • зберегти банківський документ.;== Retry і dead letter queue ==
order(id: "123") {
title: K2 ERP API
Приклад:
Sandbox потрібен для:

 ],
Приклад заголовків:<syntaxhighlight lang="text">
 "payment": {
=== Товари ===
GET /api/v1/inventory?warehouseId=2&sku=ABC-001
API K2 ERP має змогу працювати з ПРРО або РРО.;== Журнал API-запитів ==
Приклади endpoint-ів:<syntaxhighlight lang="text">
 "email": "ivan@example.com"

[[Java]]
Не всі API-операції потрібно виконувати синхронно.; '''Не плутати:''' API має надавати тільки ті інформаційні дані, які потрібні інтеграції.; як ілюстрація, інтернет-магазин має змогу передати замовлення в K2 ERP, платіжний сервіс — повідомити про оплату, складська платформа — оновити залишки, а компонент ПРРО — повернути фіскальний номер чека.; API K2 ERP бажано версіонувати, щоб зміни не ламали існуючі інтеграції.;=== Оплати ===

POST /api/v1/fiscal-receipts

== Основні ресурси API ==

GET /api/v1/payments/{id}

Idempotency-Key: 9b2d7a8e-5c1a-4e6a-9e22-123456789abc

info:

PATCH /api/v1/counterparties/{id}

Версіонування API

Типові HTTP-методи: 

"name": "Іван Петренко",

</syntaxhighlight>

Приклад фрагмента OpenAPI:<syntaxhighlight lang="yaml">

}

Отримано з https://wiki.corp2.eu/index.php?title=API_K2_ERP&oldid=1181