Для продажи автозапчастей в интернете уже сделано немало готовых платформ. Какие-то распространяются по ежемесячной подписке. Другие можно купить и установить на своем сервере. Платформа Docpart выгодно отличается на фоне конкурентов низкой стоимостью и необходимым функционалом для открытия своего интернет-магазина. Функционально она в чем-то уступает более именитым конкурентам, но далеко не все пользователи используют функционал интернет-магазина "по полной".  Платформа потихоньку обрастает новыми функциями и становится чуть-чуть лучше с каждым обновлением. Открытость кода позволяет дорабатывать необходимый функционал самостоятельно не "подсаживаясь" на сервисную поддержку производителя. 

Для реализации обмена я разработал небольшое API, которое позволяет оперативно получать данные с сайта и обрабатывать их в вашей учетной системе. Причем учетной системой может быть не только 1С. 

Работа с сервисом

Для использования API необходимо установить модули из архива docpart_1c_api.zip на ваш веб-сервер. Для примера, скопируем все модули в каталог /api/agent_1c.

Если Вы назовете свой каталог по-другому, то не забудьте изменить путь к вызову методов веб-сервиса во всех командах в обработке.

Работа с веб-сервисом осуществляется посредством отправки POST-запросов к входной точке веб-сервиса, которой является скрипт execute.php с передачей необходимого метода и параметров. В ответ будут возвращены необходимые данные. 

Для использования API версия платформы 1С значения не имеет. Работать будет с любой учетной системой для которой есть возможность отправки POST-запроса и обработки его результата. 

В нашем примере все запросы следует отправлять к адресу:

http://мой-магазин.рф/api/agent_1c/execute.php

Для запросов обязательна передача заголовка

content-type: application/x-www-form-urlencoded

В теле POST-запроса есть два общих для всех методов параметра:

• task – имя метода API для выполнения
• tech_key – Ключ для вызова скриптов. Его необходимо взять из панели управления платформы Docpart в разделе «Настройки».

При вызове любого метода будет возвращена JSON-структура с полями

• status – Булево – статус выполнения метода
• message – Строка – Сообщение об ошибке
• data – Результат выполнения метода

Пример вызова метода для платформы 8.3 (8.3.5+):

Процедура ВыполнитьЗапросDocpartAPI()

//Изменить параметры на свои значения
АдресСайта = "мой-магазин.рф";
ТелоЗапроса = "tech_key=TESTKEYTECH&task=check_connection";
ПротоколHTTPS = Истина;

//Вызов метода API
Если ПротоколHTTPS Тогда
ЗащищенноеСоединение = Новый ЗащищенноеСоединениеOpenSSL();
ПодключениеКСерверу = Новый  HTTPСоединение(АдресСайта,,,,,30, ЗащищенноеСоединение);
Иначе
ПодключениеКСерверу = Новый  HTTPСоединение(АдресСайта,,,,,30);
КонецЕсли;

ОтветСервера = Неопределено;
Если ПодключениеКСерверу = Неопределено Тогда
ОбщегоНазначения.СообщитьОбОшибке("Обмен с WEB-сайтом: ошибка подключения к сайту: "+ОписаниеОшибки());
Возврат ;
КонецЕсли;

СтрокаПодключения = "api/agent_1c/execute.php";
ЗаголовокHTTP = Новый Соответствие;
ЗаголовокHTTP.Вставить("Content-Type","application/x-www-form-urlencoded; charset=UTF-8");
ЗапросHTTP =  Новый HTTPЗапрос(СтрокаПодключения, ЗаголовокHTTP);
ЗапросHTTP.УстановитьТелоИзСтроки(ТелоЗапроса,КодировкаТекста.ANSI);
Попытка
РезультатЗапроса = ПодключениеКСерверу.ОтправитьДляОбработки(ЗапросHTTP);
ОтветСервера = РезультатЗапроса.ПолучитьТелоКакСтроку();
Исключение
ОбщегоНазначения.СообщитьОбОшибке("Обмен с WEB-сайтом: ошибка отправки данных на сервер: "+ОписаниеОшибки());
КонецПопытки;

Если НЕ ЗначениеЗаполнено(ОтветСервера) Тогда
Возврат;
КонецЕсли;

//JSON ENCODE
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(ОтветСервера);
Результат = ПрочитатьJSON(Чтение, Истина); //Структура запроса для дальнейшей обработки
Чтение.Закрыть();

//Обрабатываем дальнейший результат
Если Результат["status"] Тогда
ОбщегоНазначения.Сообщение("Связь с сайтом установлена");
Иначе
ОбщегоНазначения.Сообщение("Ошибка связи с сайтом: "+Результат["message"]);
Конецесли;

КонецПроцедуры

Пример работы с веб-сервисом

Обработка тестировалась на платформе 8.3.5 но должна работать и на более ранних версиях. В настройках обработки необходимо прописать адрес Вашего сайта и ключ доступа. Адрес скрипта на сервере можно менять по-своему усмотрению, тогда необходимо изменить соответствующую настройку.  

Для повышения безопасности на Вашем веб-сервере можно настроить HTTP-авторизацию для доступа к каталогу с модулем API. Тогда в настройках необходимо указать логин и пароль для доступа. 

В обработке реализованы вызовы всех методов API. При появлении новых методов обработка будет обновляться. Пока сделана для конфигураций на обычных формах. В случае необходимости, добавлю для управляемых. Фильтры на форме реализованы только основные. Передача остальных фильтров выполняется добавлением в структуру необходимых полей. Имена необходимых полей можно увидеть в функции модуля "ПолучитьПараметрыМетода". 

 

Для вызова метода API необходимо заполнить структуру параметров и вызвать нужный метод из модуля обработки. Метод возвращает таблицу значений с данными сайта. 

    СтруктураФильтров = Новый Структура;
Если ЗначениеЗаполнено(НачалоПериодаОплаты) Тогда
СтруктураФильтров.Вставить("НачалоПериода", НачалоПериодаОплаты);
КонецЕсли;
Если ЗначениеЗаполнено(КонецПериодаОплаты) Тогда
СтруктураФильтров.Вставить("КонецПериода", КонецПериодаОплаты);
КонецЕсли;
Если ЗначениеЗаполнено(КодОперации) Тогда
СтруктураФильтров.Вставить("КодОперации", КодОперации);
КонецЕсли;

ТаблицаОплат = ПолучитьОплатыПокупателей(СтруктураФильтров);//Вызываем метод из модуля обработки

ВНИМАНИЕ: Обработка только возвращает данные с сайта. Сохранение данных для своей конфигурации необходимо реализовывать самостоятельно! Позже планируется добавить полноценную интеграцию для типовых конфигураций. 

Методы API

Проверка соединения с сервисом

Метод используется для проверки связи с сайтом и корректности указания настроек обмена.

Операция: check_connection

Параметры запроса:

Параметр	Пример заполнения	Описание
tech_key *	TEST_KEY_FROM_SETTINGS	Строка – Ключ для вызова скриптов

 

Для проверки связи с веб-сервисом предназначен метод check_connection. При успешном выполнении метод возвращает ответ:

Поле	Описание
status	Булево – статус выполнения метода
message	Строка – всегда возвращает текст «ОК»

 

Получение списка заказов

Метод возвращает список заказов, соответствующих отбору.

Операция: get_orders

Параметры запроса:

Параметр	Пример заполнения	Описание
tech_key *	TEST_KEY_FROM_SETTINGS	Строка – Ключ для вызова скриптов
time_from *	10.01.2024	Дата – Начало периода получения заказов
time_to	12.01.2024	Дата – Окончание периода получения заказов
order_id	10	Идентификатор заказа
status	2	Идентификатор статуса заказа
paid	1	Состояние оплаты заказа (0/1)

 

Результат запроса представляет собой структуру с данными:

Поле	Описание
status	Булево – статус выполнения метода
message	Строка – всегда возвращает текст «ОК»
data	Запрашиваемые данные

 

При успешном выполнении метод возвращает данные [data]:

Поле	Описание
order_id	Число – Идентификатор заказа
time	Дата – Дата и время оформления заказа
user_id	Число – Идентификатор пользователя
amount	Число – Сумма заказа
paid	Число – Состояние оплаты (0/1)
status	Число – Идентификатор статуса заказа
obtain_id	Число – Идентификатор способа доставки
obtain_caption	Строка – Наименование способа доставки
office_id	Число – Идентификатор офиса самовывоза
office_name	Строка – Офис самовывоза

 

Получение списка позиций заказов

Метод возвращает список товаров заказов, выбранных заказов.

Операция: get_orders_items

Параметры запроса:

Параметр	Пример заполнения	Описание
tech_key *	TEST_KEY_FROM_SETTINGS	Строка – Ключ для вызова скриптов
order_id	10	Число / Массив чисел — Идентификаторы заказов

 

Результат запроса представляет собой структуру с данными:

Поле	Описание
status	Булево – статус выполнения метода
message	Строка – всегда возвращает текст «ОК»
data	Запрашиваемые данные

 

При успешном выполнении метод возвращает данные [data]:

Поле	Описание
order_id	Число – Идентификатор заказа
item_id	Число – Идентификатор позиции заказа
product_name	Строка – Наименование товара каталога. Для товара с product_type=1
brand	Строка – Наименование производителя
article	Строка – Артикул товара
count	Число – Количество
price	Число – Цена
amount	Число – Сумма
product_type	Число – Тип товара: 1 – Товар из каталога в наличии, 2 – Товар из проценки по артикулу
product_id	Число – Идентификатор товара каталога. Для товара с product_type=1
t2_time_to_exe	Дата – Срок доставки. Для товара с product_type=2
t2_time_to_exe_guaranteed	Дата – Гарантированный срок доставки. Для товара с product_type=2
status_id	Число – Идентификатор статуса позиции
status_name	Строка – Наименование статуса позиции

 

Получение информации о пользователе

Метод возвращает расширенную информацию о пользователе.

Операция: get_user_info

Параметры запроса:

Параметр	Пример заполнения	Описание
tech_key *	TEST_KEY_FROM_SETTINGS	Строка – Ключ для вызова скриптов
user_id	15	Число / массив чисел – Идентификатор пользователя

 

Для проверки связи с веб-сервисом предназначен метод check_connection. При успешном выполнении метод возвращает ответ:

Поле	Описание
status	Булево – статус выполнения метода
message	Строка – всегда возвращает текст «ОК»
Data	Запрашиваемые данные

 

Структура Data содержит следующие данные

Поле	Описание
user_id	Число –Идентификатор пользователя
reg_variant	Число – Выбранный способ регистрации (Из числа описанных в панели управления сайта раздел «Способы регистрации»)
reg_field	Строка – значение главного поля регистрации (Email / Телефон). Задается в настройках платформы: «Главное поле регистрации»
unlocked	Число – Пользователь заблокирован – 0 или нет — 1
activated	Число – Пользователь активировал свою учетную запись – 1 или нет -0.
time_registered	Дата — Дата регистрации пользователя
time_last_visit	Дата – Дата последнего визита пользователя
Дополнительные поля регистрации	Значения регистрационных полей для текущего пользователя

 

В результат запроса будут добавлены все значения регистрационных полей, определенных для текущего способа регистрации. Их состав можно определить в панели управления в разделе: Пользователи – Поля регистрации.

Получение транзакций оплаты

Метод возвращает список транзакций оплаты проведенных на сайте

Операция: get_payments

Параметры запроса:

Параметр	Пример заполнения	Описание
tech_key *	TEST_KEY_FROM_SETTINGS	Строка – Ключ для вызова скриптов
time_from *	10.01.2024	Дата – Начало периода получения заказов
time_to	15.01.2024	Дата – Окончание периода получения заказов
payment_id	10	Идентификатор транзакции
operation_code	7	Код операции из справочника
income	1	Вид операции: 1 – приход, 0- расход

 

Результат запроса представляет собой структуру с данными:

Поле	Описание
status	Булево – статус выполнения метода
message	Строка – всегда возвращает текст «ОК»
data	Запрашиваемые данные

 

При успешном выполнении метод возвращает данные [data]:

Поле	Описание
payment_id	Число – Идентификатор транзакции
user_id	Число – Идентификатор пользователя
time	Дата / время – Дата и время транзакции
income	Число, Вид операции: 1 – приход, 0- расход
pay_orders	Число, Идентификатор заказа для которого производится оплата
amount	Число, Сумма транзакции
operation_code	Число, Код операции

 

Получение информации об артикуле

Метод возвращает список производителей и наименования товара по его артикулу. Получение данных выполняется с сервера Кроссов Docpart. Для одного артикула может быть возвращено несколько вариантов производителей.

Операция: get_article_info

Параметры запроса:

Параметр	Пример заполнения	Описание
tech_key *	TEST_KEY_FROM_SETTINGS	Строка – Ключ для вызова скриптов
article	24012802171	Строка / массив строк — Артикулы товаров для которых необходимо получить информацию

 

Результат запроса представляет собой структуру с данными:

Поле	Описание
status	Булево – статус выполнения метода
message	Строка – всегда возвращает текст «ОК»
data	Запрашиваемые данные

 

При успешном выполнении метод возвращает данные [data]:

Поле	Описание
article	Строка – Артикул товара
manufacturer	Строка – Производитель
name	Строка — Наименование товара

 

Обновления

UPD 14.07.2024: Добавлена обработка получения данных для 1С

UPD 20.07.2024: Исправление некоторых замечаний. Изменены имена некоторых параметров и свойств. Для метода get_user_info добавлена возможность передачи массива идентификаторов пользователей. В архив с модулями добавлен файл описания методов API.

UPD 28.07.2024: Получение информации о товарах выделено в отдельный метод — get_orders_items. Добавлен метод для получения информации о товарах — get_article_info. Исправлена обработка для работы с новыми методами.