Odata

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/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 ",
    "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 ", "Accept": "application/json"}
)

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

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

| Тип 1С | Префикс OData | Пример ресурса | |--------|---------------|----------------| | Справочник | Catalog_ | Catalog_Сотрудники | | Документ | Document_ | Document_Отпуск | | Журнал документов | DocumentJournal_ | DocumentJournal_ДокументыОплата | | План видов характеристик | ChartOfCharacteristicTypes_ | ChartOfCharacteristicTypes_ВидыСубконто | | План счетов | ChartOfAccounts_ | ChartOfAccounts_Основной | | План видов расчета | ChartOfCalculationTypes_ | ChartOfCalculationTypes_Начисления | | План обмена | ExchangePlan_ | ExchangePlan_ОбменСБухгалтерией | | Константа | Constant_ | Constant_АдресПубликации | | Регистр сведений | InformationRegister_ | InformationRegister_Цены | | Регистр накопления | AccumulationRegister_ | AccumulationRegister_Продажи | | Регистр расчёта | CalculationRegister_ | CalculationRegister_Начисления | | Регистр бухгалтерии | AccountingRegister_ | AccountingRegister_Хозрасчетный | | Бизнес-процесс | BusinessProcess_ | BusinessProcess_ЗаявкаНаСогласование | | Задача | Task_ | Task_ЗадачаИсполнителя | | Перечисление | Enum_ | Enum_ПолФизическогоЛица |

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

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

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

| Суффикс | Назначение | Пример | |---------|-----------|--------| | _RecordType | Записи регистра | InformationRegister_Цены_RecordType | | _СрезПоследних | Срез последних (только периодические) | InformationRegister_Цены_СрезПоследних |

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

| Суффикс | Назначение | Пример | |---------|-----------|--------| | _RecordType | Записи регистра | AccumulationRegister_Продажи_RecordType |

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

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

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

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

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

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

Справочники

| Поле OData | Описание | |------------|----------| | Ref_Key | UUID элемента (ссылка) | | DeletionMark | Пометка удаления | | Predefined | Предопределённый элемент | | IsFolder | Является ли папкой (иерархический справочник) | | Parent_Key | UUID родителя (иерархия) | | Code | Код элемента | | Description | Наименование элемента |

Документы

| Поле OData | Описание | |------------|----------| | Ref_Key | UUID документа | | DeletionMark | Пометка удаления | | Date | Дата документа | | Number | Номер документа | | Posted | Проведён |

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

| Поле OData | Описание | |------------|----------| | RecordKey | Ключ записи | | Period | Период (если регистр периодический) |

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

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

| Поле OData | Описание | |------------|----------| | LineNumber | Номер строки |

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

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

| Суффикс | Когда появляется | Описание | Пример | |---------|-------------------|----------|--------| | _Key | Реквизит ссылочного типа | UUID связанного объекта | Организация_Key | | _Type | Реквизит составного типа (несколько типов) | Тип значения | Владелец_Type |

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

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

| Параметр | Описание | Пример | |----------|----------|--------| | $top | Ограничить кол-во записей | $top=10 | | $skip | Пропустить N записей | $skip=20 | | $filter | Фильтрация | $filter=DeletionMark eq false | | $select | Выбрать конкретные поля | $select=Ref_Key,Description | | $orderby | Сортировка | $orderby=Description asc | | $expand | Раскрыть связанные объекты | $expand=Организация | | $format | Формат ответа | $format=json |

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

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

| Оператор | Описание | Пример | |----------|----------|--------| | eq | Равно | $filter=DeletionMark eq false | | ne | Не равно | $filter=Code ne '000' | | gt | Больше | $filter=Date gt datetime'2024-01-01T00:00:00' | | ge | Больше или равно | $filter=Date ge datetime'2024-01-01T00:00:00' | | lt | Меньше | $filter=Date lt datetime'2024-12-31T23:59:59' | | le | Меньше или равно | $filter=Code le '000100' |

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

| Функция | Описание | Пример | |---------|-----------|--------| | substringof | Содержит подстроку | $filter=substringof('Иванов', Description) eq true | | startswith | Начинается с | $filter=startswith(Code, '000') | | endswith | Заканчивается на | $filter=endswith(Description, 'ов') |

> Важно: 1С использует OData v3. Синтаксис substringof отличается от OData v4: > - v3: substringof('значение', Поле) eq true > - v4: contains(Поле, 'значение') — не работает в 1С!

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

| Оператор | Описание | Пример | |----------|----------|--------| | and | Логическое И | $filter=DeletionMark eq false and Date gt datetime'2024-01-01T00:00:00' | | or | Логическое ИЛИ | $filter=Code eq '001' or Code eq '002' | | not | Отрицание | $filter=not(DeletionMark eq true) |

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

| Тип значения | Синтаксис | Пример | |--------------|-----------|--------| | Строка | Одинарные кавычки | 'Иванов' | | Число | Без кавычек | 100 | | Булево | true / false | eq true | | Дата | datetime'YYYY-MM-DDTHH:MM:SS' | datetime'2024-01-01T00:00:00' | | UUID (Ref_Key) | guid'uuid' | guid'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' |

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

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

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

| Имя 1С | URL-encoded | |--------|-------------| | Сотрудники | %D0%A1%D0%BE%D1%82%D1%80%D1%83%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8 | | ФизическиеЛица | %D0%A4%D0%B8%D0%B7%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5%D0%9B%D0%B8%D1%86%D0%B0 | | Организации | %D0%9E%D1%80%D0%B3%D0%B0%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8 |

Примеры запросов через 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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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 ", "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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gybson63
• Source: gybson63/1c-oData-skill
• License: MIT

Install and usage instructions live in the source repository linked above.