Почти любая интеграция 1С с внешним сервисом начинается одинаково.

Есть документ в 1С. Есть внешний API. Нужно при проведении документа отправить данные наружу. На первой встрече задача звучит просто: «Собрать JSON, дернуть метод, записать ответ».

Если делать совсем в лоб, код получается понятным:

Процедура ОбработкаПроведения(Отказ, РежимПроведения)

    // Провели документ
    // Собрали JSON
    // Отправили во внешний сервис
    // Получили ответ
    // Записали статус

КонецПроцедуры

На тестовой базе все работает. Документ проводится, внешний сервис отвечает, статус заполняется. Можно показать пользователю, можно закрыть задачу.

А потом начинается эксплуатация.

Внешний сервис недоступен 20 минут. Пользователь перепроводит документ. Потом еще раз. Потом просит администратора «как‑нибудь отправить вручную». В другой системе появляются дубли. Часть документов ушла, часть нет. В одном документе статус «Выгружено», но во внешней системе объекта нет. В другом документе ошибка, но никто ее не видел неделю. Разработчику присылают скриншот: «У нас опять не работает обмен».

И в этот момент выясняется, что HTTP‑запрос был самой простой частью интеграции.

HTTP‑запрос — это еще не интеграция

Вызвать внешний метод из 1С обычно несложно. В платформе есть HTTPСоединение, HTTPЗапрос, можно сформировать тело запроса, установить заголовки, получить код ответа и текст.

Сложность начинается не там.

Интеграция должна отвечать не только на вопрос «как отправить данные», но и на вопросы:

• что делать, если сервис недоступен;

• что делать, если ответ пришел с ошибкой;

• можно ли повторить отправку;

• как не создать дубль;

• где посмотреть историю обмена;

• кто увидит ошибку;

• как понять, какие документы еще не ушли;

• как отличить техническую ошибку от ошибки данных;

• что делать, если пользователь изменил документ после отправки.

Если на эти вопросы нет ответа, обмен может работать в идеальных условиях, но плохо переживает реальную жизнь.

А реальная жизнь у интеграций всегда примерно одинаковая: сеть иногда падает, API иногда отвечает медленно, данные иногда неполные, пользователи иногда нажимают кнопки повторно, внешняя система иногда меняет правила валидации.

Антипаттерн: отправка прямо при проведении

Самый опасный вариант — отправлять данные во внешний сервис прямо в обработчике проведения документа.

Выглядит удобно. Документ провели — сразу отправили. Пользователь сразу видит результат. Не нужно делать отдельную очередь, регламентное задание, форму мониторинга обмена.

Но у такого подхода есть несколько проблем.

Во‑первых, проведение документа начинает зависеть от внешней системы. Если внешний API недоступен, пользователь не может нормально завершить операцию в 1С. Внешняя система становится частью транзакции бизнес‑процесса, хотя технически она к этой транзакции не имеет отношения.

Во‑вторых, пользователь ждет. HTTP‑запрос может занимать секунду, пять секунд, тридцать секунд. Иногда он зависает до таймаута. Для пользователя это выглядит как «1С тормозит», хотя проблема может быть вообще не в 1С.

В‑третьих, появляются непонятные состояния. Документ мог частично провести движения, потом получить ошибку обмена, потом откатиться. Или наоборот: запрос во внешний сервис ушел, а запись результата в 1С не успела выполниться из‑за другой ошибки.

В‑четвертых, сложнее сопровождать. Если обмен выполняется внутри проведения, то часто нет нормальной истории: что отправляли, какой ответ получили, сколько было попыток, можно ли повторить.

В‑пятых, возникает соблазн перепроводить документ как способ повторной отправки. А это почти всегда плохая идея. Перепроведение документа — это учетная операция. Повтор обмена — интеграционная операция. Смешивать их опасно.

Минимальная архитектура нормального обмена

В большинстве случаев надежнее разделить бизнес‑операцию и отправку во внешний сервис.

Упрощенная схема может выглядеть так:

При проведении документа мы не отправляем данные наружу. Мы только фиксируем, что этот документ должен быть выгружен.

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

Такой подход сразу дает несколько преимуществ.

Проведение документа не зависит от доступности внешнего API. Пользователь не ждет сетевой запрос. Ошибка обмена не ломает учетную операцию. Отправку можно повторять. Очередь можно анализировать. Ошибки можно показывать отдельно. Разработчик получает место, где хранится техническая история обмена.

Да, это немного сложнее, чем один HTTP‑вызов из проведения. Но эта сложность появляется в любом случае. Вопрос только в том, будет она заложена в архитектуру сразу или всплывет в рабочей базе через месяц.

Что хранить в очереди обмена

Очередь обмена не должна быть просто списком ссылок на документы. На первых этапах кажется, что достаточно хранить объект и статус. Но очень быстро появляются дополнительные требования.

Минимальный набор полей, который я обычно закладываю:

• ОбъектОбмена

• ТипОбъекта

• НаправлениеОбмена

• Статус

• КоличествоПопыток

• ДатаСледующейПопытки

• ДатаСоздания

• ДатаПоследнейПопытки

• ИдентификаторВнешнейСистемы

• КлючИдемпотентности

• КодОтветаHTTP

• ТелоЗапроса

• ТелоОтвета

• ТекстОшибки

Не всегда нужно хранить тело запроса и ответа постоянно. В некоторых системах это может быть слишком объемно или чувствительно с точки зрения данных. Но на этапе внедрения и отладки такие поля очень помогают.

Когда пользователь говорит «не выгрузилось», разработчик должен видеть не только финальный текст ошибки, но и фактическую картину: какой метод вызывался, что отправляли, какой HTTP‑код вернулся, какой ответ отдала внешняя система, сколько было попыток.

Иначе сопровождение превращается в гадание.

Статусы обмена

Состояние обмена лучше делать явным. Например:

• ОжидаетОтправки

• ВРаботе

• Выгружено

• Ошибка

• Отложено

• Отменено

• ТребуетРучнойПроверки

Самый важный статус здесь — не «Выгружено», а «Ошибка».

Ошибка в интеграции — это не авария. Это штатное состояние обмена. Авария — это когда ошибка произошла, но никто не знает, где она, когда возникла и что с ней делать.

Статус «Ошибка» должен означать: система попыталась выполнить обмен, получила техническую или бизнес‑ошибку, сохранила результат и теперь этот объект можно проанализировать.

Не стоит прятать такие ошибки в журнал регистрации и надеяться, что кто‑то их найдет. Пользователю или администратору нужна понятная форма: какие объекты не выгружены, почему, когда была последняя попытка и можно ли повторить.

Регламентное задание и состояние «ВРаботе»

Если обмен выполняется по регламентному заданию, нужно аккуратно работать с конкурентным доступом.

Типовая ошибка: регламентное задание выбирает все строки со статусом «ОжидаетОтправки» и начинает их отправлять. Если задание запустится параллельно или пользователь вручную запустит обработку переотправки, один и тот же объект может уйти дважды.

Поэтому перед отправкой объект очереди нужно перевести в состояние «ВРаботе» и зафиксировать это изменение. Только после этого выполнять HTTP‑запрос.

Упрощенно логика такая:

// 1. Выбрали запись очереди

// 2. Установили статус ВРаботе

// 3. Зафиксировали изменение

// 4. Выполнили HTTP‑запрос

// 5. Записали результат: Выгружено или Ошибка

Важно не держать длинную транзакцию на время HTTP‑запроса. Внешний сервис может отвечать долго. Если в этот момент держать блокировки в 1С, можно получить проблемы уже внутри базы.

Поэтому обычно лучше коротко зафиксировать захват задачи, выйти из транзакции, выполнить сетевой вызов, затем отдельной операцией записать результат.

Повторы неизбежны

В любой интеграции рано или поздно появляется повторная отправка.

Причины разные:

• внешний сервис временно недоступен;

• закончился таймаут;

• вернулась ошибка 500;

• не прошла валидация данных;

• исправили реквизит документа;

• обновили таблицу соответствий;

• внешний сервис восстановился после сбоя;

• пользователь попросил отправить повторно.

Повторная отправка — это не костыль. Это нормальный сценарий.

Поэтому ее нужно проектировать заранее. У записи очереди должно быть количество попыток, дата последней попытки и дата следующей попытки. Не всегда нужно молотить внешний API каждую минуту. Иногда после ошибки лучше отложить повтор на 5, 15 или 60 минут.

Простейшая схема:

1-я ошибка → повтор через 5 минут

2-я ошибка → повтор через 15 минут

3-я ошибка → повтор через 60 минут

дальше → ТребуетРучнойПроверки

Конкретные интервалы зависят от процесса. Но сама идея важна: интеграция должна уметь ждать и повторять, а не падать в первом же нестабильном месте.

Дубли: главная боль повторной отправки

Если есть повторы, значит есть риск дублей.

Допустим, 1С отправила документ во внешний сервис. Сервис объект создал, но ответ до 1С не дошел из‑за сетевой ошибки. С точки зрения 1С отправка завершилась ошибкой. С точки зрения внешней системы объект уже существует.

Что произойдет при повторе?

Если просто еще раз вызвать метод создания, можно получить дубль. Или ошибку «объект уже существует». Или, что хуже, внешний сервис создаст второй объект без явной ошибки.

Поэтому интеграция должна быть идемпотентной хотя бы на уровне бизнес‑сценария.

Идемпотентность в прикладном смысле — это когда повторное выполнение одной и той же операции не создает повторный результат.

Варианты реализации бывают разные.

Можно передавать во внешний сервис уникальный ключ операции. Например, GUID документа 1С или специально сформированный ключ обмена.

КлючИдемпотентности = УникальныйИдентификаторДокумента1С

Можно перед созданием объекта искать его во внешней системе по внешнему идентификатору.

Можно разделить операции создания и обновления: если внешний идентификатор уже есть, выполняем update, если нет — create.

Можно хранить идентификатор внешней системы в 1С и не создавать объект повторно, если он уже был получен.

Главное — не рассчитывать, что повторов не будет. Они будут.

GUID документа 1С — полезный, но не всегда достаточный ключ

Часто в качестве ключа используют уникальный идентификатор ссылки 1С.

Для многих интеграций это удобно. Документ в 1С один, его GUID стабилен, по нему можно сопоставить объект во внешней системе.

Но есть нюансы.

Иногда один документ 1С должен порождать несколько объектов во внешней системе. Например, разные строки уходят как отдельные сущности. Тогда одного GUID документа недостаточно — нужен ключ по документу и строке.

Иногда один объект внешней системы собирается из нескольких документов 1С. Тогда ключ должен быть другим.

Иногда документ в 1С могут пометить на удаление и создать новый, а с точки зрения внешней системы это та же бизнес‑операция. Тогда технический GUID уже не совпадает с бизнес‑смыслом.

Поэтому ключ идемпотентности нужно выбирать не только технически, но и по бизнес‑логике.

Ошибка данных и техническая ошибка — разные вещи

Не все ошибки обмена одинаковые.

Есть технические ошибки: сервис недоступен, таймаут, ошибка сети, HTTP 500. Такие ошибки обычно можно повторять автоматически.

Есть ошибки данных: не заполнен обязательный реквизит, не найдено соответствие номенклатуры, не указан VIN, внешний сервис не принимает статус, не найден клиент. Такие ошибки бессмысленно повторять каждые пять минут, пока данные не исправлены.

Поэтому в очереди полезно различать хотя бы два типа ошибки:

1. ТехническаяОшибка

2. ОшибкаДанных

Для технической ошибки можно назначать автоматический повтор.

Для ошибки данных лучше показать пользователю понятное сообщение и перевести запись в состояние «ТребуетРучнойПроверки» или «Ошибка». После исправления данных пользователь или администратор сможет запустить повтор.

Плохой вариант — писать в ошибку что‑то вроде:

HTTP 400 Bad Request

Для разработчика это еще может быть полезно. Для пользователя — почти нет.

Лучше, если сообщение будет ближе к процессу:

Не заполнен VIN автомобиля

Не найдено соответствие склада во внешней системе

Внешняя система отклонила статус «Готов к выдаче»

Не указан телефон клиента

Что должен видеть пользователь

Пользователь не должен читать JSON, стек исключения и технические заголовки HTTP. Ему нужно понимать состояние операции.

Например:

Ожидает отправки

Отправлено 12.02.2026 14:35

Ошибка: не заполнен VIN

Ошибка внешнего сервиса: объект уже существует

Будет повторная попытка через 15 минут

Требуется ручная проверка

Для большинства пользователей этого достаточно. Они должны видеть, что система не молчит.

Если документ еще не отправлен — это видно. Если отправлен — видно когда. Если ошибка — понятно, что нужно исправить. Если будет повтор — понятно, что не нужно нажимать все кнопки подряд.

При этом у администратора или разработчика должна быть возможность открыть технические детали.

Что должен видеть разработчик

Для сопровождения нужны другие данные.

Я обычно хочу видеть:

1. Дата и время попытки

2. Объект обмена

3. Пользователь или регламентное задание

4. URL метода

5. HTTP‑метод

6. Код ответа HTTP

7. Тело запроса

8. Тело ответа

9. Текст исключения

10. Количество попыток

11. Длительность запроса

12. Версия формата обмена

Последний пункт часто недооценивают. Если внешний API меняется, а форматы обмена развиваются, полезно понимать, по какой версии схемы был сформирован запрос. Особенно если часть очереди была создана до обновления обработки обмена, а часть после.

В идеале журнал обмена должен позволять ответить на вопрос: «Что именно произошло с этим объектом?»

Не «кажется, мы его отправляли», а конкретно:

12:10 — зарегистрирован в очереди

12:11 — первая попытка отправки

12:11 — ошибка 500

12:26 — повторная попытка

12:26 — успешно, внешний идентификатор 784 512

Ручная переотправка — не костыль

У нормальной интеграции почти всегда должна быть ручная переотправка.

Не как основной механизм. Основной механизм — регламентное задание и автоматическая обработка очереди. Но ручная переотправка нужна для сопровождения.

Она нужна, когда:

• пользователь исправил данные;

• администратор обновил таблицу соответствий;

• внешний сервис восстановился;

• нужно переотправить один документ;

• нужно переотправить пачку документов;

• нужно снять ошибочный статус;

• нужно проверить конкретный сценарий.

Важно, чтобы ручная переотправка не означала перепроведение документа. Это отдельное действие интеграционного контура.

В идеале пользователь открывает форму обмена, видит проблемную запись и нажимает «Повторить отправку». Система меняет статус на «ОжидаетОтправки» или сразу запускает обработку конкретной записи, сохраняя историю попыток.

Не все нужно отправлять сразу

Еще одна ошибка — считать, что любой обмен должен быть мгновенным.

Иногда это действительно нужно: например, если от внешней системы зависит дальнейшее действие пользователя. Но во многих случаях достаточно асинхронной отправки с задержкой в несколько минут.

Асинхронность дает устойчивость. Если внешний сервис временно лежит, пользователи продолжают работать. Очередь копится, потом постепенно разбирается. Главное — чтобы это было видно и контролируемо.

Но асинхронность требует честного интерфейса. Нельзя показывать пользователю «все хорошо», если документ только поставлен в очередь. Лучше разделять состояния:

Документ проведен

Документ ожидает выгрузки

Документ выгружен

Это разные события.

Проведение документа и регистрация обмена

Значит ли это, что в проведении вообще не должно быть кода интеграции?

Нет.

В проведении может быть регистрация события обмена. Например, если документ проведен, и по бизнес‑правилам он должен уйти во внешний сервис, мы добавляем или обновляем запись очереди.

Но сама сетевая отправка должна жить отдельно.

Упрощенный пример:

Процедура ОбработкаПроведения(Отказ, РежимПроведения)

    // Основные движения документа
    ВыполнитьДвиженияДокумента();

    // Только регистрация необходимости обмена
    ИнтеграцияСервис.ЗарегистрироватьКВыгрузке(Ссылка);

КонецПроцедуры

А уже регламентное задание делает примерно следующее:

Процедура ВыполнитьОбмен()

    Выборка = ИнтеграцияСервис.ПолучитьОчередьКОтправке();

    Пока Выборка.Следующий() Цикл

        Если Не ИнтеграцияСервис.ЗахватитьЗадание(Выборка.Ссылка) Тогда
            Продолжить;
        КонецЕсли;

        Попытка
            Результат = нтеграцияСервис.ОтправитьВоВнешнююСистему(Выборка.ОбъектОбмена);
            ИнтеграцияСервис.ЗаписатьУспех(Выборка.Ссылка, Результат);
        Исключение
            ИнтеграцияСервис.ЗаписатьОшибку(Выборка.Ссылка, ОписаниеОшибки());
        КонецПопытки;

    КонецЦикла;

КонецПроцедуры

Это не готовый универсальный код, а схема. В реальной базе будут нюансы: транзакции, блокировки, права, фоновые задания, разделение по типам объектов, ограничение пачки, таймауты, настройки подключения.

Но принцип остается тем же: документ отвечает за учетную операцию, очередь — за интеграционную операцию.

Когда синхронная отправка все‑таки допустима

Бывают случаи, когда синхронный вызов оправдан.

Например, пользователь вводит ИНН и хочет сразу получить данные контрагента. Или нужно проверить промокод. Или получить расчет доставки. Или выполнить операцию, без ответа которой нельзя продолжать.

Но это не тот же сценарий, что фоновая выгрузка документов.

Если синхронный вызов нужен, стоит хотя бы понимать риски:

• задать разумный таймаут;

• показать пользователю понятную ошибку;

• не держать лишние блокировки;

• не выполнять тяжелый обмен внутри проведения;

• не считать внешний ответ гарантией окончательного состояния.

Синхронная интеграция не запрещена. Просто она должна быть осознанным решением, а не следствием того, что так быстрее написать.

Таблицы соответствий — скучно, но необходимо

Во многих обменах проблема не в HTTP и не в JSON, а в справочниках.

В 1С склад называется «Основной склад». Во внешней системе он имеет код MAIN. В 1С статус документа называется «Готов к отгрузке». Во внешней системе он должен быть READY_FOR_SHIPMENT. В 1С вид номенклатуры один, во внешней системе другой.

Если соответствия не вынести в настройки, разработчик быстро окажется в ситуации, когда каждое изменение внешней системы требует правки кода.

Лучше сразу предусмотреть таблицы соответствий:

Склады 1С ↔ склады внешней системы

Организации 1С ↔ юридические лица внешней системы

Статусы 1С ↔ статусы внешней системы

Виды номенклатуры 1С ↔ категории внешней системы

Типы цен 1С ↔ прайс‑листы внешней системы

И самое главное — ошибка отсутствующего соответствия должна быть нормальной ошибкой данных, а не падением обмена.

Не найдено соответствие для склада «Основной склад»

Это намного полезнее, чем общее «Ошибка формирования запроса».

Не надо скрывать интеграцию от пользователя полностью

Иногда разработчики пытаются сделать обмен максимально незаметным. Пользователь провел документ — и не думает о внешней системе. В идеале так и должно быть.

Но «незаметно» не должно означать «невидимо».

Если интеграция влияет на бизнес‑процесс, пользователь должен видеть ее состояние. Особенно если от выгрузки зависит работа другого отдела или внешней системы.

Хороший интерфейс обмена не обязан быть сложным. Часто достаточно отдельной формы со списком:

• Документ

• Дата регистрации

• Статус

• Количество попыток

• Последняя ошибка

• Дата последней попытки

• Дата следующей попытки

И кнопок:

• Повторить

• Отменить

• Открыть объект

• Показать технические данные

Для разработчика это кажется дополнительной работой. Для сопровождения это экономит часы.

Вывод

Интеграция 1С с внешним API редко ломается на самом HTTP‑запросе. Отправить запрос обычно несложно.

Она ломается в эксплуатации.

Когда внешний сервис недоступен. Когда пользователь перепроводит документ. Когда ответ не дошел. Когда объект уже создан, но 1С об этом не знает. Когда нет журнала. Когда ошибку видно только в регистрации. Когда непонятно, можно ли повторять отправку. Когда нет ключа идемпотентности. Когда техническая ошибка смешана с ошибкой данных.

Надежная интеграция начинается не с HTTP‑запроса, а с вопроса: что будет, если этот запрос не выполнится?

Если на этот вопрос есть ответ — появляются очередь, статусы, повторы, журнал, ручная переотправка и защита от дублей.

Если ответа нет — появляется обработчик проведения, в котором спрятан HTTP‑вызов, и рабочая база, в которой рано или поздно кто‑то скажет: «У нас опять не выгрузилось».