📘 Пользовательская документация по API (1С)

Что это такое

API — это единая точка доступа к данным и методам 1С. Оно позволяет:

• получать списки объектов (например, справочники или документы);
• искать и фильтровать данные;
• добавлять, изменять и удалять записи;
• интегрироваться с внешними системами или фронтендом (React, веб-клиенты);
• автоматически генерировать документацию (Swagger / OpenAPI).

---

Подключение к API

Базовый адрес (пример):

http://<HOST>/<BASE_PATH>/hs/api/v2/

Замените <HOST> и <BASE_PATH> на параметры вашего сервера.

Авторизация

Используется HTTP Basic Auth:

• Заголовок: Authorization: Basic <TOKEN>
• <TOKEN> = Base64 от строки логин:пароль

⚠️ Рекомендуется всегда использовать HTTPS.

Пример:

curl -G 'http://localhost/hs/api/v2/echo?text=Привет'   -H 'Authorization: Basic dXNlcjpwYXNzd29yZA=='

---

Формат обмена

• Формат: JSON
• Кодировка: UTF-8
• Возможна компрессия ответов (gzip)

---

Глобальные параметры

Эти параметры можно добавлять почти к каждому запросу:

Параметр	Описание
conditions	фильтрация (SQL-подобный синтаксис)
order	поле сортировки (по умолчанию time_moment)
sort_direction	направление сортировки: asc / desc
object_start	с какого объекта начать (нумерация с 1)
object_end	по какой объект включительно вернуть
get_view_references	вернуть «читаемые» представления ссылок
fields	список полей, которые нужно вернуть (остальные игнорируются)

---

Быстрые примеры

1) Простое эхо-сообщение

Запрос

curl -G 'http://localhost/hs/api/v2/echo'   -H 'Authorization: Basic <TOKEN>'   --data-urlencode 'text=Привет'

Ответ

"Привет"

---

2) Получение списка тегов с пагинацией и сортировкой

Запрос

curl -G 'http://localhost/uit/hs/api/v2/tags'   -H 'Authorization: Basic <TOKEN>'   --data-urlencode 'order=time_moment'   --data-urlencode 'sort_direction=desc'   --data-urlencode 'object_start=1'   --data-urlencode 'object_end=13'

Ответ (пример)

{
  "object_start": 1,
  "object_end": 13,
  "objects": [
    {
      "time_moment": 63860867118442,
      "ref": "ref-tags-92a2881f-ba51-11e7-8306-20cf306b6976",
      "code": null,
      "name": "Витая пара",
      "delete_mark": false,
      "representation": "Витая пара",
      "color_background": "#E00A2A",
      "color_text": "#FFFFFF"
    },
    {
      "time_moment": 63860867118447,
      "ref": "ref-tags-92a28820-ba51-11e7-8306-20cf306b6976",
      "code": null,
      "name": "зарплата",
      "delete_mark": false,
      "representation": "зарплата",
      "color_background": "#6FF241",
      "color_text": "#000000"
    },
    {
      "time_moment": 63860867118452,
      "ref": "ref-tags-92a28821-ba51-11e7-8306-20cf306b6976",
      "code": null,
      "name": "ЗУП",
      "delete_mark": false,
      "representation": "ЗУП",
      "color_background": "#704647",
      "color_text": "#FFFFFF"
    }
    // ...и так далее
  ]
}

---

Conditions (фильтрация)

conditions — это параметр для фильтрации данных при выполнении запросов к API.
Синтаксис близок к SQL WHERE.

Формат

• Передаётся в query-параметрах URL.
• Строка условий, возможны несколько условий через AND / OR.
• Поддерживаются скобки для приоритета.

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

• Сравнения: =, <>, >, <, >=, <=, LIKE
• Логические операторы: AND, OR
• Группировка: ( ... )
• Типы значений: строки "...", числа, булево true/false, ссылки ref-*

Готовые примеры

Пример conditions	Описание
status = "active"	Вернуть только записи со статусом «active»
amount > 1000	Вернуть записи, где amount > 1000
delete_mark = false	Исключить объекты с пометкой удаления
name LIKE "Test%"	Название начинается с «Test»
project = "ref-projects-123"	Объекты из указанного проекта

Рабочие кейсы

1. По проекту и пометке удаления

"conditions": "space = \"ref-projects-da99eac1-7641-4e6a-873e-aa714592ea6f\" AND delete_mark = false"

2. Сообщения конкретного чата

"conditions": "context = \"ref-assistant_context-90a88daa-511d-44aa-b43f-3a93391532ce\""

При некорректном синтаксисе возвращается ошибка (обычно 500).

---

Пагинация

Параметры

• object_start — первый возвращаемый объект (нумерация с 1);
• object_end — последний возвращаемый объект (включительно).

Поведение

• Если заданы оба параметра — возвращается срез [object_start…object_end].
• Работает совместно с conditions и order.

Формат конверта ответа

{
  "object_start": 1,
  "object_end": 3,
  "objects": [ /* элементы */ ]
}

Ошибки

• Отрицательные значения, object_start > object_end — ошибка (обычно 400; при внутренних ошибках — 500).

Рекомендации

• Для «бесконечного скролла»: фиксируйте сортировку и шаг, напр. 1–50, затем 51–100.
• На больших выборках используйте сжатие (gzip).

---

Сортировка

Параметры

• order — имя поля сортировки. По умолчанию — time_moment (если не переопределено методом).
• sort_direction — asc | desc.

Советы

• Для стабильной пагинации указывайте детерминирующее поле (например, time_moment + уникальный ref, если доступно).
• Явно задавайте sort_direction.

Шаблон запроса

curl -G 'http://<HOST>/<BASE_PATH>/hs/api/v2/<endpoint>'   -H 'Authorization: Basic <BASIC_TOKEN>'   --data-urlencode 'conditions=<условия>'   --data-urlencode 'order=<поле>'   --data-urlencode 'sort_direction=<asc|desc>'   --data-urlencode 'object_start=1'   --data-urlencode 'object_end=30'

---

Операции CRUD на примере справочника «Теги»

Создать тег

curl -X POST 'http://localhost/hs/api/v2/tags'   -H 'Authorization: Basic <TOKEN>'   -H 'Content-Type: application/json'   -d '{
    "Наименование": "Новый тег",
    "ЦветФона": "#FFFFFF",
    "ЦветТекста": "#000000"
  }'

Ответ (пример)

{
  "ref": "ref-tags-123456",
  "Наименование": "Новый тег",
  "ЦветФона": "#FFFFFF",
  "ЦветТекста": "#000000",
  "Представление": "Новый тег"
}

Получить список тегов (с пагинацией и сортировкой)

curl -G 'http://localhost/hs/api/v2/tags'   -H 'Authorization: Basic <TOKEN>'   --data-urlencode 'order=time_moment'   --data-urlencode 'sort_direction=desc'   --data-urlencode 'object_start=1'   --data-urlencode 'object_end=50'

Получить тег по ссылке

curl -G 'http://localhost/hs/api/v2/tags/ref-tags-123456'   -H 'Authorization: Basic <TOKEN>'

Изменить тег

curl -X PUT 'http://localhost/hs/api/v2/tags/ref-tags-123456'   -H 'Authorization: Basic <TOKEN>'   -H 'Content-Type: application/json'   -d '{
    "Наименование": "Тег обновлён",
    "ЦветФона": "#EEEEEE",
    "ЦветТекста": "#111111"
  }'

Удалить тег (пометка удаления)

curl -X DELETE 'http://localhost/hs/api/v2/tags/ref-tags-123456'   -H 'Authorization: Basic <TOKEN>'   --data-urlencode 'delete_mark=true'

---

Использование внутри 1С (без HTTP)

Можно вызывать методы API напрямую из конфигурации 1С.

Параметры = Новый Массив();
Параметры.Добавить("Привет");
Сообщить(API.ВыполнитьМетод("Эхо", Параметры)); // → Привет

---

Использование в React-фронтенде

• React работает с теми же эндпоинтами и JSON-контрактами.
• Доступны специальные неглобальные методы для работы с формами 1С (видны только из React-форм).
• Для интеграции используйте Swagger-спецификацию и генерацию клиентского кода.

---

Swagger / OpenAPI

Сгенерируйте описание API в 1С:

Результат = APIГенераторСпецификации.ПолучитьСпецификациюOpenAPI()

Откройте сайт https://editor.swagger.io и вставьте полученный JSON.

Публичная спецификация: https://softonit.ru/api/docs/uit_openapi_specification.json

После выхода УИТ4 — обновите JSON-спецификацию на сайте из свежей генерации.

---

Краткое резюме

• API принимает/возвращает JSON, авторизация — Basic Auth.
• Универсальные параметры: conditions, order, sort_direction, object_start, object_end, get_view_references, fields.
• Поддерживаются пагинация и сортировка; для больших выборок используйте gzip.
• Можно работать снаружи (curl/Postman/React) и изнутри 1С (без HTTP).
• Актуальную спецификацию держите в Swagger (OpenAPI).

---

Подсказка: запрос curl можно вставить в Postman — он автоматически разложит его по полям запроса.