Интеграция через обмен файлами

Информацией обмениваются 2 участника:

1с или другая учётная система, используемая на предприятии (далее — 1с)
web-приложение Snarta (далее — Сервис)

Папки

Для целей обмена файлами используются специальные папки с файлами которых работают системы:

csv — в папку сохраняются файлы c расширением “.csv”
jpg — в папку сохраняются файлы с расширением “.jpg” или “.jpeg”
del — в папке переносятся обработанные файлы из папок csv и jpg

Передача файлов

За файлами, находящимися в папках “следит” программа типа Google Drive (далее — Синхронизатор). При создании файлов, удалении или их обновлении, Cинхронизатор производит передачу файлов между устройствами.

Удаление обработанных файлов

Файлы, созданные 1с, после обработки переносятся Сервисом в папку del. Откуда их удаляет 1с
Файлы, созданные Сервисом, удаляются 1с после обработки

Формат данных

Для передачи информации используются текстовые файлы CSV.

Дополнительно ко всем файлам предъявляются требования:

Кодировка файлов — UTF-8
Разделитель колонок — символ |
Первая строка файлах — колонки таблиц
Все неразрешенные символы должны быть удалены
Пробельные символы должны быть заменены на обычные пробелы
Кавычки всех типов должны быть заменены на двойную кавычку — “
Скобки всех типов должны быть заменены на соотв. скобку — ( или )
Два (и более) последовательных пробела должны быть заменены на один пробел
Две (и более) последовательных кавычки должны быть заменены на одну двойную кавычку
Две (и более) последовательных левых скобки должны быть заменены на одну левую скобку
Две (и более) последовательных правых скобки должны быть заменены на одну правую скобку
Информация в колонке не должна начинаться с символа “пробел”
Информация в колонке не должна заканчиваться символом “пробел”

Разрешенные символы

Цифры от 0 до 9
Буквы латинского алфавита в верхнем и нижнем регистрах
Буквы русского алфавита в верхнем и нижнем регистрах
Символ “пробел”
Символ “знак вопроса” — ?
Символ “восклицательный знак” — !
Символ “левая скобка” — (
Символ “правая скобка” — )
Символ “плюс“ — +
Символ “короткое тире” -

Минимальный набор файлов для SNARTA интеграции

В этом документе дано описание большего количества файлов, чем требуется для старта. Эти дополнительные файлы нужны, чтобы открылись дополнительные функции Сервиса.

Ниже представлен минимальный список файлов, обработку которых необходимо реализовать со стороны 1с, чтобы интеграция (и Сервис) заработали.

Экспорт

customers.csv — клиенты, торговые точки
contacts.csv — контактные лица, номера телефонов пользователей
categories.csv — разделы каталога
items.csv — номенклатура, товары

Импорт

order.csv

1с → Сервис

Регионы доставки (regions.csv)

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор региона, (GUID) обязательно к заполнению
2	name	строка, 64 символа	название региона обязательно к заполнению

Клиенты (customers.csv)

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор клиента, (GUID) обязательно к заполнению
2	region_id	строка, 64 символа	уникальный идентификатор региона, (GUID) опционально
3	name	строка, 64 символа	название клиента обязательно к заполнению
4	price_col	натуральное число	номер колонки с ценами товаров Граничные значения: `min — 1` `max — 32767` обязательно к заполнению
5	price_promo_col	натуральное число	номер колонки с ценами товаров Граничные значения: `min — 0` `max — 32767` Значение по-умолчанию — `0` опционально
6	status	натуральное число	статус клиента Возможные значения: `0` - активный `1` - заблокирован обязательно к заполнению
7	debt	натуральное число	дебиторская задолженность (в копейках) Граничные значения: `min — 0` (задолженность отсутствует) `max — 2147483647` Например, 64 руб 25 коп передаётся как 6425 обязательно к заполнению
8	debt_stale	натуральное число	дебиторская задолженность (в копейках) Граничные значения: `min — 0` (просроченная задолженность отсутствует) max — 2147483647 Например, 64 руб 25 коп передаётся как 6425 опционально
9	debt_stale_limit	натуральное число	максимально допустимая дебиторская задолженность (в копейках) Граничные значения: `min — 0` (ограничение отсутствует) `max — 2147483647` Например, 64 руб 25 коп передаётся как 6425 опционально

Контактные лица (contacts.csv)

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор контактного лица, (GUID) обязательно к заполнению
2	cust_id	строка, 64 символа	уникальный идентификатор клиента, (GUID) обязательно к заполнению
3	phone	строка, 64 символа	номер мобильного телефона в международном формате, состоящий из цифр и ведущего символа `+` Например, `+79111234567` обязательно к заполнению
4	status	натуральное число	статус контактного лица Возможные значения: `0` — активный `1` — заблокирован обязательно к заполнению

Грузополучатели (addresses.csv)

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор адреса доставки, (GUID) обязательно к заполнению
2	cust_id	строка, 64 символа	уникальный идентификатор клиента, (GUID) обязательно к заполнению
3	address	строка, 64 символа	адрес доставки Например, “Ленина, 24А” обязательно к заполнению
4	status	натуральное число	статус грузополучателя Возможные значения: `0` - активный (по-умолчанию) `1` - заблокирован обязательно к заполнению
5	returns_amount_limit	натуральное число	максимально допустимая сумма возврата товаров. передаётся в копейках Граничные значения: `min — 0` (запрещено делать возвраты) `max — 2147483647` Значение по-умолчанию — `0` опционально

Категории (categories.csv)

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор категории, (GUID) обязательно к заполнению
2	name	строка, 64 символа	название категории обязательно к заполнению

Номенклатура (items.csv)

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор номенклатуры, (GUID) обязательно к заполнению
2	category_id	строка, 64 символа	уникальный идентификатор категории, (GUID) обязательно к заполнению
3	name	строка, 64 символа	название номенклатуры обязательно к заполнению
4	weight	натуральное число	вес 1 единицы товара. передаётся в граммах Граничные значения: `min — 0` `max — 2147483647` Например, 0.435 кг передаётся числом 435 обязательно к заполнению
5	weight_price	натуральное число	вес товара за который назначена цена. передаётся в граммаx Граничные значения: `min — 0` (цена за 1 шт товара) `max — 2147483647` (цена указана за этот вес товара) Например, 0.435 кг должно быть записано как 435 обязательно к заполнению
6	quantum	натуральное число	квант заказываемого количества товар заказывается кратко указанному значению Граничные значения: `min — 1` `max — 2147483647` обязательно к заполнению
7	photo	строка, 32 символа	название jpg-файла с фотографией номенклатуры в нижнем регистре. Отсутствие фотографии — пустая строка Если указана фотография, предполагается, что jpg-файл расположен в папке `jpg`. Пример — item_004323.jpg
8	status	натуральное число	статус номенклатуры Возможные значения: `0` - видна `1` - скрыта обязательно к заполнению
9	price_1	натуральное число	цена единицы товара по 1-й колонке. передаётся в копейка Граничные значения: `min — 0` `max — 2147483647` обязательно к заполнению
…
n	price_n	натуральное число	цена единицы товара по n-й колонке. передаётся в копейкаx Граничные значения: `min — 0` `max — 2147483647` обязательно к заполнению максимальное количество колонок (n) — 32767

Скидки (discounts.csv)

Все поля обязательны для заполнения

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор скидки, GUID
2	cust_id	строка, 64 символа	уникальный идентификатор клиента, GUID
3	promo_id	строка, 64 символа	уникальный идентификатор номенклатуры, GUID
4	promo_qty	строка, 10 символов	количество заказываемых единиц товара, которое необходимо превысить, чтобы получить бонус натуральное число максимальное значение — `2147483647`
5	bonus_id	строка, 64 символа	уникальный идентификатор номенклатуры, которая будет выдана в виде бонуса, GUID
6	bonus_qty	строка, 10 символов	количество бонусных единиц товара, получаемых клиентом при заказе промо-товаров натуральное число максимальное значение — `2147483647`
7	status	строка	статус скидки: `0` — активная `1` — не активная

Пример файла

|id|cust_id|promo_id|promo_qty|bonus_id|bonus_qty|status| |:-:|-|-|-|-| |3419|42|333|6|444|1|1|

Его следует читать как: Строка справочника “Промо” - 3419 Для клиента с кодом 42 Если закажет не менее 6 штук товара с кодом 333, получит 1 штуку товара с кодом 444 бесплатно Скидка действующая

Заказ (order_fix.csv)

Для каждого заказа создаётся свой файл с информацией о его статусе.

Правило именования файла

В общем виде файл с заказом описывается шаблоном - order_fix_#id#.csv, где #id# - уникальный идентификатор заказа в Snarta

Например, имя файла “order_fix_4315.csv” следует интерпретировать как: C кодом 4315 в БД Snarta

Структура файла

Файл состоит из секций (строк):

Заголовок (строка №1 файла). В заголовке указаны названия колонок “шапки” заказа: id, snarta_id, status.
Строка заголовка (строка №2 файла). В строке указаны значения шапки заказа (см. Строка заголовка)

Строка заголовка

Вторая строка файла

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор заказа (GUID) обязательно к заполнению
2	snarta_id	натуральное число	уникальный идентификатор заказа Snarta обязательно к заполнению
3	status	натуральное число	статус заказа Возможные значения: 1, 2, 3 и 4 см. Статусы заказов обязательно к заполнению

Статусы заказов

Список из возможных значений статуса заказов:

Получен (код - 1) Заказ выгружен в папку для обмена информацией
В работе (код - 2) Заказ принять в работу и готовится к отгрузке
Отгружен (код - 3) Заказ отгружен клиенту
Отменен (код - 4) Заказ отменен

Отгрузочная накладная (shipping.csv)

Правило именования файла

В общем виде файл с заказом описывается шаблоном - shipping_#id#.csv, где #id# - уникальный идентификатор заказа в web-приложении

Например, имя файла “shipping_4356.csv” следует интерпретировать как:

C кодом 4356 в БД web-приложения

Структура файла

Файл с заказом состоит из секций (строк):

Заголовок (строка №1 файла). В заголовке указаны названия колонок “шапки” заказа: id, shipped_at
Строка заголовка (строка №2 файла). В строке указаны значения шапки заказа (см. Строка заголовка)
Заголовок строк (строка №3 файла). В заголовке указаны названия колонок строк: item_id, qty
Строки отгрузки (строка №4 файла и все последующие). В строках указаны значения строк заказа (см. Строки отгрузки).

Заголовок отгрузки

Вторая строка файла. Все поля обязательны для заполнения

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор заказа (GUID) обязательно к заполнению
2	shipped_at	строка, 64 символа	временная метка отгрузки заказа с указанием часового пояса в формате ISO 8601 Например, 2019-04-22T15:21.160Z читается как “22 апреля 2019 года в 15:21 в часовом поясе Asia/Yakutsk” Дополнительная информация обязательно к заполнению

Строки отгрузки

Начинаются со строки №4 (включительно).

№	Название	Тип	Комментарии
1	item_id	строка, 64 символа	уникальный идентификатор номенклатуры (GUID) обязательно к заполнению
2	qty	натуральное число	количество заказываемых единиц товара Граничные значения: `min — 1` `max — 2147483647` обязательно к заполнению

Сервис → 1с

Заказ (order.csv)

Для каждого созданного заказа создаётся свой файл со строками этого заказа.

Правило именования файла

В общем виде файл с заказом описывается шаблоном - order_#id#.csv, где #id# - уникальный идентификатор заказа в web-приложении

Например, имя файла “order_4356.csv” следует интерпретировать как: C кодом 4356 в БД web-приложения

Структура файла

Файл с заказом состоит из секций (строк):

Заголовок заказа (строка №1 файла). В заголовке указаны названия колонок “шапки” заказа:

id,
cust_id,
contact_id,
created_at

Строка заголовка (строка №2 файла). В строке указаны значения шапки заказа (см. Строка заголовка)
Заголовок строк (строка №3 файла). В заголовке указаны названия колонок строк:

id,
item_id,
qty

Строки заказа (строка №4 файла и все последующие). В строках указаны значения строк заказа (см. Строки заказа).

Строка заголовка

Вторая строка файла. Все поля обязательны для заполнения

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор заказа в web-приложении
2	cust_id	строка, 64 символа	уникальный идентификатор покупателя
3	contact_id	строка, 64 символа	уникальный идентификатор контактного лица
4	created_at	строка, 64 символа	временная метка создания заказа с указанием часового пояса в формате ISO 8601 Например, 2019-04-22T15:21.160Z читается как “22 апреля 2019 года в 15:21 в часовом поясе Asia/Yakutsk” Дополнительная информация
5	payment	строка, возможные значения: 0, 1	способ оплаты заказа: `0` - безналичный перевод `1` - оплата наличными
6	delivery	строка, возможные значения: 0, 1	способ получения заказа: `0` - доставка `1` - самовывоз
7	shipment_address_id	строка, 64 символа	Возможные значения: пустая строка, если у клиента нет грузополучателей уникальный идентификатор грузополучателя, если у клиента есть минимум 1 грузополучатель
8	shipment_date	строка, 10 символов	предпочитаемая дата получения заказа в формате ISO 8601 Например, 2021-01-23 читается как 23 января 2021 года Важно! По-умолчанию дата не выгружается. Для активации функции обратитесь в техническую поддержку
9	shipment_trip	натуральное число	номер рейса получения заказа внутри даты, указанной в колонке `shipment_date` Граничные значения: `min — 1` `max — 2147483647` Важно! По-умолчанию рейс не выгружается. Для активации функции обратитесь в техническую поддержку

Строки заказа

Начинаются со строки №4 (включительно).

№	Название	Тип	Комментарии
1	id	строка, 64 символа	уникальный идентификатор строки заказа в web-приложении
2	item_id	строка, 64 символа	уникальный идентификатор номенклатуры
3	qty	натуральное число	количество заказываемых единиц товара Граничные значения: `min — 1` `max — 2147483647`
4	ret	натуральное число	количество возвращаемых единиц товара Граничные значения: `min — 0` `max — 2147483647` Значение по-умолчанию — `0`

Период синхронизации данных

1с → Сервис

Все справочники, выгружаемые из 1с, синхронизируются с Сервисом минимум 1 раз в сутки. В 00 часов часового пояса заказчика.

Минимальный период синхронизации:

Клиенты (customers.csv) — 1 раз в 120 минут
Контактные лица (contacts.csv) — 1 раз в 120 минут
Номенклатура (items.csv) — 1 раз в 120 минут
Скидки (discounts.csv) — 1 раз в 120 минут

Сервис → 1с

Минимальный период синхронизации:

Заказ (order.csv) — 1 раз 5 минут