Как я перестал писать HTTP-интеграции с нуля: от «нам надо было вчера» к конструктору запросов в 1С
Эта статья — не инструкция «как вызвать HTTPСоединение». Таких текстов в Базе знаний хватает. Это разбор типичного заказа на интеграцию 1С с внешним REST/JSON API: почему он всегда выглядит на два часа, почему сдаётся через две недели, и как из этой повторяющейся боли получилось расширение Апитет.
Если вы 1С-разработчик и хотя бы раз слышали фразу «там же просто JSON отправить», текст для вас. Если вы аналитик или руководитель проекта и не понимаете, почему программист на простую выгрузку закладывает неделю — тоже.
Как выглядит заказ в первый день
Заказчик пишет спокойно. «Нужно забирать статусы из их API в 1С. Документация есть. Токен выдадут. Нам это вчера надо было, клиенты уже спрашивают.»
В письме — ссылка на swagger, два скриншота Postman и фраза, что «у них всё стандартно». На созвоне выясняется стандартность:
- авторизация не в том заголовке, который в первом абзаце, а во втором, «актуальном с марта»;
- список сущностей отдаётся страницами по 100, без total, курсор живёт в заголовке ответа;
- дата — строка в ISO, но с часовым поясом UTC, а в 1С все живут в Москве;
- идентификатор контрагента в API — не ИНН, а их внутренний uuid, который в 1С никто не хранил;
- «забирать статусы» на деле значит ещё и писать обратно комментарий, когда менеджер меняет документ.
Ничего из этого не является чем-то экзотическим. Проблема в другом: каждый следующий заказ отличается деталями и совпадает каркасом. Каркас вы пишете заново, потому что копипаст прошлого модуля уже стыдно открывать.
К вечеру первого дня у заказчика ещё держится иллюзия, что «ну вы же программист, набросаете». К вечеру третьего он уже в мессенджере: «ну как там, хоть статусы уже падают?» К вечеру десятого вы правите разбор вложенного массива, а он искренне не понимает, чем вы занимались две недели.
Я это проходил достаточное количество раз, чтобы начать ненавидеть не заказчика, а собственный ритуал.
Анатомия «простой» интеграции
Любая HTTP-интеграция в 1С, если честно нарисовать её на доске, состоит из одних и тех же слоёв. Я перечисляю их специально в том порядке, в котором они всплывают в проекте — не в том, в котором их описывает документация API.
Слой 1. Транспорт. HTTPСоединение, таймаут, HTTPS, иногда прокси. Кажется, что это пять строк. Потом оказывается, что на сервере 1С нет сертификата, тонкий клиент ходит в интернет иначе, чем кластер, а тестовый контур API доступен только с белого списка IP.
Слой 2. Конверт запроса. Метод, путь, query-параметры, заголовки, тело. Документация пишет Authorization: Bearer, живой сервис ждёт X-Api-Key. Заголовки копируют из cURL руками и теряют пробел. Тело JSON собирают строковой конкатенацией, пока не приедет кавычка в наименовании номенклатуры.
Слой 3. Авторизация как отдельный квест. Сначала «просто ключ в константе». Потом ключ протухает раз в час, и нужен отдельный POST на /token. Потом этот токен надо подставлять во все остальные запросы, кешировать, не светить в журнале регистрации.
Слой 4. Разбор ответа. ЧтениеJSON в соответствие, обход, поиск нужного узла. Один сервис отдаёт объект, другой — массив в корне, третий — { "data": { "items": [] } }. XML ещё жив, его не отменяли.
Слой 5. Смысл. Сопоставить поле API с реквизитом 1С. Найти справочник по коду. Не создать дубль. Не затереть ручную правку. Понять, что status = 4 — это не «ошибка», а «доставлен».
Слой 6. Расписание и идемпотентность. Регламентное задание. Защита от двух запусков сразу. Что делать, если предыдущий ещё не закончил пагинацию. Куда писать ошибку, чтобы её увидел не только разработчик.
Слой 7. Люди. Форма, на которой аналитик сможет поменять URL, не вызывая вас из отпуска. Лог, по которому можно сказать: «вот запрос, вот 401, вот тело».
В типовом заказе оплачивают иллюзию, что существует только слой 5: «ну сопоставьте поля». Слои 1–4 и 6–7 вы делаете бесплатно, потому что «это же техничка». Именно они съедают календарь. Именно из-за них заказчик плачет в чате: интеграция нужна была вчера, а вы всё ещё отлаживаете таймаут на рабочей базе, потому что тестовой нет, а после каждого изменения кода необходимо обновлять базу и перезаходить в предприятие.
Что я копировал из проекта в проект
После пятой-шестой такой работы у меня в архиве лежали почти одинаковые общие модули с разными префиксами. итг_HTTP, сдэк_Сервис, crm_Обмен, банк_Клиент. В каждом — свой Соединение(), свой РазобратьОтвет(), свой ЗаписатьОшибку().
Расхождения между ними не в архитектуре, а в шрамах конкретного проекта:
- в одном модуле таймаут 20 секунд, потому что их API думает долго;
- в другом отключён редирект, потому что один раз словили петлю;
- в третьем даты гоняются через Формат() с магической строкой, которую нельзя трогать;
- в четвёртом JSON пишется руками, потому что «структура не умеет в нужный порядок ключей, а их шлюз капризный».
Поддержка этого зоопарка хуже, чем написание с нуля. Заказчик с прошлого года звонит: «у СДЭКа поменялся метод статусов». Вы открываете модуль, который писали в спешке, без тестов, с комментарием «временно, потом вынесем». Выносить уже некуда: конфигурация на поддержке, расширение разрослось, автор модуля — вы прошлогодний.
Повторяющийся вывод был один: я решаю предметную задачу заказчика 20% времени и заново изобретаю HTTP-клиент 80%. Предметная задача каждый раз новая. HTTP-клиент — нет.
Отсюда требование к инструменту, которое я себе сформулировал ещё до имени:
1. Настройка запроса — в предприятии, не в конфигураторе. Иначе любая правка URL = «все выйдите из базы!».
2. Поля, заголовки, тело, маппинг — данные, а не код. Иначе аналитик не сможет поменять соответствие, не дожидаясь разработчика.
3. Секреты не лежат открытым текстом в справочнике.
4. Повторный запуск той же загрузки не должен портить данные.
5. Лог запроса и ответа — штатно, а не «включим технологический журнал, если повезёт».
6. Подключение к любой конфигурации на управляемых формах, без привязки к УТ или БП.
Так появился Апитет: расширение с префиксом APt_, которое живёт рядом с учётом и не требует снимать конфигурацию с поддержки ради очередного HTTPСоединение.
Почему «просто написать ещё один модуль» перестало работать
Короткий ответ: заказчики перестали ждать, а API перестали быть одноразовыми.
Раньше интеграция была событием. Подключили банк, сдали, забыли. Сейчас у средней оптовой фирмы одновременно живые контуры: сайт, доставка, CRM, маркировка, иногда маркетплейс, иногда ЭДО. Каждый контур обновляет контракт раз в квартал. Если каждый контур — отдельный модуль на встроенном языке, вы становитесь вечным дежурным по чужим changelog.
Второй момент — люди, которые ставят задачу, всё чаще не программисты. Руководитель проекта приносит swagger и хочет сам потыкать. В конфигураторе он тыкать не будет. Значит, либо вы навсегда остаётесь оператором чужого Postman внутри 1С, либо даёте ему форму.
Третий момент — моральный, его редко пишут в ТЗ. Когда интеграция «нужна вчера», давление идёт не на качество разбора JSON, а на видимый прогресс. В такой атмосфере рождается код, который стыдно показывать, но который «уже что-то грузит». Через месяц этот код становится учётной системой. Я устал быть автором таких модулей.
Конструктор не отменяет предметную работу. Он убирает право заказчика считать, что транспорт — это «пять минут». Транспорт уже сделан. Остаётся то, за что действительно стоит платить: смысл полей, справочники, права, что считать успешной загрузкой.
Как устроен Апитет с точки зрения платформы
Это расширение конфигурации, не внешняя обработка. Внешняя обработка удобна, пока один человек запускает её руками. Как только нужно расписание, роли, хранение настроек и работа на сервере кластера — обработка начинает изображать из себя подсистему и делает это плохо.
В Апитете единица настройки — элемент справочника Endpoints. В карточке живёт то, что раньше было параметрами функции: базовый URL, путь, метод (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS), заголовки, параметры, формат ответа, правила маппинга, расписание.
URL можно вставить целиком: парсер (APURLParser) сам отделяет хост от пути. Заголовки можно вставить пачкой из документации — модуль APt_APHeadersHelper разбирает типичный текстовый блок Key: Value и не плодит дубли при повторной вставке. Это мелочь, которая экономит полчаса злости на каждом новом сервисе.
Тело запроса собирается деревом, не строкой. Модуль APt_JSONTreeHelper гоняет дерево значений в JSON и обратно. В узлах можно ставить маски: текущая дата, GUID, номер страницы. Для человека, который когда-либо собирал JSON конкатенацией, это разница между «работает на тестовом примере» и «не падает на боевой номенклатуре».
Ответ JSON или XML разбирается в схему, по которой настраивается маппинг. Маппинг — отдельный контур (APFieldMapping, APMappingConfig): поле API → реквизит справочника, документа или регистра сведений, плюс простые трансформации (регистр, обрезка, префикс, поиск ссылки по коду или наименованию). Перед записью проверяются типы и права текущего пользователя. Если в целевой реквизит нельзя писать то, что пришло, загрузка останавливается с понятной причиной, а не пишет Неопределено вглубь учёта.
Это принципиально. Интеграции, которые «почти работают», опаснее тех, которые падают сразу. Молчаливая порча справочника контрагентов стоит дороже недели разработки.
Загрузку гоняет движок (APRequestEngineCore, APUniversalLoader) плюс регламент (APScheduler, задание APAutoLoad). Если тот же процесс уже выполняется, второй экземпляр не стартует: ни вручную, ни по расписанию. Журнал запросов (APRequestLog) хранит факт вызова и код ответа — чтобы спор «у нас ничего не уходило» решался не воспоминаниями, а строкой регистра.
Секреты шифруются при записи (APEncryption), если поле похоже на токен, ключ или пароль. Окружения (APEnvironment) позволяют переключить тестовый и боевой контур, не плодя два комплекта Endpoint вручную. Rate limit и прокси задаются на группу связанных точек — на домен, а не на каждый запрос отдельно.
Вложенные запросы: один Endpoint может взять значение из другого. Классика — сначала /token, потом рабочие методы с этим токеном. Результат кешируется с TTL. Глубина строго один уровень: нельзя построить гирлянду из пяти зависимостей и потом неделю искать, кто кого вызывает. Параллельных независимых источников при этом сколько угодно. В метаданных это завязано на SourceEndpoint и признак CanBeCalledFromRequest — потребитель не может сам стать источником, цикл отсекается на форме, а не в три часа ночи в рабочем контуре.
Discovery (APDiscovery) пытается найти swagger/OpenAPI по адресу сервиса. Это не магия и не замена чтению документации. Это способ не начинать карточку с пустого листа, когда описание всё-таки лежит рядом с API.
Лицензия привязана к идентификатору информационной базы. Это скучная, но честная часть продукта: расширение живёт внутри чужого учёта, и бесконечно раздавать его «на одну копию, мы потом купим» я уже пробовал в других работах.
Типовой сценарий, который раньше занимал неделю
Разберём без привязки к конкретному вендору. Нужно забирать из внешнего сервиса список сущностей и класть их в справочник 1С. Авторизация — ключ в заголовке, плюс раз в сутки обновляемый токен.
Раньше я делал так: общий модуль, константа с ключом, регламент, попытка/исключение, запись в журнал регистрации, форма «загрузить сейчас» для директора. Потом выяснялось, что ключ нельзя светить в ЖР, токен надо кешировать, страницы надо обходить, а директор всё равно будет жать кнопку параллельно с регламентом.
В Апитете этот же сценарий раскладывается на данные:
1. Endpoint «Токен» — POST, тело с секретом, в ответе поле доступа, TTL.
2. Endpoint «Список» — GET, заголовок авторизации берётся из источника «Токен», включён обход страниц.
3. Маппинг на справочник: внешний id → реквизит, наименование → наименование, статус → перечисление через соответствие.
4. Расписание из карточки: раз в N минут или раз в сутки. Сложные схемы (дни недели, месяц) — штатные регламентные задания платформы, собственная форма Апитета на это не претендует.
5. Пробный запуск из предприятия. Смотрим лог. Правим маппинг. Не просим бухгалтерию выйти из базы.
Программист здесь нужен, если в конфигурации нет куда класть данные: нет реквизита под внешний id, нет регистра под сырой снимок, нет перечисления под статусы. Это нормальная 1С-работа на час-два. Она не должна смешиваться с изобретением HTTP-клиента.
Именно здесь кончается «нам надо было вчера». Вчера нельзя было написать с нуля устойчивый клиент, очередь ошибок, пагинацию и защиту от параллельного запуска. Вчера можно было настроить карточку и понять, жив ли сервис, не тот ли ключ, не тот ли контур. Разница для заказчика психологическая: он видит запрос и ответ в тот же день, а не «мы в конфигураторе, напишем, как освободимся».
Где конструктор не спасает — и не должен
Честный список ограничений версии 1.0, чтобы не было сюрприза после установки.
Загрузка идёт в реквизиты шапки справочников и документов и в регистры сведений. Табличные части в этой версии не заполняются. Если вам нужно разбирать заказ со строками номенклатуры в ТЧ — это пока зона кода или следующего релиза. Прятать это в статье бессмысленно: первый же боевой документ со строками всё равно вылезет. Есть возможность превратить тело ответа в массив, список значений или табличный документ для дальнейшей работы.
Собственная форма расписания закрывает «каждый день» и «каждые N минут». Календарные извращения — в штатный интерфейс регламентных заданий.
Конструктор не знает вашу учётную политику. Он не решит, что считать свободным остатком, как не создать дубль контрагента и можно ли перезаписывать реквизит, который менеджер правит руками. Это проектирование, не HTTP.
Он не заменяет шину предприятия. Если у вас двадцать систем, транзакционный сага-оркестратор и требование exactly-once на миллион сообщений в сутки — вам не карточка Endpoint, вам архитектура. Апитет закрывает слой, который в 1С делают чаще всего: походить в чужой HTTP API из учёта, не вырастив ещё одну подсистему на коленке.
Он не пишет HTTP-сервис на приём. Если ваша база должна принимать чужие POST и создавать документы с гарантированной доставкой — это отдельный контур (очередь, идемпотентный ключ, публикация /hs/). Путать исходящий клиент и входящий сервис — частая ошибка в ТЗ «интеграция через JSON».
Платформа: 8.3.10 и выше, управляемые формы. Проверялось на БП 3.0 и Документооборот КОРП конкретных релизов, КА 2.5 и УТ 11.5; на самописке работает по той же причине, по которой работает любое расширение без привязки к типовым объектам — пока вы сами указываете, куда мапить. Предположительно, Апитет должен работать на платформе 8.5, но, честно, у меня возможности проверить эту догадку не было.
Что изменилось в разговоре с заказчиком
Раньше смета выглядела как «интеграция с сервисом X — N дней», и внутри этой N сидела неизвестность их API. Теперь всё иначе.
- Есть ли в базе объекты, куда класть данные? Если нет — оценка на метаданные.
- Есть ли стабильный контракт API, стенд, ключи? Если нет — оценка на обследование, не на разработку.
- Нужна ли только загрузка шапки/регистра, или ТЧ и сложная запись документов? Если ТЧ — это уже не «настроили Endpoint».
- Нужен ли исходящий поток из проведения документа с очередью? Если да — это не Апитет, это outbox, и я это проговариваю до старта.
Заказчику от этого спокойнее, хотя звучит жёстче. Он перестаёт покупать фантазию «JSON — это просто». Вы перестаёте бесплатно тащить слои 1–4 под давлением «вчера».
Слёзы из заголовка статьи здесь никуда не делись. Они просто сменились фазой. Раньше человек плакал на второй неделе, когда «уже должно было работать». Теперь он нервничает в первый день, пока не получен 200 OK на тестовом ключе. Это другой, более честный нерв: он про их сервис и их данные, а не про то, что разработчик 1С снова пишет обёртку над ЗаписьJSON.
Практические советы, даже если вы не будете использовать Апитет
Несколько правил, которые я вынес ещё до продукта и которые в нём просто стали умолчаниями.
Не вызывайте внешний HTTP из транзакции проведения документа. Если сервис лежит, пользователи не проведут реализацию. Исходящие сообщения — в очередь, отправка — после фиксации.
Не храните токены в открытом виде в константе «для удобства». Удобство заканчивается первой копией .dt на флешке.
Не запускайте одну и ту же загрузку двумя регламентами «на всякий случай». На всякий случай у вас будут дубли.
Не считайте код ответа 200 достаточным успехом. Смотрите тело. Многие API кладут ошибку внутрь JSON и всё равно отдают 200.
Не мапьте «как называется в доке» на «как называется в 1С» без примера реального ответа. Документация врёт чаще, чем хочется думать. Один живой ответ на тестовом контуре стоит десяти страниц swagger.
Не обещайте срок, пока нет ключей и стенда. Срок без стенда — это срок на ваш оптимизм, не на интеграцию.
Эти правила не зависят от Апитета. Расширение просто не даёт их забыть в горячке «нам вчера».
Для кого этот подход, а кому стоит обойти стороной
Разработчику 1С конструктор экономит недели на типовых загрузках и оставляет время на то, что нельзя нажать формой: нетиповые объекты, сложная запись, входящие сервисы, очереди, предметные правила.
Аналитику — даёт возможность самому собрать запрос и показать заказчику живой ответ, не занимая очередь к программисту на «просто поменять URL».
Компании с пачкой мелких API — даёт один журнал, один способ хранить секреты, один регламент, вместо пяти модулей с пятью традициями именования.
Кому не стоит ждать чуда: командам, которым нужна шина; проектам, где интеграция — это 80% предметной логики и 20% HTTP; людям, которые хотят «чтобы само поняло их 1С и само написало обмен». Само ничего не поймёт. Нужно указать, какой Endpoint, какое поле, какой реквизит.
Заключение
Я не придумал новый протокол и не отменил 1С-разработку. Я вынес в данные ту работу, которую делал десятый раз с мыслью "опять?", пока заказчик ждал «простую выгрузку к вчера».
Апитет — это расширение, в котором HTTP-запрос, заголовки, JSON-тело, маппинг, расписание, лог, шифрование секретов и защита от параллельного запуска живут в предприятии. Программист подключается, когда в метаданных некуда класть результат или когда задача выходит за загрузку шапки и регистра сведений.
Если вы сейчас сидите в третьей итерации модуля ..._ИнтеграцияПоHTTP и чувствуете, что пишете не учёт, а вечный клиент к чужим API — вам знаком весь текст до этого абзаца. Разница только в том, оставляете ли вы следующий такой заказ кодом в конфигурации или карточкой Endpoint.
Ссылки на карточку расширения и требования к платформе — в публикации Апитета на Инфостарте. В статье я сознательно не копировал маркетинговый список «причин купить»: здесь важен ход мысли, а не витрина. Если после чтения вы откроете свой последний интеграционный модуль и увидите там те же семь слоёв — значит, текст попал.
Платформа: 1С:Предприятие 8.3. Расширение конфигурации. Управляемые формы. Версия Апитета, о которой идёт речь, — 1.0.
Вступайте в нашу телеграмм-группу Инфостарт