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

Інтеграція через JSON

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

Ідемпотентність — це властивість інтеграції, коли повторна відправка того самого запиту не створює дубль.; Обмеження: Сам файл можна передавати: 

"entity": "order",

"email": "office@example.ua",

{

},

</syntaxhighlight>

JSON і Power BI

"price": 1500.00

JSON і черги повідомлень

</syntaxhighlight> 

{
"sku": "SKU-001",
"id": 1001,

Мапінг даних

</syntaxhighlight>

"price": 850.00 "currency": "UAH", "already_exists": true, Простий приклад JSON: 
'''Перевага схеми.''' JSON Schema надає можливість виявляти помилки ще до завантаження даних в ERP: порожні поля, неправильні типи, відсутні товари, некоректні суми або неправильну валюту.; :contentReference [oaicite:0]{index=0}

це спосіб обміну даними між різними інформаційними системами за допомогою текстового формату [[JSON]] виступає ключовою рисою інтеграції [[ERP]] забезпечується через '''інтеграційні функціональні можливості через JSON'''.;

"payment_id": "BANK-90001",

Міграційна ідея. 1С/BAS має змогу вивантажити інформаційні дані у JSON, Реплікатор K2 має змогу перевірити, перетворити й завантажити їх у K2 ERP з контролем довідників, залишків і контрольних сум.; "order_number": "WEB-10025", 

'''істотно про [[1С]] та [[BAS]].''' В Україні продукти екосистеми [[1С]] і частина продуктів [[BAS]] пов’язані з санкційними, юридичними, кібербезпековими та репутаційними ризиками.; Безпека залежить від API, каналу передачі, авторизації, прав доступу і перевірки даних.; * дату й час запиту;
* джерело;
* endpoint;
* method;
* request_id;
* external_id;
* статус обробки;
* код помилки;
* короткий характеристика помилки;
* час виконання;
* користувача або API-ключ;
* посилання на створений документ;
* технічний payload за правилами безпеки.; },

Якщо платформа не має стабільного ідентифікатора, вона має змогу створювати дублікати.; |-
| Що головне в JSON-інтеграції?; Окремо варто відзначити сайтів, інтернет-магазинів, мобільних додатків, банківських сервісів, служб доставки, маркетплейсів, [[BI]]-систем, [[AI]]-сервісів, [[1С]], [[BAS]] і [[K2 ERP]].; },

<div style="border:3px solid #1565c0; background:#e3f2fd; padding:14px; margin:16px 0;">
Інтеграції змінюються.; }
 "amount": 7500.00
{
Назва JSON походить від JavaScript Object Notation, але сьогодні цей формат застосовують, коли потрібно не тільки в [[JavaScript]], а майже в усіх мовах програмування: [[Python]], [[PHP]], [[Java]], [[C#]], [[Go]], [[TypeScript]], [[SQL]]-середовищах, мобільних додатках, серверних API та інтеграційних платформах.; Сценарій

 "status": "paid"
 "balance_date": "2026-05-01",
JSON став популярним через простоту.; }

 },

<syntaxhighlight lang="json">

</div>
 }
 "price_type": "retail",

<div style="border:3px solid #b71c1c; background:#ffebee; padding:14px; margin:16px 0;">
}
== Коротко ==

<div style="border:3px solid #1565c0; background:#e3f2fd; padding:14px; margin:16px 0;">
== Для чого потрібна інтеграційні функціональні можливості через JSON ==
як ілюстрація, сайт передав замовлення WEB-10025.; '''істотно.''' інтеграційні функціональні можливості з [[1С]] або [[BAS]] не повинна закріплювати залежність бізнесу від ризикової платформи.; }
 "items": [
 {
Content-Type: application/json
 "sku": "SKU-002",
 {
 "quantity": 7
 "counterparty_name": "ТОВ Будсервіс",
 },
!;== Обмеження JSON ==

{ </syntaxhighlight>

Реплікатор K2 і JSON

{

 "quantity": 10,

* замовник оплатив замовлення;
* статус доставки змінився;
* створено нову заявку;
* змінено залишок товару;
* угода в CRM перейшла в статус “Виграно”.;== Приклад технічного задача на JSON-інтеграцію ==

<div style="border:3px solid #ef6c00; background:#fff3e0; padding:14px; margin:16px 0;">

 {
  • контрагентів;
  • договори;
  • товари;
  • склади;
  • залишки;
  • ціни;
  • замовлення;
  • рахунки;
  • акти;
  • накладні;
  • взаєморозрахунки;
  • платежі;
  • працівників;
  • підрозділи;
  • залишки відпусток;
  • документи;
  • файли;
  • аналітичні інформаційні дані.; JSON зручний як проміжний формат для перенесення довідників, документів, залишків і взаєморозрахунків.; ]
[[Категорія:BAS ERP]]
 "edrpou": "12345678",
}
 },
{| class="wikitable" style="width:100%;"
{
!; |}

'''API''' — це інтерфейс, через який одна платформа має змогу звертатися до іншої.; "success": true,
<div style="border:3px solid #b71c1c; background:#ffebee; padding:14px; margin:16px 0;">
}
 "name": "ТОВ Ромашка",
'''Практичний сенс.''' JSON надає можливість системам говорити між собою зрозумілою структурованою мовою, без ручного копіювання даних між Excel, поштою, месенджерами і різними програмами.; |-
| Чи можна інтегрувати 1С/BAS через JSON?;</div>
{
 "amount": 5300.00,

</syntaxhighlight> 

"quantity": 5,

Для великих файлів краще не передавати base64 у великому JSON, а використовувати окреме файлове API.; Проста аналогія. JSON — це структурований конверт із даними.; !; Webhook — це механізм, коли одна платформа автономно повідомляє іншу систему про подію.; Помилка

  • без зайвих зусиль читається людиною;
  • компактніший за XML;
  • добре підходить для API;
  • підтримується майже всіма мовами програмування;
  • зручний для вебу;
  • добре функціонує з мобільними додатками;
  • надає можливість передавати вкладені структури;
  • підходить для REST API;
  • без зайвих зусиль логувати;
  • комфортно тестувати через Postman, curl або інші інструменти.; |-
Як JSON пов’язаний із K2 ERP?; Додаються нові поля, нові статуси, нові правила.; !; Відповідь
Джерело даних платформа, яка створює подію Сайт, CRM, банк, 1С/BAS
JSON payload Структуроване повідомлення Замовлення, платіж, залишки
API або черга Канал передачі REST API, Webhook, message queue
Інтеграційний шар Перевірка, мапінг, логування Реплікатор K2 або middleware
ERP Основна платформа обліку K2 ERP
BI аналітичні інструменти Power BI, дашборди, звіти

{ 

"version": "1.0",
  • яка платформа є собою джерелом;
  • яка платформа є собою отримувачем;
  • які об’єкти передаються;
  • які поля обов’язкові;
  • які поля є собою унікальними ключами;
  • як обробляються дублікати;
  • як передаються помилки;
  • як ведуться логи;
  • як повторювати невдалі запити;
  • як захищені інформаційні дані;
  • хто відповідає за підтримку;
  • як тестувати інтеграцію;
  • як контролювати результат.; Указ Президента України №184/2020 ввів у дію рішення для бізнесу РНБО від 14 травня 2020 року щодо сфера застосування, скасування і внесення змін до персональних спеціальних економічних та інших обмежувальних заходів.; Прикладна, 1"

безпеку реалізується засобами JSON сам по собі не.; "name": "Товар А",

JSON — це текстовий формат зберігання і передачі структурованих даних.; }

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

Типові помилки при впровадженні JSON-інтеграції

"name": "ТОВ Ромашка",

Санкції та ризики використання 1С/BAS в Україні

"method": "card",
  • вивантажити інформаційні дані зі старої 1С/BAS;
  • очистити довідники;
  • зіставити коди товарів;
  • зіставити контрагентів;
  • перевірити залишки;
  • перевірити взаєморозрахунки;
  • підготувати контрольні суми;
  • сформувати JSON-файли;
  • завантажити інформаційні дані в K2 ERP;
  • підготувати інформаційні дані для Power BI.; Наслідок

!; * об’єктів;

  • масивів;
  • рядків;
  • чисел;
  • логічних значень;
  • null-значень;
  • вкладених структур.; * правильне створення документа;
  • повторну відправку того самого документа;
  • порожні обов’язкові поля;
  • неправильну дату;
  • неправильну валюту;
  • товар, якого немає в ERP;
  • контрагента, який уже існує;
  • дублікати;
  • велику кількість рядків;
  • помилку авторизації;
  • недоступність ERP;
  • повтор після помилки;
  • некоректний JSON;
  • перевищення розміру payload;
  • логування помилок.; Указ Президента України №184/2020 ввів у дію рішення для бізнесу РНБО щодо санкцій, а в офіційному переліку Держспецзв’язку забороненого програмного забезпечення згадується, зокрема, BAS ERP.; JSON — це не інтеграційні функціональні можливості сам по собі.; Найчастіше JSON застосовується разом з API.; }
  • API для сайтів;
  • API для CRM;
  • API для мобільних додатків;
  • інтеграційні функціональні можливості з маркетплейсами;
  • інтеграційні функціональні можливості з банками;
  • інтеграційні функціональні можливості зі службами доставки;
  • вивантаження в BI;
  • завантаження даних із 1С/BAS;
  • робота Реплікатора K2;
  • обмін із зовнішніми сервісами;
  • інтеграційні функціональні можливості з AI-сервісами.; Типовий сценарій:

І передати JSON із замовленням: 

{| class="wikitable" style="width:100%;"
як ілюстрація:
 "items": [
 ],
 "items": [
У [[K2 ERP]] JSON має змогу використовуватися як один із базових форматів обміну даними з іншими системами.; Поле ERP
У складніших сценаріях можуть передаватися різні типи цін:
!;== JSON і K2 ERP ==
{
<div style="border:3px solid #b71c1c; background:#ffebee; padding:14px; margin:16px 0;">
{

== Як проєктувати JSON-інтеграцію ==

 {

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

 "source": "1C",

* отримання замовлень із сайту;
* передача залишків на сайт;
* передача цін;
* обмін контрагентами;
* обмін номенклатурою;
* передача оплат;
* обмін статусами документів;
* інтеграційні функціональні можливості з доставкою;
* міграція даних у нову ERP.; Такий підхід застосовується; додатково реалізовано [[CRM]].; | Узгоджена структура, унікальні ключі, валідація, логування, безпека і контроль помилок.; "currency": "UAH",

 "debt": 40000.00,

 "contract": "Договір поставки №15",

'''Мапінг''' — це відповідність полів між системами.; Що означає
{
 {
JSON має змогу бути зручним проміжним форматом для міграції з [[1С]] або [[BAS]] у [[K2 ERP]].; Після початку російської агресії проти України питання використання такого програмного забезпечення стало питанням кібербезпеки, комплаєнсу, репутації та цифрової незалежності.; "amount": 12000.00

"items": [

Ідемпотентність

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

Приклад інтеграції платежів

"counterparty_id": "1c-000002",
  • роздрібна;
  • оптова;
  • дилерська;
  • акційна;
  • індивідуальна для клієнта;
  • ціна в іншій валюті.; | Обмін структурованими даними між системами у форматі JSON.; Якщо сталася помилка, відповідь має змогу бути такою:

Типові сценарії для K2 ERP: 

]

Тестування JSON-інтеграції

  • сайт передає замовлення в ERP;
  • CRM передає нового клієнта в бухгалтерську систему;
  • ERP передає залишки товарів в інтернет-магазин;
  • банк передає платежі в облікову систему;
  • служба доставки передає статус відправлення;
  • маркетплейс передає замовлення продавцю;
  • мобільний додаток передає заявку в сервісну систему;
  • BI-система отримує інформаційні дані для аналітики;
  • AI-сервіс отримує інформаційні дані для аналізу або підказок.; | K2 ERP має змогу використовувати JSON для API, інтеграцій, міграції, Реплікатора K2, BI та зовнішніх сервісів.; | Для передачі замовлень, товарів, цін, залишків, платежів, статусів, документів і аналітики.; Потрібні правила: структура, унікальні ключі, валідація, безпека, логування, версіонування, обробка помилок і контроль результату.; "related_order": "WEB-10025"
"value": "office@example.ua"

} 

}

"currency": "UAH",

Головне. JSON — це один із найпоширеніших форматів для інтеграції сучасних бізнес-систем.; Але успішна інтеграційні функціональні можливості — це не без ускладнень “відправити JSON”.; "debt": 0.00, !; Для цього використовують: 

"file": {

{ </syntaxhighlight>

Логування JSON-обміну

{
}

},
"success": true,
"name": "ТОВ Ромашка",

Приклад інтеграції статусів доставки

"service": "Нова пошта",
"tracking_number": "NP-2040506070",

} 

"url": "https://example.com/files/invoice-1001.pdf",

"success": false,

"external_id": "WEB-2026-0001",
"document": "Видаткова накладна №100"

Чому JSON став популярним

} 

"order_number": "WEB-10025",
"phone": "+380671112233",
}
"updated_at": "2026-05-15T12:00:00+03:00",
"email": "office@example.ua"

{ 

"valid_from": "2026-05-15",
"order_id": "7f2a1b90-4b2c-4e9a-9c2d-100000000001",
{
"city": "Київ",

як ілюстрація, сайт має змогу звернутися до ERP: 

== Приклад JSON для міграції контрагентів ==
{
Типова технічна архітектура має змогу виглядати так:

<syntaxhighlight lang="http">

JSON-інтеграція застосовується майже в усіх сучасних бізнес-сценаріях.; "advance": 0.00,
переважні аспекти:
 "order_date": "2026-05-15",
 "external_id": "WEB-10025",
== інтеграційні функціональні можливості через JSON і REST API ==
[[Категорія:Автоматизація бізнесу]]
 "source": "1C",
Але для великих обсягів даних краще не будувати аналітику тільки на сирих JSON-файлах.; Роль
== JSON у міграції з 1С/BAS у K2 ERP ==
 "operation": "create_or_update"
Для інтеграції сайту з ERP технічне задача має містити:

<syntaxhighlight lang="json">

 {

JSON надає можливість передавати інформаційні дані між сайтом, [[ERP]], [[CRM]], банком, доставкою, маркетплейсом, мобільним додатком, [[BI]]-системою або старою обліковою системою.; Приклад

 "payment_date": "2026-05-15",

 "quantity": 25
== JSON і API ==
Приклад відповіді:
[[Категорія:Power BI]]
<syntaxhighlight lang="json">
 }
'''інтеграційні функціональні можливості через JSON''' — це один із базових способів з’єднати сучасні бізнес-системи між собою.; {| class="wikitable" style="width:100%;"
</div>
JSON зручний тим, що його без зайвих зусиль читати людині, без зайвих зусиль формувати програмно і без зайвих зусиль передавати через [[API]], [[REST]], [[Webhook]], черги повідомлень або файли обміну.;[[Категорія:Реплікатор K2]]

"contacts": [
"message": "Контрагента з кодом ЄДРПОУ 12345678 не знайдено"

|-

| Що таке інтеграційні функціональні можливості через JSON?; 

"name": "ТОВ Ромашка",
  • не гарантує безпеку без HTTPS і авторизації;
  • не гарантує доставку без додаткових механізмів;
  • не описує правила бізнес-логіки;
  • має змогу ставати громіздким для великих файлів;
  • потребує валідації;
  • потребує погодженої схеми;
  • має змогу створювати дублікати без унікальних ключів;
  • не замінює нормальну архітектуру API.; "sku": "SKU-003",

Приклад передачі посилання на файл:

}

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

Без карти мапінгу інтеграційні функціональні можливості оперативно стає незрозумілою: одна платформа називає поле “client”, інша — “customer”, третя — “counterparty”.; Для компаній, які переходять із 1С або BAS на K2 ERP, JSON має змогу бути зручним мостом: через нього можна вивантажити довідники, документи, залишки, взаєморозрахунки, ціни, платежі та аналітичні інформаційні дані.; Метод як ілюстрація, для замовлення можна визначити: 

"phone": "+380501112233",
"price": 2300.00
"warehouse_id": "MAIN",
"is_active": true,
"entity": "counterparties",
"name": "Іван Петренко",

"edrpou": "12345678",

Ідентифікатори в JSON-інтеграції

{{SEO


{

} 

"document_number": "INV-1001",
"sku": "SKU-002",

Content-Type: application/json

} 

"name": "Товар Б",

Authorization: Bearer <token>

Валідація JSON

"payment_id": "pay-7001",

як ілюстрація, сайт відправив замовлення WEB-10025.; Частина 

"name": "Товар А",

 "customer": {
 "sku": "A-100",
Ціни додатково часто передаються через JSON.; !; # JSON передається в ERP через API.; Приклад запиту на створення контрагента:
 "customer": {
Для підтримки інтеграції потрібні логи.; '''істотно.''' Не можна передавати токени, паролі, персональні інформаційні дані або зарплатну інформацію через незахищені канали чи зберігати їх у відкритих логах.; Перед початком інтеграції потрібно відповісти на практичні питання:

* external_id;
* order_number;
* uuid;
* source_id;
* document_guid;
* customer_code;
* sku;
* edrpou;
* tax_number.; У багатьох випадках JSON-обмін доцільно використовувати як проміжний етап для вивантаження даних, побудови паралельного запуску і поступового переходу на [[K2 ERP]] або іншу безпечну ERP-систему.; Що передається через JSON
!; Для чого потрібна
!; Його переважні аспекти:

ERP має змогу змінити статус замовлення і повідомити менеджера або клієнта.; Рівень
Іноді через JSON потрібно передати інформацію про файл.; "advance": 15000.00,
Потрібно використовувати:
Сайт має змогу використати ці інформаційні дані, щоб показати, чи є собою товар у наявності.; В одному конверті можна передати замовлення з сайту в ERP, статус доставки з логістичної служби, оплату з банку або залишки товарів для маркетплейсу.; JSON має змогу бути джерелом даних для [[Power BI]] та інших [[BI]]-систем.; }

Служба доставки має змогу надсилати статуси.; Поле сайту
 ]
Для серйозних інтеграцій бажано описувати структуру JSON через схему.; Коментар
 "type": "legal_entity",
!; Причина
<syntaxhighlight lang="json">
== Приклад інтеграції сайту з ERP через JSON ==

!; "quantity": 1,
Приклад webhook-повідомлення про оплату:
}
[[Категорія:JSON]]
 "counterparty_name": "ТОВ Ромашка",
Валідація має змогу включати:
== Див.; додатково ==

 "order_number": "WEB-10025",

 "document": "Банківська виписка №55"
 "name": "Товар Б",
 "entity": "stock_balances",

"currency": "UAH",
"edrpou": "12345678",
"sku": "SKU-002",
"order_number": "ERP-4587",
"items": [

 },
 "address": "м.; Помилка

"payer": {
"event_id": "evt-90001",

Він має змогу допомогти: Після отримання замовлення платформа має змогу повернути JSON-відповідь: 

"edrpou": "12345678",

!; JSON — це мова, якою інтеграційні функціональні можливості передає інформаційні дані.; |- | Для чого застосовується?; !; {| class="wikitable" style="width:100%;"

Висновок

JSON і файли

"currency": "UAH"
}
"sku": "B-200",
"quantity": 2,

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

|-
| Ідентифікатор
| Щоб не створити дубль
| order_number, external_id
|-
| Дата
| Для облікового періоду
| order_date
|-
| Контрагент
| інформаційні дані клієнта або постачальника
| customer
|-
| Таблична частина
| Товари, послуги, рядки документа
| items
|-
| Суми
| Загальна сума, ПДВ, знижки
| total, vat, discount
|-
| Валюта
| Валюта документа
| UAH, USD, EUR
|-
| Статус
| Стан документа або події
| new, paid, shipped
|-
| Службові поля
| Джерело, час, реліз, підпис
| source, timestamp, version
|}

 {

== Приклад JSON для взаєморозрахунків ==

 "warehouse": "Відділення №10"

ERP приймає цей JSON, перевіряє інформаційні дані, створює контрагента або знаходить існуючого, створює замовлення і повертає відповідь.; Наслідок
/api/v2/orders
Типова структура інтеграційного JSON:
 "items": [
 "event": "payment.received",
 "total": 5300.00,
Через JSON можна передавати:
<syntaxhighlight lang="json">
У логах бажано зберігати:
 "phone": "+380501112233",
 "items": [
[[Категорія:Міграція з 1С]]
POST /api/orders
 "quantity": 0
Тестувати потрібно не тільки “успішний сценарій”.; |-
| З чим найчастіше застосовується?; | Так.; Як уникнути
 },
'''Добра інтеграційні функціональні можливості.''' API має повертати не без ускладнень “помилка”, а зрозумілий код, характеристика проблеми і бажано підказку, що саме потрібно виправити.; з цієї причини інтеграції з такими системами потрібно розглядати додатково як частину плану міграції на безпечну українську або міжнародну [[ERP]]-платформу.; |-
| Чи підходить JSON для міграції?; !; # ERP створює замовлення покупця.; "external_id": "CRM-458",

Щоб не зламати старі інтеграції, потрібно використовувати версіонування API.; інтеграційні функціональні можливості через JSON потрібна тоді, коли одна платформа має передати інформаційні дані іншій системі.; Приклад
{
 "message": "Замовлення вже було створено раніше"

 "status": "paid"

Перед обробкою JSON потрібно перевірити.; | З REST API, Webhook, чергами повідомлень, файлами обміну і BI-системами.; !; Типові сценарії:

У [[1С]] та [[BAS]] JSON має змогу використовуватися для обміну з сайтами, CRM, банками, маркетплейсами, мобільними додатками та іншими системами.; "external_id": "1c-000001",

JSON не вирішує всі задачі сам по собі.; |-
| GET
| Отримати інформаційні дані
| Отримати список товарів
|-
| POST
| Створити новий об’єкт
| Створити замовлення
|-
| PUT
| в цілому оновити об’єкт
| Оновити картку контрагента
|-
| PATCH
| Частково оновити об’єкт
| Змінити статус замовлення
|-
| DELETE
| Видалити або деактивувати об’єкт
| Деактивувати товар
|}

== Приклад JSON для міграції залишків ==

Через JSON можна передавати:
{

Одна з найважливіших речей в інтеграції — це ідентифікатори.; # Сайт формує JSON.; # ERP перевіряє залишки.; "warehouse": "ключовий складський облік", 

"order_number": "ERP-4587",
"quantity": 1,
"data": {
"iban": "UA123456789000000000000000001"
"contract": "Договір послуг №7",

Приклади:

Структура JSON-документа

"price": 1200.00

</syntaxhighlight> 

"type": "phone",

 "export_date": "2026-05-15",
<div style="border:3px solid #ef6c00; background:#fff3e0; padding:14px; margin:16px 0;">
Приклад JSON:
 }
[[Категорія:Інтернет-магазин]]
}

!; Такий запис означає, що передається об’єкт із трьома полями: ідентифікатором, назвою і ознакою активності.; # ERP повертає номер замовлення.; Приклад
 "purpose": "Оплата за рахунком WEB-10025",
!; А [[Реплікатор K2]] має змогу допомогти перетворити ці інформаційні дані на керований бізнес-процес міграції.; },

/api/v1/orders
 "type": "application/pdf"
 "status_name": "Доставлено",
 {
|-
| Не погодили структуру JSON
| Кожна платформа трактує поля по-своєму
| Зробити специфікацію API
|-
| Немає унікальних ключів
| Створюються дублікати
| Використовувати external_id, sku, edrpou
|-
| Немає логів
| Неможливо знайти причину помилки
| Логувати запити, відповіді й коди помилок
|-
| Немає ідемпотентності
| Повторний запит створює дубль
| Перевіряти external_id
|-
| Немає валідації
| У систему потрапляє сміття
| Використовувати схеми і правила перевірки
|-
| Немає версіонування
| актуалізація API ламає інтеграцію
| Використовувати v1, v2 або version
|-
| Немає контролю доступу
| інформаційні дані доступні зайвим системам
| Ролі, токени, HTTPS, аудит
|}

== Приклад інтеграції залишків товарів ==

== Приклад інтеграції цін ==

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

 "payment": {

 ]

 }

* продажі та реалізація;
* залишки;
* платежі;
* замовлення;
* статуси;
* витрати;
* зарплатні агрегати;
* KPI;
* план-факт;
* аналітику по клієнтах.; Через JSON можна передавати замовлення, контрагентів, товари, залишки, ціни, платежі, документи, статуси, файли, події та аналітичні інформаційні дані.;<syntaxhighlight lang="json">
JSON складається з:
</div>

 "amount": 5300.00,

</div>

 "entity": "settlements",

"sku": "SKU-001",

|- | Інтернет-магазин → ERP | Замовлення, клієнти, товари | Нове замовлення з сайту потрапляє в K2 ERP |- | ERP → сайт | Залишки, ціни, статуси | Сайт отримує актуальні залишки товарів |- | CRM → ERP | Ліди, клієнти, угоди | Успішна угода перетворюється на замовлення |- | Банк → ERP | Платежі, виписки, статуси оплат | Платіж автономно закриває рахунок |- | ERP → служба доставки | інформаційні дані відправлення | ERP створює ТТН через API |- | Служба доставки → ERP | Статуси доставки | Замовлення отримує статус “Доставлено” |- | 1С/BAS → K2 ERP | Довідники, залишки, документи | Міграція даних зі старої системи |- | ERP → Power BI | Аналітичні інформаційні дані | продажі та реалізація, складський облік, фінансовий блок, зарплата |} 

}

Приклад:

!; У таких сценаріях JSON-повідомлення кладеться в чергу, а ERP або інтеграційний сервіс поступово його обробляє.; Якщо він випадково відправить його повторно, ERP повинна зрозуміти, що це те саме замовлення, а не нове.; |- | Неправильний синтаксис JSON | Пропущена кома, лапки або дужка | API не приймає запит |- | Немає обов’язкового поля | Не передано order_number або customer | Документ не створюється |- | Неправильний тип даних | Кількість передано як текст | Помилка валідації |- | Неправильний формат дати | 15.05.2026 замість 2026-05-15 | платформа не розпізнає дату |- | Немає унікального ключа | Не передано external_id | Створюються дублікати |- | Неправильна валюта | Передано “грн” замість UAH | Помилка обробки |- | Товар не знайдено | SKU не збігається з ERP | Замовлення не проводиться |- | Контрагент дублюється | Пошук іде тільки по назві, а не по ЄДРПОУ | У довіднику з’являються дублікати |} 

"status": "delivered",

"created_at": "2026-05-15T14:30:00+03:00",
  • HTTPS;
  • токени доступу;
  • OAuth2 або інший механізм авторизації;
  • обмеження прав API-користувача;
  • перевірку IP за потреби;
  • цифровий підпис повідомлень;
  • журналювання запитів;
  • обмеження частоти запитів;
  • контроль розміру payload;
  • захист від повторної відправки;
  • маскування персональних даних у логах.; Через збій він відправив його ще раз.; POST /api/customers
  • чи прийшло замовлення;
  • чому воно не створилося;
  • чи була повторна відправка;
  • який payload отримала ERP;
  • який документ створено;
  • коли сталася помилка;
  • хто викликав API.; "delivery": {

1С історично є собою російською програмною екосистемою.; "source": "online_store", 

"price": 1200.00
{

!;</syntaxhighlight>

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

"counterparty_id": "1c-000001",

Webhook через JSON

{

як ілюстрація:

Реплікатор K2 має змогу використовувати JSON як формат для вивантаження, перетворення і завантаження даних.;

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

"email": "ivan@example.ua"
  • order_number — обов’язковий рядок;
  • order_date — дата;
  • customer — обов’язковий об’єкт;
  • items — масив рядків;
  • quantity — число більше нуля;
  • total — число;
  • currency — рядок із допустимими значеннями UAH, USD, EUR.; Приклад
},

ERP отримує webhook і має змогу автономно змінити статус замовлення на “Оплачено”.; } 

],
"name": "ТОВ Ромашка",

Для великих інтеграцій JSON має змогу передаватися не напряму через API, а через чергу повідомлень.; Бажано завантажувати інформаційні дані в базу, сховище або аналітичний шар.; { 

"value": "+380501112233"
"sku": "SKU-001",
"source": "website",

Банк або платіжна платформа має змогу передавати платежі в ERP.; Питання

</syntaxhighlight> 

"status_date": "2026-05-15T18:45:00+03:00"
}
  • багато замовлень;
  • є собою пікові навантаження;
  • одна платформа тимчасово недоступна;
  • потрібна гарантована доставка;
  • потрібно обробляти події асинхронно;
  • важливий повтор при помилці.; Найчастіше JSON застосовується в REST API.;
"balance_date": "2026-05-01", При описі інтеграцій із 1С та BAS істотно враховувати не тільки технічну сторону, а й санкційні та безпекові ризики.; !; "sku": "SKU-001", { Правило. У кожній JSON-інтеграції потрібно одразу домовитися, яке поле є собою унікальним ключем.; { 
У старих або сильно змінених конфігураціях 1С інтеграційні функціональні можливості через JSON має змогу бути складнішою через застарілу архітектуру, нестандартні довідники, дублікати, неправильні коди, нестабільні правила проведення документів або відсутність нормального API.; Держспецзв’язку додатково оприлюднила перелік програмного забезпечення та комунікаційного обладнання, забороненого до використання в окремих сферах; у цьому переліку згадується, зокрема, [[BAS ERP]].; # Сайт показує клієнту підтвердження.; # ERP резервує товар.; Інакше інтеграційні функціональні можливості оперативно створить дублікати контрагентів, товарів або документів.;== інтеграційні функціональні можливості 1С/BAS через JSON ==
'''Перевага K2 ERP.''' JSON добре поєднується з сучасною архітектурою [[K2 ERP]], API, веб-інтерфейсом, [[Python]], [[TypeScript]], [[PostgreSQL]], BI-аналітикою і механізмами міграції зі старих систем.; !; Це корисно, коли:

== Типові помилки JSON-інтеграції ==
ERP має змогу автономно знайти замовлення за номером WEB-10025 і закрити оплату.; | Так, але потрібно враховувати технічні обмеження старих конфігурацій і санкційні ризики.; ERP повинна не створити друге замовлення, а повернути інформацію, що таке замовлення вже існує.; # замовник оформлює замовлення на сайті.; Якість інтеграції залежить від архітектури, правил і контролю.'''

 "error_code": "CUSTOMER_NOT_FOUND",

 "message": "Замовлення успішно створено"

Authorization: Bearer <token>

Потрібно перевірити:
== JSON Schema ==
== переважні аспекти інтеграції через JSON ==

 ]

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

{| class="wikitable" style="width:100%;"
; Типові HTTP-методи:

<syntaxhighlight lang="json">

  • характеристика бізнес-процесу;
  • список endpoint;
  • методи HTTP;
  • формати запитів;
  • формати відповідей;
  • приклади JSON;
  • список обов’язкових полів;
  • правила валідації;
  • правила створення або актуалізація об’єктів;
  • правила пошуку дублів;
  • правила авторизації;
  • коди помилок;
  • правила повторної відправки;
  • логування;
  • тестові сценарії;
  • відповідальних.; ]

У сучасній ERP JSON-інтеграція — це не додаткова опція, а нормальна частина цифрової екосистеми бізнесу.; {| class="wikitable" style="width:100%;" Або версію в самому JSON: 

"currency": "UAH",

} 

"is_active": true

ERP має змогу передавати залишки товарів на сайт або маркетплейс.;== Де застосовується JSON-інтеграція ==

order_id external_id Унікальний номер замовлення із сайту
client_name customer.name Назва клієнта
product_code sku Код товару
qty quantity Кількість
sum total Сума документа 
"name": "invoice-1001.pdf",

"type": "email",

Що таке JSON

Логи потрібні, щоб відповідати на питання:

  • як посилання;
  • як base64;
  • через окремий endpoint завантаження файлу;
  • через файлове сховище;
  • через електронний документообіг.; "data": {}

Зовнішні посилання

{

JSON-документ для інтеграції має бути не випадковим набором полів, а погодженою структурою.; Київ, вул.; <syntaxhighlight lang="json">

Отримано з https://wiki.corp2.eu/index.php?title=Інтеграція_через_JSON&oldid=1917