Для продажи автозапчастей в интернете уже сделано немало готовых платформ. Какие-то распространяются по ежемесячной подписке. Другие можно купить и установить на своем сервере. Платформа 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.2019 |
Дата – Начало периода получения заказов |
|
time_to |
12.01.2019 |
Дата – Окончание периода получения заказов |
|
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.2019 |
Дата – Начало периода получения заказов |
|
time_to |
15.01.2019 |
Дата – Окончание периода получения заказов |
|
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 30.04.2020: Добавлена документация по всем методам: Полная документация по методам Docpart 1C API
UPD 14.07.2019: Добавлена обработка получения данных для 1С
UPD 20.07.2019: Исправление некоторых замечаний. Изменены имена некоторых параметров и свойств. Для метода get_user_info добавлена возможность передачи массива идентификаторов пользователей. В архив с модулями добавлен файл описания методов API.
UPD 28.07.2019: Получение информации о товарах выделено в отдельный метод - get_orders_items. Добавлен метод для получения информации о товарах - get_article_info. Исправлена обработка для работы с новыми методами.
