OData — запросы к данным 1С через MCP fetch

Описание

Скилл для получения данных из 1С:Предприятие через стандартный REST OData-интерфейс. 1С реализует OData версии 3.0 (протокол odata/standard.odata). Работает с любой конфигурацией 1С, где опубликована база через веб-сервер.

Подготовка запроса через conf-doc

Если подключён MCP 1c-conf-doc, перед построением OData-запроса уточни структуру метаданных:

1. conf_doc_search(query="...") — найти объект по смыслу запроса пользователя
2. conf_doc_get_object + conf_doc_get_object_chunk — прочитать реквизиты и типы полей
3. Сопоставить тип с OData-префиксом (Document → Document_, Catalog → Catalog_, …)
4. Выполнить fetch с корректным entity, $filter, $select

Подробнее — skills/conf-doc/SKILL.md.

Пример: вопрос «отпуска сотрудника Иванова за май»:

• conf-doc: Document.Отпуск, реквизиты Сотрудник, ДатаНачала, ДатаОкончания
• OData: Document_Отпуск?$filter=...&$select=...

MCP-инструмент fetch

Для запросов к 1С OData используется MCP-инструмент fetch (пакет @modelcontextprotocol/server-fetch).

Все запросы выполняются через вызов:

fetch(
  url="полный_URL_запроса",
  method="GET",
  headers={
    "Authorization": "Basic <base64>",
    "Accept": "application/json"
  }
)

Настройка credentials

Credentials хранятся в файле env.json (вне репозитория, в .gitignore):

{
  "default": {
    "odata_url": "http://localhost/your_base/odata/standard.odata",
    "odata_user": "Администратор",
    "odata_password": "пароль"
  }
}

Подготовка авторизации

Заголовок Authorization формируется один раз — Base64-кодировка строки логин:пароль:

"Authorization": "Basic " + Base64Encode(odata_user + ":" + odata_password)

Важно: Используйте только заголовок Authorization: Basic. Кодировка кириллических паролей корректно работает через Base64 в UTF-8.

Базовый URL

Базовый URL берётся из env.json → odata_url, например: http://localhost/your_base/odata/standard.odata

Все пути ресурсов добавляются после него через /.

Проверить доступные сущности

fetch(
  url="http://localhost/your_base/odata/standard.odata/",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Типы объектов 1С в OData

Каждый тип объекта 1С имеет свой префикс в URL-имени ресурса:

Суффиксы ресурсов регистров

Регистры имеют несколько вариантов ресурса в зависимости от типа выборки:

Регистры сведений

Регистры накопления / расчёта / бухгалтерии

Табличные части

Табличные части объектов доступны как отдельные ресурсы. Имя ресурса: ИмяРесурсаОбъекта_ИмяТабличнойЧасти.

Например, табличная часть Адреса справочника Сотрудники: Catalog_Сотрудники_Адреса

Стандартные поля табличной части:

• LineNumber — номер строки
• реквизиты табличной части
• _Key / _Type суффиксы для ссылочных и составных полей

Стандартные поля OData по типам объектов

Справочники

Документы

Регистры сведений (записи)

Для регистров сведений (срез последних) доступны: Period, измерения и ресурсы.

Табличные части

Суффиксы полей

1С добавляет специальные суффиксы к именам реквизитов в OData:

Используйте _Key для фильтрации по ссылке, _Type — для определения типа в составных полях.

Параметры OData-запросов

Операторы фильтрации

Операторы сравнения

Строковые функции

Важно: 1С использует OData v3. Синтаксис substringof отличается от OData v4:

• v3: substringof('значение', Поле) eq true
• v4: contains(Поле, 'значение') — не работает в 1С!

Логические операторы

Формат значений в фильтрах

URL-кодирование кириллических имён

Имена объектов 1С (на русском) нужно URL-кодировать перед подстановкой в URL. Используйте функцию encodeURIComponent() — это стандарт URL-кодировки UTF-8.

Примеры закодированных имён:

Примеры запросов через fetch

Запросить данные справочника

fetch(
  url="http://localhost/your_base/odata/standard.odata/Catalog_%D0%A1%D0%BE%D1%82%D1%80%D1%83%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8?$top=10&$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Запросить данные документа

fetch(
  url="http://localhost/your_base/odata/standard.odata/Document_%D0%9E%D1%82%D0%BF%D1%83%D1%81%D0%BA?$top=5&$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Получить конкретную запись по GUID

fetch(
  url="http://localhost/your_base/odata/standard.odata/Catalog_%D0%A1%D0%BE%D1%82%D1%80%D1%83%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8(guid'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee')?$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Подсчитать количество записей ($count)

fetch(
  url="http://localhost/your_base/odata/standard.odata/Catalog_%D0%A1%D0%BE%D1%82%D1%80%D1%83%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8/$count",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Выбрать конкретные поля ($select)

fetch(
  url="http://localhost/your_base/odata/standard.odata/Catalog_%D0%A1%D0%BE%D1%82%D1%80%D1%83%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8?$select=Ref_Key,Description,Code&$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Раскрыть связанный объект ($expand)

fetch(
  url="http://localhost/your_base/odata/standard.odata/Document_%D0%9E%D1%82%D0%BF%D1%83%D1%81%D0%BA?$expand=Организация&$top=5&$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Фильтрация по дате

fetch(
  url="http://localhost/your_base/odata/standard.odata/Document_%D0%9E%D1%82%D0%BF%D1%83%D1%81%D0%BA?$filter=Date ge datetime'2024-01-01T00:00:00' and Date le datetime'2024-12-31T23:59:59'&$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Фильтрация по наименованию (OData v3 синтаксис!)

fetch(
  url="http://localhost/your_base/odata/standard.odata/Catalog_%D0%A1%D0%BE%D1%82%D1%80%D1%83%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8?$filter=substringof('Иванов', Description) eq true&$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Записи регистра сведений

fetch(
  url="http://localhost/your_base/odata/standard.odata/InformationRegister_%D0%A6%D0%B5%D0%BD%D1%8B_RecordType?$top=10&$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Срез последних регистра сведений

fetch(
  url="http://localhost/your_base/odata/standard.odata/InformationRegister_%D0%A6%D0%B5%D0%BD%D1%8B_%D0%A1%D1%80%D0%B5%D0%B7%D0%9F%D0%BE%D1%81%D0%BB%D0%B5%D0%B4%D0%BD%D0%B8%D1%85?$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Запрос константы

fetch(
  url="http://localhost/your_base/odata/standard.odata/Constant_%D0%90%D0%B4%D1%80%D0%B5%D1%81%D0%9F%D1%83%D0%B1%D0%BB%D0%B8%D0%BA%D0%B0%D1%86%D0%B8%D0%B8/$value",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Запрос перечисления

fetch(
  url="http://localhost/your_base/odata/standard.odata/Enum_%D0%9F%D0%BE%D0%BB%D0%A4%D0%B8%D0%B7%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%BE%D0%B3%D0%BE%D0%9B%D0%B8%D1%86%D0%B0?$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

Запрос табличной части

fetch(
  url="http://localhost/your_base/odata/standard.odata/Catalog_%D0%A1%D0%BE%D1%82%D1%80%D1%83%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8_%D0%90%D0%B4%D1%80%D0%B5%D1%81%D0%B0?$format=json",
  method="GET",
  headers={"Authorization": "Basic <base64>", "Accept": "application/json"}
)

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

{
  "odata.metadata": "...",
  "value": [
    {
      "Ref_Key": "uuid",
      "DataVersion": "...",
      "DeletionMark": false,
      "Code": "000000001",
      "Description": "Название элемента",
      "Предопределенный": false
    }
  ]
}

Включить объект в OData

Если объект не появляется в списке сущностей, он не опубликован. Выполните в 1С (режим Сервер / Внешнее соединение / Интеграция):

МассивОбъектов = Новый Массив();
МассивОбъектов.Добавить(Метаданные.Справочники.ИмяСправочника);
УстановитьСоставСтандартногоИнтерфейсаOData(МассивОбъектов);

Типичные ошибки

401 Unauthorized / 401.5

Неверная кодировка credentials. Убедитесь, что используете заголовок Authorization: Basic с корректной Base64-кодировкой строки логин:пароль в UTF-8.

Объект не найден в списке сущностей

Объект не опубликован через OData. Выполните enable-odata.bsl или используйте обработку EnableODataInterface.epf.

contains не работает

1С использует OData v3, где вместо contains(Поле, 'значение') нужно использовать substringof('значение', Поле) eq true.

MCP-инструменты analytics (1c-odata-mcp)

Помимо fetch, сервер mcp_servers/odata_server.py предоставляет:

fetch_table

Загрузить таблицу из одной сущности в CSV или JSON:

fetch_table(
  entity="Catalog_Контрагенты",
  filter="DeletionMark eq false",
  select="Description,Code,ИНН",
  top=200,
  format="csv"
)

analyze_data

Multi-query analytics с join в pandas и опциональным графиком:

analyze_data(
  queries=[
    {"alias": "sales", "entity": "Document_Реализация", "filter": "...", "select": "...", "top": 200}
  ],
  aggregate={"group_by": ["Контрагент"], "agg": {"СуммаДокумента": "sum"}},
  chart={"type": "bar", "x": "Контрагент", "y": "СуммаДокумента", "title": "Продажи"},
  explanation="..."
)

Ответ JSON: rows, columns, csv_preview, chart_png_base64, chart_html.