Що старий API v1 робить з товарами, цінами й документами

Що варто знати до запуску

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

Де це і хто має доступ

Окремого вікна немає: правила діють на кожен запис через API v1, а наслідки видно в програмі.

Ключ

ключ v1 без «Тільки для читання» (поля ключа)

Де видно результат

таблиця товарів базового каталогу, колонка «Джерело: код»

Журнал

журнал роботи, операції типу «api»

Що перепишеться поверх ручних правок

api/scope/update для товарів переписує рівно ті поля, які є в запиті, а решту не чіпає. Товар шукається тільки за product_id: рядок з ідентифікатором, якого в базі немає, пропускається без помилки й не входить у total_item_update.

Окремо про вкладені списки в пакетному оновленні:

• якщо в записі є image_list, усі фото товару видаляються й замінюються присланими; прапорець «Не оновлювати фото» цього не зупиняє. Немає image_list — фото лишаються як були;
• якщо є attribute_list, характеристики товару стираються й записуються з пакета. Тут прапорці діють: у товару з «Не оновлювати» або «Не оновлювати атрибути» характеристики лишаються старі.

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

Чим закріпити своє значення:

Додавання з update_exist_product=1 знаходить наявні товари так само, як при захисті від дублів (нижче), і оновлює їх за іншими правилами, ніж update:

• порожнє значення або нуль у пакеті не затирає заповнене поле. Виняток — поля, де нуль означає дію: quantity, status, sort_order, subtract_quantity, shipping і всі поля flag_*;
• ціни (price, price_rrp, price_old, price_cost, price_special) не змінюються у товарів з «Фіксована ціна»;
• товари з «Не оновлювати» пропускаються цілком.

Без update_exist_product додавання поля наявних товарів не оновлює: знаходить і пропускає. Лише привʼязки до категорій зі списку category_list наявним товарам дописуються.

Замість прапорця можна передати field_list_update_exist_product — список полів, які оновити:

• пишуться тільки ці поля, так само оминаючи товари з «Не оновлювати» й ціни товарів із «Фіксована ціна»;
• price_special цей режим не захищає;
• назви, яких немає серед полів товару, пропускаються без помилки — решта списку оновлюється.

Що буде після обриву пакета і повтору

Пакет на 10 000 товарів сервер обробляє як послідовність окремих записів у базу, без транзакції: спершу категорії й виробники, потім самі товари, потім категорії товарів, характеристики, фото, знижки. Якщо обробка обірвалася посередині, в базі лишається те, що встигло записатися.

Повтор того самого пакета товари не задвоює. Перед записом кожен рядок шукається серед наявних товарів:

• якщо в рядку є uuid — за ним;
• якщо uuid порожній — за збігом трьох полів разом: mpn, назва й ext_url (без урахування регістру й пробілів по краях).

Знайдений товар удруге не створюється. Але фото й характеристики при додаванні пишуться тільки новоствореним товарам. Якщо обрив стався після створення товарів, але до запису фото, повтор фото не додасть — товар уже вважається наявним. Характеристики, яких бракує, повтор допише, якщо передати update_existing_attr[product_values]=1: відсутні значення додаються, наявні не чіпаються. Фото доведеться дослати через api/scope/update з image_list.

Без помилки пакет пропускає два види рядків, і їх видно лише з того, що total_item_add менший за відправлене:

• рядок без назви — відкидається до запису;
• новий товар без категорії — не створюється. Категорію пакет визначає за category_id, за повним шляхом у category_name_full (частини через /; якщо жодної частини шляху в базі немає, ланцюжок категорій створюється, інакше товар лягає в найглибшу знайдену за назвою) або за списком category_list. Не вийшло жодним способом — товар не записується. Параметр category_create_by_source=1 кладе такі товари в окрему службову категорію з кодом джерела в назві; вона створюється вимкненою й без вивантаження.

Чия ціна залишиться

Ціну товару в Elbuz пишуть три механізми: API, наценки базового каталогу й оновлення каталогу з прайс-листів. Хто записав останнім, того значення й лишиться — з такими правилами:

Тобто ціна, яку ви передали через API, доживе лише до наступного оновлення каталогу чи прогону наценок, якщо в товару не стоїть «Фіксована ціна». Щоб ціна з API лишалася головною, передайте разом із нею flag_fix_price=1. Прапорець знімається сам після дати в полі «Дата для зняття прапора "Фіксована ціна"», якщо її задано, — це перевіряється на кожному оновленні каталогу.

Коли додане потрапить на сайт і у вивантаження

Самі операції API нічого не вивантажують: ні add, ні update не запускають тунель чи вивантаження файлу. Товар потрапить далі найближчим прогоном того вивантаження, яке у вас налаштоване, — вручну чи за розкладом.

У межах самого запиту додавання вже зроблено все, що треба каталогу: наценки, службові дані для сортування й зведена (плоска) таблиця товарів. Якщо в акаунті кілька активних магазинів, нові товари додаються до магазину з параметра store_id, а без нього — до магазину з номером 1.

Тонке місце — режим тунелю «Вивантажувати лише нові дані». У ньому тунель бере тільки товари зі знятим «Прапор: вивантажено».

• Якщо товар створено через add, прапорець знятий, і товар поїде в найближчий прогін.
• Якщо товари змінено пакетним update (з item_list), прапорець теж знімається, і зміна поїде в найближчий прогін.
• Якщо змінено один товар без item_list, прапорець знімається, коли в запиті є хоч одне поле самого товару (ціна, залишок тощо). Запит лише з текстовими полями — назвою, описами, мета-тегами — прапорець не знімає, і в цьому режимі така зміна на сайт не поїде. Щоб поїхала, передайте в тому самому запиті flag_exported=0.

Видалення через api/scope/delete прибирає товар і з сайту, якщо в налаштуваннях тунелю дозволено видаляти товари на сайті: відразу, коли ввімкнено ще й «Видаляти дані відразу на сайті», інакше — найближчим прогоном тунелю. Без дозволу видаляти товари на сайті він лишається.

Як дізнатися про видалене

Інкрементальна синхронізація за date_modified про видалення не дізнається. Видалений товар стирається з бази повністю — разом з описами, фото, характеристиками й привʼязками до категорій, а серед довідників get журналу видалень немає. Разом із головним товаром видаляються і його товари-опції.

Щоб зловити видалене, періодично забирайте повний перелік ідентифікаторів (limit_field=product_id, max_rows=500, обхід по page_next) і звіряйте зі своїм: чого немає в Elbuz, того вже не існує.

У зворотний бік працює те саме правило: Elbuz нічого не видаляє за вас. Товар, якого у вашій системі не стало, add і update не зачіпають — він лишається в Elbuz з останніми записаними даними. Прибрати його можна лише явним api/scope/delete з його product_id.

Як відкотити помилковий пакет

Якщо пакет add завів зайві чи зіпсовані товари, знайдіть їх за позначкою джерела. Товари, створені пакетом, мають у полі «Джерело: код» ваш source_code (або jumper, якщо ви його не передавали).

• Через API: api/scope/get з фільтром filterdatafield0=source_code, filtercondition0=EQUAL, filtervalue0=my_erp дасть перелік ідентифікаторів. Для відбору саме цього прогону додайте другу умову за date_added.
• У програмі: у таблиці товарів базового каталогу відфільтруйте колонку «Джерело: код», відмітьте знайдені й видаліть — програма перепитає «Видалити вибрані товари?» з кількістю.

api/scope/delete видаляє один товар на запит, тож відкат тисячі товарів через API — це тисяча запитів у межах частоти. Таблиця товарів видаляє всі відмічені однією дією.

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

Документи: статус, залишок і дублі

Документ, створений через api/scope/add зі scope=document:

• потребує type_id — без нього відповідь «Не вказано тип документа», з неіснуючим — «Тип документа не знайдено»;
• лягає зі статусом «Новий», якщо status_id не передано;
• отримує номер автоматично, за нумерацією свого типу;
• не проводиться, якщо не передати is_sign=1. Без цього параметра залишок і резерв такий документ не змінює: резерв рахується тільки під проведені замовлення, а залишок рухає проведення. З is_sign=1 документ проводиться одразу в тому самому запиті — так само, як кнопкою проведення в програмі, з рухом залишків, а у відповіді зʼявляється поле is_sign.

Позиції документа передаються в item_list з product_id. Позиція з товаром, якого немає в базі, не записується, а у відповіді отримує статус Error і текст «Товар не знайдено»; решта документа створюється.

Від дублів при повторі захищає параметр check_unique_field_name — назва поля документа, унікального для вашої системи (наприклад, де лежить номер вашого замовлення).

• Якщо документ з таким значенням уже є, новий не створюється, а відповідь повертає «Документ уже існує» з document_id наявного.
• Для перевірки за парою полів є ще check_unique_field_name_2.
• Назва має бути точною назвою поля документа. Якщо поля з назвою з check_unique_field_name немає, перевірка не виконується й документ створюється; неіснуюча назва в check_unique_field_name_2 лише прибирає другу умову.
• Якщо значення поля в самому запиті не передали, воно вважається порожнім.

Сценарії

Облікова система шле ціни, а частину товарів менеджер веде руками

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

Що ввімкнути: на товарах менеджера — «Фіксована ціна», а там, де не можна чіпати нічого, — «Не оновлювати». Інтеграція шле api/scope/add з item_list, update_exist_product=1 і тим самим uuid, з яким товар заводила.

Що вийде: наявні товари знаходяться за uuid і оновлюються. Ціни товарів із «Фіксована ціна» лишаються менеджерськими, у товарів з «Не оновлювати» поля й характеристики не змінюються, а порожнє поле в пакеті не затирає заповнене (крім кількості, статусу й інших полів, де нуль означає дію, — перелік вище).

Чого не станеться: захисту не буде, якщо ту саму зміну відправити через api/scope/update, — там «Фіксована ціна» й «Не оновлювати» поля товару не захищають, і ціна перепишеться.

Замовлення з сайту без дублів при повторі

Задача: сайт передає замовлення в Elbuz і при збої мережі повторює запит — друге таке саме замовлення зʼявитися не повинно.

Що ввімкнути: api/scope/add зі scope=document і type_id; номер замовлення сайту — в полі документа, а назва цього поля — в check_unique_field_name.

Що вийде: документ лягає зі статусом «Новий» і номером за нумерацією свого типу. Повтор з тим самим номером відповідає «Документ уже існує» з document_id першого, другий документ не створюється.

Чого не станеться: залишок і резерв не зміняться, якщо не передати is_sign=1, — без нього документ лишається непроведеним, і проводять його в програмі.

Перше завантаження каталогу, яке можна прибрати

Задача: залити каталог з обліку так, щоб після обриву можна було повторити, а невдалий прогін — знайти й видалити.

Що ввімкнути: api/scope/add з item_list, source_code=my_erp, у кожного товару — власний uuid і шлях у category_name_full.

Що вийде: створені товари мають у полі «Джерело: код» значення my_erp. Товар лягає в найглибшу категорію шляху, знайдену за назвою, а якщо жодної частини шляху в базі немає — ланцюжок категорій створюється. Повтор пакета після обриву знаходить уже створене за uuid і не задвоює. Невдалий прогін знаходиться фільтром за «Джерело: код» — як це зробити.

Чого не станеться: повтор не додасть фото товарам, які встигли створитися до обриву, а після api/scope/update позначка джерела зміниться на api.

Що робити, коли результат не той

Часті запитання

Чи можна скасувати помилковий update?

Ні: попередні значення запит не зберігає. Відновіть дані повторним update з правильними значеннями з вашої системи (відкат).

Товар зник у моїй системі — чому він лишився в Elbuz?

Elbuz нічого не видаляє за вас: add і update такий товар не зачіпають. Видаліть його явним api/scope/delete з його product_id (докладно).

Чому замовлення з сайту не зменшило залишок?

Документ через API проводиться лише з is_sign=1. Без нього він лишається непроведеним, і залишок та резерв не змінюються (документи).

Чи можна шукати наявні товари без власного uuid?

Так: без uuid товар шукається за збігом mpn, назви й ext_url разом. Але після зміни назви збіг зникне, і повтор створить новий товар (повтор пакета).

Товар додано через API — чому його немає на сайті?

API сам нічого не вивантажує: товар поїде найближчим прогоном тунелю чи вивантаження. У режимі «Вивантажувати лише нові дані» зміна лише текстових полів без flag_exported=0 не поїде (докладно).

Суміжні теми

• Якщо потрібна загальна картина й перехід на API v2 — старий API v1: ключ і перехід.
• Якщо треба знайти параметр запиту чи розібрати помилку — довідник старого API v1.
• Якщо ціну з API переписують наценки — наценки базового каталогу.
• Якщо пишете нову інтеграцію й не хочете дублів при повторі — Idempotency-Key в API v2.