Просмотр исходного текста страницы Описание API (Кинт)

<noinclude>[[Категория: API (Кинт)|*]]</noinclude>
{| align="right"
| __TOC__
|}
== Введение ==
API программного продукта позволяет делать интеграции с другим ПО. Например, реализовать личный кабинет на сайте. Для этого, разработчики могут обращаться в базу как для операций обычного чтения, так и для записи.

== Требования ==
# База, к которой обращаются, должна быть [[1С8:Публикация информационной базы 1С на веб-сервере|опубликована на веб-сервере]].
## При публикации базы, должна быть выполнена активация HTTP-сервиса KintAPI.
## Проверить правильность выполнения публикации можно путём обращения к методу GetDBInfo. Пример: [https://demo.kint.ru/kus_demo/hs/KintAPI.hs/GetData?Method=GetDBInfo https://demo.kint.ru/kus_demo/hs/KintAPI.hs/GetData?Method=GetDBInfo]
# Разработчик должен иметь хотя бы минимальные представления о том, что такое HTTP-протокол и JSON-сериализация
## Что такое тело запроса, и чем оно отличается от параметров
## Unified Request Location и Unified Request Identifier не должны быть пустыми определениями
## Виды запросов (POST, GET, OPTIONS) и чем они отличаются
## [https://developer.mozilla.org/ru/docs/Web/HTTP/%D0%90%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F Базовая авторизация] (если публикация выполнена без предопределения аутентификационных данных)

== Вызов методов ==
Для вызова любого доступного метода, необходимо составить запрос к нему.

До версии 21.07, единственным способом вызвать какую-либо функцию, была передача названия в предопределенном параметре '''<code>Method</code>''' на URI '''<code>/pub/hs/KintAPI.hs/GetData</code>''' или '''<code>/pub/hs/KintAPI.hs/PostData</code>''', в зависимости от типа запроса.

Начиная с релиза 21.07, имя вызываемого метода стало частью URI, и вместо '''<code>GetData</code>''' / '''<code>PostData</code>''', стало возможным прописывать имя метода (например, '''<code>/pub/hs/KintAPI.hs/GetDBInfo</code>'''). Старый способ вызова методов сохранился для поддержания совместимости с уже реализованными интеграциями.

Помните, что для веб-сервера регистр букв важен, и запрос вида <code>/pub/hs/kintapi.hs/getdbinfo</code> гарантированно приведёт к ошибке 404.

== Предопределенные параметры запроса ==
На поведение сериализатора и API можно влиять путём передачи специальных параметров. Имена параметров можно передавать как на русском, так и на английском языке.
{| class="wikitable"
  !|Имя параметра на русском
  !|Имя параметра на английском
  !|Описание
  !|Пример значения
  !|Значение по-умолчанию

  |-

  |<code>Реквизиты</code>
  |<code>Fields</code>
  |Задаёт перечень реквизитов, которые должны быть переданы вместе с ссылками на элементы. Поддерживается получение нестандартных реквизитов: ПредставлениеОбъекта, Идентификатор, GUID.
  |<code>Ссылка,Контрагент,КонтактноеЛицо,Договор</code>
  |''Не задано''

  |-

  |<code>ДополнительныеСвойства</code>
  |<code>AdditionalProperties</code>
  |Перечень свойств, которые должны быть добавлены в тело ответа. Ключ под свойство добавляется даже в случае отсутствия какого-либо значения.
  |<code>Телефон,ЭлектроннаяПочта</code>
  |''Не задано''

  |- 

  |<code>ПреобразоватьКлючи</code>
  |<code>ConvertKeys</code>
  |Указывает, необходимо ли переводить ключи с русского на английский (если в встроенном словаре имеется сопоставление).
  |<code>true</code>
  |Включено

  |-

  | -
  |<code>test</code>
  |Предназначено более для тестов сериализации. API не будет вызывать метод, и просто вернёт JSON так, как она его получила и "пропарсила" из POST-запроса.
  |Значение не требуется, достаточно просто передать параметр
  |Не используется

  |-

  | -
  |<code>raw</code>
  |Возвращает ответ (если представляется возможным) сырым телом, без какой-либо сериализации. Не должно использоваться в нормальных ситуациях.
  |Значение не требуется, достаточно просто передать параметр
  |Не используется
|}

== Формат ответа ==
API возвращает ответы всегда в формате JSON, даже если запрашивается иной через заголовок <code>Accept</code>. В качестве <code>Content-Type</code> задано значение <code>application/json;charset=utf-8</code>.

Структура ответа содержит два поля:
* '''Success''' - флаг успешности выполнения, присутствует всегда
* '''Result''' - результат выполнения

В зависимости от '''Success''' и вызываемого метода, результат может быть разным. Для случаев, когда вызов завершился ошибкой, структура гарантированно следующая:
* '''Error''' - описание ошибки
* '''КодОшибки''' - код ошибки

<syntaxhighlight lang="json">
{
    "Success": false,
    "Result": {
        "Error": "Метод конфигурации «ИмяМетода» не найден!",
        "КодОшибки": 1000
    }
}
</syntaxhighlight>

=== Коды ошибок ===
Есть небольшой набор предопределенных кодов ошибок, которые могут быть вызваны по тем или иным причинам в любом продукте.
{| class=wikitable
!Код ошибки (ErrorCode)
!Описание
|-
|1000|| Передано некорректное или не существующее имя метода
|-
|1001|| Переданы некорректные параметры запроса
|-
|1002|| Передан некорректный текст POST запроса
|-
|1010|| Внутренняя ошибка конфигурации, при возникновении ошибки напишите об этом на spp@kint.ru
|-
|1032|| При отмене заявки оказалось что она уже отменена, необходимо со стороны сайта написать обработчик такой ситуации
|-
|1100|| Не передан параметр с видом справочника
|-
|1101|| Переданный вид справочника отсутствует в конфигурации
|-
|1102|| Элемент справочника не найден по полям поиска
|-
|1103|| По полям поиска найдено несколько подходящих элементов
|-
|1104|| Ошибка записи элемента справочника, возможно переданы не все обязательные реквизиты
|}

== Запрос ==
Передача параметров методу зависит от самого метода, но есть некоторые принятые стандарты в их отношении.
* Если параметр требует передачу любого ссылочного объекта - передаётся JSON-структура с одним из ключевых полей: '''ID''' или '''GUID'''.
** '''ID''' - навигационная ссылка на объект в базе 1С: Предприятия: <code>e1cib/data/Справочник.НоменклатураПомещений?ref=b4585404a66e4a8911e8bb0449fde0fc</code>
** '''GUID''' - уникальный идентификатор ссылки: <code>49fde0fc-bb04-11e8-b458-5404a66e4a89</code>
** '''Важное замечание''': Поиск по '''ID''' работает быстрее поиска по '''GUID''', потому приоритет остаётся за ним при передаче двух полей одновременно.
* Для предопределенных значений и элементов перечислений доступен поиск по имени предопределенного элемента, например <code>Перечисление.яъПол.Мужской</code>.
* Файлы приложений должны быть закодированы в формат base64 и переданы внутри тела JSON-объекта, в ключе '''<code>File</code>'''.

== Авторизация ==
Для подключения к базе-источнику требуется передать имя и пароль пользователя базы данных: пользователь должен быть добавлен в список пользователей информационной базы. '''Это ограничение, накладываемое платформой 1С: Предприятие'''. Передача данных передаётся с помощью стандартного механизма HTTP-аутентификации, подробнее о нём прочитать можно [https://developer.mozilla.org/ru/docs/Web/HTTP/Authentication здесь].

Если произвести авторизацию не представляется возможным, можно произвести публикацию базы с беcпарольной аутентификацией (когда пользователь и его пароль прописаны на веб-сервере в '''<code>default.vrd</code>'''), но имейте в виду, что в таком случае любой, у кого будет ссылка на неё, сможет заходить в базу через режим 1С: Предприятие, если соответствующие права у пользователя имеются.

== Пагинация ==
Доступно получение не всего результата запроса, а частями по страницам с сохранением порядка записей.
Для получения количества записей можно воспользоваться методом [[#КоличествоЭлементов|КоличествоЭлементов]].

{| class="wikitable"
  !|Имя параметра на русском
  !|Имя параметра на английском
  !|Описание
  !|Пример значения
  !|Значение по умолчанию

  |-

  |<code>КоличествоЭлементов</code>
  |<code>CountOnPage</code>
  |Количество элементов в результате запроса.
  |<code>100</code>
  |<code>0</code>

  |-

  |<code>НомерСтраницы</code>
  |<code>PageNumber</code>
  |Номер требуемой части результата запроса.
  |<code>10</code>
  |<code>1</code>
|}

Методы с поддержкой пагинации:
* [[#GetCatalog (СписокЭлементов)|GetCatalog (СписокЭлементов)]]. Пагинация доступна только для объектов, у которых есть свойство «Ссылка».
* [[#ПолучитьИзмененияПоУзлу|ПолучитьИзмененияПоУзлу]].
* [[#GetAvailableRooms|GetAvailableRooms]].

; Пример вызова:
 <pre>/hs/KintAPI.hs/GetData?Method=GetCatalog&CatalogName=яъФизическиеЛица&PageNumber=6&CountOnPage=10 </pre>