1c Integrations

---
name: 1c-integrations
description: "Паттерны интеграций 1С - HTTP-клиент с таймаутами, сериализация JSON/XML, безопасное хранение учётных данных, идемпотентность, ретраи, длительные сетевые операции. Используй при разработке HTTP-сервисов, REST-клиентов, веб-сервисов и файловых обменов с внешними системами."
---

# Паттерны интеграций 1С

> Нормы кода — в `.claude/rules/1c-rules.md` (единственный источник правил).
> Здесь — развёрнутые паттерны и примеры «как именно».

## Перед написанием кода

1. Проверь БСП на готовые подсистемы интеграции (протокол проверки — `.claude/rules/mcp.md`)
2. Найди существующие интеграции в конфигурации — следуй их паттернам
3. Согласуй контракт с пользователем: метод и URL, формат запроса/ответа, схема аутентификации, таймауты, политика повторов, требования к логированию

## Принципы

1. **Сначала искать** — готовые решения в БСП и в конфигурации
2. **Безопасность** — никаких учётных данных в коде
3. **Идемпотентность** — повторный вызов не должен дублировать операцию

## Паттерн: HTTP-клиент

```bsl
Функция ВыполнитьHTTPЗапрос(Метод, Путь, ТелоЗапроса = Неопределено)

    Результат = Новый Структура;
    Результат.Вставить("Успех", Ложь);
    Результат.Вставить("КодСостояния", 0);
    Результат.Вставить("Данные", Неопределено);
    Результат.Вставить("Ошибка", "");

    // Таймаут обязателен, значение - из констант/настроек, не хардкод
    Соединение = Новый HTTPСоединение(
        Сервер, Порт,
        , , , // Логин, пароль - из безопасного хранилища
        Таймаут);

    HTTPЗапрос = Новый HTTPЗапрос(Путь);
    HTTPЗапрос.Заголовки.Вставить("Content-Type", "application/json");
    HTTPЗапрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);

    Если ТелоЗапроса <> Неопределено Тогда
        HTTPЗапрос.УстановитьТелоИзСтроки(ТелоЗапроса, КодировкаТекста.UTF8);
    КонецЕсли;

    Попытка

        Если Метод = "GET" Тогда
            HTTPОтвет = Соединение.Получить(HTTPЗапрос);
        ИначеЕсли Метод = "POST" Тогда
            HTTPОтвет = Соединение.ОтправитьДляОбработки(HTTPЗапрос);
        ИначеЕсли Метод = "PUT" Тогда
            HTTPОтвет = Соединение.Записать(HTTPЗапрос);
        ИначеЕсли Метод = "DELETE" Тогда
            HTTPОтвет = Соединение.Удалить(HTTPЗапрос);
        КонецЕсли;

        Результат.КодСостояния = HTTPОтвет.КодСостояния;

        Если HTTPОтвет.КодСостояния >= 200 И HTTPОтвет.КодСостояния < 300 Тогда
            Результат.Успех = Истина;
            Результат.Данные = HTTPОтвет.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8);
        Иначе
            Результат.Ошибка = СтрШаблон("HTTP %1: %2",
                HTTPОтвет.КодСостояния,
                HTTPОтвет.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8));
        КонецЕсли;

    Исключение
        Результат.Ошибка = ОбработкаОшибок.ПодробноеПредставлениеОшибки(ИнформацияОбОшибке());
    КонецПопытки;

    Возврат Результат;

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

## Паттерн: сериализация

```bsl
// Запись JSON - через платформу, НЕ ручная сборка строк
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку(Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Unix));
ЗаписатьJSON(ЗаписьJSON, ДанныеДляОтправки);
СтрокаJSON = ЗаписьJSON.Закрыть();

// Чтение JSON - в Соответствие (не в Структуру)
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(ТелоОтвета);
Данные = ПрочитатьJSON(ЧтениеJSON, Истина);
ЧтениеJSON.Закрыть();
```

XML — через ЧтениеXML/ЗаписьXML, с XSD-валидацией при наличии схемы.

Форматы данных: даты — ISO 8601 `YYYY-MM-DDTHH:MM:SSZ` (согласовать часовой пояс); числа — точка как разделитель; булевы — true/false, не «да»/«нет».

## Безопасность

| Что | Где хранить |
|-----|------------|
| Пароли, токены, закрытые API-ключи | БСП «Безопасное хранилище паролей»; без БСП и только при неизбежности хранения в ИБ — отдельный объект с минимальными правами и явным учетом остаточного риска. Выделенная константа допустима лишь как осознанный запасной вариант, но безопасным хранилищем не является |
| Логины, адреса и несекретные идентификаторы | Константы или регистры сведений |
| Сертификаты | Хранилище сертификатов ОС |

В БСП используй `ОбщегоНазначения.ЗаписатьДанныеВБезопасноеХранилище()`,
`ПрочитатьДанныеИзБезопасногоХранилища()` и `УдалитьДанныеИзБезопасногоХранилища()`.
Секрет получай на сервере непосредственно перед вызовом внешнего ресурса и не возвращай на клиент.
Практический паттерн — в `use-bsp/references/subsystems.md`.

Токены: проверять срок действия перед каждым запросом, обновлять (refresh) централизованно.

## Паттерн: идемпотентность и ретраи

```bsl
// Ключи операций хранить в регистре сведений; перед отправкой - проверить статус
СтатусОперации = ПолучитьСтатусОперации(КлючОперации);
Если СтатусОперации = "Выполнено" Тогда
    Возврат; // Не отправлять повторно
КонецЕсли;
```

Политика повторов: ограниченное число попыток (3-5), экспоненциальная задержка между попытками, повторять только сетевые ошибки и 5xx (не 4xx).

## Длительные сетевые операции

Сетевые вызовы — через БСП `ДлительныеОперации.ВыполнитьФункцию()`. Прямой вызов `ФоновыеЗадания.Выполнить()` для сетевых операций запрещён. На клиенте обрабатывай завершение по контракту используемого API; если доступны оба варианта, следуй настройке стиля асинхронности из `.claude/rules/1c-rules.md`.

## Тестирование интеграций

1. Сначала проверить контракт вручную (Postman, curl)
2. Затем реализовать в коде 1С

## Документирование интеграции

Для каждой интеграции фиксировать: внешняя система и версия; контракт (методы, URL, формат); схема аутентификации и место хранения учётных данных; требуемые роли; ссылки на документацию внешней системы.