Интеграция нейросети в 1С:Предприятие через API

В базах 1С много работы с текстом, которую делают вручную: разобрать входящие письма по типам, подготовить ответ клиенту, вытащить реквизиты из свободного текста. Подключить нейросеть к 1С можно встроенными средствами платформы — HTTPСоединение, HTTPЗапрос и чтение/запись JSON, без внешних компонент. Ниже — шаблон функции для обращения к модели через Zukko, примеры задач, обработка ошибок и расчёт стоимости.

Как устроена интеграция 1С с нейросетью

Схема простая:

1. Код 1С собирает JSON с текстом задания и параметрами модели.
2. HTTPS-запрос уходит на https://api.zukko.pro/v1/chat/completions.
3. Модель возвращает ответ в JSON.
4. Код 1С достаёт текст ответа и записывает его в документ, справочник или регистр.

Понадобится платформа 8.3.6 или новее: в ней появились объекты ЧтениеJSON и ЗаписьJSON. Запросы выполняйте на сервере — так ключ не попадает на клиентский компьютер.

Шаг 1: создайте API-ключ

1. Откройте страницу ключей в кабинете↗.
2. Создайте ключ с понятным именем, например «1С».
3. Ограничьте его: задайте дневной лимит расходов и список разрешённых моделей.
4. Скопируйте ключ вида fetch_... — полностью он показывается один раз.

Ключ не стоит хранить в коде модуля. В конфигурациях на БСП для этого есть безопасное хранилище — процедуры ЗаписатьДанныеВБезопасноеХранилище и ПрочитатьДанныеИзБезопасногоХранилища общего модуля ОбщегоНазначения (точную сигнатуру сверьте с вашей версией БСП). В остальных случаях подойдёт константа, доступ к которой есть только у администратора.

Шаг 2: шаблон функции запроса к модели

Ниже — шаблон, а не готовая обработка: перенесите его в серверный общий модуль (например, ИнтеграцияСМоделью), адаптируйте под свою конфигурацию и проверьте на копии базы.

// ШАБЛОН. Серверный общий модуль, платформа 8.3.6+.
// Отправляет текст модели через Zukko и возвращает ответ строкой.
Функция ЗапросКМодели(ТекстЗадания, КлючAPI, Модель = "claude-sonnet-5") Экспорт

	// 1. Тело запроса в формате OpenAI Chat Completions
	Сообщения = Новый Массив;
	Сообщения.Добавить(Новый Структура("role, content", "user", ТекстЗадания));

	Данные = Новый Структура;
	Данные.Вставить("model", Модель);
	Данные.Вставить("max_tokens", 1000);
	Данные.Вставить("messages", Сообщения);

	ЗаписьJSON = Новый ЗаписьJSON;

На что обратить внимание:

• BOM. Параметр ИспользованиеByteOrderMark.НеИспользовать убирает метку BOM в начале тела: с ней сервер может не разобрать JSON.
• Соответствие вместо Структуры. Второй параметр ПрочитатьJSON(Чтение, Истина) читает ответ в Соответствие. Так не возникнет проблем с ключами JSON, которые не являются допустимыми именами свойств структуры.
• Таймаут. 120 секунд — с запасом для длинных ответов. Если ответы короткие, его можно уменьшить.
• Сертификат. Чтобы платформа проверяла сертификат сервера по хранилищу ОС, в конструктор ЗащищенноеСоединениеOpenSSL можно передать вторым параметром Новый СертификатыУдостоверяющихЦентровОС — доступность зависит от версии платформы.
• Прокси. Если сервер 1С выходит в интернет через прокси, передайте объект ИнтернетПрокси пятым параметром HTTPСоединение.

Названия объектов и параметров сверяйте с синтакс-помощником вашей версии платформы.

Примеры задач

Многострочные строки в 1С склеиваются через Символы.ПС. Пример вызова из формы:

&НаСервереБезКонтекста
Функция КлассифицироватьПисьмо(ТекстПисьма)

	Задание = "Отнеси письмо к одной категории: заказ, жалоба, вопрос, благодарность. "
		+ "Ответь одним словом." + Символы.ПС + Символы.ПС
		+ "Письмо:" + Символы.ПС + ТекстПисьма;

	Возврат ИнтеграцияСМоделью.ЗапросКМодели(Задание, ПолучитьКлючAPI(), "glm-5.3-flash");

КонецФункции

ПолучитьКлючAPI() — ваша функция, которая читает ключ из безопасного хранилища или константы. По тому же образцу:

• Черновик ответа клиенту: «Составь вежливый ответ на письмо клиента. Сообщи, что обращение принято и ответим в течение рабочего дня. Письмо: ...». Отправлять клиенту стоит после проверки менеджером.
• Извлечение данных: «Найди в тексте ФИО, должность, телефон и email. Верни только JSON с ключами fio, position, phone, email. Текст: ...». Ответ разберите тем же ПрочитатьJSON и проверьте поля перед записью в справочник.

Выбор модели и расчёт стоимости

Цены Zukko за 1M токенов: claude-sonnet-5 — $0.3 на вход и $0.3 на выход, gpt-5.6-luna — $0.1 / $0.1, glm-5.3-flash — $0.04 / $0.04.

Пример: 1000 писем, в среднем 500 входных и 100 выходных токенов на письмо. Это 1000 × 500 = 500 000 входных (0,5M) и 1000 × 100 = 100 000 выходных (0,1M) токенов.

Реальное число токенов для ваших писем смотрите в поле usage ответа или в истории расходов в кабинете. Какая модель справится с вашими задачами, проверьте на выборке: прогоните 50 типовых писем через две-три модели и сравните с ручной разметкой. Актуальный список моделей — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете↗.

Обработка ошибок и лимиты

Шаблон бросает исключение с кодом и текстом ошибки. Что означают коды:

• 401 — неверный ключ;
• 402 — недостаточно средств на балансе;
• 403 — модель не входит в список разрешённых для ключа;
• 413 — слишком большой запрос, текст нужно сократить;
• 429 — слишком частые запросы или исчерпан лимит ключа;
• 503 — провайдер модели временно недоступен.

При массовой обработке (регламентное задание по сотням документов) повторяйте запрос только на 429 и 503, с паузой, растущей от попытки к попытке. На 401, 402 и 403 задание лучше остановить и записать ошибку в журнал регистрации: повторы не помогут. Подробнее о лимитах ключа — в разделе о лимитах ключей и кэше↗.

Частые вопросы

Какая версия платформы нужна?

8.3.6 или новее — в ней есть ЧтениеJSON, ЗаписьJSON и СтрШаблон. На более старых версиях JSON придётся собирать и разбирать вручную или через внешнюю компоненту. Для HTTPS платформа должна поддерживать современный TLS, поэтому на старых релизах сначала проверьте, проходит ли запрос к api.zukko.pro вообще.

Как отправить большой документ?

У моделей Claude и GPT в Zukko контекст 1M токенов, у GLM — 128K, так что обычный договор или письмо помещаются целиком. Если получаете 413, разбейте текст на части и обрабатывайте их по очереди. Для классификации часто хватает первых нескольких тысяч символов.

Можно ли не платить за одинаковые запросы?

Сделайте свой кэш: регистр сведений с измерением «хеш запроса» и ресурсом «ответ». Перед отправкой проверяйте, нет ли уже ответа для такого же текста задания. Хеш можно посчитать объектом ХешированиеДанных.

Как проверить баланс перед массовой обработкой?

Через API баланса↗ или в кабинете. Надёжнее всего задать ключу дневной лимит расходов: тогда регламентное задание не потратит больше, чем вы рассчитывали.