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

JSON: відмінності між версіями

Матеріал з K2 ERP Wiki
R (обговорення | внесок)
Бюрократи, Адміністратори інтерфейсу, Адміністратори
1886 редагувань
ВізуальнийВікірозмітка
Створена сторінка: {{DISPLAYTITLE:JSON}} {{SEO |title=JSON — формат обміну даними, API, інтеграції та роль у K2 ERP |description=JSON — легкий текстовий формат обміну даними, який використовується в API, веб-додатках, інтеграціях, налаштуваннях, мобільних додатках, AI-сервісах і сучасних ERP-платформах....
 
Немає опису редагування
 
Рядок 7: Рядок 7:
|image=https://erp.kyiv.ua
|image=https://erp.kyiv.ua
}}
}}
[[Файл:K2 ERP JSON.png|центр|міні|800x800пкс|JSON як формат обміну даними, API та інтеграцій у K2 ERP]]


'''JSON''' — текстовий формат представлення та обміну даними, який широко використовується у веб-розробці, [[API]], інтеграціях, мобільних додатках, конфігураціях, обміні між серверами та клієнтами, а також у взаємодії з [[AI|AI-сервісами]].
'''JSON''' — текстовий формат представлення та обміну даними, який широко використовується у веб-розробці, [[API]], інтеграціях, мобільних додатках, конфігураціях, обміні між серверами та клієнтами, а також у взаємодії з [[AI|AI-сервісами]].

Поточна версія на 19:03, 14 травня 2026


SEO title: JSON — формат обміну даними, API, інтеграції та роль у K2 ERP SEO description: JSON — легкий текстовий формат обміну даними, який використовується в API, веб-додатках, інтеграціях, налаштуваннях, мобільних додатках, AI-сервісах і сучасних ERP-платформах. Роль JSON у K2 ERP поряд із YML, ORM, ER-моделями, Python, TypeScript та PostgreSQL. SEO keywords: JSON, JavaScript Object Notation, K2 ERP, ERP, API, REST API, інтеграції, YML, XML, ORM, Python, TypeScript, PostgreSQL, AI, ШІ, бізнес-автоматизація, українська ERP, альтернатива 1С, альтернатива BAS Alternative to:


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

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

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

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

Для K2 ERP. JSON використовується там, де потрібно швидко, зрозуміло й універсально передавати дані між системами: через API, інтеграції, frontend, backend, мобільні додатки, зовнішні сервіси та ШІ.

JSON і YML. У K2 ERP YML більше підходить для декларативного опису моделей, структур і компонентів, а JSON — для обміну даними, API-відповідей, інтеграцій і машинної взаємодії.

Важливо. JSON здається простим, але в серйозних ERP-інтеграціях навіть маленька помилка в структурі може перетворити “швидко передамо дані” на вечір пошуку однієї зайвої коми. А кома, як відомо, іноді коштує дорожче за консультанта.

Вступ

У сучасній розробці бізнес-систем дані постійно рухаються.

Користувач відкриває форму у веб-інтерфейсі. Frontend запитує дані через API. Backend отримує запит, звертається до бази даних, формує відповідь і повертає її назад. Мобільний додаток синхронізує документи. Сайт передає замовлення в ERP. Банк відправляє виписку. Служба доставки повертає статус посилки. ШІ отримує структуровану інформацію для аналізу або генерації відповіді.

У всіх цих процесах потрібен зручний формат обміну даними.

Саме таким форматом став JSON.

Він достатньо простий для людини, достатньо формальний для машини й достатньо універсальний, щоб використовуватися майже всюди.

Для K2 ERP JSON — це один із ключових форматів взаємодії із зовнішнім світом. Якщо YML можна назвати мовою опису моделей і компонентів, то JSON можна назвати мовою руху даних між системами.

Що таке JSON

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

Найпростіший приклад JSON: 

{
  "code": "000001",
  "name": "Ноутбук Lenovo",
  "price": 32000,
  "active": true
}

Цей фрагмент описує товар із кодом, назвою, ціною та ознакою активності.

JSON легко читати. Видно, що:

  • `code` — це код товару;
  • `name` — назва;
  • `price` — ціна;
  • `active` — ознака активності.

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

Основні типи даних у JSON

JSON підтримує кілька базових типів даних.

Тип Приклад Пояснення
Рядок "Контрагент" Текстове значення
Число 1250 Ціле або дробове число
Логічне значення true, false Так або ні
Об’єкт {"name": "ТОВ Приклад"} Набір ключів і значень
Масив ["UAH", "USD", "EUR"] Список значень
Null null Відсутність значення

Об’єкти JSON

Об’єкт JSON — це набір пар “ключ-значення”.

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

{
  "id": 15,
  "code": "000015",
  "name": "ТОВ Приклад",
  "edrpou": "12345678",
  "phone": "+380501112233",
  "email": "office@example.ua",
  "active": true
}

Такий об’єкт може бути відповіддю API при отриманні картки контрагента з K2 ERP.

Масиви JSON

Масив — це список значень або об’єктів.

Приклад списку валют: 

[
  "UAH",
  "USD",
  "EUR"
]

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

[
  {
    "id": 1,
    "name": "Ноутбук",
    "price": 32000
  },
  {
    "id": 2,
    "name": "Монітор",
    "price": 8500
  },
  {
    "id": 3,
    "name": "Клавіатура",
    "price": 1200
  }
]

У ERP масиви часто використовуються для передачі списків документів, товарів, контрагентів, рядків табличної частини, статусів або результатів пошуку.

Вкладені структури

JSON дозволяє створювати вкладені об’єкти.

Наприклад, документ “Замовлення покупця” може містити шапку документа і табличну частину: 

{
  "id": 101,
  "number": "ЗП-000101",
  "date": "2026-05-14",
  "contractor": {
    "id": 15,
    "name": "ТОВ Приклад"
  },
  "warehouse": {
    "id": 2,
    "name": "Основний склад"
  },
  "items": [
    {
      "product_id": 1,
      "product_name": "Ноутбук",
      "quantity": 2,
      "price": 32000,
      "amount": 64000
    },
    {
      "product_id": 2,
      "product_name": "Монітор",
      "quantity": 3,
      "price": 8500,
      "amount": 25500
    }
  ],
  "total_amount": 89500
}

Це дуже зручно для API, тому що один JSON може передати весь документ разом із рядками.

JSON у веб-розробці

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

У сучасних веб-додатках frontend і backend часто спілкуються саме через JSON.

Наприклад:

  • користувач відкриває список документів;
  • frontend відправляє запит до backend;
  • backend повертає JSON зі списком документів;
  • frontend показує ці дані у таблиці.

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

{
  "data": [
    {
      "id": 101,
      "number": "ЗП-000101",
      "date": "2026-05-14",
      "contractor": "ТОВ Приклад",
      "total_amount": 89500
    },
    {
      "id": 102,
      "number": "ЗП-000102",
      "date": "2026-05-15",
      "contractor": "ФОП Тест",
      "total_amount": 12400
    }
  ],
  "total": 2
}

JSON і API

API — одна з головних сфер використання JSON.

У більшості сучасних REST API дані передаються саме у форматі JSON.

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

{
  "code": "000020",
  "name": "ТОВ Новий клієнт",
  "edrpou": "87654321",
  "phone": "+380671234567",
  "email": "client@example.ua"
}

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

{
  "success": true,
  "id": 20,
  "message": "Контрагента створено"
}

Для K2 ERP це принципово важливо, бо ERP не може жити ізольовано. Вона повинна інтегруватися із сайтами, банками, маркетплейсами, CRM, BI, мобільними додатками, службами доставки та державними сервісами.

JSON у K2 ERP

У K2 ERP JSON може використовуватися в багатьох сценаріях:

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

JSON у K2 ERP. Це формат, через який дані можуть швидко рухатися між компонентами, зовнішніми системами, веб-інтерфейсом, мобільними додатками та AI-сервісами.

JSON і YML

У K2 ERP важливо розуміти різницю між JSON і YML.

Обидва формати текстові. Обидва можуть описувати структури. Обидва зрозумілі машинам і людям.

Але їхня роль різна.

Критерій JSON YML
Основна роль Обмін даними Декларативний опис структур і моделей
Типове використання API, відповіді сервера, інтеграції ER-моделі, компоненти, форми, меню, генерація
Читабельність для людини Добра Дуже добра для великих конфігурацій
Коментарі У стандартному JSON не підтримуються Підтримуються
Зручність для API Дуже висока Менш типова
Зручність для конфігурацій Добра Часто зручніша

Простіше кажучи:

YML — для опису того, що система має створити.

JSON — для передачі того, що система вже створила, отримала або обробляє.

JSON і XML

До популярності JSON у багатьох інтеграціях активно використовувався XML.

XML досі використовується в багатьох державних, банківських, корпоративних і старих інтеграціях.

Але JSON став популярнішим у веб-розробці через простоту.

Приклад XML: 

<product>
  <code>000001</code>
  <name>Ноутбук Lenovo</name>
  <price>32000</price>
  <active>true</active>
</product>

Той самий опис у JSON: 

{
  "code": "000001",
  "name": "Ноутбук Lenovo",
  "price": 32000,
  "active": true
}

JSON зазвичай коротший, легший для читання і простіший для обробки у веб-додатках.

JSON і TypeScript

TypeScript добре працює з JSON, тому що JSON природно схожий на об’єкти JavaScript.

Наприклад, якщо API повертає JSON контрагента: 

{
  "id": 15,
  "code": "000015",
  "name": "ТОВ Приклад",
  "active": true
}

У TypeScript можна описати тип: 

export interface Contractor {
  id: number;
  code: string;
  name: string;
  active: boolean;
}

Це дозволяє frontend-розробнику працювати з даними без хаосу.

Якщо поле `name` має бути рядком, TypeScript допоможе не переплутати його з числом або об’єктом.

JSON і Python

Python також дуже зручно працює з JSON.

Приклад: 

import json

data = {
    "code": "000001",
    "name": "Ноутбук Lenovo",
    "price": 32000,
    "active": True
}

json_text = json.dumps(data, ensure_ascii=False)
print(json_text)

Приклад читання JSON: 

import json

json_text = '''
{
  "code": "000001",
  "name": "Ноутбук Lenovo",
  "price": 32000,
  "active": true
}
'''

data = json.loads(json_text)

print(data["name"])

Для K2 ERP це важливо, бо Python може використовуватися для backend-логіки, інтеграцій, обробки даних, API та AI-сценаріїв.

JSON і PostgreSQL

PostgreSQL має потужні можливості роботи з JSON і JSONB.

Це корисно в тих випадках, коли потрібно зберігати гнучкі структури даних.

Наприклад:

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

Приклад умовного запису JSON-даних: 

{
  "source": "bank_api",
  "operation_id": "ABC-123",
  "status": "processed",
  "raw_amount": "1200.50",
  "currency": "UAH"
}

Але важливо не зловживати JSON у базі даних.

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

Баланс. JSON у базі даних корисний для гнучких структур, але не варто перетворювати ERP на один великий стовпець data, у якому “десь точно все є”. Це шлях до цифрового горища.

JSONB у PostgreSQL

У PostgreSQL існує тип `jsonb`, який зберігає JSON у бінарному оптимізованому вигляді.

Це дозволяє:

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

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

SELECT *
FROM integration_logs
WHERE payload->>'status' = 'processed';

Тут `payload` — поле типу JSONB, а `status` — значення всередині JSON.

JSON і ORM

ORM-моделі можуть працювати з JSON-полями як зі звичайними структурами.

Наприклад, у Python-моделі може бути поле `metadata`, яке зберігає додаткові дані: 

class IntegrationLog(BaseModel):
    id: int
    source: str
    payload: dict

У TypeScript це може виглядати так: 

export interface IntegrationLog {
  id: number;
  source: string;
  payload: Record<string, unknown>;
}

Але важливо правильно типізувати дані там, де структура відома.

Якщо все описувати як `dict` або `any`, система швидко втрачає контроль над структурою.

JSON і ER-модель

ER-модель описує сутності та зв’язки.

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

Наприклад, ER-модель говорить, що є сутність `contractor`.

JSON передає конкретного контрагента: 

{
  "id": 15,
  "code": "000015",
  "name": "ТОВ Приклад",
  "edrpou": "12345678"
}

ER-модель говорить, що документ `customer_order` має табличну частину `items`.

JSON передає конкретне замовлення: 

{
  "number": "ЗП-000101",
  "date": "2026-05-14",
  "contractor_id": 15,
  "items": [
    {
      "product_id": 1,
      "quantity": 2,
      "price": 32000
    }
  ]
}

Тобто ER-модель описує структуру, а JSON передає дані цієї структури.

JSON і AI

Штучний інтелект часто працює з JSON.

Багато AI-сервісів приймають запити у JSON і повертають відповіді також у JSON.

Це зручно, бо JSON дозволяє передавати структуровані дані.

Наприклад, можна передати ШІ опис задачі: 

{
  "task": "generate_yml_model",
  "module": "service_requests",
  "description": "Створи модель для сервісних заявок на ремонт обладнання",
  "language": "uk"
}

А отримати відповідь: 

{
  "success": true,
  "result": {
    "entity": "repair_request",
    "title": "Заявка на ремонт",
    "type": "document"
  }
}

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

JSON і автоматична генерація компонентів

У K2 ERP основою автоматичного створення компонентів може бути YML і ER-модель.

Але JSON також може брати участь у цьому процесі.

Наприклад, frontend-редактор ER-моделі може передавати на сервер структуру у JSON: 

{
  "component": "sales",
  "entities": [
    {
      "name": "contractor",
      "type": "directory",
      "fields": [
        {
          "name": "code",
          "type": "string",
          "required": true
        },
        {
          "name": "name",
          "type": "string",
          "required": true
        }
      ]
    },
    {
      "name": "customer_order",
      "type": "document",
      "fields": [
        {
          "name": "number",
          "type": "string",
          "auto": true
        },
        {
          "name": "date",
          "type": "datetime",
          "required": true
        }
      ]
    }
  ]
}

Сервер може перетворити цю структуру на YML, ORM-моделі, міграції та інші елементи.

Тобто JSON може бути транспортним форматом між веб-редактором і backend.

JSON і мобільні додатки

Мобільні додатки майже завжди активно використовують JSON.

Для K2 ERP це важливо в сценаріях:

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

Приклад JSON для мобільної заявки: 

{
  "request_id": 501,
  "status": "in_work",
  "engineer_id": 8,
  "comment": "Роботи розпочато",
  "geo": {
    "lat": 50.4501,
    "lng": 30.5234
  }
}

Мобільний додаток може передати такий JSON на сервер, коли інженер почав виконання заявки.

JSON і офлайн-режим

В офлайн-режимі JSON може використовуватися для збереження черги змін.

Наприклад, користувач створив документ без інтернету.

Мобільний додаток зберігає локальний JSON: 

{
  "operation": "create",
  "entity": "repair_request",
  "local_id": "tmp-001",
  "data": {
    "date": "2026-05-14",
    "contractor_id": 15,
    "equipment_id": 7,
    "problem_description": "Не запускається обладнання"
  }
}

Коли інтернет з’являється, додаток синхронізує цю операцію з сервером.

JSON і інтеграції з сайтами

Сайт або інтернет-магазин може передавати замовлення в K2 ERP у JSON.

Приклад: 

{
  "order_number": "WEB-10025",
  "date": "2026-05-14",
  "customer": {
    "name": "Іван Петренко",
    "phone": "+380671234567",
    "email": "ivan@example.ua"
  },
  "delivery": {
    "service": "Нова пошта",
    "city": "Київ",
    "warehouse": "Відділення №12"
  },
  "items": [
    {
      "sku": "NB-001",
      "name": "Ноутбук",
      "quantity": 1,
      "price": 32000
    }
  ],
  "payment": {
    "method": "card",
    "status": "paid"
  }
}

K2 ERP може прийняти ці дані, створити контрагента, замовлення покупця, резерв товару або інші документи.

JSON і банки

Банківські сервіси можуть передавати інформацію про платежі.

Приклад JSON виписки: 

{
  "account": "UA123456789000000000000000000",
  "date": "2026-05-14",
  "transactions": [
    {
      "id": "BANK-001",
      "date": "2026-05-14T10:15:00",
      "amount": 12500.50,
      "currency": "UAH",
      "payer": "ТОВ Клієнт",
      "purpose": "Оплата за рахунком №100"
    }
  ]
}

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

JSON і служби доставки

Служби доставки також часто використовують JSON у своїх API.

Приклад статусу доставки: 

{
  "tracking_number": "20400012345678",
  "status": "delivered",
  "status_title": "Доставлено",
  "delivered_at": "2026-05-14T15:40:00"
}

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

JSON і маркетплейси

Маркетплейси передають багато даних через API:

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

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

{
  "sku": "NB-001",
  "warehouse": "main",
  "quantity": 12
}

ERP може автоматично синхронізувати ці дані з маркетплейсом.

JSON і BI

BI-системи можуть отримувати дані з ERP через API у JSON.

Наприклад: 

{
  "period": "2026-05",
  "sales": [
    {
      "department": "Київ",
      "amount": 1200000
    },
    {
      "department": "Львів",
      "amount": 850000
    }
  ]
}

Далі ці дані можуть використовуватися для побудови графіків, дашбордів і аналітики.

JSON і логіювання

JSON зручний для логіювання подій.

Наприклад, лог інтеграції: 

{
  "timestamp": "2026-05-14T12:30:00",
  "source": "bank_api",
  "event": "payment_received",
  "status": "success",
  "payload_id": "BANK-001"
}

Такі логи легко зберігати, аналізувати, фільтрувати і передавати в системи моніторингу.

JSON і помилки API

Для API важливо повертати помилки у структурованому вигляді.

Приклад: 

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Поле 'name' є обов'язковим",
    "field": "name"
  }
}

Такий формат дозволяє frontend або зовнішній системі зрозуміти, що саме сталося і як це показати користувачу.

JSON Schema

JSON Schema — це спосіб описати структуру JSON-даних.

Вона дозволяє визначити:

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

Приклад JSON Schema для контрагента: 

{
  "type": "object",
  "required": ["code", "name"],
  "properties": {
    "code": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "edrpou": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    }
  }
}

У великих інтеграціях JSON Schema допомагає уникати хаосу.

Валідація JSON

Валідація потрібна, щоб система не приймала некоректні дані.

Наприклад, якщо API очікує поле `quantity` як число, а зовнішня система передає рядок `"багато"`, це має бути помилкою.

Приклад правильного JSON: 

{
  "product_id": 1,
  "quantity": 5
}

Приклад некоректного JSON: 

{
  "product_id": 1,
  "quantity": "багато"
}

Для ERP це дуже важливо, бо помилка в даних може створити неправильні залишки, документи, звіти або платежі.

Типові помилки в JSON

JSON простий, але має суворий синтаксис.

Типові помилки:

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

Приклад помилки із зайвою комою: 

{
  "name": "Товар",
  "price": 100,
}

Правильно: 

{
  "name": "Товар",
  "price": 100
}

Приклад помилки з лапками: 

{
  'name': 'Товар'
}

Правильно: 

{
  "name": "Товар"
}

Рекомендації щодо JSON в API

Для якісного API варто дотримуватися кількох правил.

Правило Пояснення
Стабільні назви полів Не треба сьогодні повертати contractor_id, а завтра clientId без версії API.
Єдиний формат дат Наприклад, ISO-формат 2026-05-14T12:30:00.
Структуровані помилки Помилка має мати код, повідомлення і, за можливості, поле.
Пагінація списків Великі списки не треба повертати одним нескінченним JSON.
Версіонування API Зміни структури мають бути контрольованими.
Валідація API має перевіряти вхідні дані.
Документація Для інтеграторів потрібні приклади запитів і відповідей.

JSON і дати

Одна з типових проблем в інтеграціях — дати.

Різні системи можуть передавати дати по-різному: 

14.05.2026
2026-05-14
2026-05-14T12:30:00
05/14/2026

Для API краще використовувати єдиний стандартний формат.

Приклад: 

{
  "date": "2026-05-14",
  "created_at": "2026-05-14T12:30:00"
}

Це зменшує кількість помилок при інтеграціях.

JSON і гроші

Гроші в JSON потрібно передавати обережно.

Наприклад: 

{
  "amount": 12500.50,
  "currency": "UAH"
}

Для деяких систем важливо передавати суми як рядки, щоб уникнути проблем із точністю: 

{
  "amount": "12500.50",
  "currency": "UAH"
}

В ERP це критично, бо фінансові помилки — це вже не “ой, поправимо колір кнопки”.

JSON і кодування

JSON зазвичай використовується з UTF-8.

Це дозволяє нормально передавати українські символи: 

{
  "name": "Українська компанія",
  "city": "Київ",
  "comment": "Оплата за рахунком"
}

Для української ERP це важливо, бо дані містять українські назви, адреси, документи, коментарі та службові тексти.

JSON і безпека

JSON сам по собі не є небезпечним або безпечним.

Безпека залежить від того, як система його приймає й обробляє.

Важливо:

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

Приклад того, чого не варто робити: 

{
  "api_key": "secret-key-in-open-json",
  "password": "123456"
}

Секрети потрібно зберігати й передавати правильно, а не “тимчасово в JSON”. Бо тимчасове в ІТ часто живе довше за деякі ERP-проєкти.

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

Для інтеграцій дуже важливо мати приклади JSON.

Документація API має показувати:

  • URL запиту;
  • метод;
  • заголовки;
  • приклад запиту;
  • приклад відповіді;
  • можливі помилки;
  • обов’язкові поля;
  • типи даних;
  • обмеження;
  • версію API.

Приклад документації: 

POST /api/contractors

Request:
{
  "code": "000020",
  "name": "ТОВ Новий клієнт",
  "edrpou": "87654321"
}

Response:
{
  "success": true,
  "id": 20
}

Без прикладів інтегратор починає ворожити. А ворожіння в API зазвичай закінчується листом “у вас щось не працює”.

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

З часом API змінюється.

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

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

Наприклад: 

/api/v1/contractors
/api/v2/contractors

Або в заголовках запиту.

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

JSON і імпорт даних

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

Наприклад, імпорт довідника товарів: 

[
  {
    "code": "NB-001",
    "name": "Ноутбук",
    "unit": "шт",
    "price": 32000
  },
  {
    "code": "MN-001",
    "name": "Монітор",
    "unit": "шт",
    "price": 8500
  }
]

Система може прочитати цей JSON і створити або оновити номенклатуру.

JSON і експорт даних

JSON також зручний для експорту даних.

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

{
  "warehouse": "main",
  "date": "2026-05-14",
  "items": [
    {
      "sku": "NB-001",
      "quantity": 12
    },
    {
      "sku": "MN-001",
      "quantity": 25
    }
  ]
}

Це може використовуватися для сайтів, маркетплейсів, мобільних додатків або BI-систем.

JSON і фільтри

У API JSON може використовуватися для передачі фільтрів.

Приклад: 

{
  "filter": {
    "date_from": "2026-05-01",
    "date_to": "2026-05-31",
    "contractor_id": 15,
    "status": "completed"
  },
  "sort": {
    "field": "date",
    "direction": "desc"
  },
  "limit": 50,
  "offset": 0
}

Це дозволяє клієнту гнучко запитувати потрібні дані.

JSON і дашборди

Дашборди часто отримують дані у JSON.

Наприклад: 

{
  "widgets": [
    {
      "type": "kpi",
      "title": "Продажі за місяць",
      "value": 1250000,
      "currency": "UAH"
    },
    {
      "type": "chart",
      "title": "Продажі по днях",
      "data": [
        {
          "date": "2026-05-01",
          "amount": 42000
        },
        {
          "date": "2026-05-02",
          "amount": 51000
        }
      ]
    }
  ]
}

Frontend може використати такий JSON для побудови інтерфейсу.

JSON і налаштування користувача

JSON може зберігати налаштування користувача.

Наприклад: 

{
  "theme": "light",
  "language": "uk",
  "table_settings": {
    "customer_orders": {
      "columns": ["number", "date", "contractor", "total_amount"],
      "page_size": 50
    }
  }
}

Такі налаштування можуть визначати мову, тему, видимі колонки, розмір сторінки, фільтри та інші параметри.

JSON і події

У подієвій архітектурі JSON може описувати події.

Приклад: 

{
  "event": "customer_order.created",
  "timestamp": "2026-05-14T12:30:00",
  "data": {
    "id": 101,
    "number": "ЗП-000101",
    "contractor_id": 15
  }
}

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

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

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

Наприклад, модуль продажів створив замовлення і відправив подію в чергу: 

{
  "type": "order_created",
  "order_id": 101,
  "created_at": "2026-05-14T12:30:00"
}

Інший сервіс може отримати це повідомлення й виконати дію.

Це корисно для масштабованих систем, де компоненти не повинні жорстко залежати один від одного.

JSON і webhooks

Webhook — це спосіб повідомити зовнішню систему про подію.

Наприклад, K2 ERP може надіслати JSON на зовнішній URL, коли створено нове замовлення. 

{
  "event": "order.created",
  "order": {
    "id": 101,
    "number": "ЗП-000101",
    "total_amount": 89500
  }
}

Webhooks зручні для інтеграцій із CRM, сайтами, службами доставки, аналітичними системами й іншими сервісами.

JSON і структура відповіді API

Добре спроєктоване API має єдину структуру відповідей.

Наприклад: 

{
  "success": true,
  "data": {
    "id": 101,
    "number": "ЗП-000101"
  },
  "meta": {
    "request_id": "req-123"
  }
}

Для помилки: 

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Документ не знайдено"
  },
  "meta": {
    "request_id": "req-124"
  }
}

Єдина структура спрощує життя frontend-розробникам та інтеграторам.

JSON і права доступу

API не повинен повертати користувачу більше даних, ніж йому дозволено бачити.

Наприклад, один користувач може бачити суму документа, а інший — ні.

Це означає, що JSON-відповідь може залежати від прав доступу.

Для користувача з повними правами: 

{
  "number": "ЗП-000101",
  "contractor": "ТОВ Приклад",
  "total_amount": 89500
}

Для користувача з обмеженими правами: 

{
  "number": "ЗП-000101",
  "contractor": "ТОВ Приклад"
}

JSON і персональні дані

JSON часто використовується для передачі персональних даних: імен, телефонів, email, адрес.

Тому потрібно уважно контролювати:

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

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

JSON і продуктивність

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

Проблеми можуть виникати, якщо:

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

Тому API має бути продуманим.

Не потрібно повертати весь “цифровий склад” на кожен клік користувача.

JSON і кешування

JSON-відповіді можна кешувати.

Це корисно для:

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

Кешування допомагає зменшити навантаження на сервер і пришвидшити роботу інтерфейсу.

JSON і файли

JSON не призначений для зберігання великих файлів.

Файли краще передавати окремо, а в JSON зберігати метадані.

Наприклад: 

{
  "file_id": 501,
  "name": "dogovir.pdf",
  "content_type": "application/pdf",
  "size": 245120,
  "entity": "contractor",
  "entity_id": 15
}

Так система знає, до якої сутності прикріплено файл, але сам файл не “запихається” у JSON без потреби.

JSON і GraphQL

Окрім REST API, JSON часто використовується і в GraphQL.

GraphQL дозволяє клієнту точніше вказувати, які дані потрібні.

Приклад відповіді GraphQL теж часто має JSON-структуру: 

{
  "data": {
    "contractor": {
      "id": 15,
      "name": "ТОВ Приклад",
      "orders": [
        {
          "number": "ЗП-000101",
          "total_amount": 89500
        }
      ]
    }
  }
}

Для ERP це може бути цікавим у складних frontend-сценаріях.

JSON і конфігурації

JSON може використовуватися для конфігурацій, але для великих ручних конфігурацій у K2 ERP часто зручнішим є YML.

Приклад JSON-конфігурації: 

{
  "module": "sales",
  "enabled": true,
  "settings": {
    "default_warehouse": 1,
    "allow_negative_stock": false
  }
}

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

JSON і тестування API

JSON зручно використовувати в тестах.

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

{
  "code": "TEST001",
  "name": "Тестовий контрагент"
}

Тест може перевірити, що API повернув: 

{
  "success": true
}

Або що при відсутності назви повертається помилка: 

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

JSON і автодокументація

Якщо API має чіткі JSON-схеми, на їх основі можна генерувати документацію.

Це корисно для:

  • frontend-розробників;
  • інтеграторів;
  • партнерів;
  • тестувальників;
  • зовнішніх клієнтів API;
  • AI-асистентів, які допомагають писати інтеграції.

Документація з прикладами JSON значно зменшує кількість питань.

JSON і сумісність між системами

JSON став популярним саме тому, що він універсальний.

Система на Python може відправити JSON.

Система на TypeScript може його прийняти.

Сервіс на Java може обробити.

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

ШІ може проаналізувати.

BI може використати для звіту.

Це робить JSON дуже зручним для інтеграцій.

JSON у порівнянні з таблицями Excel

Іноді бізнес звик обмінюватися даними через Excel.

Excel зручний для людини, але не завжди зручний для автоматичних інтеграцій.

JSON краще підходить для машинного обміну.

Наприклад, сайт не буде надсилати в ERP замовлення через Excel-файл кожні 5 секунд. Він відправить JSON через API.

Але для ручного імпорту Excel може залишатися корисним.

Тобто формати не конкурують напряму. Вони мають різні ролі.

JSON і майбутнє ERP

Сучасна ERP — це не монолітна програма, яка живе сама по собі.

Це центр цифрової екосистеми.

Навколо неї є:

  • сайти;
  • мобільні додатки;
  • банки;
  • маркетплейси;
  • служби доставки;
  • CRM;
  • BI;
  • AI;
  • державні сервіси;
  • партнерські модулі;
  • хмари;
  • зовнішні API.

JSON є одним із головних форматів, який дозволяє всім цим частинам говорити між собою.

JSON у програмуванні зі швидкістю думки

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

Основна модель компонента може створюватися через ER-модель і YML.

Але JSON може використовуватися:

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

Тобто JSON — це не “архітектор” системи, але дуже важливий “кур’єр”, який швидко й акуратно переносить дані між її частинами.

Метафора. Якщо YML — це креслення майбутнього модуля, то JSON — це транспорт, який возить дані між будівельниками, складами, диспетчерами й готовим будинком.

Переваги JSON

Перевага Пояснення
Простота JSON легко читати й писати.
Універсальність Підтримується майже всіма мовами програмування.
Зручність для API Є стандартним форматом для багатьох REST API.
Легкість Зазвичай компактніший за XML.
Вкладені структури Дозволяє передавати складні об’єкти й масиви.
Сумісність із JavaScript/TypeScript Природно працює у веб-інтерфейсах.
AI-сумісність Зручний для передачі структурованих даних AI-сервісам.
Придатність для інтеграцій Добре підходить для сайтів, банків, маркетплейсів, мобільних додатків і зовнішніх сервісів.

Недоліки JSON

Недолік Пояснення
Немає коментарів у стандарті Для конфігурацій це може бути незручно.
Суворий синтаксис Зайва кома або неправильні лапки роблять JSON некоректним.
Немає вбудованих типів дат Дати передаються як рядки, тому потрібна домовленість про формат.
Можливі проблеми з точністю чисел Для фінансових даних треба бути уважним.
Може стати хаотичним Без схем і документації JSON-структури швидко розповзаються.
Не замінює модель даних JSON не повинен підміняти нормальну ER-модель і структуру бази.

Коли використовувати JSON

JSON добре використовувати для:

  • API;
  • інтеграцій;
  • відповідей сервера;
  • запитів frontend;
  • мобільних додатків;
  • синхронізації;
  • webhooks;
  • черг повідомлень;
  • AI-сервісів;
  • логів;
  • імпорту/експорту;
  • передачі параметрів;
  • дашбордів;
  • обміну з сайтами й маркетплейсами.

Коли краще не використовувати JSON

JSON не завжди є найкращим вибором.

Не варто використовувати JSON:

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

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

Приклад поганого JSON

{
  "data": {
    "field1": "щось",
    "field2": "десь",
    "field3": 123,
    "field4": true
  }
}

Проблема такого JSON у тому, що він нічого не пояснює.

Незрозуміло, що таке `field1`, навіщо `field3`, хто це використовує і що буде, якщо його змінити.

Приклад кращого JSON

{
  "contractor": {
    "id": 15,
    "name": "ТОВ Приклад",
    "edrpou": "12345678"
  },
  "order": {
    "number": "ЗП-000101",
    "date": "2026-05-14",
    "total_amount": 89500
  }
}

Тут структура зрозуміла: є контрагент і замовлення.

Рекомендації для K2 ERP

Для K2 ERP JSON варто використовувати за такими принципами:

  • JSON — для обміну даними;
  • YML — для опису моделей і компонентів;
  • ER-модель — для архітектури сутностей і зв’язків;
  • ORM — для роботи коду з базою даних;
  • API — для стабільної взаємодії між системами;
  • JSON Schema — для контролю структури;
  • документація — для партнерів та інтеграторів;
  • валідація — для безпеки й якості;
  • версіонування — для довгострокової сумісності.

Приклад повного API-сценарію

Уявімо, що сайт передає замовлення в K2 ERP.

Запит

{
  "external_id": "WEB-10025",
  "date": "2026-05-14T11:25:00",
  "customer": {
    "name": "Іван Петренко",
    "phone": "+380671234567",
    "email": "ivan@example.ua"
  },
  "items": [
    {
      "sku": "NB-001",
      "quantity": 1,
      "price": 32000
    },
    {
      "sku": "MN-001",
      "quantity": 2,
      "price": 8500
    }
  ],
  "delivery": {
    "service": "Нова пошта",
    "city": "Київ",
    "warehouse": "Відділення №12"
  },
  "payment": {
    "method": "card",
    "status": "paid"
  }
}

Відповідь

{
  "success": true,
  "data": {
    "order_id": 101,
    "order_number": "ЗП-000101",
    "status": "created"
  }
}

Помилка

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Товар з кодом NB-001 не знайдено",
    "field": "items[0].sku"
  }
}

Такий підхід робить інтеграцію передбачуваною.

JSON і партнери K2 ERP

Для партнерів K2 ERP JSON важливий як інструмент інтеграцій.

Партнер може створювати:

  • конектори до сайтів;
  • інтеграції з банками;
  • інтеграції з маркетплейсами;
  • обмін із CRM;
  • мобільні додатки;
  • BI-конектори;
  • webhooks;
  • AI-сервіси;
  • галузеві API;
  • сервіси синхронізації.

Усі ці сценарії часто використовують JSON.

JSON і цифрова незалежність

На перший погляд JSON не має прямого стосунку до цифрової незалежності.

Але насправді має.

Сучасна українська ERP повинна говорити мовою сучасного світу.

Не бути закритим островом.

Не вимагати від усіх вивчати внутрішню мову старої системи.

Не тримати дані в технологічній клітці.

JSON, API, YML, ORM, Python, TypeScript, PostgreSQL — це частина відкритої сучасної екосистеми, яка дозволяє K2 ERP інтегруватися з іншими системами й розвиватися незалежно.

Коротко

Питання Відповідь
Що таке JSON? Текстовий формат обміну даними, який використовує об’єкти, масиви, рядки, числа, логічні значення та null.
Для чого використовується JSON? Для API, інтеграцій, веб-додатків, мобільних додатків, AI-сервісів, імпорту, експорту, логів і обміну даними.
Чим JSON відрізняється від YML? JSON частіше використовується для обміну даними, а YML — для декларативного опису моделей, структур і компонентів.
Чим JSON відрізняється від XML? JSON зазвичай компактніший, простіший і зручніший для веб-розробки, хоча XML досі використовується в багатьох інтеграціях.
Чи використовується JSON у K2 ERP? Так. JSON може використовуватися в API, інтеграціях, frontend/backend-взаємодії, мобільних додатках, AI-сервісах і логіюванні.
Чи можна зберігати JSON у PostgreSQL? Так. PostgreSQL підтримує JSON і JSONB, але не варто замінювати JSON-ом нормальну структуру бази даних там, де потрібні зв’язки й звіти.
Чи підтримує JSON коментарі? У стандартному JSON коментарі не підтримуються.
Чому JSON важливий для API? Бо він легкий, універсальний, зрозумілий і підтримується майже всіма сучасними мовами програмування.

Висновок

JSON — один із найважливіших форматів сучасної розробки.

Він простий, легкий, універсальний і добре підходить для обміну даними між системами.

Для K2 ERP JSON важливий як формат API, інтеграцій, frontend/backend-взаємодії, мобільних додатків, AI-сервісів, логіювання, імпорту, експорту та синхронізації.

Але JSON не повинен підміняти собою всю архітектуру.

У правильній системі кожен інструмент має своє місце:

  • ER-модель описує сутності та зв’язки;
  • YML описує структури, моделі й компоненти;
  • ORM дозволяє коду працювати з базою даних;
  • PostgreSQL зберігає дані;
  • API відкриває взаємодію із зовнішнім світом;
  • JSON передає дані між системами.

JSON у K2 ERP — це універсальна мова обміну даними, яка допомагає системі спілкуватися з сайтами, мобільними додатками, банками, маркетплейсами, AI-сервісами, BI та зовнішніми системами.

Саме завдяки таким відкритим і зрозумілим форматам, як JSON, K2 ERP може розвиватися як сучасна українська ERP-платформа: модульна, інтеграційна, API-first, готова до ШІ та відкрита до партнерської екосистеми.

Див. також

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

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