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

API K2 ERP

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

Можливі помилки під час інтеграції

}

Залишки

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

Це особливо критично для:

Rate limiting обмежує кількість запитів до API за певний період часу. # Після оплати сайт або платіжний сервіс надсилає подію. POST /api/v1/orders

Приклад заголовка:

== Monitoring API ==
POST /api/v1/payments
 "orderId": "12345",
POST /api/v1/fiscal/shifts/open
=== ЕДО ===
=== GraphQL API ===
 description: Order created

У журналі можна зберігати:
 "message": "Замовлення з таким externalId вже існує",
  • створити доставку;
  • прив’язати ТТН до замовлення;
  • отримати статус доставки;
  • оновити tracking number;
  • отримати інформаційні дані перевізника;
  • створити е-ТТН;
  • отримати історію доставки. # API створює фіскальний чек. query {
quantity

DevOps Можливі операції: GET /api/v1/payments/{id} POST /api/v1/fiscal/shifts/close

Приклад заголовків:

</div>

 "eventId": "evt_100001",

* 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. }
GET /api/v1/products/{id}/prices
Приклади:
У K2 ERP бажано зберігати журнал API-запитів. GET /api/v1/products?page=1&pageSize=100
 "quantity": 2,

* авторизацію користувачів і сервісів;
* роботу з access token;
* роботу з API keys;
* отримання списку компаній;
* отримання довідника контрагентів;
* отримання довідника товарів;
* отримання цін;
* отримання залишків;
* створення замовлення клієнта;
* створення документа продажу;
* створення документа закупівельна діяльність;
* створення оплати;
* створення повернення;
* створення складського руху;
* створення фіскального чека;
* отримання статусу документа;
* отримання історії змін;
* обробку webhooks;
* журналювання інтеграційних операцій;
* контроль помилок і повторних запитів. # API передає документ у компонент ЕДО. # Сайт передає замовлення в K2 ERP.[[Edin]]

* ERP передає товари;
* ERP передає ціни;
* ERP передає залишки;
* магазин передає замовлення;
* магазин передає оплату;
* ERP передає статус;
* ERP передає tracking number;
* ERP виконує фіскалізацію;
* ERP передає чек або посилання на чек.
  • створити документ;
  • відправити документ;
  • отримати статус;
  • отримати підписаний файл;
  • отримати квитанцію;
  • обробити відмову;
  • синхронізувати вхідні документи. # ERP створює відвантаження. Типові операції:

IDE

Типовий обмін:

</syntaxhighlight>Або cursor-based pagination:

* автоматизацію обміну даними;
* менше ручного введення;
* менше дублювання документів;
* швидше створення інтеграцій;
* централізований доступ до даних ERP;
* контроль прав доступу;
* зв’язок зовнішніх систем із бізнес-логікою ERP;
* прозорий журнал обміну;
* підтримку інтернет-магазинів;
* підтримку маркетплейсів;
* підтримку оплат;
* підтримку фіскалізації;
* підтримку ЕДО;
* можливість створення мобільних застосунків;
* можливість побудови B2B і B2C-порталів. # K2 ERP зберігає чек. '''API Gateway''' здатна бути вхідною точкою для API K2 ERP.<div style="background:#e8f4ff; border-left:5px solid #1e88e5; padding:12px; margin:12px 0;">
</div>
взаємодії зовнішніх систем забезпечується через '''API K2 ERP''' — це програмний інтерфейс; так само реалізовано модулів. API залишків застосовується для для отримання доступної кількості товарів на складах. /api/v2/orders
=== Оплати ===
== API для інтернет-магазинів ==
 "sku": "SKU-001",
<div style="background:#e8f5e9; border-left:5px solid #43a047; padding:12px; margin:12px 0;">
Можливі операції:
як приклад:

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

version: 1.0.0
  • створити оплату;
  • отримати статус оплати;
  • прив’язати платіж до замовлення;
  • обробити callback;
  • створити повернення;
  • отримати історію платежів;
  • виконати звірку оплат.
Приклад фрагмента OpenAPI:
Під час роботи з API K2 ERP можуть виникати такі помилки:
GET /api/v1/edo/documents/{id}

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

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

API K2 ERP здатна використовуватися для роботи з банківськими даними.

}

  • HTTPS;
  • автентифікацію;
  • авторизацію;
  • ролі;
  • права доступу;
  • IP allowlist;
  • rate limiting;
  • audit log;
  • secrets management;
  • token rotation;
  • захист від SQL injection;
  • захист від XSS для web-інтерфейсів;
  • валідацію вхідних даних;
  • CORS;
  • CSRF для браузерних сценаріїв;
  • журнал доступів;
  • контроль персональних даних. # компонент ЕДО надсилає документ оператору.K2 Модуль Shopify

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

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

Пагінація потрібна для:

Spring

API K2 ERP здатна приймати події від платіжних сервісів або передавати платіжні запити. Приклад:

K2 ERP здатна надсилати webhooks у зовнішні системи. # Після підписання зберігається підписаний файл. Довгі або ризиковані операції краще передавати в чергу. GET /api/v1/inventory?warehouseId=1

API контрагентів застосовується для для роботи з клієнтами, постачальниками, перевізниками, партнерами та іншими учасниками обліку.</div>

* синхронізація товарів;
* оновлення версій цін;
* оновлення версій залишків;
* отримання замовлень;
* передавання статусів;
* передавання ТТН;
* фіскалізація;
* обробка повернень.== конкурентні переваги API K2 ERP ==

== Типовий сценарій фіскалізації через API ==
API електронного документообігу здатна використовуватися для інтеграції з M.E.Doc, EDIN, СОТА, FREDO або іншими сервісами. # Магазин отримує ціни.== OpenAPI ==

</div>
GET /api/v1/orders?status=paid&createdFrom=2026-05-01

OpenAPI корисний для:

Документацію можна оформити через: Документація повинна містити:

API для ЕДО

Для K2 ERP API виступає як основою інтеграційної архітектури: воно дає можливість будувати модулі Shopify, Magento, Wix, Prom, LiqPay, ПРРО, ЕДО, SAF-T UA, е-ТТН, банківські й логістичні інтеграції без ручного дублювання даних. Без зрозумілої документації інтеграції стають залежними від усних пояснень, ручних тестів і технічної підтримки. GET /api/v1/products/changes?updatedAfter=2026-05-08T00:00:00Z

Приклади endpoint-ів:

Під час впровадження API потрібно враховувати:
 }
Типові події:
'''Рекомендація:''' усі API-операції, які створюють гроші, документи, чеки або складські рухи, мають підтримувати ідемпотентність. "email": "ivan@example.com"
Приклад:<syntaxhighlight lang="text">
=== REST API ===
API фіскалізації застосовується для для створення чеків через ПРРО або РРО. * Нова пошта;
* Укрпошта;
* Мурашина логістика;
* кур’єрські служби;
* внутрішня доставка;
* е-ТТН. Перевіряти потрібно:
 "jobId": "job_12345",
<div style="background:#ffebee; border-left:5px solid #e53935; padding:12px; margin:12px 0;">
Приклад:
[[YouTrack]]
</div>
== API для платіжних сервісів ==

Через API не можна безконтрольно відкривати:
POST /api/v1/products

 "status": "queued"
API K2 ERP потрібне для інтеграції ERP з іншими системами та автоматизації бізнес-процесів. GET /api/v1/products/{id}

</syntaxhighlight> K2 ERP здатна містити багато функціональних модулів: продажі та реалізація, закупівельна діяльність, складський облік, виробництво, зарплата, основні засоби, бухгалтерський обліковий облік, електронний документообіг, інтеграції з банками, ДПС, ЕДО, РРО, ПРРО, маркетплейсами, інтернет-магазинами та логістичними сервісами.== Retry і dead letter queue ==

  • LiqPay;
  • інтернет-еквайринг;
  • банківські платежі;
  • оплата карткою;
  • післяплата;
  • переказ на рахунок. /api/v1/orders:

X-RateLimit-Limit: 1000

Приклади endpoint-ів:
 "customer": {
Типові операції:
 ],

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

POST /api/v1/payments/{id}/refund

  • створити фіскальний чек;
  • створити чек повернення;
  • отримати статус чека;
  • отримати фіскальний номер;
  • отримати посилання на чек;
  • відкрити зміну;
  • закрити зміну;
  • сформувати Z-звіт.РРО
"error": {

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

  • отримати список товарів;
  • отримати товар за ID;
  • отримати товар за SKU;
  • створити товар;
  • оновити товар;
  • отримати характеристики;
  • отримати фото;
  • отримати статус публікації;
  • отримати категорії.== Безпека API K2 ERP ==
  1. У K2 ERP створюється документ. }

Webhooks

Приклади:
=== Товари ===
GET /api/v1/orders/{id}

}
 summary: Create order
'''Incremental synchronization''' — це синхронізація тільки тих даних, які змінилися після певного часу або версії.== Валідація даних ==
[[ПРРО]]
{

Типові HTTP-методи:
Accept: application/vnd.k2erp.v1+json

# Інтернет-магазин отримує товари з K2 ERP. GET /api/v1/counterparties/{id}
API оплат застосовується для для зв’язку з LiqPay, банками, еквайрингом, касами та внутрішніми документами оплати.[[K2 Модуль Wix]]

Для якісної роботи API в K2 ERP бажано зберігати:
 id
== Типовий сценарій інтеграції з ЕДО ==
</div>
/api/v1/orders

* товарів;
* замовлень;
* документів;
* платежів;
* журналів;
* залишків;
* подій;
* контрагентів.[[Git]]
Типовий сценарій інтеграції інтернет-магазину з API K2 ERP здатна виглядати так:
Для деяких інтеграцій так само можуть використовуватися:
  • захисту від перевантаження;
  • контролю інтеграцій;
  • захисту від помилкових циклів;
  • стабільності системи;
  • пріоритезації критичних запитів. openapi: 3.0.3
Приклад webhook-повідомлення:
[[Е-ТТН]]

* [https://swagger.io/specification/ OpenAPI Specification]
* [https://restfulapi.net/ REST API Tutorial]
* [https://graphql.org/ GraphQL]
* [https://jwt.io/introduction Introduction to JSON Web Tokens]
* [https://oauth.net/2/ OAuth 2.0]
* [https://developer.mozilla.org/en-US/docs/Web/HTTP/Status HTTP response status codes — MDN]

Типові HTTP-коди:
 items {

'''REST API''' — це найпоширеніший варіант API для ERP-інтеграцій.</div>

=== Компанії ===
[[M.E.Doc.ЕДО]]

Приклад:<syntaxhighlight lang="text">

* GET;
* POST;
* PUT;
* PATCH;
* DELETE. },

* отримати залишок за товаром;
* отримати залишки за складом;
* отримати доступний залишок;
* отримати резерви;
* отримати залишки для каналу продажів;
* оновити зовнішню систему після складського руху. Приклади REST endpoint-ів:<syntaxhighlight lang="text">
API K2 ERP має повертати зрозумілі помилки.== API для ДПС ==
GET /api/v1/orders/by-external-id/{externalId}

PATCH /api/v1/shipments/{id}/tracking

* ПРРО;
* SAF-T UA;
* електронна формування звітів;
* податкові накладні;
* розрахунки коригування;
* запити до електронного кабінету;
* контроль строків звітності;
* отримання квитанцій. API K2 ERP здатна взаємодіяти з сервісами електронного документообігу. Це дає можливість перевіряти права доступу, статуси документів, обов’язкові поля, залишки, проводки, податки та інші правила.== Загальний SEO-опис ==

Приклад відповіді:<syntaxhighlight lang="json">
<div style="background:#ede7f6; border-left:5px solid #5e35b1; padding:12px; margin:12px 0;">

Типові операції:

* створити замовлення;
* отримати замовлення;
* змінити статус;
* додати оплату;
* додати доставку;
* скасувати замовлення;
* створити повернення;
* отримати історію змін. інформаційні дані передаються через HTTP-запити, а об’єкти зазвичай представлені у форматі JSON. У такій архітектурі зовнішня платформа не функціонує напряму з базою даних K2 ERP, а звертається до API, яке перевіряє запит і виконує бізнес-операцію. '''Не плутати:''' API — це не обхід бізнес-правил ERP. # Оператор повертає статус.<div style="background:#fff3e0; border-left:5px solid #fb8c00; padding:12px; margin:12px 0;">
Приклад:<syntaxhighlight lang="text">

== інформаційні дані, які бажано зберігати для інтеграції ==

* дату і час запиту;
* endpoint;
* HTTP-метод;
* користувача або сервіс;
* IP-адресу;
* request ID;
* correlation ID;
* статус відповіді;
* час виконання;
* текст помилки;
* ідентифікатор об’єкта;
* напрям інтеграції;
* кількість повторних спроб. "status": "paid"
 }

* паролі;
* хеші паролів;
* private keys;
* ключі електронного підпису;
* access tokens;
* refresh tokens;
* production connection strings;
* повні інформаційні дані платіжних карток;
* зайві персональні інформаційні дані;
* внутрішні технічні секрети;
* системні журнали без фільтрації;
* фінансові інформаційні дані без прав доступу. API K2 ERP бажано версіонувати, щоб зміни не ламали існуючі інтеграції. # платформа резервує товар. paths:
== технічна архітектура API K2 ERP ==

Типовий сценарій фіскалізації здатна виглядати так:

* відкрити зміну;
* закрити зміну;
* створити чек;
* створити чек повернення;
* отримати статус чека;
* отримати фіскальний номер;
* створити Z-звіт;
* зберегти відповідь ДПС;
* надіслати електронний чек покупцю. Можливі операції:
API K2 ERP здатна працювати з ПРРО або РРО. "price": 450.00
API K2 ERP здатна працювати з логістичними сервісами.== Див. так само ==

Dead letter queue потрібна для повідомлень, які не вдалося обробити після кількох спроб. API K2 ERP потрібне для того, щоб ці модулі могли взаємодіяти із зовнішніми системами без ручного дублювання даних. API має повертати не лише статус, а й фіскальний номер та технічну відповідь. Він дає можливість формально описати endpoint-и, параметри, схеми даних, відповіді, помилки й авторизацію. '''Безпека:''' журнал API потрібен для діагностики, але в ньому не можна зберігати паролі, private keys, access tokens, повні реквізити карток, ключі електронного підпису або зайві персональні інформаційні дані. # Покупець оформлює замовлення. '''Зверніть увагу:''' API K2 ERP має працювати не напряму з таблицями бази даних, а через бізнес-логіку системи. * отримати банківські виписки;
* імпортувати платежі;
* зіставити платіж із замовленням;
* створити платіжне доручення;
* отримати статус платежу;
* виконати звірку;
* зберегти банківський документ. '''Для K2 ERP:''' API-документація має бути частиною продукту.<div style="background:#ffebee; border-left:5px solid #e53935; padding:12px; margin:12px 0;">
GET /api/v1/orders/changes?sinceToken=abc123
Можливі операції:
Основним форматом для API K2 ERP здатна бути JSON. GET /api/v1/shipments/{id}
GET /api/v1/inventory?warehouseId=2&sku=ABC-001
POST /api/v1/shipments

<div style="background:#ffebee; border-left:5px solid #e53935; padding:12px; margin:12px 0;">
Приклади версіонування:<syntaxhighlight lang="text">

== Idempotency ==

* зовнішній сервіс тимчасово недоступний;
* стався timeout;
* виникла мережева помилка;
* endpoint повернув 503;
* webhook не доставлено;
* фіскальний сервер не відповів. Варто контролювати:
[[TeamCity]]

* integration ID;
* назву інтеграції;
* тип інтеграції;
* користувача або service account;
* права доступу;
* API token у захищеному вигляді;
* дату створення токена;
* дату останнього використання;
* статус інтеграції;
* request ID;
* correlation ID;
* external ID об’єкта;
* internal ID об’єкта;
* статус синхронізації;
* останню дату синхронізації;
* текст помилки;
* технічну відповідь;
* кількість повторних спроб. PATCH /api/v1/orders/{id}/status
API доставки застосовується для для роботи з логістикою. GET /api/v1/products

Основні задачі API:
Приклад:<syntaxhighlight lang="text">

 "event": "order.created",

* login і password;
* access token;
* refresh token;
* API key;
* OAuth2;
* JWT;
* service account;
* client credentials;
* IP allowlist;
* mTLS для критичних інтеграцій. }
[[Gradle]]

 status

* масовий експорт товарів;
* масове оновлення версій залишків;
* фіскалізація після оплати;
* передавання документів в ЕДО;
* формування SAF-T UA;
* імпорт великих файлів;
* синхронізація маркетплейсів;
* відправлення webhooks;
* повторна обробка помилок.== Типи API ==

[[Java]]
== API для банків ==

 "items": [

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

* базовий URL;
* версію API;
* спосіб авторизації;
* список endpoint-ів;
* приклади запитів;
* приклади відповідей;
* моделі даних;
* помилки;
* rate limits;
* webhooks;
* правила ідемпотентності;
* changelog;
* sandbox-оточення;
* contact support;
* приклади інтеграції. # У картці документа зберігається історія продукту обміну.== Журнал API-запитів ==
{
API K2 ERP застосовують, коли потрібно для автоматизації обміну даними: створення документів, отримання довідників, синхронізації товарів, клієнтів, замовлень, оплат, залишків, бухгалтерських операцій, статусів, інтеграційних подій і результатів обробки. # Магазин надсилає замовлення в K2 ERP через API. Не всі API-операції потрібно виконувати синхронно. sku
Це потрібно для:
 "externalId": "SHOPIFY-10025"
GET /api/v1/products

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

Типові операції:

Контрагенти

ЕДО

Приклади endpoint-ів:
 title: K2 ERP API

 name

* отримання довідників;
* створення документів;
* оновлення версій статусів документів;
* отримання залишків;
* синхронізація товарів;
* синхронізація цін;
* отримання замовлень;
* передавання замовлень;
* обробка оплат;
* передавання даних для фіскалізації;
* отримання фіскальних чеків;
* інтеграційні функції ERP з інтернет-магазинами;
* інтеграційні функції ERP з маркетплейсами;
* інтеграційні функції ERP з банками;
* інтеграційні функції ERP з ЕДО;
* інтеграційні функції ERP з ДПС;
* інтеграційні функції ERP з логістикою;
* робота з мобільними застосунками;
* обмін даними між модулями K2 ERP. Це спрощує інтеграцію та підтримку зовнішніх систем. POST /api/v1/edo/documents
API здатна бути реалізоване як REST API, GraphQL API, WebSocket API, RPC-інтерфейс, webhook-механізм або внутрішній сервісний інтерфейс між модулями.
Це дає можливість інтеграціям не завантажувати всі інформаційні дані щоразу, а отримувати лише потрібні зміни.== Filtering і sorting ==

Документація API

K2 Модуль Magento API K2 ERP здатна використовуватися для інтеграцій із ДПС або сервісами, які передають інформаційні дані до ДПС. Не плутати: API має надавати тільки ті інформаційні дані, які потрібні інтеграції.== Обробка помилок ==

  • XML;
  • CSV;
  • XLSX;
  • YAML;
  • multipart/form-data;
  • binary files;
  • ZIP-архіви;
  • підписані файли. # Магазин отримує залишки. # ERP передає tracking number у магазин. X-RateLimit-Reset: 1715179200

Retry потрібен, якщо:

Приклад відповіді з помилкою:
== Для чого потрібне API K2 ERP ==
 post:
GET /api/v1/edo/documents/{id}/status
== Формат даних ==

</syntaxhighlight>

Приклад:
'''Idempotency''' — це властивість API-запиту, за якої повторне виконання того самого запиту не створює дублікати. order(id: "123") {

Для великих списків API має підтримувати пагінацію. # Документ проходить внутрішню перевірку.== Rate limiting ==
== інформаційні дані, які не можна відкривати через API ==
GET /api/v1/products/by-sku/{sku}
 "createdAt": "2026-05-08T12:30:00Z",
 "externalId": "SHOPIFY-10025",
[[Модуль Prom]]
Можливі операції:
Можливі напрями:
POST /api/v1/payments/liqpay/callback
{
API замовлень застосовується для для створення та оновлення версій замовлень клієнтів. POST /api/v1/payments

* OpenAPI / Swagger;
* Postman Collection;
* Markdown;
* MediaWiki;
* Redoc;
* Developer Portal.[[ДПС]]
 phone
=== Замовлення ===
Це корисно для: 
responses:

Для облікової системи: фіскальний чек має бути пов’язаний із замовленням, оплатою, касиром, зміною, складом, клієнтом і документом продажу. API цін застосовується для для синхронізації прайсів з інтернет-магазинами, маркетплейсами, мобільними застосунками або B2B-порталами.== Sandbox == API K2 ERP здатна використовуватися для інтеграції з інтернет-магазинами: 

}
  • маршрутизацію запитів;
  • авторизацію;
  • rate limiting;
  • логування;
  • перевірку токенів;
  • балансування навантаження;
  • трансформацію запитів;
  • кешування;
  • контроль версій;
  • захист від некоректних запитів.</syntaxhighlight>Або через заголовок:
    '''критично:''' API K2 ERP — це не окремий компонент обліку, а технічний інтерфейс доступу до функцій і даних ERP. # Зовнішній сайт створює замовлення. GET /api/v1/products?updatedFrom=2026-05-01T00:00:00Z

* створити платіж;
* отримати callback;
* перевірити підпис;
* оновити статус оплати;
* створити документ оплати;
* запустити фіскалізацію;
* створити повернення. # API оновлює статус документа в K2 ERP. # Статус замовлення оновлюється.=== Фіскальні чеки ===

* M.E.Doc;
* EDIN;
* СОТА;
* FREDO;
* Вчасно;
* інші оператори ЕДО. API K2 ERP має мати документацію. GET /api/v1/inventory/{sku}
info:

GET /api/v1/companies
Sandbox потрібен для:

* API Gateway;
* компонент авторизації;
* бізнес-сервіси;
* сервіс довідників;
* сервіс документів;
* сервіс залишків;
* сервіс оплат;
* сервіс фіскалізації;
* сервіс інтеграцій;
* журнал обміну;
* систему черг;
* базу даних;
* компонент моніторингу;
* механізм webhooks;
* механізм rate limiting;
* механізм аудиту. API товарів застосовується для для отримання і синхронізації номенклатури. '''Безпека:''' API token, private key, client secret і access token не можна зберігати у відкритому коді, логах, публічних файлах, wiki-сторінках або повідомленнях. Принцип мінімально необхідного доступу важливий для безпеки ERP, персональних даних, платежів і фіскальних операцій. Якщо зовнішня платформа створює документ через API, він має проходити ті самі перевірки, що й документ, створений користувачем у K2 ERP. Через API зовнішні системи можуть читати, створювати або оновлювати інформаційні дані відповідно до прав доступу та бізнес-правил.== API для логістики ==
Можливі варіанти:
 "phone": "+380501112233",
POST /api/v1/fiscal/receipts
POST /api/v1/orders
'''Практичне сценарії використання:''' REST API інтуїтивно використовувати для запитів і команд, а webhooks — для швидкого повідомлення про події без постійного опитування системи.</div>
 "code": "ORDER_ALREADY_EXISTS",

* потребу в якісній документації;
* потребу в стабільному версіонуванні;
* потребу в захисті токенів;
* потребу в логуванні без секретів;
* ризик перевантаження API;
* ризик дублювання документів;
* ризик некоректної фіскалізації;
* ризик неправильного оновлення версій цін;
* ризик неправильних залишків;
* потребу в ідемпотентності;
* потребу в моніторингу;
* потребу в sandbox;
* потребу в тестах;
* потребу в підтримці сумісності. * створено замовлення;
* змінено статус оплати;
* фіскальний чек створено;
* товар оновлено;
* залишок змінився;
* документ підписано в ЕДО;
* замовлення відправлено;
* отримано банківську виписку.== Авторизація і автентифікація ==
Типовий сценарій інтеграції з ЕДО здатна виглядати так:
PATCH /api/v1/counterparties/{id}
[[LiqPay]]

[[СОТА]]
'''OpenAPI''' — це формат опису REST API. Можливі операції:
POST /api/v1/fiscal/refunds

GET /api/v1/orders?cursor=eyJpZCI6MTIzfQ
</div>

Приклад:<syntaxhighlight lang="text">

* отримати ціну товару;
* отримати ціни за типом цін;
* оновити ціну;
* отримати акційну ціну;
* отримати валюту ціни;
* отримати історію зміни ціни. Типова технічна архітектура API K2 ERP здатна включати:

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

GET /api/v1/companies/{id}

PATCH /api/v1/products/{id}

=== Доставка ===

Приклади endpoint-ів:<syntaxhighlight lang="text">

POST /api/v1/fiscal-receipts

=== Ціни ===

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

[[Medoc REST API]]

 "status": "new"

'''Webhooks''' — це механізм, за якого K2 ERP або зовнішня платформа надсилає повідомлення про подію. GET /api/v1/products/{id}

}

{
  • 200 — успішний запит;
  • 201 — створено;
  • 400 — помилка валідації;
  • 401 — не авторизовано;
  • 403 — немає прав доступу;
  • 404 — об’єкт не знайдено;
  • 409 — конфлікт або дублювання;
  • 422 — бізнес-правило не виконано;
  • 429 — перевищено ліміт запитів;
  • 500 — внутрішня помилка сервера;
  • 503 — сервіс тимчасово недоступний.</syntaxhighlight>
  • отримати список контрагентів;
  • створити контрагента;
  • оновити контактні інформаційні дані;
  • знайти контрагента за ЄДРПОУ;
  • знайти контрагента за ІПН;
  • знайти клієнта за телефоном;
  • знайти клієнта за email. Можливі операції:

</syntaxhighlight> API K2 ERP здатна використовуватися для інтеграції з маркетплейсами:

{ 

customer {
number

Висновок

GET /api/v1/orders/{id} 

price
  • підтримки старих інтеграцій;
  • безпечного розвитку API;
  • поступового переходу клієнтів;
  • тестування нових endpoint-ів;
  • документування змін;
  • контролю сумісності. Приклади:

Приклади:

  • неправильний token;
  • token прострочений;
  • немає прав доступу;
  • неправильний формат JSON;
  • відсутнє обов’язкове поле;
  • некоректний SKU;
  • контрагент не знайдений;
  • товар не знайдений;
  • складський облік не знайдений;
  • замовлення вже існує;
  • недостатній залишок;
  • неправильний статус документа;
  • оплата вже проведена;
  • чек уже фіскалізований;
  • помилка зовнішнього сервісу;
  • timeout;
  • дублювання webhook;
  • перевищено rate limit;
  • API-версія застаріла;
  • помилка бізнес-правила. API має перевіряти вхідні інформаційні дані до виконання бізнес-операції. POST /api/v1/orders/{id}/cancel

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

Практичне сценарії використання: для великих каталогів товарів краще використовувати синхронізацію змін, а не щоразу вивантажувати весь каталог на 100%. # Платіжний сервіс надсилає callback про оплату. }

Incremental synchronization

Для інтеграцій потрібно підтримувати повторну обробку помилок.</syntaxhighlight>
"name": "Іван Петренко",
  • Prom;
  • Rozetka;
  • Hotline;
  • інші торгові майданчики. Вони мають зберігатися в захищених сховищах. Окремо варто відзначити сервісів, сайтів, мобільних застосунків, інтеграційних конекторів і внутрішніх компонентів із системою K2 ERP. '201':

Webhooks API K2 ERP

  • тестування інтеграцій;
  • перевірки авторизації;
  • перевірки форматів;
  • навчання партнерів;
  • тестування webhooks;
  • перевірки помилок;
  • тестування фіскалізації в тестовому режимі;
  • перевірки обробки повторних запитів. # K2 ERP створює замовлення клієнта. Рекомендація: для інтернет-магазинів і маркетплейсів API має повертати не бухгалтерський залишок, а доступний до продажу залишок: фактична кількість мінус резерви та інші блокування. Це захищає систему від дублювання при повторному запиті.</syntaxhighlight>

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

API K2 ERP здатна забезпечувати такі функції ERP: GET /api/v1/counterparties

API для маркетплейсів

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

Типовий обмін:

Джерела

}
"data": {

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

  • доступність API;
  • середній час відповіді;
  • кількість запитів;
  • кількість помилок;
  • error rate;
  • кількість 401 і 403;
  • кількість 429;
  • кількість 500;
  • повільні endpoint-и;
  • стан черг;
  • статус зовнішніх інтеграцій;
  • помилки webhooks;
  • невдалі фіскалізації;
  • невдалі платежі. GraphQL API здатна використовуватися тоді, коли клієнту потрібно гнучко отримувати лише потрібні поля, об’єднувати кілька типів даних в одному запиті або будувати складні інтерфейси. API має підтримувати фільтрацію та сортування. # K2 ERP перевіряє оплату. # Магазин показує покупцю статус замовлення. "externalId": "SHOPIFY-10025",

</syntaxhighlight> API K2 ERP потрібно моніторити. # За потреби виконується фіскалізація.== Черги і асинхронна обробка ==

Приклад замовлення:

GET /api/v1/prices?priceType=shopify
Можливі операції:

POST /api/v1/edo/documents/{id}/send
Асинхронно можуть оброблятися:

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

  • створити електронний документ;
  • відправити документ;
  • отримати статус;
  • отримати квитанцію;
  • отримати підписаний файл;
  • обробити відхилення;
  • зберегти технічну відповідь. "payment": {

Якісне API K2 ERP має підтримувати авторизацію, версіонування, REST або GraphQL endpoint-и, webhooks, ідемпотентність, журнал обміну, зрозумілі помилки, документацію OpenAPI, sandbox, моніторинг, rate limiting і безпечне зберігання секретів. "method": "liqpay", FREDO

Pagination

"details": {
  • Shopify;
  • Magento;
  • Wix;
  • OpenCart;
  • Tilda Commerce;
  • власний сайт;
  • мобільний застосунок;
  • B2B-портал;
  • B2C-портал.== API Gateway ==

Idempotency-Key: 9b2d7a8e-5c1a-4e6a-9e22-123456789abc Sandbox — це тестове середовище API, у якому інтеграції можуть перевірятися без впливу на production-дані. # ПРРО повертає фіскальний номер. * створити ТТН;

  • отримати статус доставки;
  • отримати вартість доставки;
  • отримати відділення;
  • передати tracking number;
  • створити е-ТТН;
  • отримати підтвердження доставки. # Покупцю надсилається електронний чек. До основних переваг API K2 ERP можна віднести:

SAF-T UA

X-RateLimit-Remaining: 850

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