Что нужно знать 1С разработчику при написании интеграции с сайтом

Кастомный JSON обмен между 1С и Битрикс

21.03.2025

4 минуты

При разработке нестандартных интеграции 1С с веб-платформами, такими как Битрикс, зачастую требуется создание кастомного обмена данными. Стандартные механизмы Битрикс (например, модуль "Обмен с 1С") не всегда подходят, особенно если обмен имеет специфические бизнес-правила или требует работы с нестандартными объектами.

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

В качестве формата передаваемых данных, предлагается использовать формат JSON.

Почему для обмена лучше использовать JSON?

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

JSON (JavaScript Object Notation) — это текстовый формат, который отличается компактностью, простотой и удобством обработки. В отличие от XML, который содержит большое количество тегов, JSON имеет более лаконичную структуру, что сокращает объем передаваемых данных. Это особенно важно при частых запросах, так как уменьшает нагрузку на сеть и ускоряет обмен.

Кроме того, JSON проще обрабатывать в современных языках программирования, включая JavaScript и Python, а также в самой 1С, где его можно легко разобрать с помощью встроенных методов. XML, хоть и более формален и строг, требует дополнительных усилий при разборе и зачастую приводит к усложнению кода.

Таким образом, если требуется простой и быстрый обмен данными между 1С и веб-сайтом, JSON будет лучшим выбором.

Что нужно знать при работе с JSON

При создании JSON файлов, необходимо помнить о правилах, которые надо учитывать при работе с этим форматом.

Структура данных – JSON состоит из пар "ключ-значение", где ключи – строки, а значения могут быть строками, числами, массивами, объектами, true, false или null.
Правильное форматирование – строки должны быть заключены вво дйные кавычки ("), а не в одинарные (').
Запятые – последнему элементу в массиве или объекте не ставится запятая.
Кодировка – JSON использует UTF-8, что позволяет работать с любыми языками.
Именование ключей – лучше использовать понятные, человекочитаемые и согласованные названия.
Отсутствие комментариев – стандарт JSON не поддерживает комментарии, поэтому их нельзя добавлять в файлы JSON.
Ограниченные типы данных – JSON поддерживает только базовые типы (строки, числа, логические значения, массивы, объекты, null). Например, нет поддержки Date, BigInt или Set.

Типы данных, которые поддерживает JSON

Строки (String) – записываются в двойных кавычках.
```
"name": "Иван"
```
Числа (Number) – могут быть целыми или с плавающей точкой.
```
"age": 25,
"price": 99.99
```
Логические значения (Boolean) – могут быть true или false.
```
"isActive": true
```
Null – используется для обозначения отсутствующего значения.
```
"value": null
```
Массивы (Array) – содержат упорядоченные элементы любого поддерживаемого типа.
```
"users": ["Иван", "Мария", "Петр"]
```
Объекты (Object) – представляют собой коллекции пар "ключ-значение".
```
"user": {
    "name": "Иван",
    "age": 25
}
```

JSON не поддерживает сложные типы данных, такие как Date, BigInt, Set, Map или функции. Если нужно передать дату, обычно используется строка в формате ISO 8601:

"createdAt": "2024-03-24T12:00:00Z"

Структура ответа

Для обеспечения единообразия все ответы сервера (любой из сторон) должны следовать единому формату, независимо от результата выполнения запроса. Это упрощает обработку ответов на стороне клиента и делает интеграцию более предсказуемой.

Предлагаемая структура ответа

Формат ответа включает три ключевых элемента:

{
  "status": String,
  "data": Object,
  "messages":Array
}

status – строковый параметр, указывающий на результат выполнения ( "success" или "error" ).
data – объект с передаваемыми данными, если запрос выполнен успешно. В случае ошибки может быть пустым ({}).
messages – массив ошибок или предупреждений. Если ошибок нет, массив остается пустым. Каждая ошибка представляется объектом с кодом и описанием.

Формат ответа может быть в JSON, XML или другом удобном формате, но структура должна сохраняться.

Примеры ответов

Успешный ответ

Запрос выполнен успешно, в data передаются необходимые данные:

{
  "status": "success",
  "data": {
    "guid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "messages": []
}

Ответ с ошибкой

Если в ходе выполнения запроса возникли ошибки, они передаются в массиве messages:

{
  "status": "error",
  "data": {},
  "messages": [
    {
      "code": "EMPTY_GUID",
      "message": "Не заполнен guid клиники"
    },
    {
      "code": "NO_AVAILABLE_DATES",
      "message": "Нет свободных дат у выбранного врача"
    }
  ]
}

Дополнительные рекомендации

Единый формат кодов ошибок – рекомендуется использовать читаемые и однозначные коды (EMPTY_GUID, NO_AVAILABLE_DATES), чтобы клиент мог корректно интерпретировать их.
Описательные сообщения – каждое сообщение должно ясно объяснять причину ошибки, но не раскрывать лишнюю информацию (например, детали серверных ошибок).
Расширяемость – можно добавлять дополнительные поля (например, warnings для предупреждений), но основные ключи (status, data, messages) должны оставаться неизменными.
HTTP-коды – желательно, чтобы ответы соответствовали HTTP-стандартам:
- 200 OK – успешный ответ
- 400 Bad Request – ошибка в запросе
- 500 Internal Server Error – ошибка на сервере

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

Пример контроллера API в Битрикс

Для реализации кастомного обмена на стороне Битрикс создадим API-контроллер, который будет обрабатывать запросы от 1С. В данном примере используется встроенный в Битрикс класс Result для формирования стандартного ответа.

Для написания контроллера на стороне php нам понадобится классы Bitrix\Main\Error и Bitrix\Main\Result.

Создание API-контроллера

Создадим обработчик в файле /local/api/exchange.php

use Bitrix\Main\Error;
use Bitrix\Main\Result;
use Bitrix\Main\Context;
use Bitrix\Main\Web\Json;

$result = new Result();
$request = Context::getCurrent()->getRequest();


if (!$request->isPost())
{
    $result->addError(new Error("Метод не поддерживается", "METHOD_NOT_ALLOWED"));
}
else
{
    $postData = Json::decode($request->getInput());

    if (empty($postData["guid"]))
    {
        $result->addError(new Error("Не заполнен guid", "EMPTY_GUID"));
    }

    if ($result->isSuccess())
    {
        $data = [
            "guid" => $postData["guid"],
            "status" => "processed"
        ];
        $result->setData($data);

    }
}

$errors = [];
foreach ($result->getErrors() as $error)
{
    $errors[] = [
        "code" => $error->getCode(),
        "message" => $error->getMessage()
    ];
}

echo Json::encode([
    "status" => $result->isSuccess() ? "success" : "error",
    "data" => $result->getData(),
    "messages" => $errors
]);

exit();

Полная документация по Result есть на официальном сайте.

Обработка ответа в 1С

На стороне 1С необходимо корректно разбирать JSON-ответ и учитывать возможные ошибки.

Пример обработки ответа в 1С:

Функция ОбработатьОтвет(ТекстОтвета)
    Перем СтруктураОтвета;
    
    Попытка
        СтруктураОтвета = JSONРазобратьСтроку(ТекстОтвета);
    Исключение
        Возврат "Ошибка разбора ответа";
    КонецПопытки;
    
    Если СтруктураОтвета.status = "success" Тогда
        Возврат "Операция выполнена успешно, GUID: " + СтруктураОтвета.data.guid;
    Иначе
        Для Каждого Ошибка Из СтруктураОтвета.messages Цикл
            Сообщить("Ошибка [" + Ошибка.code + "]: " + Ошибка.message);
        КонецЦикла;
        Возврат "Ошибка выполнения операции";
    КонецЕсли;
КонецФункции

Преимущества предлагаемого подхода

Стандартизация обработки данных – вне зависимости от типа запроса формат остается единым.
Удобство работы с ошибками – ошибки всегда представлены в виде массива с кодами и описаниями.
Использование класса Result в Битрикс – позволяет гибко работать с результатами выполнения.
Гибкость – data может быть легко расширен новыми параметрами без изменения логики обработки ошибок.
Совместимость – такой формат подходит как для API 1С, так и для работы с другими системами.

Заключение

Если стандартные механизмы обмена с 1С не подходят, то разработка кастомного API является наиболее правильным решением. Использование предложенного унифицированного формата ответа, позволяет значительно упростить интеграцию, сделать её предсказуемой и легко поддерживаемой.

Рекомендуется придерживаться данной структуры при разработке API, что обеспечит удобную обработку запросов как на стороне 1С, так и в Битрикс.