Цитрус.Документация

Протокол обмена

На данной странице описан протокол обмена информацией между Учетной системой (1С, другой программой или внешним сервисом) и Продуктом 1С:Сайт ЖКХ

Инициатором обмена всегда выступает Учетная система: обмен происходит путем выполнения определенного вида запросов к сайту по протоколу HTTP. При этом на сайт передаются или получаются данные в формате XML.

Такие же файлы администратор сайта может передавать или получать вручную через административный интерфейс.
Страница указана в описании (см Форматы файлов).

Общие положения

Учетная система должна отправлять свои запросы на адрес вида: http://<адрес сайта>/bitrix/admin/tszh_exchange.php

Данный адрес используется в решении 1С:Сайт ЖКХ по умолчанию. Он может отличаться, если необходимо использовать защищенный протокол HTTPS, а также в случае если используется модифицированный вариант обмена

К этому адресу добавляются GET-параметры в зависимости от типа запроса. Основными параметрами являются:

  • mode — обязательный для любого запроса параметр
    Режим обмена. Может принимать значения checkauth, init, file, import или export
  • type — обязателен для всех запросов режима export или import
    Определяет тип данных загружаемых или выгружаемых с сайта (подробнее об этом в разделах ниже).

Авторизация

Любой сеанс обмена всегда начинается запросом c параметром ?mode=checkauth и заголовком Authorization для выполнения Basic-аутентификации по протоколу HTTP.

В качестве логина и пароля для HTTP-авторизации указываются данные пользователя на сайте, имеющего достаточные права на импорт или экспорт данных (например, администратора).

На этот запрос сайт отвечает тремя строками (используется разделитель строк \n):

success
<имя cookie>
<значение cookie>

Внимание! Во всех последующих запросах к сайту необходимо будет передать это значение в заголовке Cookie (что это?).

Возможные варианты ответа сервера

В первой строке ответа сервер отправляет результат операции:

  • success — запрос обработан успешно
  • failure — при обработке произошла ошибка
  • warning — запрос обработан, однако возникли предупреждения
    Может возникать при запросах с параметром ?mode=import
    Файлы, переданные на сайт, могут содержать ошибки и неточности, такой ответ означает, что файл был обработан не полностью и нужно исправить данные на стороне Учетной системы
  • progress — для завершения необходимо повторить текущий запрос
    На данный момент такой ответ можно получить только при запросах параметром с ?mode=import.
    Некоторые операции требуют достаточно длительного времени, из-за ограничений на стороне сервера они разбиваются на несколько «шагов». При получении такого ответа, Учетная система должна повторить текущий запрос для продолжения обработки.

Вторая и последующие строки содержат текст ответа (ошибки, предупреждения, текущего состояния или другие сообщения, которые можно показать пользователю).

Кодировка
На данный момент Продукт всегда отдает данные и сообщения в кодировке windows-1251.
Однако, рекомендуется ориентироваться на кодировку и тип содержимого, указанные в заголовке Content-Type ответа сервера — возможны внештатные ситуации, когда в ответ будет получено неожиданное содержимое (пользвоателем указан неверный адрес сервера, сервер временно недоступен, ответ содержит ошибки и т.п.)

Тип содержимого указывается в заголовке ответа Content-Type и может принимать следующие значения:

  • text/plain; charset=<кодировка> для всех вариантов ответа, описанных выше
  • application/xml; charset=<кодировка> в случае успешных ответов на запросы выгрузки данных (с параметром ?mode=export)
  • text/html или text/html; charset=<кодировка> в случае непредвиденных ошибок (внештатных ситуаций)

Для запросов с ?mode=export в случае успешной выгрузки, в ответ посылается содержимое файла выгрузки в формате XML. (см. Форматы обмена), в виде исключения первая строка со словом success при этом режиме опускается.

Для запроса с ?mode=checkauth текст ответа содержит имя и значение Cookie для авторизации (см. Авторизация), либо сообщение об ошибке.

Загрузка данных

Если в процессе обмена предполагается загрузка файлов обмена на сайт, после Авторизации должен следовать обязательный запрос с параметром ?mode=init

В ответ на него возвращается строка: file_limit=<число>, где <число> — максимально допустимый размер данных в байтах для передачи за один запрос. Если размер файла больше, он должен быть разбит на части, и передаваться в несколько запросов, каждый из которых будет дописывать данные к ранее переданным.

Процесс загрузки данных происходит в два этапа: передачи и обработки.

Общие требования к XML-файлам

  1. Стандарт XML не допускает использования в текстовых данных непечатаемых символов с ASCII-кодами в диапазоне значений от 0 до 31 (за исключением символов с кодами 9, 10, 13 — табуляция, перевод строки, возврат каретки). Это требует обязательной замены некоторых символов на эквивалентные им символьные коды:

    Символ в тексте Код для XML-файла
    " &quot;
    & &amp;
    > &gt;
    < &lt;
    ' &apos;

  2. Допустимы кодировки UTF-8 и windows-1251.

  3. Все элементы должны иметь открывающие и закрывающие теги. Если элемент не содержит значения или других элементов, правильной будет такая запись: <tag />

  4. Порядок следования элементов имеет значение: они должны указываться в порядке описанном в примерах файлов

  5. Атрибуты обязательно должны быть разделены пробелом, а их значения заключены в открывающие и закрывающие кавычки.

    Недопустимо:

    <tag attribute1="example"attribute="example2" />

    <tag attribute1="example />

    Правильная запись:

    <tag attribute1="example" attribute="example2" />

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

Для этого отправляется запрос с параметрами ?mode=file&filename=<имя файла>.

  • filename — имя загружаемого файла (регистр имеет значение)

Содержимое файла в виде данных POST-запроса (в исходном виде). В случае успешной записи файла сайт выдает строку success. Большие файлы (превышающие максимально допустимый размер данных) должны последовательно загружаться путём выполнения нескольких запросов с очередной частью файла.

Загрузка файлов

После передачи файлов производится пошаговая загрузка данных запросом с параметрами ?mode=import&type=<тип>&filename=<имя файла>&inn=<ИНН организации>.

  • type — тип загружаемого файла. Может принимать значения:
  • inn — ИНН организации, которой принадлежат данные из файла
    Должен соответствовать ИНН одного из Объектов управления, существующих на сайте
  • filename — имя ранее загруженного файла (регистр имеет значение)

Для обработки файла может потребоваться несколько запросов (см. Возможные варианты ответов сервера).

Важно! Двойные кавычки (") в значениях атрибутов, символы < и > внутри тегов обязательно должны заменяться на соответствующие XML-сущности.

Получение данных

Получение данных с сайта производится после (авторизации)[#Общие-положения_Авторизация] запросом с параметрами ?mode=export&type=<тип>&inn=<ИНН организации>.

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

В отличие от [загрузки данных](#Загрузка данных), выгрузка происходит в один запрос, в результате которого будет возвращены данные, либо сообщение об ошибке. Смотрите также: Возможные варианты ответа сервера.

На данный момент выгружаемые файлы всегда имеют кодировку windows-1251, однако рекомендуется определять кодировку на основании заголовка Content-Type, либо содержимого XML-файла

Последнее обновление: 9/20/2023, 6:04:42 AM

← Форматы файлов →