Торгсофт офіційно підтримує інтеграції, які вже реалізовані компанією та описані в документації програми й Торгсофт Онлайн Маркет. Підключення інших платформ можуть розробляти сторонні інтегратори та розробники. Вони створюють сервіс обміну, налаштовують роботу з платформою та забезпечують його супровід.
Для сторонніх підключень використовують наявні можливості Торгсофт: експорт товарів, цін, залишків і клієнтських даних, імпорт нових замовлень, спеціалізовані опції та експорт окремих звітів. Універсального відкритого API для довільного керування обліковими документами в цій схемі немає.
Посібник визначає, що потрібно підготувати з кожного боку та як розподілити роботу між власником магазину, інтегратором і розробником. У таблицях окремо зазначені штатні підключення та сценарії створення стороннього адаптера.
Додаткові опції Торгсофт можна безплатно активувати на 30 днів, зокрема «Синхронізацію з інтернет-магазином». Шлях у програмі: Налаштування → Перелік додаткових функцій → Активувати на 30 днів. Після активації перезапустіть Торгсофт.
Виняток — «Видалення статистик закритих періодів». Для окремих опцій діють демообмеження: наприклад, інтеграція з Rozetka у пробному режимі включає до XML-прайсу до 10 товарів. Доступ до API, підписки платформ, хостинг і розроблення адаптера оформлюють окремо. Строк розроблення та погодження доступу визначають незалежно від пробного періоду.
1. Як організувати обмін і хто за що відповідає
Адаптер — окрема програма або модуль сайту, який перетворює файли Торгсофт на запити до API зовнішнього сервісу та готує файли нових замовлень для Торгсофт. API платформи надає дозволені операції з її товарами, замовленнями чи контактами. Фід — файл каталогу, який сервіс завантажує за посиланням або приймає через свій механізм імпорту.
Підключення складається з двох частин. Інтегратор налаштовує експорт та імпорт у Торгсофт. Розробник створює або встановлює сумісний модуль із боку сайту, CRM чи маркетплейсу. Активація опції забезпечує можливості Торгсофт у межах її документації; сторонній сервіс обміну виконує перетворення даних і працює з API обраної платформи.
| Учасник | Що готує | За що відповідає |
|---|---|---|
| Власник магазину | Кабінети продавця, товари, склад, валюту, правила цін, оплат, резервування й відвантаження. | Допуск до платформи, достовірність обліку, дозволені товари та погоджений порядок роботи працівників. |
| Інтегратор Торгсофт | Опції, об’єкти синхронізації, поля файлів, центри обліку, рахунки для оплат, розклад і повідомлення. | Налаштування програми та перевірку створених документів, резервів, цін і роботи завдань. |
| Розробник адаптера | Застосунок платформи, авторизацію, відповідності товарів, перетворення форматів, журнал і відновлення. | Роботу API, повноту передавання, захист від повторного імпорту та сумісність інтерфейсів. |
| Адміністратор сервера | Каталоги обміну, права, шифрований транспорт, запуск сервісів, резервні копії та моніторинг. | Роботу після перезапуску й відокремлення службових даних від публічних фідів. |
| Менеджер замовлень | Перевірку замовлень, комплектацію, підтвердження оплат, відправлень, скасувань і повернень. | Дії, які залишені ручними, та звірку винятків, що не обробляються автоматично. |
Одна людина може виконувати кілька ролей. У технічному завданні для кожної ділянки все одно визначають виконавця та результат, за яким перевіряють роботу.
Напрямки передавання даних
| Напрямок | Механізм Торгсофт | Дія адаптера | Межі сценарію |
|---|---|---|---|
| Торгсофт → каталог | CSV/YML та фотографії. | Зіставляє товари, готує поля платформи, оновлює картки, ціни й кількість. | Нові картки потребують категорій, характеристик та інших обов’язкових даних платформи. |
| Платформа → нове замовлення | Імпорт SAL/XML/JSON. | Отримує замовлення, перевіряє позиції та формує файл зі значенням SaleType. | Формат визначає створення замовлення або рахунка, оплату й відвантаження за передбаченим сценарієм. |
| Торгсофт → контакти | TSClients.trs за налаштуванням. | Відбирає дозволені поля та приводить їх до структури CRM або розсилки. | Наявність контакту не встановлює згоду на рекламну розсилку. |
| Торгсофт → аналітика | Товарний файл та експорт конкретних звітів. | Завантажує файли в таблицю або аналітичну модель. | Історія продажів не входить до товарного файла. Експорт кожного звіту визначають окремо. |
Передавання каталогу не включає отримання замовлень. Імпорт нового замовлення не надає універсальної команди для зміни вже створеного рахунка, повернення або фінансової операції. Для таких дій використовують можливості конкретної штатної інтеграції чи окремий процес в інтерфейсі Торгсофт.
Три способи підключення
- Штатна інтеграція. Власник активує опцію або модуль ТОМ, інтегратор налаштовує його за інструкцією. Перелік операцій визначає документація підключення.
- Сторонній адаптер. Інтегратор готує файловий обмін Торгсофт, розробник працює з API чи фідом платформи та формує файли замовлень.
- Підключення через сайт або CRM. Торгсофт обмінюється даними з однією системою, яка має конектори до інших каналів. Розробник визначає маршрут замовлень, джерело залишків і правила резервування для всіх ланок.
Для кожного каналу визначають один маршрут надходження замовлення в Торгсофт. Наприклад, замовлення маркетплейсу передають прямим адаптером або через CRM. Одночасний імпорт обома маршрутами потребує спільного механізму виключення дублів.
2. Що підготувати в Торгсофт і як читати його файли
Основою адаптера є формат синхронізації інтернет-магазину з Торгсофт. Налаштування описані в інструкції до опції. До розроблення інтегратор передає розробнику фактичний файл товарів, налаштування експорту та номер версії бази даних.
2.1. Підготовка об’єкта синхронізації
- Активувати «Синхронізацію з інтернет-магазином» та відкрити Склад → Синхронізація з інтернет-магазином.
- Створити об’єкт із назвою каналу. Вибрати центри обліку для експорту та центр, із якого оформлюються замовлення.
- Визначити джерело ціни для рахунка: Торгсофт або інтернет-магазин. Для збереження ціни покупки на платформі перевірити «Для товарів рахунка брати ціни з».
- Узгодити резервування, обробку відсутньої кількості та рахунок або касу для оплат.
- Задати поля, назви файлів, кодування, передавання клієнтів і спосіб доставки фотографій.
- Налаштувати адресу обміну, вручну передати тестові товари та завантажити одне замовлення.
- Після перевірки ввімкнути розклад і повідомлення відповідальному працівнику.
На вкладці «Клієнти» перевіряють пошук за телефоном, створення нових клієнтів та оновлення їхніх даних. Розробник передає телефон у погодженому міжнародному форматі. Пошук за телефоном не замінює ключа замовлення й не захищає від повторного створення документа.
2.2. Доставка файлів: FTP із TLS або каталог вебсервера
| Спосіб | Налаштування Торгсофт | Робота адміністратора й розробника |
|---|---|---|
| FTP із SSL/TLS | Адреса сервера, логін, пароль, каталог і «Використовувати шифрування SSL/TLS». | Налаштувати сумісний FTP-сервер і TLS. Перевірити пасивний режим, права запису, завантаження й видалення. Підтвердити шифрування під час обміну. |
| Web-сервер: інформація | Каталог файлів товарів, клієнтів та інших даних. Тут програма також шукає файли замовлень. | Надати адаптеру доступ до каталогу. Для зовнішнього доступу створити захищений шлюз; HTTPS й авторизацію забезпечує вебсервер. |
| Web-сервер: фотографії | Каталог фотографій із параметрів Торгсофт. | Організувати доступ до зображень. Для цього способу фотографії мають зберігатися в каталозі. |
Тип «Web-сервер» працює з файлами у визначеному каталозі. Він не створює універсального REST API Торгсофт. SFTP є іншим протоколом; його підтримка в Make, n8n або маркетплейсі не означає підтримку в обраному способі доставки Торгсофт.
Каталоги товарного фіда, замовлень, контактів і сертифікатів розділяють за правами доступу. За публічним URL рекламної системи розміщують тільки дозволений товарний файл та зображення.
2.3. Товари, ціни, залишки та фотографії
TSGoods.trs — типова назва CSV із роздільником ;. Поля, їхні назви, порядок, заголовок і назва файла налаштовуються. Альтернативний формат — YML, XML-каталог із відповідною структурою тегів.
| Дані | Дії інтегратора | Дії розробника |
|---|---|---|
GoodID |
Включає ключ товару до експорту. | Зіставляє ключ із товаром або варіантом платформи та передає його назад у замовленні. Розрізняє бази різних магазинів. |
Articul, Barcode |
Перевіряє артикули, штрихкоди та дублікати. | Використовує для первинного зіставлення зі SKU. Для імпорту товарної позиції підставляє GoodID. |
| Назва, опис, виробник, категорії, динамічні характеристики | Заповнює картки та включає потрібні поля до файла. | Зіставляє категорії й характеристики з класифікатором платформи. Додає обов’язкові дані, яких немає в експорті. |
RetailPrice, WholesalePrice, акційні й валютні ціни |
Вибирає вид ціни та джерело ціни рахунка. | Застосовує валюту, націнку й округлення каналу. Зберігає фактичну ціну покупки та перевіряє підсумок замовлення. |
WarehouseQuantity |
Перевіряє врахування центрів обліку й резервів у файлі. | Розраховує доступність каналу за погодженим правилом. Враховані резерви повторно не віднімаються. |
WarehouseQuantityForPartner |
Включає кількість за центрами обліку. | Розбирає 2=1,000|3=2,000: код центру та кількість. Зіставляє коди зі складами платформи. |
ModelGoodID, колір, розмір |
Готує моделі й окремі складські варіанти. | Зіставляє кожен варіант. Розміри або кольори з окремими залишками зберігає як окремі складські позиції. |
GoodPhotoList, GoodPhotoListWithLinks |
Налаштовує каталог фото, назви файлів і префікс посилань. | Перевіряє URL та вимоги до зображень. Для цих полів використовує передбачений режим зберігання фото в каталозі. |
Парсер CSV налаштовують за фактичним експортом: роздільник, заголовки, кодування, лапки та числа. Спеціальні символи перевіряють на тестовому файлі. У режимі UTF-8 Торгсофт формує товарний CSV із BOM — службовою ознакою кодування на початку файла; адаптер повинен її обробляти.
YML Торгсофт не є готовим фідом для кожного сервісу. Розробник перевіряє кореневий елемент, обов’язкові теги, характеристики, мови та ID одержувача. Наприклад, Hotline використовує власну структуру XML, а маркетплейси потребують кодів категорій і значень характеристик.
2.4. Формат нового замовлення
Торгсофт приймає текстові файли .sal. Із версії БД 493 також підтримуються XML та JSON у UTF-8. Для SAL використовують кодування об’єкта синхронізації; у режимі UTF-8 потрібен BOM. Назву файла складають з ASCII-символів: латинських літер, цифр і безпечних роздільників.
Дані API перетворюють на схему Торгсофт: покупець потрапляє в Client, параметри — в Options, позиції — в Goods. Обов’язкові поля: Client.Name, Options.OrderNumber, Options.SaleType та GoodID, Price, Count для кожного товару.
Приклад JSON із умовними даними для попереднього замовлення:
{
"Client": {
"Name": "Тестовий покупець",
"MPhone": "+380670000000",
"EMail": "buyer@example.com"
},
"Options": {
"OrderNumber": "SHOP-A-100042",
"SaleType": "1",
"OrderDate": "2026-10-05 12:00:00",
"CurrencyInternationalCode": "UAH",
"Comment": "Тестове замовлення зовнішнього каналу"
},
"Goods": [
{ "GoodID": "201", "Price": "1290.00", "Count": "1" },
{ "GoodID": "202", "Price": "350.00", "Count": "2" }
]
}До завантаження інтегратор підставляє реальні GoodID тестової бази та перевіряє документи в програмі. Розробник формує стабільний OrderNumber із коду каналу, магазину та зовнішнього ID. Номери різних замовлень і магазинів не повинні збігатися.
Додаткові поля передають адресу, доставку, дату резерву, код валюти, вид торгівлі та центр обліку. Доступність залежить від версії БД. WarehouseID беруть із Торгсофт; код складу маркетплейсу потребує зіставлення. Призначення WarehouseID у загальних параметрах і товарному рядку описане у форматі обміну.
| Поле | Формат і призначення | Що погодити |
|---|---|---|
Options.OrderDate |
Дата замовлення: yyyy-mm-dd hh:mm:ss. |
Часову зону магазину та перетворення часу API до погодженого локального часу. |
Options.ReserveDate |
Дата резерву: ddmmyyyy, наприклад 05102026. |
Строк резервування й поведінку після його завершення. |
Options.CurrencyInternationalCode |
Міжнародний код валюти. За відсутності поля обробка відбувається в національній валюті. | Валюту замовлення, налаштування обліку та курси, якщо потрібне перерахування. |
Options.SaleForm |
1 — гурт, 2 — роздріб; відсутнє або некоректне значення означає роздріб. |
Вид торгівлі й джерело цін рахунка. |
Options.WarehouseID, Goods[].WarehouseID |
Центр обліку рахунка та центр списання окремої товарної позиції. | Реальні коди центрів із Торгсофт і обробку замовлення з кількох складів. |
Options.BonusPay, Options.GiftCertificate |
Сума оплати бонусами та перелік номерів використаних сертифікатів через кому. | Увімкнені опції, відповідні налаштування синхронізації, перевірку доступного балансу та результат списання. |
Options.DeliveryCondition, Options.DeliveryAddress |
Умова доставки й текстова адреса. | Заповнення цих полів та окремих структурованих параметрів перевізника. |
2.5. SaleType: які документи створює імпорт
| SaleType | Результат | Що перевіряють |
|---|---|---|
1 |
Попереднє замовлення, за яким можна створити рахунок. | Хто перевіряє замовлення й виписує рахунок. Підходить для першого випробування імпорту. |
2 |
Рахунок зі 100% передоплатою. | Повну оплату, суму, рахунок надходження та налаштування обліку. |
3 |
Рахунок зі 100% передоплатою та відвантаженням, створення видаткової накладної. | Повну оплату та момент облікового відвантаження. Статус «оплачено» не підтверджує передачу посилки перевізнику. |
4 |
Рахунок без оплати, з відвантаженням і створенням видаткової накладної. | Підставу для відвантаження без передоплати й подальший облік розрахунків. |
5 |
Одразу рахунок; попереднє замовлення не створюється. | Хто проводить оплату, резервування та відвантаження за рахунком. |
Для SaleType 2–5 документація передбачає наявність усієї потрібної кількості в центрі обліку. За відсутності товару продаж може пройти в мінус. До автоматичного створення документів перевіряють кількість і правила дій при її нестачі.
Коментар «оплачено» не проводить оплату. SaleType не виконує повернення коштів у платіжному сервісі. Розробник та інтегратор погоджують подію платформи, тип документа, рахунок надходження й подальші дії працівника.
2.6. Клієнти, гуртові ціни та сертифікати
За налаштуванням Торгсофт експортує TSClients.trs: ПІБ, контакти, адресу, картку клієнта, знижку, суму для її розрахунку та накопичені бонуси. Розробник визначає ключ зіставлення й передає одержувачу тільки потрібні поля. Історія покупок не входить до цього файла.
Опція «Політика гуртових цін» додає XML із порогами кількості та цінами. Для сертифікатів передбачений CSV TSGiftCertificate.trs. Одержувач має реалізувати відповідні правила цін або лояльності.
Використані бонуси й сертифікати передають у замовленні через BonusPay та GiftCertificate. Інтегратор активує потрібні опції й налаштування; розробник перед оплатою перевіряє актуальні дані за погодженим процесом. Команда звіряє остаточне списання в Торгсофт і правила скасування покупки.
Експорт бонусів і сертифікатів є знімком на час формування. Для використання лояльності в кількох каналах потрібен погоджений процес перевірки й списання. Сам файл не блокує повторне використання сертифіката в іншому магазині.
2.7. Розклад, POST-повідомлення та підтвердження імпорту
Товари й замовлення можуть мати окремі завдання. Інтегратор вибирає тип синхронізації та виконавця: Торгсофт або сервер автоматичних завдань. Для запуску програмою потрібна відкрита програма на зазначеному комп’ютері під указаним користувачем. Для фонової роботи перевіряють службу, її версію, права й доступ до файлів.
Інтервал установлюють за рекомендаціями довідки: не частіше одного разу на 10 хвилин з урахуванням інших об’єктів. Розробник окремо налаштовує частоту запитів до API. Часте опитування платформи не прискорює імпорт файла в Торгсофт поза розкладом.
«Відправляти POST-запит після синхронізації» повідомляє сайт про завершення обміну. Розробник надає URL, назву та значення параметра; інтегратор установлює їх у програмі. Для запиту задають кінцевий тайм-аут, допустимий User-Agent і перенаправлення. Тайм-аут 0 означає необмежене очікування.
Це повідомлення не є потоком усіх подій продажу чи повернення. Після нього адаптер читає готові файли. Webhooks зовнішньої платформи приймає власний HTTP-обробник адаптера.
У FTP-сценарії файл замовлення завантажується локально й видаляється з FTP, потім обробляється програмою та після успішного імпорту видаляється локально. Зникнення файла з FTP не підтверджує створення документа. Помилковий файл у локальному каталозі може перешкоджати подальшому імпорту; інтегратор перевіряє журнал і документи.
3. Штатні інтеграції та можливості ТОМ
Для цих сценаріїв використовують функції Торгсофт або спеціалізовані опції. Власник отримує доступ у зовнішньому сервісі, інтегратор налаштовує режим. Підтримка охоплює задокументовані операції підключення.
| Сервіс | Штатний сценарій | Підготовка й налаштування | Умови |
|---|---|---|---|
| Prom.ua | Товарний обмін і замовлення через «Інтеграцію з Prom.ua». | Власник: кабінет і доступи. Інтегратор: опцію, об’єкт, прайс, відповідності товарів та оформлення замовлень. | Перевірити варіанти, ціни, зв’язування позицій і підтримувані переходи статусів за інструкцією опції. |
| Rozetka | XML-прайс і замовлення через «Інтеграцію з Rozetka.ua». | Власник: кабінет, картки й доступи. Інтегратор: опцію, характеристики, фото, правила приймання й розклад. | Прайс має відповідати Rozetka. Демо — до 10 товарів. Перед публікацією перевірити повноту файла та його обробку. |
| Satu.kz | Обмін через спеціалізовану опцію Satu.kz. | Власник: магазин на Satu. Інтегратор: доступи, товари, ціни, об’єкт і приймання замовлень. | Підключення Satu та Kaspi є різними сценаріями. Для Kaspi потрібен окремий адаптер. |
| Нова пошта | Накладні через опцію «Нова пошта». | Власник: кабінет та API-ключ. Інтегратор: відправника, адреси, доставку й пов’язані документи. | Формат замовлення підтримує NewPostDeliveryOptions і номер ТТН. Деталі наведені в розділі про доставку. |
| Укрпошта | Передбачені опцією поштові відправлення. | Власник: доступи. Інтегратор: опцію, відправника, адреси й параметри посилок. | Параметри Нової пошти не використовуються для Укрпошти. Налаштування виконують за окремою інструкцією. |
| Binotel | Телефонія та передбачена опцією взаємодія з клієнтами. | Власник: акаунт і доступ. Інтегратор: опцію, підключення та телефони клієнтів. | Перевірити пошук клієнта й дозволи працівників. Підключення телефонії не надає API продажів. |
| ПриватБанк, monobank, UKRSIBBANK | Виписки через «Банківські виписки». | Власник: доступ до рахунків. Інтегратор: рахунки Торгсофт, спосіб отримання й розпізнавання оплат. | Рахунки, валюти й авторизацію перевіряють для конкретного підключення. Виписка й інтернет-еквайринг мають різні механізми. |
| TurboSMS, AlphaSMS | SMS через TurboSMS та AlphaSMS; Viber через TurboSMS Viber. | Власник: акаунт, баланс і погодженого відправника. Інтегратор: сервіс, доступи, шаблони й адресатів. | Діють вимоги провайдера до повідомлень і відправника. Для реклами потрібна належна згода адресатів. |
| SendGrid, SMTP | Надсилання електронних листів засобами програми. | Власник: поштовий сервіс і домен. Інтегратор: спосіб надсилання, доступи й відправника. | Перевірити домен, ліміти, відписки та недійсні адреси. Налаштування надсилання не включає всі функції маркетингового сервісу. |
| Google Drive | Архівування у хмарне сховище. | Власник: акаунт і місце. Інтегратор: опцію архівування, авторизацію, склад архіву й розклад. | Перевірити завершення копіювання та відновлення. Архів бази не використовують для оперативних залишків маркетплейсу. |
| M.E.Doc, Арт-Звіт | Документи через передбачені формати експорту. | Бухгалтер: тип документа й реквізити. Інтегратор: відповідний експорт та імпорт в одержувачі. | Обсяг визначається типом документа. Повна двостороння синхронізація бухгалтерії до цього сценарію не входить. |
| Webkassa, ІС ЕШФ Казахстану | Спеціалізовані опції для фіскалізації й електронних рахунків-фактур. | Власник і бухгалтер: реєстрацію, реквізити й доступи. Інтегратор: опції та налаштування. | Ці функції мають власні вимоги й не замінюють обмін товарами та замовленнями з Kaspi. |
Документація: інтеграції Торгсофт, довідка програми, банківські виписки.
Готові модулі Торгсофт Онлайн Маркет
Торгсофт Онлайн Маркет, ТОМ — платформа інтернет-магазину, яка працює разом із Торгсофт. Доступи, оплати, фіди й зовнішні ресурси налаштовують у панелі ТОМ. Його інтеграції стосуються даних магазину й не створюють API до всіх документів Торгсофт.
| Модуль ТОМ | Дані | Дії інтегратора | Перевірки |
|---|---|---|---|
| KeyCRM | Замовлення ТОМ, покупець, товари, ціни, оплати й доставка; налаштовані зворотні статуси до ТОМ. | Активувати модуль; указати ключ, ID джерела, менеджера, доставок, оплат і статусів. | Інші канали KeyCRM потребують окремого маршруту до Торгсофт. Статус у ТОМ та стан облікових документів перевіряють окремо. |
| LiqPay, Portmone, monobank | Оплата в ТОМ і передавання замовлення за вибраним типом. | Підключити мерчанта, ключі та «Тип замовлення Торгсофт» для способу оплати. | Перевірити успішну оплату, рахунок, суму й документ. Повні банківські дані платежу цим модулем не передаються. |
| Google Merchant Center, Hotline | Товарні фіди. | Активувати фід, включити категорії, заповнити характеристики й перевірити звіт формування. | Фід має пройти перевірку одержувача. Передавання каталогу не означає погодження рекламної кампанії. |
| Google Analytics 4, Google Tag Manager | Вебаналітика й події магазину. | Указати ID ресурсів, налаштувати теги й перевірити події. | Перевірити transaction ID та дублювання purchase. Офлайн-продажі потребують окремого джерела даних. |
4. Платформи інтернет-магазинів
Для CMS потрібен модуль, який зіставляє позиції сайту з товарами Торгсофт, оновлює погоджені поля й передає нові замовлення. Власник надає доступ до магазину та визначає склад. Інтегратор готує файловий обмін. Розробник установлює сумісний конектор або створює адаптер до API платформи.
Перед запуском зафіксуйте, хто створює картки товарів і керує описами. Для вже заповненого сайту можна передавати лише ціни й залишки. Якщо картки створюватиме адаптер, йому додатково потрібні категорії, характеристики, варіанти, фотографії та правила публікації.
| Платформа | Сценарій | Що підготувати та зробити | Умови й перевірки |
|---|---|---|---|
| Хорошоп | Каталог, ціни, залишки та замовлення через підключення платформи. | Власник узгоджує підключення з Хорошоп. Інтегратор налаштовує опцію синхронізації, файл, фотографії й каталог замовлень за вимогами конектора. | До запуску погодити склад полів та ідентифікатор зіставлення. Перевірити розміри, кольори, наявні картки, ціни зі знижками й тип документа замовлення. |
| OpenCart | Каталог і замовлення через модуль обміну. | Власник надає версію CMS та перелік розширень. Розробник установлює сумісний модуль або додає обробник файлів і завдання обміну. Інтегратор налаштовує Торгсофт. | Стандартний API OpenCart не замінює повний конектор каталогу. Перевірити сумісність із модулем варіантів, знижками, податками та нестандартним оформленням замовлення. |
| WooCommerce | Товари, варіації, залишки й нові замовлення. | Розробник отримує ключі REST API з потрібними правами, використовує товари, варіації та замовлення wc/v3. Зберігає зв’язок GoodID із product/variation ID. |
Окремо перевірити керування запасом батьківського товару й варіації, статуси замовлення та повторну доставку webhook. Вебхуки мають проходити перевірку підпису. |
| PrestaShop | Товари, комбінації, запаси та замовлення через Webservice. | Адміністратор активує Webservice та видає обмежений ключ. Розробник працює з ресурсами товарів, комбінацій, stock_availables і замовлень. |
Формат запитів і доступні ресурси звірити з версією магазину. За багатомагазинного режиму врахувати shop ID; запас комбінації оновлювати за її ідентифікатором. |
| Shopify | Каталог, ціни, складські кількості та замовлення через GraphQL Admin API. | Власник установлює застосунок. Розробник налаштовує авторизацію, дозволи на товари, запаси й замовлення; зіставляє варіанти, inventory item та location ID. | Доступ до даних покупців і старих замовлень потребує відповідних дозволів. Перевірити версію API, ліміти GraphQL та відмінність доступної кількості від інших станів запасу. |
| Wix Stores | Каталог, запаси й замовлення Wix. | Розробник визначає версію каталогу магазину, отримує дозволи Stores та eCommerce, зіставляє варіанти й місця зберігання, використовує відповідні Inventory API та Orders API. | Поля агрегованого запасу в об’єкті товару можуть бути лише для читання. Оновлювати кількість через призначений для цього ресурс; не змішувати моделі каталогів V1 і V3. |
| Ecwid | Товари, комбінації, кількість і замовлення. | Власник перевіряє доступність API для магазину. Розробник отримує store ID і токен із правами читання замовлень та роботи з каталогом. | Зіставляти окремі комбінації, зберігати ID магазину разом з ID замовлення. Перевірити статуси оплати, замовлень і обмеження плану. |
| BigCommerce | Каталог, залишки та замовлення. | Розробник налаштовує API account/OAuth і потрібні scopes. Для каталогу використовує Catalog API, для складів — Inventory API, для замовлень — відповідний Orders API. | Ресурси належать до різних версій API. Врахувати location ID, варіанти, канали та прайс-листи; не переносити одну ціну на всі групи покупців без погодження. |
| Magento / Adobe Commerce | Товари, складські кількості та замовлення через REST API. | Адміністратор створює інтеграцію з потрібними ресурсами. Розробник зіставляє SKU, website/store scope та inventory sources. | У Multi-Source Inventory кількість у source й salable quantity мають різне призначення. Врахувати резервування Magento та не віднімати той самий резерв двічі. |
| MODX та індивідуальний сайт | Каталог і замовлення через власний модуль. | Розробник додає обробник товарного файла до фактичного модуля магазину, журнал зіставлення та генератор файлів замовлень. Налаштовує фонові завдання. | MODX сам по собі не задає єдиного формату кошика та замовлення. Контракт обміну визначають для встановленого компонента магазину або власної бази сайту. |
5. Маркетплейси та сервіси оголошень
Prom.ua, Rozetka та Satu.kz розглянуті серед штатних опцій. Для платформ у цій таблиці описано роботу стороннього адаптера. Власник спочатку оформлює кабінет продавця й доступ до потрібних операцій. Розробник перевіряє дозволи застосунку, вимоги категорій, формат ціни й кількості, а інтегратор готує обмін Торгсофт.
Передавання лише артикулу, назви й ціни достатнє для оновлення частини вже створених пропозицій. Для публікації нової картки потрібні всі обов’язкові атрибути платформи. Відсутні у товарному файлі дані зберігають у таблиці відповідностей або довідниках адаптера.
| Сервіс | Сценарій | Що робить розробник | Що перевірити власнику й інтегратору |
|---|---|---|---|
| Etsy | Оновлення лістингів, варіантів, цін, кількості; отримання замовлень. | Реєструє застосунок Open API v3, налаштовує OAuth з PKCE і потрібні scopes. Зіставляє GoodID із listing/product/variation, готує файл замовлення. | Тип доступу застосунку, правила допустимих товарів Etsy, характеристики варіантів, профілі доставки й валюта магазину. Комерційний доступ для обслуговування інших продавців погоджують за правилами Etsy. |
| eBay | Пропозиції через Inventory API, замовлення через Fulfillment API. | Отримує seller OAuth, налаштовує inventory location, бізнес-політики та SKU. Створює або оновлює inventory items/offers, завантажує замовлення. | Погодити спосіб перенесення наявних лістингів. Пропозиції, створені через Inventory API, обслуговувати його операціями. Перевірити ринок, валюту, доставку й залишок кожної варіації. |
| Allegro | Пропозиції, ціни, наявність і замовлення. | Реєструє застосунок, виконує OAuth, зіставляє товари з offers, читає checkout forms та події замовлень. | Обов’язкові параметри категорій, каталог Allegro, доступні ринки, валюта й способи доставки. Прив’язка товару до каталогу та публікація пропозиції — окремі операції. |
| Amazon | Пропозиції й запаси продавця, отримання замовлень через Selling Partner API. | Оформлює застосунок і ролі, налаштовує авторизацію продавця, зв’язки SKU/ASIN/marketplace ID та відповідні Listings, Feeds і Orders API. | Розділити FBM і FBA: локальний запас магазину не замінює залишки складу Amazon. Доступ до персональних даних оформити за чинними правилами відповідного API та ролі. |
| Епіцентр Маркетплейс | Каталог, ціни й залишки через XML; замовлення через API. | Готує XML за вимогами Епіцентру, категорії та атрибути. За токеном кабінету отримує замовлення й створює файли для Торгсофт. | API замовлень не замінює товарний XML-фід. Тести API проводити з урахуванням роботи в продуктивному середовищі; узгодити контрольне замовлення й уникнути масових змін. |
| АЛЛО Маркетплейс | Каталог, ціни й залишки через товарний фід. | Перетворює експорт Торгсофт на XML за вимогами кабінету, додає категорії, характеристики та фотографії, публікує файл для завантаження. | Спосіб отримання замовлень узгодити окремо через дозволений інтерфейс або конектор CRM. Товарний фід сам по собі замовлень не передає. |
| eMAG | Каталог, пропозиції, запаси й замовлення через Marketplace API. | Одержує API-доступ продавця, реалізує ресурси продуктів/пропозицій та замовлень для потрібного регіону. | Категорії, локалізовані дані, податки й валюта регіону. Обробляти результати по кожній позиції та повідомлення асинхронного опрацювання. |
| Kaufland Global Marketplace | Товарні дані, пропозиції та замовлення через Seller API; імпорт частини даних через CSV. | Налаштовує підписані API-запити, storefront і склади. Зіставляє EAN/товар із units продавця, отримує order units. | Створення товарних даних та пропозиції продавця мають різні вимоги. Перевіряти результат CSV-імпорту після завершення обробки, а не лише прийняття URL. |
| Kaspi Магазин | Пропозиції через XML; замовлення через API. | Формує XML-прайс із merchant ID, SKU, складськими даними та цінами; отримує замовлення з дозволеним токеном і переводить їх у формат Торгсофт. | Доступ продавця до Kaspi, правила регіону, міста й склади. Штатна синхронізація Satu.kz не виконує підключення Kaspi. |
| Kasta | Каталог через XML та обмін залишками через інтерфейси HUB. | Одержує від продавця контракт підключення для його моделі співпраці; налаштовує XML і дозволені операції HUB API, зіставляє товари та варіанти. | Уточнити схему складів і спосіб передавання замовлень у кабінеті постачальника. Ланцюжок через іншу CRM потребує окремої перевірки кожного напрямку обміну. |
| OLX | Публікація та керування оголошеннями через доступні операції OLX API. | Реєструє застосунок, отримує авторизацію користувача, готує оголошення із товарних даних і зберігає їхні ID. | Категорії, пакети, модерація й дозволи облікового запису. Оголошення не є замовленням: оформлення продажу та імпорт у Торгсофт визначають окремо. |
| Temu | Отримання замовлень через дозволені методи Partner API. | Оформлює застосунок і авторизацію продавця в потрібному регіоні. За наданими правами читає список та деталі замовлень, зіставляє позиції й формує імпорт. | До початку робіт перевірити доступ до методів замовлень і даних доставки для моделі продавця. Каталог і запаси включати в завдання лише після погодження відповідних операцій API. |
| TikTok Shop | Товари й замовлення через TikTok Shop Open Platform. | Оформлює застосунок, авторизацію продавця, підписування запитів і scopes. Працює з доступними Product та Order API, складами й SKU. | Магазин має бути допущений до підтримуваного ринку. Перевірити вимоги категорії, відповідність товарів, дозволи й регіональні відмінності API. |
Обов’язкові відповідності маркетплейсу
- Товар: GoodID Торгсофт → SKU продавця → ID пропозиції та її варіанта. Для комплекту зберігають склад і правило перерахунку кількості.
- Склад: центр обліку → warehouse/location/storefront платформи. Продажі зі складів маркетплейсу відокремлюють від власних.
- Замовлення: канал + кабінет продавця + зовнішній ID → OrderNumber. Номер використовують незмінно на всіх повторних отриманнях.
- Ціна: валюта, податки, акційна та фактична ціна покупки. Комісія платформи не зменшує автоматично суму товарів у замовленні.
- Стан: які статуси дозволяють імпорт, резерв, оплату, відвантаження та ручне скасування. Статуси різних систем мають власні значення.
6. Товарні каталоги та рекламні канали
Ці сервіси отримують товарні дані для показу пропозицій. Замовлення оформлюється у визначеному каналі продажу, звідки його й передають до Торгсофт. Власник готує бізнес-кабінет і сайт; розробник створює фід або використовує готовий модуль магазину; маркетолог перевіряє діагностику та рекламу.
| Сервіс | Підключення | Дії виконавця | Вимоги |
|---|---|---|---|
| Google Merchant Center | Готовий фід ТОМ або адаптер товарного файла. | Розробник додає стабільний ID, посилання на сторінку й зображення, ціну, валюту, наявність та ідентифікатори товару. Власник налаштовує джерело даних і підтверджує сайт. | Ціна й наявність мають відповідати сторінці та оформленню покупки. GTIN, бренд та інші поля заповнюють за вимогами конкретного товару. Результат перевіряють у діагностиці Merchant Center. |
| Hotline | Фід ТОМ або XML за специфікацією Hotline. | Розробник зіставляє категорії, виробників, характеристики, ціни, посилання й умови доставки. Власник підключає прайс у кабінеті магазину. | YML іншої платформи не приймають за готовий файл Hotline без перетворення. Перевіряють валюту, товарні URL, обов’язкові поля та підсумок завантаження. |
| Facebook та Instagram: каталог Meta через Shopify | Торгсофт → Shopify → офіційний канал Facebook & Instagram. | Розробник підтримує каталог Shopify, власник підключає бізнес-ресурси Meta, маркетолог налаштовує каталог і кампанії. | Доступність функцій залежить від країни, бізнес-акаунта й правил Meta. Імпорт замовлень виконують із Shopify лише для фактично створених там замовлень. |
| Pinterest Catalogs | Фід для товарного каталогу. | Розробник готує файл за специфікацією Pinterest із посиланнями, цінами та наявністю. Власник налаштовує business account, домен і джерело. | Перевірити доступність каталогів для країни й відповідність магазину вимогам Pinterest. Публікація товарного піна не створює замовлення в Торгсофт. |
Фід публікують повністю: розробник перевіряє структуру, кількість позицій і доступність посилань, після чого замінює робочу версію. Порожній або неповний файл блокують до з’ясування причини, щоб зовнішній сервіс не зняв з публікації чинні пропозиції.
7. CRM та багатоканальні продажі
CRM може об’єднувати замовлення сайтів і маркетплейсів. Для такої схеми потрібен окремий міст між CRM і Торгсофт. Наявність у CRM конекторів до каналів не налаштовує цей міст автоматично.
Власник визначає джерело залишків та порядок резервування. Розробник збирає замовлення, зберігає вихідний канал і ID, зіставляє товари та створює файл Торгсофт. Інтегратор перевіряє результуючі документи. Поки замовлення ще не імпортоване й не вплинуло на обліковий запас, адаптер або CRM враховує його в погодженому резерві каналу.
| Сервіс | Сценарій | Підготовка й реалізація | Межі обміну |
|---|---|---|---|
| KeyCRM | Готовий модуль ТОМ або сторонній адаптер замовлень інших джерел. | Для ТОМ інтегратор використовує модуль із розділу 3. Для інших каналів розробник отримує API-ключ, визначає джерела, відбирає замовлення, зіставляє SKU й готує файли. | Штатний модуль ТОМ обслуговує описаний маршрут ТОМ. Статуси інших каналів, платежі та зворотні зміни в Торгсофт включають до окремого технічного завдання. |
| SalesDrive | Нові замовлення в Торгсофт; товарні залишки в CRM через дозволений механізм. | Власник видає ключ із потрібними правами. Розробник читає список замовлень, застосовує фільтри й пагінацію, перетворює позиції. Для залишків обирає документований XML/API-інтерфейс. | Перевірити доступність методів для тарифу та налаштувань кабінету, поточні ліміти й поля форми. За ручної зміни замовлення після імпорту потрібна процедура звірки. |
| KeepinCRM | Каталог, ціни та залишки через XML. | Розробник формує XML і налаштовує відповідності полів; власник указує URL та правила імпорту в KeepinCRM. | Документований автоматичний XML-імпорт виконується кожні 12 годин. Цей маршрут не означає автоматичного передавання всіх замовлень або запуску подій руху складу під час перезапису залишків. |
| Base / BaseLinker | Запаси в inventory та замовлення з підключених каналів. | Розробник отримує токен, inventory ID, склади й відповідності товарів. Оновлює кількості, читає підтверджені замовлення та, за ввімкнення, журнал подій. | Опрацьовувати всі сторінки й замовлення з однаковою часовою міткою. Один імпорт у Торгсофт на одне зовнішнє замовлення; зміни після підтвердження обробляти за окремими правилами. |
| HubSpot | Передавання вибраних контактних даних. | Розробник перетворює TSClients.trs на запити Contacts API або файл імпорту. Власник погоджує поля й ключ зіставлення; адміністратор видає доступ. | Контакти не містять автоматично всієї історії покупок, угод і балансів. Правила оновлення та захист від дублів задають окремо. |
| Pipedrive | Синхронізація погоджених полів контактів. | Розробник використовує актуальний Persons API, зіставляє контакт із зовнішнім ключем і зберігає Pipedrive ID. | Не створювати нову особу при кожному експорті. Створення угод, активностей та історії продажів потребує інших джерел і окремого сценарію. |
| Zoho CRM | Оновлення контактів через API. | Розробник налаштовує OAuth для потрібного дата-центру, обов’язкові поля Contacts та upsert із погодженим ключем. | Перевірити Last Name, користувацькі поля, правила дублів і permissions. Поля з іншими форматами попередньо нормалізувати. |
Як розподілити статуси
Розробник веде таблицю відповідностей: статус CRM, умова імпорту, SaleType і дія менеджера. Наприклад, підтверджене неоплачене замовлення може створювати рахунок без відвантаження. Після фактичної оплати вже створеного рахунка менеджер або окремий підтримуваний механізм реєструє платіж. Повторний імпорт того самого замовлення як нового рахунка виключають.
Скасування та повернення після імпорту потрапляють у чергу звірки. Відповідальний працівник змінює документи Торгсофт і підтверджує завершення операції. Автоматизацію цього етапу включають тільки з конкретним підтримуваним способом роботи з документом.
8. Розсилки, телефонія та месенджери
Для SMS, Viber, електронних листів і телефонії спочатку перевіряють штатні налаштування Торгсофт із розділу 3. Для маркетингових платформ розробник використовує дозволений експорт контактів. Власник визначає мету передавання, підставу для надсилання повідомлень і порядок відписки.
| Сервіс | Сценарій | Робота розробника й власника | Перевірки |
|---|---|---|---|
| SendPulse | Контакти для розсилок через імпорт або API. | Розробник перетворює TSClients.trs на список із потрібними полями, налаштовує авторизацію й адресну книгу. Власник погоджує аудиторію та повідомлення. | Зберігати статус згоди й відписки. Експортований телефон чи email не означає дозвіл на всі канали повідомлень. |
| Mailchimp | Імпорт або оновлення аудиторії. | Розробник готує CSV чи використовує Marketing API, зіставляє email і додаткові поля. Маркетолог обирає audience та правила сегментації. | Не відновлювати підписку відписаних контактів повторним експортом. Дані e-commerce та події покупок потребують окремого джерела. |
| Brevo | Контакти, атрибути й списки через API. | Розробник зіставляє поля, ідентифікатори й list IDs, створює або оновлює контакти. Власник налаштовує списки й правила комунікації. | Перевірити формати телефону, типи атрибутів та поведінку при збігу email і номера. Відписки й блокування мають пріоритет над повторним імпортом. |
| Telegram Bot API | Сповіщення адаптера та структуровані замовлення з бота. | Розробник створює бота, збирає кошик із відомих SKU, кількість і дані покупця, формує файл замовлення. Для повідомлень використовує погоджені chat IDs. | Вільне повідомлення в чаті не є готовим замовленням. Потрібні перевірка користувача, токена, webhook, ціни й усіх позицій. Сповіщення відображають тільки підтверджені адаптером події. |
| WhatsApp, Instagram, Facebook Messenger через SendPulse | Замовлення зі сценарію чатбота через webhook. | Власник підключає потрібний бізнес-канал. Розробник приймає дані оформленого кошика, знаходить GoodID і створює файл для Торгсофт. | Перевірити права бізнес-акаунта, доступність каналу, правила повідомлень, шаблони та згоду. Довільне листування з менеджером потребує окремого оформлення замовлення. |
Webhook месенджера приймає адаптер. Він перевіряє подію, зберігає її в журналі та відповідає платформі. Файл для Торгсофт створюється після перевірки замовлення. Це дає змогу повторно обробити подію без повторного створення документа.
Binotel використовують у межах штатного сценарію телефонії. Для зв’язування дзвінка з CRM або окремим ботом визначають власний маршрут і права доступу до даних розмов. Телефонний номер покупця не є ідентифікатором його замовлення.
9. Платежі та доставка
9.1. Онлайн-оплата й банківська виписка
Модулі ТОМ для LiqPay, Portmone та monobank і штатні банківські виписки наведені в розділі 3. Для іншого сайту платіжний провайдер підключається з боку сайту. Розробник підтверджує результат платежу, а інтегратор погоджує його відображення в Торгсофт.
| Провайдер | Сценарій | Що реалізувати | Умови |
|---|---|---|---|
| WayForPay | Оплата на сайті; імпорт підтвердженого нового замовлення. | Власник отримує merchant account. Розробник підключає платіж, перевірку підпису callback, номер, суму, валюту й кінцевий статус. | Сторінка успішного повернення покупця не замінює перевірки платежу. Повторний callback не повинен повторно створювати замовлення. |
| Stripe | Оплата сайту через доступний бізнесу акаунт Stripe. | Розробник перевіряє підпис webhook на оригінальному тілі запиту, співвідносить платіж із замовленням і підтверджує фінальний стан. | Власник перевіряє доступність Stripe для країни та бізнесу. Відкладені способи оплати завершуються окремою подією; створення платіжної сесії не підтверджує оплату. |
| PayPal | Оплата на сайті через бізнес-акаунт. | Розробник підключає checkout, перевірку webhook і результат фактичного списання — capture. Зберігає payment/capture ID. | Погодження замовлення покупцем та завершене списання мають різні стани. Перевірити доступність приймання платежів, валюту та суму. |
Якщо нове замовлення отримують уже з підтвердженою повною оплатою, для нього можна погодити SaleType=2. Для автоматичного облікового відвантаження потрібен окремо погоджений сценарій SaleType=3. Якщо рахунок уже створений у Торгсофт, пізніша оплата не є підставою завантажувати це замовлення повторно як нове.
Часткові платежі, післяплату, комісії, повернення та розбіжності сум опрацьовують за окремими правилами. Інтегратор указує рахунок надходження, менеджер звіряє суму продажу з оплатою, бухгалтер — із виплатою провайдера. Утримана комісія й отримана на банк сума не змінюють автоматично ціну придбаних товарів.
9.2. Передавання даних доставки
Документ продажу та транспортна накладна мають різне призначення. Для доставки власник оформлює акаунт перевізника. Розробник передає адресні дані та зовнішні ідентифікатори; інтегратор визначає, де створюється ТТН і як працівник бачить її в Торгсофт.
| Сервіс | Маршрут | Що підготувати | Межі сценарію |
|---|---|---|---|
| Нова пошта | Штатна опція та дані NewPostDeliveryOptions у файлі замовлення. |
Інтегратор налаштовує акаунт, відправника й опцію. Розробник передає одержувача, тип доставки, відділення або адресу; для наявної ТТН — DeclarationNumber. | Перевірити чинні ідентифікатори відділень, телефон і українські адресні дані. Імпорт наявної ТТН має власні умови, наведені нижче. |
| Укрпошта | Штатна опція Торгсофт. | Власник отримує доступ перевізника. Інтегратор налаштовує відправника, адресу, тип відправлення та дані одержувача за інструкцією опції. | Блок NewPostDeliveryOptions призначений для Нової пошти. Його поля не є універсальним форматом усіх перевізників. |
| Meest Пошта через KeyCRM | Створення та друк ТТН у CRM. | Власник підключає перевізника в KeyCRM. Менеджер створює накладну там; адаптер передає саме замовлення в Торгсофт за узгодженим маршрутом. | Друк документів у CRM доступний для ТТН, створених її інтеграцією. Номер ТТН Meest не передають як DeclarationNumber Нової пошти. |
| Rozetka Delivery через KeyCRM | ТТН та документи доставки у CRM. | Власник налаштовує перевізника, менеджер оформлює доставку в CRM. Розробник зберігає tracking ID у журналі зв’язку із замовленням. | Доставку в CRM та облікове відвантаження в Торгсофт звіряють окремо. Автоматичного запису сторонньої ТТН у довільний документ Торгсофт цей маршрут не додає. |
| InPost | Оформлення відправлення стороннім адаптером. | Власник отримує доступ до API потрібного ринку. Розробник передає адресні дані, пункт видачі й параметри посилки, отримує етикетку та tracking ID. | Використовувати API й договір конкретної країни. Відстеження зберігається в адаптері, сайті або CRM; запис у Торгсофт погоджують окремо. |
| DHL Express | Відправлення й етикетки через MyDHL API. | Власник готує акаунт і договір. Розробник передає адресу, вагу, габарити, сервіс та митні дані для міжнародного відправлення. | Потрібні реальні параметри пакування. Товарний файл Торгсофт сам по собі не містить усіх даних для транспортної й митної документації. |
Поля Нової пошти, які потрібно зіставити
У NewPostDeliveryOptions передають RecepientType, ПІБ і телефон. Для доставки у відділення використовують WarehouseRef або місто та номер відділення. Якщо переданий WarehouseRef, місто й номер відділення для цього пошуку не потрібні. Для адресної доставки заповнюють відповідні поля вулиці, будинку та квартири.
Якщо заповнений DeclarationNumber, інші поля цього блоку ігноруються: використовується наявна ТТН. Її завантаження передбачене для імпорту з видатковою накладною — SaleType 3 або 4 — або після формування рахунка з попереднього замовлення. Інтегратор перевіряє цей процес у своєму сценарії.
10. Аналітика та автоматизація файлів
В аналітичний сервіс передають визначений набір даних: каталог, залишки, клієнтів або експортований звіт. Розробник і аналітик погоджують назви полів, дату зрізу, валюту та період. Товарний файл не використовують як джерело повної історії продажів.
| Сервіс | Сценарій | Реалізація | Перевірки |
|---|---|---|---|
| Google Sheets | Таблиці товарів, цін, залишків або звітів. | Розробник читає погоджений файл і записує дані через Sheets API. Власник відкриває доступ потрібному користувачу або service account. | Додати час оновлення, відокремити ручні колонки. Не передавати персональні дані до публічної таблиці. Редагування таблиці не змінює автоматично Торгсофт. |
| Microsoft Power BI | Модель із CSV та інших підготовлених експортів. | Аналітик створює модель; розробник організовує регулярне отримання файлів. Адміністратор налаштовує джерело та, за потреби, gateway. | Розклад залежить від розміщення файлів і ліцензії. Визначити, чи звіт містить знімок або операції за період; уникнути повторного додавання тих самих продажів. |
| Looker Studio | Звіти через підготовлене джерело або конектор. | Розробник завантажує дані до Google Sheets, сховища або створює Community Connector. Аналітик визначає типи полів і метрики. | Підготувати агреговані дані потрібного рівня деталізації, правила кешування й права доступу. Конектор не додає джерел, яких немає у вихідному експорті. |
| GA4, GTM та рекламні теги | Події інтернет-магазину через ТОМ або CMS. | Маркетолог визначає події, розробник додає їх у магазин, перевіряє item IDs і transaction ID. Через GTM підключає погоджені теги. | Подія purchase має надходити один раз із фактичним складом покупки. Вона не замінює обліковий документ і не містить автоматично офлайн-продажів Торгсофт. |
| Make | Оркестрація читання файлів, перетворення й HTTP-запитів. | Розробник налаштовує сумісний захищений транспорт, розбір CSV/XML/JSON, сховище станів, обробку помилок і доступ до API платформи. | Перевірити підтримку потрібного протоколу та операцій у конекторах. Зв’язування модулів не забезпечує саме по собі зіставлення GoodID, захист від дублів і підтвердження імпорту. |
| n8n | Фонові сценарії обміну файлами та API. | Розробник розгортає workflow, налаштовує читання файлів або HTTPS-шлюз, перетворення даних, журнал і повторні спроби. | FTP/SFTP-вузол та спосіб доставки Торгсофт мають бути сумісними. Якщо потрібний TLS-режим не підтриманий вузлом, використовують захищений шлюз. Перезапуск workflow не повинен повторювати імпорт. |
Для регулярного експорту звіту інтегратор окремо визначає спосіб його формування в Торгсофт. Розробник не планує автоматичний доступ до будь-яких даних бази лише на підставі наявності файлової синхронізації.
11. Як забезпечити надійність, безпеку та супровід
11.1. Зберігати відповідності окремо від назви товару
Розробник створює постійне сховище відповідностей. Назва товару може змінюватися, а штрихкод не завжди унікальний для всіх записів. Перед первинним зіставленням інтегратор перевіряє довідник; непогоджені збіги не об’єднують автоматично.
| Сутність | Що зберігає адаптер | Призначення |
|---|---|---|
| База й канал | Внутрішній код бази, платформа, акаунт продавця, магазин. | Відокремлення однакових числових ID різних баз і магазинів. |
| Товар | GoodID, SKU, product/listing/offer ID, variant ID. | Однозначне оновлення пропозиції й імпорт конкретної позиції. |
| Склад | Центр обліку, warehouse/location ID, правило резерву. | Правильна кількість для каналу та списання з потрібного центру. |
| Замовлення | Зовнішній ID, OrderNumber, стан, контрольна сума, час, ім’я файла. | Повторна доставка подій, звірка й контроль дублів. |
| Оплата й доставка | Payment/capture ID, перевізник, shipment/tracking ID. | Зв’язок фінансової або транспортної події з відповідним замовленням. |
11.2. Визначити єдине правило залишку
Інтегратор показує розробнику, що саме містить експортована кількість: фізичний запас або вже зменшену на враховані резерви доступність. Розробник документує розрахунок для кожного каналу.
Кількість каналу = max(0, кількість експорту − невраховані резерви − страховий запас).
У «невраховані резерви» входять тільки замовлення, які ще не вплинули на експортовану кількість. Після імпорту й підтвердження облікового резерву відповідний зовнішній резерв прибирають. Для вже врахованого резерву повторне віднімання не застосовують.
Для набору з кількох товарів розробник розраховує кількість комплектів за складом набору. Для дробового товару перевіряє одиницю виміру та допустиму точність платформи. Нульова кількість означає погоджену дію з доступністю, а видалення картки виконується лише за окремим правилом.
11.3. Перевіряти замовлення до публікації файла
- Перевірити джерело, акаунт, зовнішній ID і дозволений статус.
- Знайти GoodID для кожної позиції. За невідомого SKU направити все замовлення в чергу виправлення.
- Перевірити кількість, одиниці, валюту, ціни та знижки. Розрахувати підсумок і зіставити його з даними платформи.
- Погодити відображення доставки, доплат і подарунків. Якщо використовується окрема послуга, її GoodID та облікову поведінку перевіряє інтегратор.
- Перевірити покупця, адресу та параметри перевізника, потрібні для обраного сценарію.
- Вибрати SaleType за погодженою таблицею й сформувати файл схеми, яку підтримує версія бази.
Файл із пропущеною позицією або невідомим товаром не публікують як часткове замовлення без окремо погодженого процесу. Дані помилки зберігають для виправлення; після нього використовують той самий зовнішній ID.
11.4. Захищати імпорт від повторів
Розробник заводить у журналі унікальний ключ «канал + акаунт + зовнішній ID». Повторна подія оновлює стан цього запису. Перед новою публікацією адаптер перевіряє, чи файл уже передавався й чи підтверджений документ у Торгсофт.
Практичні стани журналу: отримано → перевірено → файл підготовлено → опубліковано → імпорт підтверджено. Окремо ведуть помилки та записи, що потребують звірки. Підтвердження останнього стану визначають за реальним доступним механізмом конкретної інтеграції або перевіркою відповідального працівника.
Прийняття FTP-сервером, HTTP 200 і видалення файла не вважають універсальним підтвердженням документа. Після збою на межі передавання адаптер зупиняє повторну публікацію цього замовлення до звірки. Саме значення OrderNumber не є задокументованою гарантією захисту від усіх повторних імпортів.
11.5. Публікувати тільки завершені файли
Вхідний товарний файл читають після завершення формування й перевірки структури. POST-повідомлення, розклад або шлюз використовують відповідно до налаштованого маршруту. Адаптер контролює цілісність файла й відхиляє неповні записи.
Результат адаптера спочатку записують у службовий каталог, перевіряють і потім публікують завершеним файлом. Для замовлень тимчасовий файл має розширення, яке імпортер не обробляє. Перейменування виконують у межах файлової системи або перевіреного механізму сервера; атомарність цього кроку перевіряє адміністратор.
Робочий товарний фід зберігають до успішної перевірки наступної версії. Порівнюють кількість товарів, частку нульових залишків, обов’язкові поля й обсяг файла. Пороги аномалій погоджують із власником, щоб планове зняття асортименту не блокувалося без пояснення.
11.6. Розділити помилки й повторні спроби
- Авторизація: зупинити відповідний маршрут, повідомити адміністратора, поновити доступ за правилами платформи.
- Ліміт API або тимчасова недоступність: зберегти завдання й повторити з керованою затримкою та дотриманням Retry-After, якщо він переданий.
- Некоректні дані: передати запис на виправлення; незмінний помилковий файл повторно не публікувати.
- Частковий результат пакета: прочитати відповіді для кожного товару й повторювати тільки дозволені невиконані операції.
- Невизначений результат імпорту: звірити документ перед повтором.
Моніторинг показує останнє успішне оновлення, вік залишків, кількість і вік непереданих замовлень, помилки SKU та прострочені підтвердження. Власник призначає працівника для кожного виду повідомлень. API-запит з успішним HTTP-кодом додатково перевіряють на бізнес-помилки в тілі відповіді.
11.7. Захистити доступи та персональні дані
- Для FTP Торгсофт увімкнути SSL/TLS і перевірити фактичне шифрування. Зовнішні HTTP-інтерфейси адаптера працюють через HTTPS.
- Ключі й паролі зберігати у захищених налаштуваннях. Не додавати їх до URL публічних фідів, репозиторіїв, повідомлень і журналів.
- Видавати мінімальні права. Окремі доступи використовувати для продуктивного середовища й випробувань.
- Перевіряти підпис webhook та актуальність авторизації за інструкцією провайдера. Записувати подію до надійного сховища перед підтвердженням її прийняття.
- Відокремити публічний каталог від файлів клієнтів, замовлень, бонусів і сертифікатів. Обмежити строк зберігання та доступ працівників.
- У журналах маскувати зайві контактні й платіжні дані. Передавання контактів для реклами узгоджувати з правилами згоди й відписки.
11.8. Перевіряти ручний і фоновий запуск окремо
Адміністратор та інтегратор перевіряють актуальну версію Торгсофт, сервер автоматичних завдань і бібліотеки, що постачаються для цього підключення. Несумісні SSL-бібліотеки не замінюють випадковими DLL із сторонніх сайтів.
Контрольне замовлення запускають вручну та через фактичну службу. Звіряють користувача служби, права, каталоги, мову й регіональні налаштування, доступ до мережі та результат після перезапуску. Успішний ручний імпорт не підтверджує роботу фонового завдання.
Після зміни версії програми, схеми файлів, ціноутворення, модулів сайту або API повторюють ключові тести. Розробник веде версії адаптера та контракту обміну; власник визначає відповідального за оновлення.
12. План випробування та приймання інтеграції
Безплатні 30 днів опції можна використати для перевірки обміну з обраним сервісом. Спочатку власник оформлює доступи й погоджує сценарій; після цього інтегратор активує опцію, а розробник запускає підготовлений адаптер. Погодження застосунку зовнішньою платформою, її тарифи та розроблення враховують окремо.
Що має бути готове до першого запуску
| Результат підготовки | Відповідальний | Що передати команді |
|---|---|---|
| Погоджений обсяг | Власник та інтегратор | Канали, напрямки, поля, склади, валюти, ручні дії й критерії приймання. |
| Доступ платформи | Власник та розробник | Кабінет, дозволи застосунку, робочі методи API, регіон, ліміти й тестове середовище, якщо воно надається. |
| Обмін Торгсофт | Інтегратор | Версію БД, об’єкт синхронізації, фактичний експорт і список налаштувань. |
| Сервер | Адміністратор | Захищений транспорт, права каталогів, запуск служби, журнал, резервну копію й відновлення. |
| Відповідності | Розробник та інтегратор | Товари/варіанти, склади, категорії, статуси, способи оплати й доставки. |
| Обліковий сценарій | Інтегратор та менеджер | SaleType, джерело цін, оплату, резерв, відвантаження, скасування та повернення. |
Для тестової копії бази вимкніть або переналаштуйте всі продуктивні автоматичні завдання, каталоги обміну та підключення. Перевірте відправлення SMS, листів, хмарних архівів і роботу з перевізниками. Копія не повинна публікувати тестові залишки в робочий магазин або завантажувати його замовлення.
Якщо платформа не надає окремого тестового середовища, власник погоджує контрольні товари й замовлення в продуктивному кабінеті. Права та завдання адаптера обмежують до цього переліку; масові зміни залишають вимкненими.
Послідовність робіт
- Перевірка доступів. Розробник виконує дозволене читання каталогу й замовлень, перевіряє авторизацію та потрібні операції.
- Тест каталогу. Інтегратор експортує контрольні товари; розробник перевіряє нові й наявні картки, варіанти, ціни та нульову кількість.
- Тест замовлення. Розробник передає файл; інтегратор звіряє покупця, кожний GoodID, кількість, ціну, валюту й створені документи.
- Оплати й доставка. Менеджер та інтегратор перевіряють погоджені типи оплат, резерв, відвантаження й ТТН.
- Відмови й повтори. Команда випробовує повторні події, втрату доступу, неповний файл, невідомий SKU й перезапуск служби.
- Обмежений запуск. Власник допускає погоджений асортимент і канал; команда спостерігає кілька повних циклів та звіряє результат.
- Приймання. Власник отримує інструкцію, журнал тестів, доступи до моніторингу та порядок супроводу.
Контрольні тести
| Тест | Що перевіряють | Критерій приймання |
|---|---|---|
| Новий і наявний товар | Створення та оновлення за погодженим маршрутом. | Наявна картка зберегла ID; нова має всі обов’язкові поля; дубль відсутній. |
| Два розміри або кольори | GoodID, variant ID, ціни й запаси. | Замовлення кожного варіанта створює правильну позицію. |
| Нульовий залишок і резерв | Доступність та перехід зовнішнього резерву в обліковий. | Недоступний товар не пропонується до продажу; резерв не віднімається двічі. |
| Кілька складів | WarehouseID та відповідності location ID. | Публікується погоджений запас; документ належить потрібному центру обліку. |
| Акція й ручна знижка | Фактична ціна покупки та джерело ціни рахунка. | Ціни й підсумок відповідають погодженій політиці, без непередбаченого перерахунку. |
| Валюта й дробова кількість | Код валюти, точність, одиниці й округлення. | Усі суми та кількості збігаються в обох системах. |
| Український текст і спецсимволи | Кодування, BOM, лапки, роздільники. | ПІБ, адреса й позиції прочитані без спотворення або зміщення колонок. |
| Невідомий SKU | Повноту кошика. | Замовлення потрапило в чергу виправлення, неповний документ не створено. |
| Повторне замовлення або webhook | Унікальний ключ і стан журналу. | Створено один комплект документів для зовнішнього замовлення. |
| Пагінація та однаковий час подій | Повноту отримання замовлень. | Усі контрольні замовлення з усіх сторінок включені без пропусків. |
| Неоплачене та оплачене замовлення | SaleType, рахунок і момент оплати. | Документи відповідають погодженій схемі; пізній платіж не створив другого рахунка. |
| Скасування та повернення | Чергу звірки й дії менеджера. | Стан документів і залишків узгоджений; відповідальний підтвердив завершення. |
| Адреса та наявна ТТН | Перевізника, одержувача, відділення й tracking ID. | Накладна належить правильному замовленню; зайва ТТН не створена. |
| Неповний або порожній фід | Перевірку перед публікацією. | Помилковий файл заблокований; робочий каталог збережений. |
| Збій у момент передавання | Поведінку журналу й відновлення. | Невизначений результат направлено на звірку; сліпий повтор відсутній. |
| Помилка API або закінчення доступу | Повтори, чергу й повідомлення. | Записи збережені, відповідальний отримав повідомлення, ліміти дотримані. |
| Ручний і фоновий імпорт | Службу, каталоги, локаль і права. | Однаковий результат у двох режимах і після перезапуску. |
| Резервна копія й відновлення | Стан журналу, відповідності й конфігурацію. | Після відновлення команда бачить підтверджені та непередані записи; дублювання виключене погодженим процесом. |
Для кожного тесту команда записує в журналі фактичний результат, зовнішній ID, OrderNumber і документ Торгсофт. Приклад JSON та перевірка його синтаксису не замінюють імпорту у встановленій версії програми.
До передачі в роботу власник отримує перелік автоматизованих операцій, ручних винятків, інтервалів оновлення та відповідальних. Окремо фіксують тарифи платформ, необхідні опції, строк підтримки адаптера, порядок оновлень і відновлення після збою.
Повернутися до попереднього кроку