PunchOut/OCI: интеграция с системами закупок клиента

Крупный корпоративный заказчик почти никогда не покупает «через сайт» руками. У него есть собственная система закупок — SAP SRM, Ariba, Coupa, Jaggaer или отраслевая надстройка над 1С, — в которой снабженец формирует заявку, а дальше идёт согласование по лимитам и центрам затрат. Если ваш каталог существует отдельно от этой системы, менеджеру заказчика приходится вручную переносить артикулы и цены из вашего интернет-магазина в свою заявку. Это долго, порождает ошибки и на практике заканчивается тем, что вы проигрываете конкуренту, который такую интеграцию уже сделал.

PunchOut (а в мире SAP — его реализация OCI, Open Catalog Interface) закрывает ровно эту боль: снабженец из своей системы закупок «проваливается» в ваш каталог на 1С-Битрикс, набирает корзину по персональным ценам и одним нажатием возвращает её обратно в заявку. Никакого двойного ввода, никаких ошибок в артикулах. Ниже — практический разбор, как устроен этот обмен и как его собрать на Битриксе: от архитектуры round-trip до полей протокола, аутентификации и возврата заказа в ERP. Это выжимка из наших проектов по разработке B2B-порталов на 1С-Битрикс — без общих слов.

Что такое PunchOut и OCI

PunchOut — это модель интеграции между системой электронных закупок покупателя (e-procurement) и каталогом поставщика. Название буквально означает «пробить наружу»: пользователь, находясь внутри своей закупочной системы, на секунду выходит наружу — в каталог поставщика, — работает там как в обычном интернет-магазине, а затем возвращается обратно, принося с собой собранную корзину. Ключевая идея в том, что каталог остаётся на стороне поставщика: покупатель всегда видит актуальные позиции, цены и остатки, а не выгруженный полгода назад прайс.

Существует два способа выгрузки товаров в закупочную систему: статический (поставщик отдаёт файл-каталог, который заказчик загружает к себе) и динамический, он же PunchOut. Статический каталог быстро устаревает и не умеет показывать персональные условия, поэтому для сложных номенклатур и контрактных цен применяют именно PunchOut. Поставщик держит один живой каталог, а условия под каждого клиента подставляются на лету.

OCI (Open Catalog Interface) — это конкретная спецификация PunchOut, разработанная SAP для интеграции с SAP SRM и модулем закупок SAP ERP. Она предельно прагматична: обмен идёт обычными HTTP-запросами, а корзина возвращается как HTML-форма с фиксированным набором скрытых полей. Именно за счёт простоты OCI стал де-факто стандартом в России и Европе — его поддерживают почти все закупочные системы, а реализовать приём и отдачу OCI-запросов можно на любой платформе, включая 1С-Битрикс.

Важно с самого начала различать три вещи. PunchOut — это концепция (round-trip между двумя системами). OCI — один из протоколов, реализующих эту концепцию (от SAP, на HTTP-формах). cXML PunchOut — другой протокол той же концепции (от Ariba, на XML-документах). Когда клиент говорит «нам нужен PunchOut», первым делом уточните, какой именно диалект использует его закупочная система: от этого зависит формат полей и способ обмена.

Зачем это клиенту и поставщику

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

Что получает покупатель (заказчик). Снабженец работает в привычном интерфейсе своей закупочной системы и не переносит данные руками. Заявка формируется из актуального каталога с правильными артикулами, поэтому исчезают ошибки ввода и пересорт. Все внутренние процедуры — согласование по бюджету, центрам затрат, лимитам — остаются в системе заказчика и не ломаются. Плюс полная прослеживаемость: каждая закупка привязана к контракту и проходит через корпоративный контроль.

Что получает поставщик (вы). Во-первых, вы попадаете в закупочный контур крупного клиента и становитесь «предпочтительным поставщиком» — заявки идут к вам, а не к конкуренту с ручным прайсом. Во-вторых, каталог остаётся под вашим контролем: цены, ассортимент и остатки вы меняете у себя, и клиент сразу видит актуальное. В-третьих, заказы приходят структурированными и уже с правильными артикулами, что резко снижает нагрузку на ваших менеджеров и ускоряет обработку.

• Меньше ручного труда с обеих сторон — нет двойного ввода номенклатуры и цен.
• Актуальность в реальном времени — каталог живёт у поставщика, а не в устаревшем выгруженном файле.
• Персональные условия — контрактные цены и ассортимент подставляются под каждого клиента автоматически.
• Меньше ошибок — артикулы, единицы измерения и ставки НДС передаются машинно, а не перепечатываются.
• Лояльность и «прилипание» — интегрированного поставщика меняют неохотно: переключение стоит клиенту новой интеграции.

Архитектура интеграции: round-trip

Технически PunchOut — это цикл из двух HTTP-переходов между системой закупок и вашим каталогом. Его удобно представлять как «туда и обратно» (round-trip), где у каждого шага своя роль. Разберём цикл по этапам на примере OCI.

1. Setup-запрос (вход). Пользователь в закупочной системе выбирает вашего поставщика из списка каталогов. Система отправляет на ваш заранее согласованный URL HTTP-запрос с параметрами: идентификатор пользователя и организации, пароль или токен, код контракта, язык, валюта и — важнейшее поле — HOOK_URL, адрес, на который позже нужно вернуть корзину.

2. Аутентификация и сессия. Ваш обработчик на Битриксе проверяет подпись/пароль запроса, находит по идентификатору профиль компании-клиента и создаёт временную сессию. С этого момента каталог работает в «режиме PunchOut»: он знает, кто пришёл, по какому контракту и куда возвращать корзину.

3. Работа в каталоге. Покупатель попадает в ваш каталог на Битриксе и работает как в обычном интернет-магазине: ищет товары, применяет фильтры, смотрит персональные цены, набирает корзину. Всё это — ваш штатный функционал витрины, просто с ограничениями и ценами под конкретный контракт.

4. Возврат корзины (выход). Покупатель нажимает «Оформить в закупку». Битрикс формирует ответ по всем позициям корзины и отправляет его на тот самый HOOK_URL. В OCI это HTML-форма со скрытыми полями, которая автоматически сабмитится в закупочную систему; в cXML — XML-документ PunchOutOrderMessage.

5. Заявка и согласование. Закупочная система принимает корзину, превращает её в позиции заявки и запускает свой внутренний процесс — согласование, проверку бюджета, выпуск заказа. На этом round-trip завершён; дальше заказ может прийти к вам уже отдельным каналом (по EDI, почтой или через обмен с вашей ERP).

Протокол OCI: поля и формат

OCI ценят за минимализм. Никаких сложных схем и SOAP-конвертов — только HTTP-запрос с параметрами на вход и HTML-форма со скрытыми полями на выход. Разберём обе стороны.

Входящий setup-запрос. Закупочная система вызывает ваш URL методом GET или POST и передаёт служебные параметры. Ключевые из них:

• USERNAME и PASSWORD — учётные данные для аутентификации PunchOut-сессии (обычно технические, не персональные).
• HOOK_URL — адрес, на который каталог должен вернуть корзину. Самое важное поле: без него round-trip не замкнётся.
• OCI_VERSION — версия интерфейса (например, 4.0), от неё зависит набор допустимых полей ответа.
• returntarget — как открыть возврат (в том же окне, в родительском фрейме). Влияет на то, куда сабмитить форму.
• Дополнительно передают язык, валюту и идентификатор контракта или пользователя — по ним вы определяете персональные условия.

Исходящий ответ с корзиной. Обратно OCI ждёт HTML-форму, в которой каждая позиция описана набором полей с индексом. По каждой строке корзины формируется группа полей вида NEW_ITEM-*[n]:

Индекс [n] нумерует позиции: первая строка корзины — [1], вторая — [2] и так далее. Задача вашего обработчика на Битриксе — обойти корзину и для каждой позиции сгенерировать полный комплект этих полей, а затем автоматически отправить форму на HOOK_URL клиентским JavaScript-сабмитом.

cXML PunchOut как альтернатива

Если клиент работает на SAP Ariba или Coupa, он с большой вероятностью попросит не OCI, а cXML PunchOut. Это протокол компании Ariba (ныне часть SAP), и он устроен принципиально иначе: вместо HTTP-форм с плоскими полями обмен идёт полноценными XML-документами.

Цикл тот же самый round-trip, но упакован в XML:

• PunchOutSetupRequest — входящий XML-документ вместо GET-параметров. Содержит блок аутентификации Credential, идентификаторы покупателя и адрес возврата BrowserFormPost.
• PunchOutSetupResponse — ваш ответ с URL стартовой страницы каталога, куда система направит браузер пользователя.
• PunchOutOrderMessage — исходящий XML с корзиной. Каждая позиция описана элементом ItemIn с вложенными ItemID, ItemDetail, ценой, единицей и классификацией (UNSPSC).

cXML строже и богаче OCI: он поддерживает классификаторы товаров, вложенную структуру, расширения через Extrinsic и цифровые подписи. Но и реализовать его сложнее — нужен разбор и генерация XML, обработка ошибок на уровне документа, поддержка версий cXML DTD. На Битриксе оба протокола делаются как обработчики на PHP, просто у cXML больше кода на парсинг и валидацию XML.

Практический вывод: закладывайте архитектуру так, чтобы «ядро» PunchOut (определение клиента, персональный каталог, сборка корзины) было общим, а протокольный слой (OCI-форма или cXML-документ) — сменным адаптером. Тогда подключение второго клиента на другом протоколе не потребует переписывать всё заново.

OCI против cXML — сравнение

Для большинства российских внедрений первым делают OCI: он проще, распространён среди клиентов на SAP и 1С, а порог входа минимальный. cXML добавляют, когда появляется клиент на Ariba или Coupa. Оба протокола прекрасно сосуществуют на одном каталоге, если протокольный слой вынесен в отдельный адаптер.

Сценарий закупки глазами покупателя

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

1. Открывает заявку в своей системе. Снабженец создаёт новую заявку на закупку и видит список доступных внешних каталогов — среди них ваш магазин на Битриксе.
2. Проваливается в ваш каталог. По клику система тихо отправляет setup-запрос, аутентифицируется, и в том же окне или во фрейме открывается ваша витрина — уже с персональными ценами под его контракт.
3. Ищет и подбирает товары. Работает как в обычном интернет-магазине: поиск, фильтры, карточки товаров, сравнение. Видит остатки и сроки поставки.
4. Набирает корзину. Добавляет позиции с нужным количеством. Здесь важна выверенная логика витрины — снабженцу нужно быстро найти повторяемую номенклатуру, а не «продающие» баннеры.
5. Возвращается в заявку. Нажимает «Перенести в закупку» — корзина уходит на HOOK_URL, окно каталога закрывается, и он снова в своей системе, но заявка уже заполнена позициями.
6. Отправляет на согласование. Дальше — внутренний процесс заказчика: проверка бюджета, подписи, выпуск заказа поставщику. Ваш каталог в этом уже не участвует.

Из этого сценария следует важный дизайн-принцип: витрина в режиме PunchOut должна быть заточена под быстрый повторный подбор, а не под импульсную розничную покупку. Снабженцу нужны быстрый поиск по артикулу, готовые списки заказов, прошлые корзины и понятные единицы измерения. Всё, что мешает быстро набрать заявку (лишние шаги, капризная авторизация, медленный фильтр), напрямую бьёт по вашей выручке.

Реализация в 1С-Битрикс

На платформе 1С-Битрикс PunchOut/OCI собирается как связка обработчиков поверх штатного торгового каталога и механики B2B-профилей. Никакого «коробочного модуля PunchOut» в поставке нет — это всегда разработка, но она опирается на готовые подсистемы платформы. Разберём, из каких частей состоит реализация.

1. Точка входа (входящий обработчик). Отдельный публичный скрипт или контроллер (например, /local/punchout/oci_login.php или маршрут через routing), который принимает setup-запрос. Его задачи: проверить учётные данные, найти профиль компании по идентификатору, сохранить HOOK_URL и параметры сессии, авторизовать технического пользователя и сделать редирект в каталог.

2. Привязка к профилю компании. Клиент в B2B-каталоге Битрикса — это, как правило, отдельный пользователь или компания с назначенным типом цены и группой. PunchOut-сессия связывается именно с этим профилем: от него берутся тип цены, доступные разделы каталога, склад и правила показа остатков.

3. Персональный каталог. Штатные компоненты каталога (catalog.section, catalog.smart.filter, sale.basket.basket) работают в контексте PunchOut-сессии и показывают цены и ассортимент под контракт. Здесь пригодится грамотно настроенный умный фильтр — снабженцу важно быстро отсекать номенклатуру.

4. Точка выхода (исходящий обработчик). Кнопка «Перенести в закупку» ведёт на скрипт, который обходит корзину пользователя (Bitrix\Sale\Basket), формирует по каждой позиции комплект OCI-полей (или XML для cXML) и рендерит самосабмитящуюся форму на сохранённый HOOK_URL.

5. Обмен заказами с ERP. Отдельно от round-trip настраивается канал получения финальных заказов, которые заказчик выпустил из своей системы. Обычно это стандартный обмен 1С-Битрикс с 1С:ERP по CommerceML или EDI, чтобы заказ автоматически попал в вашу учётную систему.

Технически ядро удобно вынести в модуль /local/modules/ или в /local/php_interface/, а протокольные адаптеры (OCI, cXML) — в отдельные классы, чтобы добавление нового клиента сводилось к настройке, а не к переписыванию. Все входящие и исходящие запросы обязательно логируются: при разборе проблем с заказчиком лог round-trip экономит дни переписки.

Как это выглядит в админке

Настройка PunchOut-клиента в админке Битрикса сводится к карточке контракта: реквизиты доступа, привязка к профилю цены и параметры протокола. Схематично интерфейс выглядит так:

В такой карточке администратор задаёт: учётные данные для аутентификации setup-запроса, тип цены и группу доступа (они определяют персональный каталог), протокол и его версию, а также при необходимости — маппинг единиц измерения и формат артикулов. Отдельно ведётся журнал обменов: когда пришёл setup-запрос, сколько позиций вернулось, был ли успешный round-trip. Этот журнал — первый инструмент диагностики при подключении нового заказчика.

Аутентификация и безопасность

PunchOut — это машинный обмен между двумя корпоративными системами, поэтому к безопасности требования выше, чем к обычной витрине. Разберём уровни защиты.

• Транспорт только по HTTPS. И setup-запрос, и возврат корзины идут по защищённому каналу. Никакого HTTP: в запросах передаются учётные данные и цены под контракт.
• Технические учётные данные. USERNAME/PASSWORD (в OCI) или shared secret в блоке Credential (в cXML) выдаются под конкретный контракт и хранятся на вашей стороне в защищённом виде. Компрометация пары не должна открывать доступ к чужим каталогам.
• Ограничение по IP. Setup-запросы разумно принимать только с известных адресов закупочной системы клиента — это отсекает попытки подобрать доступ снаружи.
• Короткоживущая сессия. PunchOut-сессия должна жить ограниченное время и не давать доступа к разделам вне персонального каталога. По завершении round-trip или таймауту сессия закрывается.
• Валидация HOOK_URL. Адрес возврата приходит извне, поэтому его нужно проверять по белому списку доменов клиента, чтобы корзину нельзя было отправить на подставной адрес.
• Изоляция каталогов. По идентификатору контракта пользователь видит только свой ассортимент и цены и не может «дотянуться» до данных другого заказчика подменой параметров.

Персональные цены и каталог под контракт

Главная ценность PunchOut для B2B — не сам обмен, а то, что каждый заказчик видит свои условия. Одна и та же гайка стоит для дистрибьютора одну цену, для разового заказчика — другую, а часть ассортимента вообще может быть скрыта. В 1С-Битрикс это реализуется штатными механизмами каталога, привязанными к PunchOut-сессии.

• Типы цен. Каждому контракту сопоставляется свой тип цены (или несколько с приоритетами). Setup-запрос определяет профиль, профиль — тип цены, и каталог показывает нужные цифры без «наценок на лету».
• Договорные цены на позицию. Для контрактов с фиксированной ценой на конкретные SKU удобно вести отдельную ценовую матрицу и подставлять её поверх базового типа цены.
• Ограничение ассортимента. Группа доступа контракта определяет, какие разделы и товары видны. Позиции вне контракта либо скрываются, либо показываются без возможности заказа.
• Остатки и склад. PunchOut-сессия может смотреть на конкретный склад отгрузки клиента, показывая реальные к нему остатки и сроки.
• Единицы и кратность. Для опта важна кратность отгрузки (упаковками, паллетами). Её тоже привязывают к профилю, чтобы снабженец не заказал «3 штуки» там, где отгрузка идёт коробами по 50.

Именно связка «идентификатор контракта → профиль → тип цены и ассортимент» превращает обычный интернет-магазин в полноценный B2B-каталог. Подробно механику персональных цен, договоров и лимитов мы разбираем в материале про интеграцию B2B-портала с ERP — PunchOut опирается ровно на эту же основу, добавляя к ней внешний вход из системы закупок.

Возврат корзины и заказ в ERP

Здесь важно чётко развести два потока, которые новички часто путают. PunchOut-корзина и финальный заказ — это разные вещи, и приходят они по разным каналам.

Поток 1 — корзина по round-trip. Собранная в вашем каталоге корзина возвращается в систему закупок заказчика. Это ещё не заказ, а «наполнение заявки». Внутри системы клиента она проходит согласование, и только после этого может стать заказом. На этом этапе в вашей ERP ничего не появляется.

Поток 2 — финальный заказ. После внутреннего согласования заказчик выпускает заказ поставщику. Он приходит к вам отдельным каналом: по EDI, через электронный документооборот (ЭДО), по email или напрямую в обмен с вашей учётной системой. Этот заказ и нужно завести в 1С/ERP для отгрузки и выставления документов.

Грамотная архитектура связывает оба потока: позиции корзины несут артикулы вашего каталога, поэтому пришедший позже финальный заказ по этим артикулам однозначно матчится с вашей номенклатурой и без ручной сверки попадает в ERP. Здесь и подключается стандартный обмен Битрикса с учётной системой.

Тестирование и подключение клиента

PunchOut почти никогда не заводится «с первого раза начисто»: слишком много параметров согласуется между двумя ИТ-командами. Поэтому внедрение строят как серию контролируемых тестов round-trip.

1. Согласуйте параметры на бумаге. До кода зафиксируйте: URL точки входа, метод и протокол (OCI/cXML), учётные данные, формат артикулов, справочник единиц измерения, валюту, версию интерфейса. Разночтения здесь — источник 80% проблем.
2. Поднимите тестовый контур. Разверните обработчик на стейджинге и получите доступ к тестовой системе закупок клиента (или к эмулятору OCI/cXML). Боевой каталог трогать рано.
3. Прогоните вход. Убедитесь, что setup-запрос проходит аутентификацию, находит профиль и открывает персональный каталог с правильными ценами.
4. Прогоните выход. Соберите тестовую корзину и проверьте, что она корректно возвращается на HOOK_URL и «ложится» в заявку клиента без потери полей и с правильными единицами.
5. Проверьте пограничные случаи. Пустая корзина, дробные количества, товары без цены по контракту, спецсимволы в наименованиях, длинные артикулы — всё это ломает неаккуратные реализации.
6. Зафиксируйте эталонный лог. Сохраните пример успешного round-trip как эталон. При будущих сбоях сравнение с ним быстро показывает, что изменилось.
7. Переведите на боевой контур. Только после зелёных тестов подключайте продакшн-каталог и реальный контракт, начав с ограниченного круга снабженцев.

От клиента на этих этапах нужны три вещи: доступ к тестовой закупочной системе, справочник соответствия артикулов и единиц, и контактное лицо со стороны ИТ, а не только закупок. Чем чище справочники с обеих сторон, тем быстрее и дешевле проходит подключение.

Частые ошибки при внедрении

• Не согласовали маппинг единиц измерения — каталог отдаёт «шт» и «кг», а система клиента ждёт коды по ISO (PCE, KGM), и позиции не принимаются.
• Забыли, что возвращается корзина, а не заказ — пытаются сразу писать заказ в ERP из round-trip и получают двойные заказы после согласования у клиента.
• Не экранировали входящие параметры и HOOK_URL — открытый редирект и XSS в точке входа PunchOut.
• Привязали PunchOut-сессию к обычному пользователю с логином и паролем — конфликт машинной и персональной авторизации, «слетающие» сессии.
• Не изолировали каталоги по контракту — подменой параметра один заказчик видит цены и ассортимент другого.
• Захардкодили протокол под одного клиента — подключение второго на cXML требует переписывать всё ядро.
• Не ведут лог обменов — при сбое у клиента невозможно понять, что именно ушло и вернулось, разбор растягивается на недели.
• Тестируют сразу на боевом каталоге и живом контракте — ошибки в ценах и артикулах уходят в реальные заявки заказчика.
• Игнорируют производительность витрины в режиме PunchOut — медленный фильтр и поиск бьют по скорости набора заявки и по вашей выручке.

Чек-лист внедрения

Сведём всё в практический список для приёмки PunchOut перед подключением реального заказчика:

1. Протокол определён. Выяснено, что использует система клиента — OCI или cXML PunchOut, — и зафиксирована версия интерфейса.
2. Точка входа готова. Обработчик setup-запроса принимает параметры, аутентифицирует, находит профиль и открывает персональный каталог.
3. Профиль и цены привязаны. Контракт связан с типом цены, группой доступа и складом; ассортимент под контракт изолирован.
4. Маппинг согласован. Единицы измерения, артикулы и валюта соответствуют справочникам клиента.
5. Точка выхода готова. Корзина корректно превращается в OCI-форму (или cXML) и возвращается на валидированный HOOK_URL.
6. Безопасность закрыта. HTTPS, IP-фильтр, экранирование ввода, короткая сессия, белый список доменов HOOK_URL.
7. Обмен с ERP настроен. Финальные заказы по EDI/ЭДО матчатся по артикулам и попадают в учётную систему.
8. Тесты пройдены. Успешный round-trip и пограничные случаи проверены на стейджинге, эталонный лог сохранён.

Вывод

PunchOut/OCI — это не «ещё один способ выгрузить прайс», а прямой вход в закупочный контур крупного клиента. Технически на 1С-Битрикс он собирается как связка входящего и исходящего обработчиков поверх торгового каталога и B2B-профилей: setup-запрос авторизует контракт, каталог показывает персональные цены, корзина возвращается в систему закупок, а финальный заказ приходит к вам отдельным каналом и ложится в ERP. Сделайте эти звенья аккуратно — согласуйте маппинг, изолируйте каталоги, закройте безопасность и вынесите протокол в сменный адаптер — и вы станете «предпочтительным поставщиком», которого не хотят менять из-за уже работающей интеграции.