> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.pricer24.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# ТЗ на розробку фіду для передачі каталогу в Pricer24

# Призначення документа

Ця стаття описує технічні вимоги до JSON-фіду (файлу), через який ваш каталог товарів передається в Pricer24.
Загальні принципи роботи з фідами, підтримувані формати даних та способи передачі описані в [цій статті](https://help.pricer24.com/uk/article/fidi-danih-pricer24-zagalni-principi-ta-pidtrimuvani-formati-1ulqs83/).

# Загальні вимоги

Ви надаєте URL фіду, а Pricer24 регулярно завантажує за цим посиланням файл із вашим каталогом товарів.

*  Стиснення: не обов’язкове. За необхідності - gzip. 
*  Ліміт розміру: відсутній  

Фід (файл) має містити **повний і актуальний** каталог товарів. Після завантаження файла, Pricer24 автоматично порівняє його із поточним каталогом і оновить лише необхідне.
Актуальними вважаються лише ті товари, які присутні у фіді (файлі) на момент його завантаження.

# Приклад JSON-фіду:

Тут наведений приклад, як може виглядати фід. Детальна структура і вимоги до полів фіду описані [нижче](#1-struktura-fidu).

```
 {
  "categories": [
    { "id": "1000", "parent_id": null, "name": "Бакалея" },
    { "id": "1001", "parent_id": "1000", "name": "Кондитерські вироби" },
    { "id": "1002", "parent_id": "1001", "name": "Цукерки" }
  ],
  "price_types": [
    { "id": "1", "name": "Магазин Київ 1" },
    { "id": "2", "name": "Магазин Київ 2" },
    { "id": "3", "name": "Магазин Харків 1" },
    { "id": "4", "name": "Онлайн" }
  ],
  "properties": [
    { "id": "weight", "name": "Вага (кг)", "type": "decimal" },
    { "id": "stock", "name": "Залишки товара", "type": "int" },
    { "id": "follow_rrp", "name": "Чи тримаємо РРЦ", "type": "bool"},
    { "id": "category_manager", "name": "Категорійний менеджер", "type": "string" }
  ],
  "products": [
    {
      "id": "153",
      "category_id": "1002",
      "name": "Цукерки Bonjour Десерт 500г",
      "vendor": "Konti",
      "vendor_code": "08013914",       
      "barcode": "4820000356848",
      "link": "https://example.com/products/konti-bonjour-dessert-500",
      "image_link": "https://example.com/products/konti-bonjour-dessert-500.jpg",
      "availability": "+",
      "prices": [
        		{ "price_type_id": "1", "price": 189.90, "currency": "UAH" },
        		{ "price_type_id": "2", "price": 189, "currency": "UAH" }
      ],
      "properties": {"weight": 0.152, "stock": 20, "follow_rrp": true, "category_manager": "Тарас Шевченко"}
     },
    {
      "id": "154",
      "category_id": "1002",
      "name": "Шоколад Milka Oreo 100г",
      "vendor": "Milka",
      "vendor_code": "7622210578266",
      "barcode": "7622210951182",
      "link": "https://example.com/products/milka-oreo-100",
      "image_link": "https://example.com/products/milka-oreo-100.jpg",
      "availability": "-",
      "prices": [
        		{ "price_type_id": "3", "price": 178.00, "currency": "UAH" },
        		{ "price_type_id": "4", "price": 150, "currency": "UAH" }
      ],
      "properties": {"weight": 0.2, "stock": 0, "follow_rrp": false, "category_manager": "Тарас Шевченко"}
    }
  ]
}
```

# Структура фіду

На верхньому рівні JSON-фід складається з чотирьох масивів: категорій, типів цін, властивостей (додаткових полів) і товарів.

* categories:	структура категорій товарів
* price_types: 	довідник типів цін, на які посилаються ціни товарів 
* properties:      додаткові кастомні поля, не передбачені основним контрактом
* products: 	детальний каталог товарів

```
{
"categories": [ ... ],
"price_types": [ ... ],
"properties": [ ... ],
"products": [ ... ]
}
```

# Масив **categories[ ]**:

Масив **categories[ ]** потрібен для передачі всіх товарних категорій у тій ієрархії, у якій вони існують у вашому каталозі, наприклад: Корм для тварин → Корм для котів → Сухий корм для котів → … 
Глибина вкладеності - як у вашому власному каталогу.
Зв’язок між категоріями різних рівнів задається через **parent_id**.

Формат даних масиву **categories[ ]**:
| **Поле** | **Тип даних** | **Обов’язкове** | **Опис** |
| **id** | string | Так | Код (ідентифікатор) категорії товару. Унікальний у межах масиву. Має залишатися незмінним у кожному наступному фіді. |
| **parent_id** | string / null | Так | Ідентифікатор батьківської категорії. Для кореневої категорії значення має бути **null** |
| **name** | string | Так | Назва категорії товару |


Приклад масиву **categories[ ]**:
```json
"categories": 
[
  { "id": "1000", "parent_id": null, "name": "Бакалея" },
  { "id": "1001", "parent_id": "1000", "name": "Кондитерські вироби" },
  { "id": "1002", "parent_id": "1001", "name": "Торти" },
    ...
    ...
  { "id": "100Х", "parent_id": "100(Х-1)", "name": "Каштан"},
  { "id": "100(Х+1)", "parent_id": "100Х", "name": "Каштан 500 г пластик" }
]
```

# Масив price_types[ ]:

У масиві **price_types[ ]** ви визначаєте типи цін, які ви хочете синхронізувати з нашою системою.
Це можуть бути стандартні типи цін або ціни в окремих торгових точках чи каналах продажу.  
Наприклад:
*     роздрібна
*     рекомендована роздрібна
*     акційна
*     оптова 
*     закупівельна
*     ціна окремого каналу продажу

Формат даних масиву **price_types[ ]**:
| **Поле** | **Тип даних** | **Обов’язкове** | **Опис** |
| **id** | string | Так | Код (ідентифікатор) типу ціни. Унікальний у межах масиву. Має залишатися незмінним у кожному наступному фіді. |
| **name** | string | Так | Назва типу ціни. Наприклад: "Роздрібна ціна", "Акційна ціна", "РРЦ", "Магазин Київ", "Онлайн" |

Приклади масиву **price_types[ ]**:

```
[ { "id": "1", "name": "Моя ціна" } ]
```
 
```
[ { "id": "1", "name": "Роздрібна ціна" }, 
  { "id": "2", "name": "Акційна ціна" }, 
  { "id": "3", "name": "РРЦ" } ]
```

```
[ { "id": "XXXX", "name": "Магазин Харків" }, 
  { "id": "YYYY", "name": "Онлайн" } ]
```


# Масив properties[ ]:

У масиві properties**[ ]** ви визначаєте додаткові поля, їх назви та типи, для синхронізації додаткових даних. Це можуть бути: залишки товарів, Id чи назви підрозділів, які відповідають за товар, Id чи ім'я категорійного менеджера і т.д. Будь яка додаткова інформація, яка потрібна для реалізації проєкта.

Формат даних масиву **properties[ ]**:
| **Поле** | **Тип даних** | **Обов’язкове** | **Опис** |
| **id** | string | Так | Ідентифікатор додатково поля, саме його ми будемо шукати в масиві товарів. |
| **name** | string | Так | Назва доп. поля. Використовується виключно для розуміння, що передається у відповідному полі. |
| **type** | enum | Так | Синхронізація підтримує обмежений перелік типів даних. Підтримуються значення: **int**, **decimal**, **bool**, **string**. |

Всі властивості із іншим типом будуть проігноровані системою.

Приклади масиву **properties[ ]:**
```
[ { "id": "weight", "name": "Вага (кг)", "type": "decimal" } ]
```
 
```
[ { "id": "stock", "name": "Залишки товара", "type": "int" } ]
```

```
[ { "id": "follow_rrp", "name": "Чи тримаємо РРЦ", "type": "bool"},
  { "id": "category_manager", "name": "Категорійний менеджер", "type": "string" } ]
```

Безпосередньо значення властивостей вже задаються для кожного товару у масиві **products[ ]**.

# Масив products[ ]:

Масив **products[ ]** є основною частиною фіду: саме тут передаються всі ваші товари, їхні характеристики, наявність і ціни.

Формат даних масиву **products[ ]**:
| **Поле** | **Тип даних** | **Обов’язкове** | **Опис** |
| **id** | string | Так | Код (ідентифікатор) товару. Є ключовим для оновлення товару в Pricer24. Має бути **унікальним і постійним** для одного й того самого товару. Pricer24 використовує його, щоб оновлювати той самий товар у наступних версіях фіду. |
| **category_id** | string | Так | Код (ідентифікатор) категорії, до якої належить товар. Має відповідати одному з id у масиві **categories[] ** |
| **name** | string | Так | Назва товару |
| **vendor** | string | Ні | Назва виробника товару |
| **vendor_code** | string | Ні | Артикул товару (код виробника). Передається за наявності |
| **barcode** | string | Ні | Штрих-код товару (EAN/UPC) |
| **link** | string (URL) | Ні | Посилання на сторінку товару на вашому сайті |
| **image_link** | string (URL) | Ні | Посилання на зображення товару |
| **availabilty** | boolean / string | Ні | Поточний стан наявності товару |
| **prices** | array<object> | Ні | Масив цін товару (тип ціни, значення ціни, валюта) |
| **properies** | object | Ні | Об’єкт зі значеннями додаткових полів у стандартному форматі JSON. Містить пари `key: value`, де `key` — `property_id`, а `value` — значення відповідного поля товару згідно зі специфікацією JSON. |

||| ${color}[#ff0000](⚠ ВАЖЛИВО!) Ідентифікатори товарів, тип цін, властивостей та категорій (${color}[#ff0000](id)) мають залишатися незмінними у кожному наступному фіді протягом усього часу роботи з Pricer24.

Саме за ${color}[#ff0000](**id**) Pricer24 розуміє, чи потрібно оновити вже наявний запис, чи створити новий. 
Назву товару можна уточнювати, перекладати або доповнювати, але ${color}[#ff0000](**id**) не потрібно змінювати, якщо товар залишається тим самим.

||| **Зміна** ${color}[#ff0000](id) **для вже переданого товару або категорії може призвести до втрати попередніх зіставлень** ваших товарів з пропозиціями конкурентів. 
**У такому випадку налаштування доведеться виконувати повторно**, що призведе до фінансових витрат, яких можна уникнути

# Масив prices[ ] всередині об'єкту product:

Масив **product.prices[ ]** містить усі ціни, які ви передаєте для одного конкретного товару.
Кожна ціна має посилатися на один із типів цін, описаних у кореневому масиві **price_types[ ]**.
Спочатку ви описуєте всі типи цін у кореневому масиві **price_types[ ]**, а потім у кожному товарі (у **product.prices[ ]** ) передаєте ціни з посиланням на відповідний **id** з довідника **price_types[ ]**.

`product.prices.price_type_id` ← `price_types.id`


Формат даних масиву **product.prices[ ]:**
| **Поле** | **Тип даних** | **Обов’язкове** | **Опис** |
| **price_type_id** | string | Так | Ідентифікатор типу ціни. Має відповідати одному з **id** у масиві **price_types[]** |
| **price** | number | Так | Ціна товару для цього типу ціни. Значення має бути числом. Для дробової частини використовуйте крапку, наприклад** 189.99** |
| **currency** | string | Так | Валюта ціни згідно зі стандартом [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)  ("UAH", "PLN", "USD", "EUR" … ) |
 
# Об'єкт properties всередині об'єкту product:

Об'єкт **product.properties {}** містить значення усіх властивостей (доп. полів) для конкретного товара. Спочатку ви описуєте всі необхідні вам властивості у кореневому масиві **properties[ ]**, а потім у кожному товарі (у **product.properties**) передаєте відповідні значення.

Приклади об'єкта **properties:**
```
{
  ... ,
  "properties": [ ... ],
  "products": [
    {
      ... ,
      "properties": {
      	"weight": 0.120, 
      	"stock": 20, 
      	"follow_rrp": true, 
      	"category_manager": "Тарас Шевченко"
      }
    },
    {
      ..., 
      "properties": {
      	"weight": 2.1, 
      	"stock": 0, 
      	"follow_rrp": false, 
      	"category_manager": "Тарас Шевченко"
      }
    }
  ]
}
```

||| ${color}[#ff0000](⚠ ВАЖЛИВО!)  Типи значень у `product.properties` повинні відповідати типам визначеним у масиві `properties[]`. Наприклад, якщо властивість `stock` оголошена як ціле число, але в товарі її значення передано як рядок — `"properties": {"stock": "20"}`, синхронізацію даних буде повністю призупинено до усунення помилки.


# Поле availability всередині об'єкту product - правила передачі

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

Приклади:
| **Тип** | **Товар в наявності** | **Товар не в наявності** |
| **boolean** | true | false |
| **string** | "+" | "-" |
| **string** | "1" | "0" |
| **string** | "yes", "in_stock", “Х”, "В наявності" … | "no", "out_of_stock", "Не в наявності"… |