Технічні вимоги для синхронізації інтернет-магазину з програмою Торгсофт

Перелік вимог до інтернет-магазину для успішної інтеграції

1. Завантаження товарів на сайт

Ваш інтернет-магазин повинен вміти завантажувати прайс-лист з файлу у форматі *.csv з роздільником ;, який має назву TSGoods.trs, або з файлу формату yml, який буде розташований на FTP сервері. У файлі можуть бути не всі поля; які поля вивантажуються, їх порядок та назви можуть бути налаштовані. Як ви назвете поля у вашій базі інтернет-магазину — не принципово, чи будете ви їх всі використовувати, чи ні — також.

Перелік можливих полів:

Загальна інформація про товар

Ключ товару — GoodID (пошуковий), ціле число (назва колонки за замовчуванням — GoodID)
Назва товару — рядкове (500 символів) (назва колонки за замовчуванням — GoodName)
Опис товару — рядкове (255 символів) (назва колонки за замовчуванням — Description)
Артикул — рядкове (30 символів) (назва колонки за замовчуванням — Articul)
Коротка назва товару — рядкове (255 символів) (назва колонки за замовчуванням — ShortName)
Штрих-код — рядкове (40 символів) (з версії бази даних Торгсофт 376) (назва колонки за замовчуванням — Barcode)
Виробник — рядкове (100 символів) (з версії бази даних Торгсофт 482) (назва колонки за замовчуванням — PCName)

Цінова інформація

Роздрібна ціна — дійсне число (назва колонки за замовчуванням — RetailPrice)
Оптова ціна — дійсне число (назва колонки за замовчуванням — WholesalePrice)
Акційна ціна (зі знижкою на товар) — дійсне число (назва колонки за замовчуванням — RetailPriceWithDiscount)
Ціна за одиницю міри — дійсне число (з версії бази даних Торгсофт 428) (назва колонки за замовчуванням — RetailPricePerUnit)
Відображення за одиницю міри — дійсне число (з версії бази даних Торгсофт 428) (назва колонки за замовчуванням — WholesalePricePerUnit)
Еквівалент роздрібної ціни — дійсне число (з версії бази даних Торгсофт 449) (назва колонки за замовчуванням — EqualSalePrice)
Еквівалент оптової ціни — дійсне число (з версії бази даних Торгсофт 449) (назва колонки за замовчуванням — EqualWholesalePrice)
Валюта еквівалентної ціни — рядкове (3 символи) (з версії бази даних Торгсофт 449) (назва колонки за замовчуванням — EqualCurrencyName)
Ціна в валюті роздрібна — дійсне число, може бути декілька (з версії бази даних Торгсофт 492) (назва колонки за замовчуванням — CurrencyPriceRetail_"ID валюти")
Ціна в валюті оптова — дійсне число, може бути декілька (з версії бази даних Торгсофт 492) (назва колонки за замовчуванням — CurrencyPriceWholesale_"ID валюти")
Собівартість — дійсне число (з версії бази даних Торгсофт 461) (назва колонки за замовчуванням — PrimeCost)
Знижка — дійсне число (з версії бази даних Торгсофт 482) (назва колонки за замовчуванням — PriceDiscountPercent)

Інформація про запаси

Кількість на складі — дійсне число (назва колонки за замовчуванням — WarehouseQuantity)
Мінімальна кількість для замовлення клієнтом, шт — ціле число (назва колонки за замовчуванням — MinQuantityForOrder)
Мінімальна оптова кількість — дійсне число (з версії бази даних Торгсофт 482) (назва колонки за замовчуванням — WholesaleCount)

Атрибути товару

Розмір — рядкове (20 символів) (назва колонки за замовчуванням — TheSize)
Колір — рядкове (50 символів) (назва колонки за замовчуванням — Color)
Матеріал — рядкове (200 символів) (назва колонки за замовчуванням — Material)
Вік — рядкове (255 символів) (з версії бази даних Торгсофт 380) (назва колонки за замовчуванням — Age)
Стать — ціле число (0 — не визначена, 1 — чоловіча, 2 — жіноча, 3 — хлопчик, 4 — дівчинка, 5 — унісекс) (назва колонки за замовчуванням — Sex)
Сезон — рядкове (100 символів) (назва колонки за замовчуванням — Season)
Будь-які динамічні характеристики товару (з версії бази даних Торгсофт 481) (назва колонки за замовчуванням — "Назва" динамічної характеристики)

Розміри та виміри

Висота — дійсне число (назва колонки за замовчуванням — Height)
Ширина — дійсне число (назва колонки за замовчуванням — Width)
Довжина — дійсне число (назва колонки за замовчуванням — Length)
Міра — дійсне число (з версії бази даних Торгсофт 380) (назва колонки за замовчуванням — Measure)
Одиниця вимірювання міри — рядкове (255 символів) (з версії бази даних Торгсофт 380) (назва колонки за замовчуванням — MeasureUnit)
Одиниця вимірювання — рядкове (10 символів) (з версії бази даних Торгсофт 482) (назва колонки за замовчуванням — MesUnit)

Виробник та колекція

Країна — рядкове (100 символів) (назва колонки за замовчуванням — Country)
Колекція виробника повністю — рядкове, містить всю ієрархію колекції (назва колонки за замовчуванням — ProducerCollectionFull)
Назва моделі товару — рядкове (500 символів) (назва колонки за замовчуванням — FashionName)
ID моделі — ціле число (з версії бази даних Торгсофт 482) (назва колонки за замовчуванням — ModelGoodID)
Код постачальника — рядкове (255 символів) (з версії бази даних Торгсофт 461) (назва колонки за замовчуванням — SuppLierCode)

Категоризація

Ідентифікатор розділу інтернет-магазину (Категорія) — ціле число (назва колонки за замовчуванням — Category)
Вид товару повністю — рядкове, містить всю ієрархію видів (назва колонки за замовчуванням — GoodTypeFull)
Вид товару — рядкове (255 символів), назва кореневого виду товару (назва колонки за замовчуванням — GoodTypeName)
Розділ синхронізації — рядкове (255 символів) (назва колонки за замовчуванням — SynchronizationSection)
Розділ синхронізації повністю — рядкове (назва колонки за замовчуванням — SynchronizationSectionFull)

Додаткова інформація

Відображення — 0 (не відображати на сайті) або 1 (відображати на сайті) (назва колонки за замовчуванням — Display)
Ознака уцінки товару — ціле число (0 — не уцінений, 1 — уцінений) (з версії бази даних Торгсофт 403) (назва колонки за замовчуванням — Closeout)
Термін гарантії — ціле число (з версії бази даних Торгсофт 493) (назва колонки за замовчуванням — GuaranteePeriod)
Одиниця вимірювання терміну гарантії — рядкове (може приймати значення: д., міс., р.) (з версії бази даних Торгсофт 493) (назва колонки за замовчуванням — GuaranteeMesUnit)
Дата випуску — рядкове (10 символів) (назва колонки за замовчуванням — ProductionDate)
Фотографія товару (список файлів через кому) — рядкове (назва колонки за замовчуванням — GoodPhotoList)
Фотографія товару (посилання на файли через кому) — рядкове (назва колонки за замовчуванням — GoodPhotoListWithLinks)

Упаковка та логістика

Упаковка — рядкове (255 символів) (з версії бази даних Торгсофт 380) (назва колонки за замовчуванням — Pack)
Розмір упаковки — рядкове (255 символів) (з версії бази даних Торгсофт 380) (назва колонки за замовчуванням — PackSize)
Живлення — рядкове (255 символів) (з версії бази даних Торгсофт 380) (назва колонки за замовчуванням — PowerSupply)
Кількість штук в ящику — рядкове (255 символів) (з версії бази даних Торгсофт 380) (назва колонки за замовчуванням — CountUnitsPerBox)

Інше

Аналоги — рядкове (1000 символів) (з версії бази даних Торгсофт 481) (назва колонки за замовчуванням — Analogs)

Зарезервовані теги при вивантаженні в файл YML

Під час вивантаження в файл YML існує список зарезервованих тегів. Якщо ми назвемо вивантажуване поле так само, воно буде вивантажене саме як тег з такою назвою, а не через тег param — тег додаткових характеристик товару.

Основна інформація про товар

name — назва товару
model — назва моделі товару
vendor — виробник товару
vendorCode — артикул
description — опис товару
barcode — штрих-код товару
url — URL сторінки товару на сайті магазину
typePrefix — тип або категорія
country — країна виробника
country_of_origin — країна походження
age — вікова категорія товару

Цінова інформація

price — ціна зі знижкою
oldprice — роздрібна ціна
price_old — роздрібна ціна
enable_auto_discounts — автоматичний розрахунок та показ знижок для пропозиції
partType — оплата частинами
partCount — кількість платежів при оплаті частинами
partPrice — сума платежу
sale — товар доступний за програмою "Теплі кредити" (за умови обов'язкової наявності блоку "Оплата частинами"); значення має бути hc

Категоризація та ідентифікація

categoryId — ID виду товару/категорії
group_id — ID моделі товару

Наявність та запаси

stock_quantity — кількість товару
min-quantity — мінімальна кількість однакових товарів у замовленні (для випадків, коли покупка можлива тільки комплектом, а не поштучно)

Доставка та самовивіз

delivery — можливість кур'єрської доставки: true або false
delivery-options — умови кур'єрської доставки товару по регіону магазину (види доставки, строки, вартість)

option — опції доставки

cost — вартість доставки
days — строк доставки в робочих днях
order-before — час, до якого потрібно зробити замовлення, щоб отримати його в цей строк

pickup — можливість самовивозу з пунктів видачі в усіх регіонах, куди доставляє магазин: true або false
store — можливість купити товар без попереднього замовлення: true або false

Гарантії та обмеження

manufacturer_warranty — офіційна гарантія виробника: true або false
sales_notes — обов'язковий елемент, якщо є обмеження при покупці (наприклад, мінімальна кількість товарів або необхідність передоплати). Також можна вказати варіанти оплати, акції та розпродажі. У цьому випадку використання елемента не обов'язкове.
adult — товар має відношення до задоволення сексуальних потреб або іншим чином експлуатує інтерес до сексу: true або false
expiry — термін придатності або термін служби, або дата закінчення терміну придатності чи служби

Вага та розміри

weight — вага товару в кілограмах з урахуванням упаковки
dimensions — габарити товару (довжина, ширина, висота) в упаковці. Розміри вказуйте у сантиметрах

Податки

vat — ставка ПДВ

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

2. Формування файлів із замовленнями

Ваш інтернет-магазин повинен вміти формувати один із типів (на вибір) файлів із замовленнями та розміщувати їх у тому ж каталозі на FTP сервері, де знаходиться файл із товарами:

Текстовий файл з розширенням .sal

Кодування файлу: Win-1251 або UTF-8 (з версії 428 БД), залежно від налаштувань Об'єкта синхронізації.

Файл у форматі XML (з версії 493 бази даних Торгсофт)

Кодування файлу: UTF-8

Файл у форматі JSON (з версії 493 бази даних Торгсофт)

Кодування файлу: UTF-8

Ім'я файлу замовлення повинно складатися з ASCII символів (латинські літери, цифри та роздільники).

Опис полів

Текстовий файл з розширенням .sal

Блок інформації про клієнта [Client]

[Client]

Name=ПІБ (обов'язкове поле)

Mphone=0672356147

CPhone=2568974

ZIP=61072

Country=Україна

Region=Харківська

City=Харків

Address=вул. Гіршмана,16

EMail=info@torgsoft.ua

Блок інформації про замовлення [Options]

[Options]

OrderNumber=12/21 (обов'язкове поле)

Comment=Доставка з 14 до 18

DeliveryCondition=Нова Пошта - рядкове (255) //з версії 390 бази даних Торгсофт

DeliveryAddress=Харків, вул. Сумська, 124 (Відділення №33) - рядкове (255) //з версії 505 бази даних Торгсофт

ReserveDate=28082013 - дата резерву у форматі ddmmyyyy //з версії 392 бази даних Торгсофт

SaleType=1* (обов'язкове поле)

BonusPay=28,50 - дійсне число, що відображає суму по замовленню, яку клієнт сплатив бонусами //з версії 463 бази даних Торгсофт

GiftCertificate=9567200000106,9567200000182 - перелік подарункових сертифікатів, використаних клієнтом для оплати замовлення через кому //з версії 470 бази даних Торгсофт

OrderDate=2009-01-31 01:55:14 - дата оформлення замовлення (необов'язкове поле) у форматі yyyy-mm-dd hh:mm:ss //з версії 470 бази даних Торгсофт

CurrencyInternationalCode=UAH - рядкове (4) міжнародний код валюти замовлення (необов'язкове поле; якщо не вказано, замовлення обробляється в національній валюті) //з версії 493 бази даних Торгсофт

SaleForm=1 - цифрове (значення 1 - Опт | 2 - Роздріб), вид торгівлі замовлення; якщо поле не вказано або вказано некоректно, замовлення обробляється з видом торгівлі - роздріб //з версії 500 бази даних Торгсофт

Додано новий розділ [NewPostDeliveryOptions]

[NewPostDeliveryOptions]

RecepientType=2 (тип отримувача: 1 - Юридична особа, 2 - Фізична особа)

EGRPOU= (для юридичної особи вказується код ЄДРПОУ (8-символьний числовий код))

LastName=Франко (Прізвище контактної особи отримувача Нової Пошти)

FirstName=Іван (Ім'я контактної особи отримувача Нової Пошти)

MiddleName=Якович (По батькові контактної особи отримувача Нової Пошти)

Phone=0676758462 (Мобільний телефон контактної особи отримувача Нової Пошти)

DeliveryType=2 (Тип доставки: 1 - адресна доставка отримувачу, 2 - доставка на відділення Нової Пошти)

DeliveryCity=Заболотів (Місто для доставки та створення нової адреси при DeliveryType=1 або вибір відділення Нової Пошти при DeliveryType=2)

WarehouseNumber=1 (Номер відділення Нової Пошти)

WarehouseRef=e62a5ed5-87bf-11eb-b05e-b8830365bd14 - ідентифікатор відділення Нової Пошти. Якщо передається ідентифікатор у поле WarehouseRef, заповнювати поля "DeliveryCity" та "WarehouseNumber" не потрібно.

StreetType= (при адресній доставці тип вулиці "вул", "пров" тощо; при доставці на відділення залишається порожнім)

StreetName= (при адресній доставці назва вулиці; при доставці на відділення залишається порожнім)

BuildingNumber= (Номер будинку при адресній доставці)

Flat= (Номер квартири, якщо є)

DeclarationNumber – номер ТТН Нової Пошти (для подальшого завантаження в програму). Якщо це поле заповнене, інші поля блоку ігноруються.

Примітка: Адресні поля повинні бути заповнені українською мовою, оскільки при роботі з API Нової Пошти список вулиць та відділень завантажується українською. Це необхідно для коректного пошуку та додавання адреси.

Для файлів формату .JSON та .XML опис полів аналогічний.

Блоки інформації про товари замовлення

[1] (Блок інформації про перший товар замовлення)

GoodID=201 (Ключ товару) (обов'язкове поле)

Price=120,05 (Ціна продажу товару) (обов'язкове поле)

Count=20 (Кількість замовленого товару) (обов'язкове поле)

[2] (Блок інформації про другий товар замовлення)

GoodID=20294

Price=19,00

Count=1

...

[n] (Блок інформації про n-ий товар замовлення)

GoodID=13854

Price=63,00

Count=5

Файл у форматі XML (з версії 493 бази даних Торгсофт)

<?xml version="1.0" encoding="UTF-8"?>

<Order>

<Name>Франко Іван Якович</Name>

<Country>Україна</Country>

<Region>Харківська</Region>

<City>Харків</City>

<Address>вул. Гіршмана, 16</Address>

<EMail>info@torgsoft.com.ua</EMail>

</Client>

<DeliveryCondition>Нова Пошта</DeliveryCondition>

<DeliveryAddress>Харків, вул. Сумська, 124 (Відділення №33)</DeliveryAddress>

</Options>

<Goods>

<Good_1>

</Good_1>

<Good_2>

</Good_2>

</Goods>

</Order>

Файл у форматі JSON (з версії 493 бази даних Торгсофт)

{

"Client": {

"Name": "Франко Іван Якович",

"MPhone": "0675746830",

"CPhone": "7601828",

"ZIP": "61072",

"Country": "Україна",

"Region": "Харківська",

"City": "Харків",

"Address": "вул. Гіршмана,16",

"EMail": "info@torgsoft.com.ua"

"Options": {

"SaleType": "1",

"Comment": "Код під'їзду 1685",

"OrderNumber": "12",

"DeliveryCondition": "Нова Пошта",

"DeliveryAddress": "Харків, вул. Сумська, 124 (Відділення №33)",

"ReserveDate": "28082013",

"BonusPay": "100.8",

"GiftCertificate": "9567200000106,9567200000182",

"OrderDate": "2020-02-04 18:19:44",

"CurrencyInternationalCode": "USD"

"Goods": [

{

"GoodID": "38280",

"Price": "145.33",

"Count": "2"

{

"GoodID": "38281",

"Price": "131.61",

"Count": "1"

}

]

}

Значення SaleType

Значення SaleType може бути від 1 до 5:

1 - попереднє замовлення (створюється замовлення, за яким можна буде створити рахунок)
2 - оформлений продаж (створюється рахунок зі 100% передоплатою)
3 - оформлений продаж з відвантаженням (створюється рахунок зі 100% передоплатою, за яким відбувається відвантаження товару)
4 - оформлений продаж з відвантаженням без оплати (створюється рахунок без оплати, за яким відбувається відвантаження товару)
5 - тільки рахунок (замовлення не створюється, створюється одразу рахунок)

Необов'язкові можливості передачі додаткової інформації в інтернет-магазин

1. Обробка фотографій та їх прив'язка до товарів

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

З версії 452 бази даних Торгсофт до папки з фотографіями переміщуються також додаткові фотографії товару з іменем у форматі:

Код фотографії (ID товару)_номер додаткової фотографії (не обов'язково по черзі).розширення файлу

Для обробки фотографій можна використовувати відповідні поля з файлу товарів:

“Фотографія товару (список файлів через кому)”
“Фотографія товару (посилання на файл через кому)”

Якщо вони присутні (це налаштовується).
Є можливість у Торгсофт не вивантажувати фотографії на FTP, а надати до них доступ на локальному комп'ютері через організацію Web-сервера. У цьому випадку імена файлів фотографій можуть не відповідати зазначеному вище принципу (залежить від налаштувань у Торгсофт). Якщо так, то їх необхідно отримувати з полів:

“Фотографія товару (список файлів через кому)”
“Фотографія товару (посилання на файл через кому)”

2. Завантаження клієнтів на сайт

Торгсофт може формувати файл *.csv (роздільник ;) з клієнтською базою TSClients.trs. Чи формувати цей файл вирішує користувач за допомогою відповідного налаштування. Файл відправляється в ту ж папку, що і TSGoods.trs.

Набір полів:

Основна інформація про клієнта

ПІБ — рядкове поле (100 символів)
Номер карти (штрих-код клієнта) — рядкове поле (16 символів)

Контактна інформація

E-mail — рядкове поле (50 символів)
Номер телефону, мобільний — рядкове поле (100 символів)
Міський телефон — рядкове поле (255 символів)

Адреса

Індекс — рядкове поле (15 символів)
Країна — рядкове поле (50 символів)
Область — рядкове поле (100 символів)
Місто — рядкове поле (50 символів)
Адреса — рядкове поле (255 символів)

Знижки та бонуси

Знижка клієнта — дійсне число
Сума для розрахунку знижки — дійсне число
Сума накопичених бонусів — дійсне число

Додаткова інформація

Додаткова інформація — рядкове поле необмеженої довжини (максимальна довжина не визначена)

3. Експорт політики оптових цін (з версії 447 БД)

При активації додаткової функції "Політика оптових цін" є можливість зберігати політику оптових цін у XML-файл та передати його на FTP-сервер.

Приклад файлу:

<?xml version="1.0" encoding="UTF-8"?>

<Price>

</Price>

<Price>

</Price>

<Price>

</Price>

</Good>

<Price>

</Price>

<Price>

</Price>

<Price>

</Price>

</Good>

</WholesalePrice>

Опис тегів:

WholesalePrice — батьківська секція (кореневий елемент)
Good — секція товару, має один параметр GoodID — ключ товару (пошуковий), ціле число
Price — секція ціни
Quantity — секція кількості, значення — кількість для переходу, дійсне число
QuantityPrice — секція ціни, значення — ціна при переході, дійсне число

Цей XML-файл містить інформацію про оптові ціни для товарів. Кожен товар (Good) може мати декілька цінових порогів (Price), які визначають ціну при закупівлі певної кількості товару (Quantity).

Наприклад, у наведеному прикладі для товару з GoodID="1378" встановлені такі оптові ціни:

При покупці 2 одиниць — ціна 33
При покупці 3 одиниць — ціна 32
При покупці 5 одиниць — ціна 30

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

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

4. Експорт подарункових сертифікатів (з версії 470 БД) у файл .csv з назвою TSGiftCertificate.trs

Чи формувати цей файл (ім'я файлу можна змінити) вирішує користувач за допомогою відповідного налаштування. Файл відправляється в ту ж папку, що і TSGoods.trs.

Набір полів:

Штрих-код сертифіката — рядкове поле (40 символів)
Сума сертифіката — дійсне число
Дата закінчення терміну дії сертифіката — дата у форматі ddmmyyyy (якщо відсутня, то сертифікат не має терміну дії або він відлічується від дати продажу сертифіката, але ще не проданий)
Тип сертифіката — може приймати значення 1 або 2:

1 — випущений, можна продати, але не можна використовувати для оплати покупок
2 — куплений клієнтом, можна використовувати для оплати покупок

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

Прізвище та ім'я
Номер телефону
Інша контактна інформація
Вид бази даних
Чи потрібен дзвінок та консультація від співробітника компанії? Так Ні Оберіть один з варіантів
Я згоден з Політикою конфіденційності Торгсофт® Ознайомтеся з Політикою конфіденційності Торгсофт. Якщо ви згодні, підтвердіть це нижче.