Сервис

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

С помощью этого сервиса вы можете:

• Искать, читать, создавать, изменять и удалять данные в 1С (например, справочники, документы).
• Использовать стандартизированный способ общения, называемый API (Application Programming Interface – программный интерфейс приложения).

Ключевые характеристики

• OpenAPI v3: Описание всех возможностей сервиса (его API) представлено в формате OpenAPI v3. Это как подробная инструкция или карта, которая показывает, какие команды можно отправлять Сервису и какие ответы ожидать.

  • Вы можете найти эту спецификацию по адресу: [Адрес вашего сервиса]/spec.json.

• Интерфейс просмотра спецификации: Есть удобный веб-интерфейс для просмотра этой спецификации, созданный с помощью RapiDoc.

  • Адрес интерфейса: [Адрес вашего сервиса]/spec-ui.

  

• RESTful архитектура: Взаимодействие с Сервисом построено на принципах REST (Representational State Transfer). Это популярный архитектурный стиль для создания веб-сервисов. Если упрощенно, вы отправляете запросы на определенные адреса (URL), используя стандартные методы (GET, POST, PUT, DELETE), и получаете ответы.

• JSON формат: Все данные, которыми вы обмениваетесь с Сервисом, передаются в формате JSON (JavaScript Object Notation). Это легковесный текстовый формат, который понятен и людям, и компьютерам.

Манипуляции данными информационной базы 1С

Поддерживаемые объекты метаданных:

Имя	Получение списка	Получение объекта	Создание	Удаление	Изменение	Порядок поиска по реквизитам
Справочники	✅	✅	✅	✅	✅	Ссылка, ИмяПредопределенного, Код, Наименование
Документы	✅	✅	✅	✅	✅	Ссылка, Номер
Перечисления	✅	✅	❌	❌	❌	ИмяПредопределенного
ПланыВидовХарактеристик	✅	✅	✅	✅	✅	Ссылка, ИмяПредопределенного, Код, Наименование
ПланыСчетов	✅	✅	✅	✅	✅	Ссылка, ИмяПредопределенного, Код, Наименование
ПланыВидовРасчета	✅	✅	✅	✅	✅	Ссылка, ИмяПредопределенного, Код, Наименование
ПланОбмена	✅	✅	✅	✅	✅	Ссылка, ИмяПредопределенного, Код, Наименование
РегистрыСведений (независимые)	✅	✅	✅	✅	✅
РегистрыСведений (подч. регистратору)	✅	✅	❌	❌	❌
РегистрыНакопления	✅	✅	❌	❌	❌
РегистрыБухгалтерии	✅	✅	❌	❌	❌
РегистрыРасчета	✅	✅	❌	❌	❌
БизнесПроцессы	✅	✅	✅	✅	✅	Ссылка, Номер
Задачи	✅	✅	✅	✅	✅	Ссылка, Номер

Дополнительные возможности

• Работа с регламентными заданиями
  • Получение списка
  • Мониторинг состояния
  • Запуск, остановка перезапуск
• Работа с движениями документов
  • Получение списка движений, как по одному регистру, так и по всем
  • Изменение движений

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

Манипуляции данными

• Получение списка объектов. Используется для чтения (запроса) списка данных. Например, получить список всех пользователей.

  GET /:ТипМетаданных/:ВидМетаданных{?query_parameters}

  query_parameters - на данный момент не используются в этом простом варианте запроса.
• Расширенный поиск данных. Используется для поиска объектов с возможностью указания фильтров, сортировки и выбора нужных полей. Это более гибкий способ получения данных, чем простой GET.

  POST /:ТипМетаданных/:ВидМетаданных/Поиск

• Создание нового объекта. Используется для добавления новой записи в систему. Например, создать новый документ.

  POST /:ТипМетаданных/:ВидМетаданных/

• Получение конкретного объекта по его идентификатору. Используется для чтения одного объекта, если вы знаете его уникальный идентификатор. Например, получить данные конкретного пользователя.

  GET /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта

• Изменение существующего объекта. Используется для обновления данных объекта, который уже есть в системе.

  PUT /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта

• Удаление объекта. Используется для удаления объекта из системы.

  DELETE /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта

Движения документов

• Получение всех движений документа. Используется для получения всех движений документа по всем регистрам.

  GET /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта/Движения

• Получение движений документа по регистру. Используется для получения движений документа по конкретному регистру.

  GET /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта/Движения/:ИмяРегистра

• Изменение движений документа по регистру. Используется для изменения движений документа по конкретному регистру.

  POST /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта/Движения/:ИмяРегистра

Описание параметров шаблонов

Параметр	Описание	Значения
ТипМетаданных	Имя типа метаданных	Это категория объекта в системе 1С, например: Справочник, Документ, РегистрСведений. Посмотреть все возможные типы можно в конфигураторе 1С или в таблице выше.
ВидМетаданных	Имя вида метаданных	Это конкретное имя объекта внутри его типа, как оно задано в конфигураторе 1С (не путайте с представлением для пользователя!). Например, для справочника пользователей это может быть Пользователи, для документа реализация - РеализацияТоваровУслуг.
ИдентификаторОбъекта	Идентификатор объекта информационной базы	Это уникальный код, который позволяет точно определить нужный объект. Способы указания идентификатора зависят от типа объекта (см. выше) и подробно описаны в разделе форматы данных. Для ссылочных объектов (Справочники, Документы и т.д.) - обычно это уникальный идентификатор ссылки (UID) в виде длинной строки символов, или другие поля (Код, Номер). Для перечислений - имя значения (например, Приход, Расход). Для независимых регистров сведений - это комбинация значений его измерений и периода (если регистр периодический), разделенных точкой с запятой (;).
ИмяРегистра	Имя регистра, в который пишет документ	Имя регистра, как оно задано в конфигураторе 1С. Например, ТоварыНаСкладах, Продажи.

Регламентные задания

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

  GET /РегламентныеЗадания{?query_parameters}

  Возможные параметры отбора:

  • УникальныйИдентификатор
  • Ключ
  • Метаданные
  • Предопределенное
  • Использование
  • Наименование

• Получение информации о регламентном задании. Используется для получения детальной информации о конкретном регламентном задании по его идентификатору.

  GET /РегламентныеЗадания/:ИдентификаторЗадания

• Запуск регламентного задания. Используется для запуска регламентного задания без проверки текущей активности.

  POST /РегламентныеЗадания/:ИдентификаторЗадания/Запустить

• Остановка регламентного задания. Используется для остановки выполнения регламентного задания.

  POST /РегламентныеЗадания/:ИдентификаторЗадания/Остановить

• Перезапуск регламентного задания. Используется для перезапуска регламентного задания (остановка и запуск).

  POST /РегламентныеЗадания/:ИдентификаторЗадания/Перезапустить

Описание параметров шаблонов

Параметр	Описание	Значения
ИдентификаторЗадания	Идентификатор регламентного задания	Доступные варианты указания идентификатора рассмотрены на отдельной странице

Особенности работы сервиса

Получение списка объектов

Для получения данных из таблиц реализовано два способа

• Простое получение списка. Возвращает список первых 100 элементов таблицы. Рекомендуется использовать второй вариант.

  GET /:ТипМетаданных/:ВидМетаданных

• Расширенный поиск данных. Предоставляет возможности поиска, фильтрации, сортировки данных.

  POST /:ТипМетаданных/:ВидМетаданных/Поиск

  На вход метод принимает структуру параметров

  Имя параметра	Тип	Значение по умолчанию	Описание
  filter	Объект		Позволяет задать условия отбора (фильтрации) данных. Вы указываете имя поля (реквизита) и значение, которому оно должно быть равно. Пример: { "Контрагент": "a772d037-9519-4c2b-8c9b-ad9de187fe90" } (найти все записи, где поле Контрагент равно указанному значению). На текущий момент поддерживается только отбор на точное равенство.
  order	Объект		Задает порядок сортировки возвращаемых данных. Вы указываете список полей, по которым нужно сортировать, и направление сортировки (Возр - по возрастанию, Убыв - по убыванию). Пример: ["Дата Убыв", "Номер Возр"] (сортировать сначала по полю Дата в порядке убывания, а затем по полю Номер в порядке возрастания). По умолчанию сортировка идет по возрастанию (Возр).
  fields	Массив	"Ссылка" или ключевые поля регистра	Позволяет указать, какие именно поля (реквизиты) объекта вы хотите получить в ответе. Это полезно, если вам не нужна вся информация об объекте. Пример: ["Наименование", "Цена", "Количество"]. Если нужны все поля, укажите ["*"].
  limit	Число	10	Ограничивает количество записей, которые вернет запрос. Пример: 1 (вернуть только одну запись). Максимальное значение – 100.

Примеры

1. Последнмй документ по контрагенту:

   POST {baseUrl}/Документ/ПКО/Поиск
   Content-Type: application/json
   {
     "filter": { "Контрагент": "a772d037-9519-4c2b-8c9b-ad9de187fe90"},
     "fields": ["*"],
     "order": ["Дата Убыв"],
     "limit": 1
   }

2. Записи регистра сведений "Информация об ошибках" по роботу:

   POST {baseUrl}/РегистрыСведений/ИнформацияОбОшибках/Поиск
   Content-Type: application/json
   {
       "filter":{ "Пользователь": "ИмяРобота"},
       "fields": ["ОписаниеОшибки", "УровеньОшибки", "Категория", "Период"],
       "order": ["Период УБЫВ"]
   }

Получение объекта

Получение объекта по идентификатору. Используется для получения конкретного объекта по его уникальному идентификатору.

GET /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта

Параметры шаблона URL описаны выше. Здесь хотел бы уделить внимание полю идентификатор.

Ограничения и описание, что такое идентификатор для ссылок смотрите на странице форматы данных.

Для регистров накопления/бухгалтерии и регистров сведений, подчиненных регистратору, в качестве идентификатора выступает составное поле с реквизитами Регистратор и НомерСтроки

Для регистров сведений без регистратора идентификатором будет составное поле с реквизитами: Период (для периодических) + измерения регистра

Составное поле похоже на параметры URL, но не начинается с "?" и в качестве разделителя параметров используется ";"

Например:

GET /РегистрыСведений/АудиторскийСлед/Объект=Справочники.Товары.Носочки;Период=2020-01-01T00:00:00
GET /РегистрыНакопления/РасчетыСКлиентами/Регистратор=Документ.ПриходныйКассовыйОрдер.00000000001;НомерСтроки=1

Создание и изменение данных

Создание нового объекта. Используется для добавления новой записи в систему.

POST /:ТипМетаданных/:ВидМетаданных/

Изменение существующего объекта. Используется для обновления данных объекта, который уже есть в системе.

PUT /:ТипМетаданных/:ВидМетаданных/:ИдентификаторОбъекта

В большей части логика работы механизмов одинакова, за исключением:

1. Для изменения нужно указать идентификатор существующего объекта
2. При изменении нужно указывать только изменяемые реквизиты, при изменении табличной части объекта ее нужно передавать целиком

Структура тела запроса

Ключ	Обязательный	Тип	Описание
data	Да (только для создания нового объекта)	Объект/Массив	Содержит данные объекта, который вы хотите создать или изменить. Поля этого объекта должны совпадать с полями (реквизитами) объекта в 1С. Если вы изменяете существующий объект, здесь нужно передавать только те поля, которые вы хотите поменять. При работе с регистром (например, изменение его записей) сюда можно передать массив объектов (несколько записей для набора).
writeSettings	Нет (необязательный)	Объект	Позволяет указать специальные настройки для процесса записи объекта в 1С. См. подробное описание ниже.
additionalProperties	Нет (необязательный)	Объект	Позволяет передать дополнительные свойства для объекта, которые будут записаны в специальное хранилище Объект.ДополнительныеСвойства в 1С. Это может быть полезно для хранения какой-то служебной информации, не предусмотренной стандартной структурой объекта.
additionalParameters	Нет (необязательный)	Объект	Позволяет передать дополнительные параметры, которые могут быть использованы специальными доработками (алгоритмами расширения) в вашей системе 1С в момент записи объекта.

Реквизит data

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

Примеры:

{
    "data": {
        "Объект": "CatalogRef.Пользователи.a772d037-9519-4c2b-8c9b-ad9de187fe90",
        "Период": "2021-01-01T00:00:00",
        "Пользователь": "Справочник.Пользователи.ИмяПользователя"
    }
}

{
    "data": [
        {
            "Объект": "CatalogRef.Пользователи.a772d037-9519-4c2b-8c9b-ad9de187fe90",
            "Период": "2021-01-01T00:00:00",
            "Пользователь": "Справочник.Пользователи.ИмяПользователя1"
        },
        {
            "Объект": "CatalogRef.Пользователи.a772d037-9519-4c2b-8c9b-ad9de187fe90",
            "Период": "2021-01-01T01:00:00",
            "Пользователь": "Справочник.Пользователи.ИмяПользователя2"
        }
    ]
}

Если для документа, бизнес-процесса или задачи не указать номер или дату, они будут установлены автоматически

Реквизит writeSettings

Этот реквизит позволяет тонко настроить, как именно объект будет записан в базу данных 1С. Это может быть полезно в специфических ситуациях.

Реквизит	Тип	Значение по умолчанию	Описание
dataExchangeParametersLoad	Булево (true/false)	false	Отключить стандартные обработки при записи. Если установлено в true, то при записи объекта будут отключены некоторые стандартные проверки, регистрации для обмена данными и другие автоматические действия. Когда использовать: Может быть полезно при массовой загрузке данных, когда стандартные обработки не нужны или замедляют процесс. Используйте с осторожностью.
writeMode	Строка (Write, Posting, UndoPosting)	Write	Режим записи документа. Актуально только для объектов типа "Документ". Позволяет не просто записать документ (Write), но и провести его (Posting – т.е. зафиксировать все его влияния на учет) или отменить его проведение (UndoPosting). Если этот параметр не указан, то при изменении уже проведенного документа он будет автоматически перепроведен.
postingMode	Строка (Regular, RealTime)	Зависит от настроек документа в конфигурации	Режим проведения документа. Актуально только для документов и используется вместе с writeMode: Posting. Определяет, как проводить документ: оперативно (RealTime – сразу же, с контролем остатков и т.п.) или неоперативно (Regular – отложено, без строгого контроля в момент проведения). Когда использовать: Используется редко, в основном для специфических сценариев управленческого или бухгалтерского учета.
replace	Булево (true/false)	true	Замещать существующие записи в регистре. Актуально только для регистров. Если true (по умолчанию), то при записи данных в регистр система сначала ищет записи с такими же ключевыми полями и, если находит, заменяет их новыми данными. Если false, то система пытается просто добавить новые записи; если при этом найдутся существующие записи с такими же ключами, возникнет ошибка. Когда использовать: false может быть полезно, если вы точно уверены, что добавляете уникальные записи и хотите избежать случайной перезаписи существующих.

POST {baseUrl}/Документ/Документ1
Content-Type: application/json
{
    "data": {
        "Объект": "CatalogRef.Пользователи.a772d037-9519-4c2b-8c9b-ad9de187fe90",
        "Период": "2021-01-01T00:00:00",
        "Пользователь": "Справочник.Пользователи.ИмяПользователя"
    },
    "writeSettings":{
        "writeMode": "Posting"
    }
}
// Создать и провести документ

PUT {baseUrl}/Документ/Документ1/00000001
Content-Type: application/json
{
    "writeSettings":{
        "writeMode": "UndoPosting"
    }
}
// Отменить проведение документа

Реквизит additionalProperties

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

Реквизит additionalParameters

Позволяет повлиять на существующую логику работы расширения (сервиса). При адаптации логики сервиса под конкретную конфигурацию можно использовать этот объект для управления логикой "адаптации".