Integrating AI Models into 1C:Enterprise via API

1C databases involve a lot of manual text work: sorting incoming emails by type, drafting replies to customers, pulling details out of free-form text. You can connect an AI model to 1C with built-in platform tools — HTTPСоединение (HTTPConnection), HTTPЗапрос (HTTPRequest), and JSON reading/writing — without external components. Below are a function template for calling a model through Zukko, example tasks, error handling, and cost estimates.

How the 1C integration works

The flow is simple:

1. 1C code builds a JSON payload with the task text and model parameters.
2. An HTTPS request goes to https://api.zukko.pro/v1/chat/completions.
3. The model returns its answer as JSON.
4. 1C code extracts the answer text and writes it to a document, catalog, or register.

You need platform 8.3.6 or later, which introduced the ЧтениеJSON (JSONReader) and ЗаписьJSON (JSONWriter) objects. Run requests on the server so the key never reaches a client machine.

Step 1: create an API key

1. Open the API keys page in the dashboard↗.
2. Create a key with a clear name, for example "1C".
3. Restrict it: set a daily spend limit and a list of allowed models.
4. Copy the fetch_... key — it is shown in full only once.

Don't store the key in module code. Configurations built on the Standard Subsystems Library (BSP) have a secure storage for this — the ЗаписатьДанныеВБезопасноеХранилище and ПрочитатьДанныеИзБезопасногоХранилища procedures of the ОбщегоНазначения common module (check the exact signature for your BSP version). Otherwise, a constant that only administrators can access will do.

Step 2: a function template for calling the model

Below is a template, not a finished data processor: move it into a server common module (for example, ИнтеграцияСМоделью), adapt it to your configuration, and test it on a copy of the database. The code uses Russian 1C syntax, as most 1C codebases do; the platform also supports English syntax if your project uses it.

// TEMPLATE. Server common module, platform 8.3.6+.
// Sends text to a model via Zukko and returns the answer as a string.
Функция ЗапросКМодели(ТекстЗадания, КлючAPI, Модель = "claude-sonnet-5") Экспорт

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

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

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

Things to note:

• BOM. ИспользованиеByteOrderMark.НеИспользовать (ByteOrderMarkUse.DontUse) removes the BOM at the start of the body; with it, the server may fail to parse the JSON.
• Map instead of Structure. The second parameter of ПрочитатьJSON(Чтение, Истина) reads the response into a Соответствие (Map). That avoids problems with JSON keys that aren't valid Structure property names.
• Timeout. 120 seconds leaves room for long answers. If answers are short, you can lower it.
• Certificate. To have the platform verify the server certificate against the OS store, you can pass Новый СертификатыУдостоверяющихЦентровОС (OS certification authority certificates) as the second parameter of ЗащищенноеСоединениеOpenSSL; availability depends on the platform version.
• Proxy. If the 1C server reaches the internet through a proxy, pass an ИнтернетПрокси (InternetProxy) object as the fifth parameter of HTTPСоединение.

Check object and parameter names against the syntax assistant for your platform version.

Example tasks

Multi-line strings in 1C are joined with Символы.ПС (Chars.LF). An example call from a form:

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

	Задание = "Classify the email into one category: order, complaint, question, thanks. "
		+ "Answer with one word." + Символы.ПС + Символы.ПС
		+ "Email:" + Символы.ПС + ТекстПисьма;

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

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

ПолучитьКлючAPI() is your own function that reads the key from secure storage or a constant. Following the same pattern:

• Draft reply to a customer: "Write a polite reply to the customer's email. Say the request has been received and we will answer within one business day. Email: ...". Send it to the customer only after a manager reviews it.
• Data extraction: "Find the full name, position, phone, and email in the text. Return only JSON with keys fio, position, phone, email. Text: ...". Parse the answer with the same ПрочитатьJSON and validate the fields before writing them to a catalog.

Choosing a model and estimating cost

Zukko prices per 1M tokens: claude-sonnet-5 — $0.3 input and $0.3 output, gpt-5.6-luna — $0.1 / $0.1, glm-5.3-flash — $0.04 / $0.04.

Example: 1,000 emails, on average 500 input and 100 output tokens each. That's 1,000 × 500 = 500,000 input (0.5M) and 1,000 × 100 = 100,000 output (0.1M) tokens.

Check the real token counts for your emails in the response's usage field or in the spending history in the dashboard. Test which model handles your tasks on a sample: run 50 typical emails through two or three models and compare against manual labels. The current model list is at GET https://api.zukko.pro/v1/models or on the "Models" page in the dashboard↗.

Error handling and limits

The template raises an exception with the status code and error text. What the codes mean:

• 401 — invalid key;
• 402 — insufficient balance;
• 403 — the model isn't in the key's allowed list;
• 413 — request too large, shorten the text;
• 429 — requests too frequent, or the key's limit is used up;
• 503 — the model provider is temporarily unavailable.

For bulk processing (a scheduled job over hundreds of documents), retry only on 429 and 503, with a pause that grows with each attempt. On 401, 402, and 403, stop the job and write the error to the event log: retries won't help. More about key limits is in the key limits and cache↗ section.

FAQ

Which platform version do I need?

8.3.6 or later — it has ЧтениеJSON, ЗаписьJSON, and СтрШаблон. On older versions you would have to build and parse JSON by hand or via an external component. HTTPS requires the platform to support modern TLS, so on old releases first check whether a request to api.zukko.pro goes through at all.

How do I send a large document?

Claude and GPT models in Zukko have a 1M-token context, GLM has 128K, so a typical contract or email fits whole. If you get 413, split the text into parts and process them one by one. For classification, the first few thousand characters are often enough.

Can I avoid paying for identical requests?

Build your own cache: an information register with a "request hash" dimension and an "answer" resource. Before sending, check whether an answer already exists for the same task text. You can compute the hash with the ХешированиеДанных (DataHashing) object.

How do I check the balance before bulk processing?

Through the balance API↗ or in the dashboard. The most reliable option is a daily spend limit on the key: then the scheduled job can't spend more than you planned.