Перейти к содержимому
BXWiki

Обмен с 1С и интеграции в 1С-Битрикс - CommerceML, HttpClient

Граница системы: точки, где данные сайта встречаются с 1С, маркетплейсами и чужими API. Разберём обмен по CommerceML - самую частую интеграцию в проектах на 1С-Битрикс - и штатный клиент для исходящих запросов.

Как это работает

Обмен идёт между модулем на стороне 1С и сайтом. Формат данных - CommerceML, единый XML-стандарт обмена коммерческой информацией. На стороне сайта техническая точка входа одна - служебный скрипт обмена в административном разделе. Его адрес прописывают в настройке обмена в 1С вместе с логином и паролем пользователя, имеющего право на обмен.

Понятийное соответствие, без которого сложно понять, что куда попадёт: контрагенты 1С становятся пользователями сайта, справочники - highload-блоками, номенклатура - товарами, характеристики товара - торговыми предложениями.

Что умеет обмен: выгрузку каталога и прайс-листов из 1С, обновление товаров, цен и остатков по расписанию, приём и обработку заказов в 1С, передачу покупателю статусов заказа.

Направления настраиваются независимо: выгрузка номенклатуры, выгрузка справочников, обмен документами, выгрузка контрагентов. Порядок операций, число повторных попыток и интервал задаются в настройках обмена.

Три режима синхронизации: реальное время, по расписанию и только вручную. Реальное время доступно только для клиент-серверного варианта базы 1С - на файловой базе сеанс блокируется на время мониторинга.

Контроль изменений. Выгрузка бывает полной или только изменённых объектов. Отдельный флаг решает судьбу товаров, не попавших в полную выгрузку. Для ускорения включают контрольные суммы элементов - тогда обновляются только реально изменившиеся позиции.

Служебные артефакты. Логи и XML-протоколы складываются в каталог загрузок, а связка объектов между 1С и сайтом хранится в таблице идентификаторов. Эту таблицу трогать нельзя.

Примеры

1. Исходящий запрос к чужому API

use Bitrix\Main\Web\HttpClient;
use Bitrix\Main\Web\Json;


$http = new HttpClient([
    'socketTimeout' => 5,
    'streamTimeout' => 10,
]);
$http->setHeader('Content-Type', 'application/json');
$http->setHeader('Authorization', 'Bearer ' . $token);


$body = $http->post($url, Json::encode(['order_id' => $orderId]));


if ($body === false) {
    $logger->error('Transport error', ['error' => $http->getError()]);
    return;
}


if ($http->getStatus() !== 200) {
    $logger->warning('Unexpected status', ['status' => $http->getStatus()]);
    return;
}


$data = Json::decode($body);

Три обязательные вещи: явные таймауты, раздельная проверка транспортной ошибки и HTTP-статуса, и разбор ответа только после этих проверок. Непустое тело ответа успехом не является.

Если адрес запроса приходит от пользователя, включайте защиту от обращений во внутреннюю сеть.

2. Свой эндпоинт для внешней системы

Современный способ - контроллер с объявленным маршрутом: он даёт типизированные аргументы, фильтры доступа и единый формат ответа. Легаси-вариант - отдельный скрипт, но тогда проверку прав, метода и токена придётся делать вручную.

#[Authentication]
#[HttpMethod([HttpMethod::METHOD_POST])]
public function statusAction(int $orderId, string $status): array
{
    $result = $this->service->updateStatus($orderId, $status);


    return ['success' => $result->isSuccess()];
}

Справочник

ЭлементНазначениеОсобенности
Служебный скрипт обменаточка входа для 1Садрес прописывается в настройке обмена
CommerceMLформат обменаXML-стандарт коммерческой информации
Режимы синхронизацииреальное время, расписание, вручнуюреальное время только для клиент-серверной базы
Полная и частичная выгрузкаконтроль измененийфлаг деактивации непопавших товаров
Контрольные суммы элементовускорение импортаобновляются только изменившиеся
Идентификаторы объектовсвязка 1С и сайтаудалять нельзя - появятся дубли
Журнал ошибок обменадиагностикапишется только при включённом флаге
Web\HttpClientисходящие запросытаймауты, статус, защита от обращений внутрь сети
Web\Jsonкодирование и разбор JSON
Контроллер с маршрутомсвой эндпоинтфильтры доступа и единый формат ответа

Частые ошибки

Обмен не отвечает на запросы 1С. Частая причина - включённый режим правки сайта без перезагрузки страницы.

Сбой авторизации на CGI-варианте PHP. Заголовок авторизации не доходит до скрипта - нужен проброс на уровне веб-сервера.

Дубли товаров и заказов после обмена. Обычно следствие ручного удаления записей связки объектов: 1С перестаёт узнавать существующие объекты и создаёт их заново.

После обмена пропали товары. Сработал флаг деактивации товаров при неполной выгрузке.

Товар не выгружается. Позиция без цены, включая вычисляемую по формуле, не попадает в выгрузку - цену задают явно.

Журнал ошибок пустой при явных сбоях. Не включено хранение информации об ошибках.

Два обмена запущены одновременно. Процедуры конфликтуют на временных таблицах

  • параллельный запуск недопустим.

Внешний запрос считают успешным по непустому ответу. Проверять нужно и транспортную ошибку, и статус ответа.

Частые вопросы

Откуда начинать диагностику обмена с 1С?

С трёх вещей: доступен ли служебный скрипт обмена по адресу, указанному в 1С; проходит ли авторизация пользователя, от имени которого идёт обмен; включено ли хранение информации об ошибках - иначе журнал будет пустым при реальных сбоях. Дальше смотрят логи и XML-протоколы, которые 1С складывает в каталог загрузок.

Почему после обмена задвоились товары?

Почти всегда потому, что потеряна связка объектов между 1С и сайтом - её хранит служебная таблица идентификаторов. Если её очистили вручную или восстановили базу частично, 1С перестаёт узнавать существующие позиции и создаёт новые. Восстановить связку постфактум сложно, поэтому таблицу идентификаторов не трогают.

Какой режим синхронизации выбрать?

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

Чем делать исходящие запросы к внешним API?

Штатным HTTP-клиентом платформы, а не файловыми функциями или прямыми вызовами curl. Он даёт таймауты, работу с заголовками, скачивание в файл и режим защиты от обращений во внутреннюю сеть. Главное - задавать таймауты явно и проверять раздельно транспортную ошибку и HTTP-статус: непустой ответ не означает успех.

Связанные темы

Первоисточники