Описание API (Кинт) - История изменений

Григорий Дударев: /* Коды ошибок */

2025-09-25T08:10:48Z

‎Коды ошибок

Дмитрий Малюгин: /* Требования */

2024-11-28T13:00:32Z

‎Требования

Дмитрий Малюгин в 15:19, 21 ноября 2024

2024-11-21T15:19:42Z

Дмитрий Малюгин в 15:12, 21 ноября 2024

2024-11-21T15:12:33Z

Дмитрий Малюгин в 15:05, 21 ноября 2024

2024-11-21T15:05:43Z

Дмитрий Малюгин: Новая страница: «Категория: API (Кинт) == Введение == API программного продукта позволяет делать интеграции…»

2024-11-21T15:04:21Z

Новая страница: «Категория: API (Кинт) == Введение == API программного продукта позволяет делать интеграции…»

Новая страница

[[Категория: API (Кинт)]]
== Введение ==
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>

@@ Строка 1: / Строка 1: @@
-<noinclude>[[Категория: API (Кинт)|*]]</noinclude>
+<noinclude>[[Категория: API (Кинт)|A]]</noinclude>
 {| align="right"
 | __TOC__

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

@@ Строка 111: / Строка 111: @@
 |-
 |1032|| При отмене заявки оказалось что она уже отменена, необходимо со стороны сайта написать обработчик такой ситуации
 |-
 |1100|| Не передан параметр с видом справочника

@@ Строка 10: / Строка 10: @@
 ## При публикации базы, должна быть выполнена активация 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-сериализация
+# Разработчик должен иметь базовые знания о том, что такое HTTP-протокол и JSON-сериализация
 ## Что такое тело запроса, и чем оно отличается от параметров
 ## Unified Request Location и Unified Request Identifier не должны быть пустыми определениями