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

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

API серверов обеспечивает передачу внешней системе списка измененных объектов данных с указанного момента времени, а не полного списка объектов. Это позволяет существенно экономить вычислительные ресурсы и сетевой трафик, но требует от внешней стороны вести учет меток актуальности данных 1С-Коннект.

Основные возможности

API серверов поддерживает следующие действия с объектами системы 1С-Коннект:

Создание, изменение, удаление и выгрузку списков следующих видов объектов:
- сотрудник своей организации;
- клиент (юр.лицо);
- сотрудник клиента;
- линия поддержки;
- компетенция сотрудника по линии;
- подключение линии поддержки потребителю (сотруднику своей организации/ сотруднику клиента);
- обращение по линии поддержки;
- заявка на обслуживание.
Выгрузку истории коммуникации пользователей.
Получение статистики показов/просмотров по стартовым заставкам и продуктам витрины.
Создание, изменение и отправку рассылок и уведомлений пользователям.
Отправку сообщений и файлов в чат по линии поддержки.

Доступ к API серверов, а также настройка часового пояса, в соответствии с которым будет показана информация, полученная с помощью web-сервисов, настраиваются в Личном кабинете в разделе "Администрирование" подраздел "Настройки API". Также в этом подразделе вы можете посмотреть статистику по использованию web-сервисов.

Реализация

API серверов основан на механизмах Web-сервисов в реализации "1С: Предприятие 8.3".
Все операции манипулирования данными сгруппированы по-объектно.
Добавление, изменение и удаление объектов определенного вида можно делать пакетно, т.е. "пачкой за 1 раз".
Все входные параметры вызова ws-операции передаются одной переменной-массивом (XDTO-совместимой с типом «Структура» прикладного языка "1С: Предприятие 8") - это позволяет впоследствии расширять перечень передаваемых параметров, сохраняя совместимость с ранее написанными клиентами внешними алгоритмами.
У всех ws-операций единая структура ответа, она позволяет при успехе выполнения передать результат, а при ошибке выполнения - сведения об ошибке и месте её возникновения.
Во избежание непреднамеренной DDoS-атаки путём беспрерывной бесконечной цепочки запросов к API, на каждый вид ws-операции наложено ограничение по максимальному количеству вызовов операции в час. Параметры ограничений указаны в таблице.

Пример реализации на платформе 1С

Обработка-пример вызова операции GetHistoryOfServiceCalls: ВызовОперацийPartnerAPI2.epf

Структура результата ws-операции

Каждая операция на выходе выдает структуру из двух полей: ResultCode, ResultData. ResulеCode содержит код выполнения, если код = SUCCESS, то в поле ResultData результат операции, иначе текстовое описание ошибки. Необработанная ошибка вызовет исключение, и операция вернет исключение с текстом ошибки.

При пакетной передаче данных поле ResultData будет содержать таблицу значений. Объекты в пакете обрабатываются построчно. При этом номер строки входного параметра будет соответствовать номеру строки, соответствующей этому запросу на выходе.При возникновении ошибки выполнение операции не прекратится, пока не обработаются все содержимое пакета, либо не будет достигнут лимит.

Пример запроса

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<m:ClientAdditionalParameterValueEdit xmlns:m="http://buhphone.com/PartnerWebAPI2">
			<m:Params xmlns:d4p1="http://v8.1c.ru/8.1/data/core"
					xmlns:xs="http://www.w3.org/2001/XMLSchema"
					xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
					xsi:type="d4p1:ValueTable">
				<d4p1:column>
					<d4p1:Name>ClientParameterID</d4p1:Name>
					<d4p1:ValueType>
						<d4p1:Type>xs:string</d4p1:Type>
						<d4p1:StringQualifiers>
							<d4p1:Length>0</d4p1:Length>
							<d4p1:AllowedLength>Variable</d4p1:AllowedLength>
						</d4p1:StringQualifiers>
					</d4p1:ValueType>
				</d4p1:column>
				<d4p1:column>
					<d4p1:Name>ClientID</d4p1:Name>
					<d4p1:ValueType>
						<d4p1:Type>xs:string</d4p1:Type>
						<d4p1:StringQualifiers>
							<d4p1:Length>0</d4p1:Length>
							<d4p1:AllowedLength>Variable</d4p1:AllowedLength>
						</d4p1:StringQualifiers>
					</d4p1:ValueType>
				</d4p1:column>
				<d4p1:column>
					<d4p1:Name>Value</d4p1:Name>
					<d4p1:ValueType>
						<d4p1:Type>xs:string</d4p1:Type>
						<d4p1:StringQualifiers>
							<d4p1:Length>0</d4p1:Length>
							<d4p1:AllowedLength>Variable</d4p1:AllowedLength>
						</d4p1:StringQualifiers>
					</d4p1:ValueType>
				</d4p1:column>
				<d4p1:column>
					<d4p1:Name>Color</d4p1:Name>
					<d4p1:ValueType>
						<d4p1:Type>xs:string</d4p1:Type>
						<d4p1:StringQualifiers>
							<d4p1:Length>0</d4p1:Length>
							<d4p1:AllowedLength>Variable</d4p1:AllowedLength>
						</d4p1:StringQualifiers>
					</d4p1:ValueType>
				</d4p1:column>
				<d4p1:row>
					<d4p1:Value>xfafb2b5-8552-11e6-80e3-xx25904f970x</d4p1:Value>
					<d4p1:Value>xa29b1a9-26ef-11e8-80e6-x025904f970x</d4p1:Value>
					<d4p1:Value>Значение1</d4p1:Value>
					<d4p1:Value>RED</d4p1:Value>
				</d4p1:row>
				<d4p1:row>
					<d4p1:Value>xfafb2b5-8552-11e6-80e3-x025904f970x</d4p1:Value>
					<d4p1:Value>x74f2212-ed24-49b9-8bb1-xx5822033abx</d4p1:Value>
					<d4p1:Value>Значениe2</d4p1:Value>
					<d4p1:Value>BLUE</d4p1:Value>
				</d4p1:row>
			</m:Params>
		</m:ClientAdditionalParameterValueEdit>
	</soap:Body>
</soap:Envelope>

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

<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:ClientAdditionalParameterValueEditResponse
      xmlns:m="http://buhphone.com/PartnerWebAPI2">
      <m:return
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Property
          xmlns="http://v8.1c.ru/8.1/data/core"
						name="ResultCode">
          <Value xsi:type="xs:string">SUCCESS</Value>
        </Property>
        <Property
          xmlns="http://v8.1c.ru/8.1/data/core"
						name="ResultData">
          <Value xsi:type="ValueTable">
            <column>
              <Name>ResultCode</Name>
              <ValueType>
                <Type>xs:string</Type>
                <StringQualifiers>
                  <Length>0</Length>
                  <AllowedLength>Variable</AllowedLength>
                </StringQualifiers>
              </ValueType>
            </column>
            <column>
              <Name>ResultData</Name>
              <ValueType/>
            </column>
            <row>
              <Value xsi:type="xs:string">SUCCESS</Value>
              <Value xsi:type="xs:boolean">true</Value>
            </row>
            <row>
              <Value xsi:type="xs:string">SUCCESS</Value>
              <Value xsi:type="xs:boolean">true</Value>
            </row>
          </Value>
        </Property>
      </m:return>
    </m:ClientAdditionalParameterValueEditResponse>
  </soap:Body>
</soap:Envelope>

Ссылка для подключение к web-сервису

Страна	URL
Россия, Казахстан, Беларусь, Туркмения, Таджикистан, Узбекистан, Киргизия и Вьетнам	https://cus.buhphone.com/cus/ws/PartnerWebAPI2?wsdl
Украина, Азербайджан, Армения, Грузия, Латвия, Литва, Эстония, Молдова и Румыния	https://eu-cus.1c-connect.com/cus/ws/PartnerWebAPI2?wsdl

Алгоритм выполнения ws-операции

Подключение к web-сервису.
Проверка превышения лимита по количеству вызовов этого вида операции в текущее время суток.
Преобразование входных параметров в ссылочные типы ЛК.
Проверка правильности введенных параметров и их согласованности.
Проверка допустимости значений согласно уровню доступа к данной информации.
Выполнение операции согласно вызванной функции. Вывод результата для данного объекта.В качестве результата выполнения ws-операции может быть возвращена ошибка. При обнаружении первой же ошибки, операция завершает выполнение, возвращая в качестве результата код ошибки и её описание.
Возвращаемое значение операции:
- ResultCode - <Строка> Содержит код результата исполнения. При успешном исполнении значение поля = «SUCCESS». Возможные коды результата приведены на странице Коды ошибок.
- ResultData - <Структура>
  - Если ResultCode < > "SUCCESS", то содержит дополнительное описание ошибки: поле, которое не удовлетворяет условиям, или прочие сведения.
  - Если ResultCode = "SUCCESS", то содержит целевые данные, соответствующие назначению функции (см. описание конкретной ws-операции).