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

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

Матеріал з K2 ERP Wiki
Версія від 11:56, 15 травня 2026, створена R (обговорення | внесок) (Створена сторінка: {{DISPLAYTITLE:Інтеграція через JSON}} {{SEO |title=Інтеграція через JSON — API, ERP, 1С, BAS, K2 ERP, приклади запитів і обмін даними |description=Інтеграція через JSON: що це таке, як працює JSON-обмін між ERP, CRM, сайтами, 1С, BAS, K2 ERP, API, REST, Webhook, приклади запитів і відповідей, помилки, безпека,...)
(різн.) ← Попередня версія | Поточна версія (різн.) | Новіша версія → (різн.)


SEO title: Інтеграція через JSON — API, ERP, 1С, BAS, K2 ERP, приклади запитів і обмін даними SEO description: Інтеграція через JSON: що це таке, як працює JSON-обмін між ERP, CRM, сайтами, 1С, BAS, K2 ERP, API, REST, Webhook, приклади запитів і відповідей, помилки, безпека, логування, міграція даних. SEO keywords: інтеграція через JSON, JSON API, REST API, ERP API, інтеграція 1С JSON, інтеграція BAS JSON, K2 ERP API, обмін даними JSON, webhook JSON, інтеграція сайту з ERP, інтеграція CRM з ERP, міграція даних JSON, автоматизація бізнесу, українська ERP Alternative to:


Інтеграція через JSON — це спосіб обміну даними між різними інформаційними системами за допомогою текстового формату JSON. Такий підхід використовується для інтеграції ERP, CRM, сайтів, інтернет-магазинів, мобільних додатків, банківських сервісів, служб доставки, маркетплейсів, BI-систем, AI-сервісів, , BAS та K2 ERP.

JSON зручний тим, що його легко читати людині, легко формувати програмно і легко передавати через API, REST, Webhook, черги повідомлень або файли обміну.

Головне. JSON — це один із найпоширеніших форматів для інтеграції сучасних бізнес-систем. Через JSON можна передавати замовлення, контрагентів, товари, залишки, ціни, платежі, документи, статуси, файли, події та аналітичні дані.

Проста аналогія. JSON — це структурований конверт із даними. В одному конверті можна передати замовлення з сайту в ERP, статус доставки з логістичної служби, оплату з банку або залишки товарів для маркетплейсу.

Важливо про та BAS. В Україні продукти екосистеми і частина продуктів BAS пов’язані з санкційними, юридичними, кібербезпековими та репутаційними ризиками. Указ Президента України №184/2020 ввів у дію рішення РНБО щодо санкцій, а в офіційному переліку Держспецзв’язку забороненого програмного забезпечення згадується, зокрема, BAS ERP. Тому інтеграції з такими системами потрібно розглядати також як частину плану міграції на безпечну українську або міжнародну ERP-платформу.

Що таке JSON

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

Назва JSON походить від JavaScript Object Notation, але сьогодні цей формат використовується не тільки в JavaScript, а майже в усіх мовах програмування: Python, PHP, Java, C#, Go, TypeScript, SQL-середовищах, мобільних додатках, серверних API та інтеграційних платформах.

JSON складається з:

  • об’єктів;
  • масивів;
  • рядків;
  • чисел;
  • логічних значень;
  • null-значень;
  • вкладених структур.

Простий приклад JSON:

{
  "id": 1001,
  "name": "ТОВ Ромашка",
  "is_active": true
}

Такий запис означає, що передається об’єкт із трьома полями: ідентифікатором, назвою і ознакою активності.

Для чого потрібна інтеграція через JSON

Інтеграція через JSON потрібна тоді, коли одна система має передати дані іншій системі.

Наприклад:

  • сайт передає замовлення в ERP;
  • CRM передає нового клієнта в бухгалтерську систему;
  • ERP передає залишки товарів в інтернет-магазин;
  • банк передає платежі в облікову систему;
  • служба доставки передає статус відправлення;
  • маркетплейс передає замовлення продавцю;
  • мобільний додаток передає заявку в сервісну систему;
  • BI-система отримує дані для аналітики;
  • AI-сервіс отримує дані для аналізу або підказок.

Практичний сенс. JSON дозволяє системам говорити між собою зрозумілою структурованою мовою, без ручного копіювання даних між Excel, поштою, месенджерами і різними програмами.

Де використовується JSON-інтеграція

JSON-інтеграція використовується майже в усіх сучасних бізнес-сценаріях.

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

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

JSON став популярним через простоту.

Його переваги:

  • легко читається людиною;
  • компактніший за XML;
  • добре підходить для API;
  • підтримується майже всіма мовами програмування;
  • зручний для вебу;
  • добре працює з мобільними додатками;
  • дозволяє передавати вкладені структури;
  • підходить для REST API;
  • легко логувати;
  • зручно тестувати через Postman, curl або інші інструменти.

JSON і API

Найчастіше JSON використовується разом з API.

API — це інтерфейс, через який одна система може звертатися до іншої.

Наприклад, сайт може звернутися до ERP:

POST /api/orders
Content-Type: application/json
Authorization: Bearer <token>

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

{
  "order_number": "WEB-10025",
  "order_date": "2026-05-15",
  "customer": {
    "name": "ТОВ Ромашка",
    "edrpou": "12345678",
    "phone": "+380501112233",
    "email": "office@example.ua"
  },
  "items": [
    {
      "sku": "A-100",
      "name": "Товар А",
      "quantity": 2,
      "price": 1500.00
    },
    {
      "sku": "B-200",
      "name": "Товар Б",
      "quantity": 1,
      "price": 2300.00
    }
  ],
  "total": 5300.00,
  "currency": "UAH"
}

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

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

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

{
  "success": true,
  "order_id": "7f2a1b90-4b2c-4e9a-9c2d-100000000001",
  "order_number": "ERP-4587",
  "message": "Замовлення успішно створено"
}

Якщо сталася помилка, відповідь може бути такою:

{
  "success": false,
  "error_code": "CUSTOMER_NOT_FOUND",
  "message": "Контрагента з кодом ЄДРПОУ 12345678 не знайдено"
}

Добра інтеграція. API має повертати не просто “помилка”, а зрозумілий код, опис проблеми і бажано підказку, що саме потрібно виправити.

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

JSON-документ для інтеграції має бути не випадковим набором полів, а погодженою структурою.

Типова структура інтеграційного JSON:

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

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

Одна з найважливіших речей в інтеграції — це ідентифікатори.

Якщо система не має стабільного ідентифікатора, вона може створювати дублікати.

Наприклад, сайт передав замовлення WEB-10025. Якщо він випадково відправить його повторно, ERP повинна зрозуміти, що це те саме замовлення, а не нове.

Для цього використовують:

  • external_id;
  • order_number;
  • uuid;
  • source_id;
  • document_guid;
  • customer_code;
  • sku;
  • edrpou;
  • tax_number.

Приклад:

{
  "external_id": "WEB-10025",
  "source": "online_store",
  "operation": "create_or_update"
}

Правило. У кожній JSON-інтеграції потрібно одразу домовитися, яке поле є унікальним ключем. Інакше інтеграція швидко створить дублікати контрагентів, товарів або документів.

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

Найчастіше JSON використовується в REST API.

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

Метод Що означає Приклад
GET Отримати дані Отримати список товарів
POST Створити новий об’єкт Створити замовлення
PUT Повністю оновити об’єкт Оновити картку контрагента
PATCH Частково оновити об’єкт Змінити статус замовлення
DELETE Видалити або деактивувати об’єкт Деактивувати товар

Приклад запиту на створення контрагента:

POST /api/customers
Content-Type: application/json
Authorization: Bearer <token>
{
  "external_id": "CRM-458",
  "name": "ТОВ Ромашка",
  "edrpou": "12345678",
  "phone": "+380501112233",
  "email": "office@example.ua",
  "address": "м. Київ, вул. Прикладна, 1"
}

Webhook через JSON

Webhook — це механізм, коли одна система автоматично повідомляє іншу систему про подію.

Наприклад:

  • клієнт оплатив замовлення;
  • статус доставки змінився;
  • створено нову заявку;
  • змінено залишок товару;
  • угода в CRM перейшла в статус “Виграно”.

Приклад webhook-повідомлення про оплату:

{
  "event": "payment.received",
  "event_id": "evt-90001",
  "created_at": "2026-05-15T14:30:00+03:00",
  "data": {
    "payment_id": "pay-7001",
    "order_number": "WEB-10025",
    "amount": 5300.00,
    "currency": "UAH",
    "status": "paid"
  }
}

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

Приклад інтеграції сайту з ERP через JSON

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

  1. Клієнт оформлює замовлення на сайті.
  2. Сайт формує JSON.
  3. JSON передається в ERP через API.
  4. ERP створює замовлення покупця.
  5. ERP перевіряє залишки.
  6. ERP резервує товар.
  7. ERP повертає номер замовлення.
  8. Сайт показує клієнту підтвердження.

Приклад JSON:

{
  "source": "website",
  "external_id": "WEB-2026-0001",
  "customer": {
    "name": "Іван Петренко",
    "phone": "+380671112233",
    "email": "ivan@example.ua"
  },
  "delivery": {
    "service": "Нова пошта",
    "city": "Київ",
    "warehouse": "Відділення №10"
  },
  "items": [
    {
      "sku": "SKU-001",
      "quantity": 1,
      "price": 1200.00
    }
  ],
  "payment": {
    "method": "card",
    "status": "paid"
  }
}

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

ERP може передавати залишки товарів на сайт або маркетплейс.

{
  "warehouse_id": "MAIN",
  "updated_at": "2026-05-15T12:00:00+03:00",
  "items": [
    {
      "sku": "SKU-001",
      "quantity": 25
    },
    {
      "sku": "SKU-002",
      "quantity": 0
    },
    {
      "sku": "SKU-003",
      "quantity": 7
    }
  ]
}

Сайт може використати ці дані, щоб показати, чи є товар у наявності.

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

Ціни також часто передаються через JSON.

{
  "price_type": "retail",
  "currency": "UAH",
  "valid_from": "2026-05-15",
  "items": [
    {
      "sku": "SKU-001",
      "price": 1200.00
    },
    {
      "sku": "SKU-002",
      "price": 850.00
    }
  ]
}

У складніших сценаріях можуть передаватися різні типи цін:

  • роздрібна;
  • оптова;
  • дилерська;
  • акційна;
  • індивідуальна для клієнта;
  • ціна в іншій валюті.

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

Банк або платіжна система може передавати платежі в ERP.

{
  "payment_id": "BANK-90001",
  "payment_date": "2026-05-15",
  "payer": {
    "name": "ТОВ Ромашка",
    "edrpou": "12345678",
    "iban": "UA123456789000000000000000001"
  },
  "amount": 5300.00,
  "currency": "UAH",
  "purpose": "Оплата за рахунком WEB-10025",
  "related_order": "WEB-10025"
}

ERP може автоматично знайти замовлення за номером WEB-10025 і закрити оплату.

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

Служба доставки може надсилати статуси.

{
  "tracking_number": "NP-2040506070",
  "order_number": "WEB-10025",
  "status": "delivered",
  "status_name": "Доставлено",
  "status_date": "2026-05-15T18:45:00+03:00"
}

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

Інтеграція 1С/BAS через JSON

У та BAS JSON може використовуватися для обміну з сайтами, CRM, банками, маркетплейсами, мобільними додатками та іншими системами.

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

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

У старих або сильно змінених конфігураціях 1С інтеграція через JSON може бути складнішою через застарілу архітектуру, нестандартні довідники, дублікати, неправильні коди, нестабільні правила проведення документів або відсутність нормального API.

JSON у міграції з 1С/BAS у K2 ERP

JSON може бути зручним проміжним форматом для міграції з або BAS у K2 ERP.

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

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

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

Приклад JSON для міграції контрагентів

{
  "entity": "counterparties",
  "source": "1C",
  "export_date": "2026-05-15",
  "items": [
    {
      "external_id": "1c-000001",
      "name": "ТОВ Ромашка",
      "edrpou": "12345678",
      "type": "legal_entity",
      "is_active": true,
      "contacts": [
        {
          "type": "phone",
          "value": "+380501112233"
        },
        {
          "type": "email",
          "value": "office@example.ua"
        }
      ]
    }
  ]
}

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

{
  "entity": "stock_balances",
  "source": "1C",
  "balance_date": "2026-05-01",
  "warehouse": "Основний склад",
  "items": [
    {
      "sku": "SKU-001",
      "name": "Товар А",
      "quantity": 10,
      "amount": 12000.00
    },
    {
      "sku": "SKU-002",
      "name": "Товар Б",
      "quantity": 5,
      "amount": 7500.00
    }
  ]
}

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

{
  "entity": "settlements",
  "source": "1C",
  "balance_date": "2026-05-01",
  "items": [
    {
      "counterparty_id": "1c-000001",
      "counterparty_name": "ТОВ Ромашка",
      "contract": "Договір поставки №15",
      "currency": "UAH",
      "debt": 40000.00,
      "advance": 0.00,
      "document": "Видаткова накладна №100"
    },
    {
      "counterparty_id": "1c-000002",
      "counterparty_name": "ТОВ Будсервіс",
      "contract": "Договір послуг №7",
      "currency": "UAH",
      "debt": 0.00,
      "advance": 15000.00,
      "document": "Банківська виписка №55"
    }
  ]
}

JSON Schema

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

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

Наприклад, для замовлення можна визначити:

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

Перевага схеми. JSON Schema дозволяє виявляти помилки ще до завантаження даних в ERP: порожні поля, неправильні типи, відсутні товари, некоректні суми або неправильну валюту.

Валідація JSON

Перед обробкою JSON потрібно перевірити.

Валідація може включати:

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

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

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

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

JSON сам по собі не забезпечує безпеку. Безпека залежить від API, каналу передачі, авторизації, прав доступу і перевірки даних.

Потрібно використовувати:

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

Важливо. Не можна передавати токени, паролі, персональні дані або зарплатну інформацію через незахищені канали чи зберігати їх у відкритих логах.

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

Для підтримки інтеграції потрібні логи.

У логах бажано зберігати:

  • дату й час запиту;
  • джерело;
  • endpoint;
  • method;
  • request_id;
  • external_id;
  • статус обробки;
  • код помилки;
  • короткий опис помилки;
  • час виконання;
  • користувача або API-ключ;
  • посилання на створений документ;
  • технічний payload за правилами безпеки.

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

  • чи прийшло замовлення;
  • чому воно не створилося;
  • чи була повторна відправка;
  • який payload отримала ERP;
  • який документ створено;
  • коли сталася помилка;
  • хто викликав API.

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

Ідемпотентність — це властивість інтеграції, коли повторна відправка того самого запиту не створює дубль.

Наприклад, сайт відправив замовлення WEB-10025. Через збій він відправив його ще раз. ERP повинна не створити друге замовлення, а повернути інформацію, що таке замовлення вже існує.

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

{
  "success": true,
  "already_exists": true,
  "order_number": "ERP-4587",
  "message": "Замовлення вже було створено раніше"
}

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

Інтеграції змінюються. Додаються нові поля, нові статуси, нові правила.

Щоб не зламати старі інтеграції, потрібно використовувати версіонування API.

Приклади:

/api/v1/orders
/api/v2/orders

Або версію в самому JSON:

{
  "version": "1.0",
  "entity": "order",
  "data": {}
}

Мапінг даних

Мапінг — це відповідність полів між системами.

Наприклад:

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

Без карти мапінгу інтеграція швидко стає незрозумілою: одна система називає поле “client”, інша — “customer”, третя — “counterparty”.

JSON і файли

Іноді через JSON потрібно передати інформацію про файл.

Сам файл можна передавати:

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

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

{
  "document_number": "INV-1001",
  "file": {
    "name": "invoice-1001.pdf",
    "url": "https://example.com/files/invoice-1001.pdf",
    "type": "application/pdf"
  }
}

Для великих файлів краще не передавати base64 у великому JSON, а використовувати окреме файлове API.

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

Для великих інтеграцій JSON може передаватися не напряму через API, а через чергу повідомлень.

Це корисно, коли:

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

У таких сценаріях JSON-повідомлення кладеться в чергу, а ERP або інтеграційний сервіс поступово його обробляє.

JSON і Power BI

JSON може бути джерелом даних для Power BI та інших BI-систем.

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

  • продажі;
  • залишки;
  • платежі;
  • замовлення;
  • статуси;
  • витрати;
  • зарплатні агрегати;
  • KPI;
  • план-факт;
  • аналітику по клієнтах.

Але для великих обсягів даних краще не будувати аналітику тільки на сирих JSON-файлах. Бажано завантажувати дані в базу, сховище або аналітичний шар.

JSON і K2 ERP

У K2 ERP JSON може використовуватися як один із базових форматів обміну даними з іншими системами.

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

  • API для сайтів;
  • API для CRM;
  • API для мобільних додатків;
  • інтеграція з маркетплейсами;
  • інтеграція з банками;
  • інтеграція зі службами доставки;
  • вивантаження в BI;
  • завантаження даних із 1С/BAS;
  • робота Реплікатора K2;
  • обмін із зовнішніми сервісами;
  • інтеграція з AI-сервісами.

Перевага K2 ERP. JSON добре поєднується з сучасною архітектурою K2 ERP, API, веб-інтерфейсом, Python, TypeScript, PostgreSQL, BI-аналітикою і механізмами міграції зі старих систем.

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

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

Він може допомогти:

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

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

При описі інтеграцій із та BAS важливо враховувати не тільки технічну сторону, а й санкційні та безпекові ризики.

історично є російською програмною екосистемою. Після початку російської агресії проти України питання використання такого програмного забезпечення стало питанням кібербезпеки, комплаєнсу, репутації та цифрової незалежності.

Указ Президента України №184/2020 ввів у дію рішення РНБО від 14 травня 2020 року щодо застосування, скасування і внесення змін до персональних спеціальних економічних та інших обмежувальних заходів. Держспецзв’язку також оприлюднила перелік програмного забезпечення та комунікаційного обладнання, забороненого до використання в окремих сферах; у цьому переліку згадується, зокрема, BAS ERP. :contentReference[oaicite:0]{index=0}

Важливо. Інтеграція з або BAS не повинна закріплювати залежність бізнесу від ризикової платформи. У багатьох випадках JSON-обмін доцільно використовувати як проміжний етап для вивантаження даних, побудови паралельного запуску і поступового переходу на K2 ERP або іншу безпечну ERP-систему.

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

Типова архітектура може виглядати так:

Рівень Роль Приклад
Джерело даних Система, яка створює подію Сайт, CRM, банк, 1С/BAS
JSON payload Структуроване повідомлення Замовлення, платіж, залишки
API або черга Канал передачі REST API, Webhook, message queue
Інтеграційний шар Перевірка, мапінг, логування Реплікатор K2 або middleware
ERP Основна система обліку K2 ERP
BI Аналітика Power BI, дашборди, звіти

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

Перед початком інтеграції потрібно відповісти на практичні питання:

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

Приклад технічного завдання на JSON-інтеграцію

Для інтеграції сайту з ERP технічне завдання має містити:

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

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

Тестувати потрібно не тільки “успішний сценарій”.

Потрібно перевірити:

  • правильне створення документа;
  • повторну відправку того самого документа;
  • порожні обов’язкові поля;
  • неправильну дату;
  • неправильну валюту;
  • товар, якого немає в ERP;
  • контрагента, який уже існує;
  • дублікати;
  • велику кількість рядків;
  • помилку авторизації;
  • недоступність ERP;
  • повтор після помилки;
  • некоректний JSON;
  • перевищення розміру payload;
  • логування помилок.

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

Помилка Наслідок Як уникнути
Не погодили структуру JSON Кожна система трактує поля по-своєму Зробити специфікацію API
Немає унікальних ключів Створюються дублікати Використовувати external_id, sku, edrpou
Немає логів Неможливо знайти причину помилки Логувати запити, відповіді й коди помилок
Немає ідемпотентності Повторний запит створює дубль Перевіряти external_id
Немає валідації У систему потрапляє сміття Використовувати схеми і правила перевірки
Немає версіонування Оновлення API ламає інтеграцію Використовувати v1, v2 або version
Немає контролю доступу Дані доступні зайвим системам Ролі, токени, HTTPS, аудит

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

Переваги:

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

Обмеження JSON

JSON не вирішує всі задачі сам по собі.

Обмеження:

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

Коротко

Питання Відповідь
Що таке інтеграція через JSON? Обмін структурованими даними між системами у форматі JSON.
Для чого використовується? Для передачі замовлень, товарів, цін, залишків, платежів, статусів, документів і аналітики.
З чим найчастіше використовується? З REST API, Webhook, чергами повідомлень, файлами обміну і BI-системами.
Що головне в JSON-інтеграції? Узгоджена структура, унікальні ключі, валідація, логування, безпека і контроль помилок.
Чи можна інтегрувати 1С/BAS через JSON? Так, але потрібно враховувати технічні обмеження старих конфігурацій і санкційні ризики.
Чи підходить JSON для міграції? Так. JSON зручний як проміжний формат для перенесення довідників, документів, залишків і взаєморозрахунків.
Як JSON пов’язаний із K2 ERP? K2 ERP може використовувати JSON для API, інтеграцій, міграції, Реплікатора K2, BI та зовнішніх сервісів.

Висновок

Інтеграція через JSON — це один із базових способів з’єднати сучасні бізнес-системи між собою.

JSON дозволяє передавати дані між сайтом, ERP, CRM, банком, доставкою, маркетплейсом, мобільним додатком, BI-системою або старою обліковою системою. Але успішна інтеграція — це не просто “відправити JSON”. Потрібні правила: структура, унікальні ключі, валідація, безпека, логування, версіонування, обробка помилок і контроль результату.

JSON — це не інтеграція сам по собі. JSON — це мова, якою інтеграція передає дані. Якість інтеграції залежить від архітектури, правил і контролю.

Для компаній, які переходять із або BAS на K2 ERP, JSON може бути зручним мостом: через нього можна вивантажити довідники, документи, залишки, взаєморозрахунки, ціни, платежі та аналітичні дані. А Реплікатор K2 може допомогти перетворити ці дані на керований процес міграції.

У сучасній ERP JSON-інтеграція — це не додаткова опція, а нормальна частина цифрової екосистеми бізнесу.

Див. також

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