План интеграций сайта: 1С, CRM и платежи без хаоса

1. Начинаем не с API, а с карты процессов

Главная ошибка интеграционных проектов — начинать с вопроса "какой эндпоинт дернуть?". Правильнее сначала описать бизнес-процесс: откуда появляется заявка, кто ее квалифицирует, когда создается заказ, где резервируется товар, в какой момент возникает платеж, что видит пользователь и где менеджер меняет статус. Только после этого становится понятно, какие системы участвуют в процессе и какие события должны между ними проходить.

Для типового проекта Enginx.ru мы строим карту сущностей: лид, контакт, компания, заказ, счет, платеж, отгрузка, акт, возврат, обращение в поддержку. У каждой сущности есть владелец и жизненный цикл. Например, CRM может владеть стадиями сделки, 1С — номенклатурой, ценами, остатками и закрывающими документами, платежный шлюз — фактом списания и возврата, а сайт — пользовательским сценарием и отображением статусов.

• Определите system of record: где хранится "истина" по клиенту, заказу, оплате и остаткам.
• Разделите synchronous UX и asynchronous back-office: пользователю нужен быстрый ответ, а учетные системы могут обновиться позже.
• Зафиксируйте владельца каждого статуса: сайт не должен сам придумывать, что заказ "выполнен", если это решает 1С.

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

2. 1С УТ/ERP: учетный контур и его ограничения

В российских проектах 1С УТ или 1С ERP часто является самым важным и самым консервативным участником интеграции. Там живут номенклатура, характеристики, цены, скидки, остатки, контрагенты, счета, реализации, возвраты и закрывающие документы. Сайту может казаться, что ему нужен "просто каталог", но на практике каталог включает единицы измерения, НДС, разные типы цен, доступность по складам, архивные позиции и правила округления.

Интеграция с 1С бывает файловой, через HTTP-сервисы, OData, обмен по расписанию или через промежуточный слой. У каждого варианта есть цена. Прямой синхронный запрос из сайта в 1С прост на схеме, но опасен в продакшене: 1С может быть недоступна ночью во время регламентных операций, отвечать медленно под нагрузкой или возвращать данные в формате, удобном бухгалтерии, но не фронтенду. Поэтому мы часто проектируем буферный слой: сайт работает с собственным API и базой, а обмен с 1С идет асинхронно и контролируемо.

1С не должна становиться "онлайн API для всего". В хорошей архитектуре она остается учетным ядром, а быстрый пользовательский интерфейс обслуживает отдельный backend-слой.

3. CRM: Bitrix24 и amoCRM как контур продаж

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

Перед подключением CRM мы согласуем, что считается лидом, когда создается сделка, какие поля обязательны, как определяется источник, какие UTM сохраняются, где происходит дедупликация и кто владеет изменением стадий. Если этого не сделать, маркетинг увидит красивые цифры отправки форм, менеджеры получат мусор, а руководство не сможет связать рекламные расходы с выручкой.

• Для Bitrix24 заранее проверяйте лимиты REST API, права вебхуков и структуру пользовательских полей.
• Для amoCRM особое внимание уделяйте OAuth, сроку жизни токенов и обновлению access token без ручного участия.
• Для обеих CRM критична дедупликация по телефону, email, ИНН и внешнему идентификатору сайта.

4. Платежи: YooKassa, Тинькофф и жизненный цикл денег

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

Для российских проектов важно учитывать онлайн-кассы, чеки, НДС, признак предмета расчета, способы оплаты, возвраты, рекуррентные списания, корпоративные платежи и требования бухгалтерии. Платеж "успешен" для пользователя и платеж "корректно отражен в учете" — не всегда один и тот же момент. Поэтому мы проектируем отдельные статусы: payment_created, payment_pending, payment_succeeded, fiscalization_pending, fiscalized, accounting_synced, refund_requested, refund_succeeded.

• Всегда храните внешний payment_id и внутренний order_id, не полагаясь только на сумму и email.
• Проверяйте подпись вебхука и источник запроса, особенно для событий изменения статуса.
• Не считайте оплату завершенной до подтвержденного статуса от провайдера.
• Проектируйте возвраты сразу: это не "редкая операция", а часть финансового жизненного цикла.

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

5. Вебхуки, очереди и идемпотентность

Вебхуки — это не гарантированная "магическая доставка". Провайдер может отправить событие повторно, сайт может ответить 500, сеть может оборваться, а обработчик может упасть посередине. Поэтому любой входящий вебхук должен быть записан в журнал до бизнес-обработки. Сначала сохраняем raw payload, headers, источник, время получения и id события. Затем валидируем подпись, вычисляем идемпотентный ключ и передаем событие в обработчик.

Идемпотентность означает, что повтор одного и того же события не меняет результат сверх первого успешного применения. Если YooKassa отправила payment.succeeded дважды, система должна один раз отметить заказ оплаченным, один раз отправить письмо, один раз поставить задачу на синхронизацию с 1С и один раз выдать доступ. Для этого нужны уникальные ключи, транзакции, блокировки на уровне бизнес-сущности и журнал побочных действий.

• Храните статус обработки каждого события: received, validated, processing, processed, failed, ignored.
• Разделяйте технические ошибки и бизнес-отказы: "CRM недоступна" и "не найден клиент" требуют разных действий.
• Сделайте админский экран для повторной обработки событий, иначе поддержку ждет работа в базе данных.

6. Saga-паттерны для длинных операций

Когда операция затрагивает несколько систем, классическая транзакция уже не помогает. Нельзя открыть одну ACID-транзакцию на сайт, 1С, CRM и платежный шлюз. Поэтому используется подход saga: процесс разбивается на последовательность локальных шагов, каждый шаг фиксируется отдельно, а для ошибок описываются компенсирующие действия. Например: создать заказ на сайте, создать платеж, получить оплату, создать сделку в CRM, отправить заказ в 1С, выдать доступ. Если CRM недоступна, заказ и оплата не откатываются, но появляется задача на повторную доставку и предупреждение ответственному.

Saga важна для сценариев, где деньги уже списаны, а учетная система временно недоступна. В плохой архитектуре пользователь видит ошибку и платит повторно. В хорошей архитектуре он видит честный статус: "Оплата получена, заказ синхронизируется. Мы пришлем подтверждение". Внутри система продолжает повторять шаги, а поддержка видит, где процесс застрял.

• Описывайте saga как диаграмму состояний, а не только как код.
• Для каждого шага задайте retry policy, timeout и владельца ручного разбора.
• Компенсация не всегда означает автоматический rollback: иногда это задача менеджеру или возврат платежа после проверки.

Saga-подход особенно полезен для B2B: счета, договоры, лимиты и отгрузки редко укладываются в одну мгновенную операцию.

7. Staging-стратегия: тестировать нужно всю цепочку

Интеграции нельзя качественно проверить только моками. Моки полезны на ранней разработке, но перед релизом нужен staging-контур: тестовая 1С или отдельная база, sandbox YooKassa/Тинькофф, тестовый портал Bitrix24 или amoCRM, отдельные ключи, отдельные домены вебхуков и контрольные сценарии. Иначе команда узнает о несовместимости форматов уже на боевом заказе.

Staging должен быть максимально похож на production по инфраструктуре, но безопасно отделен по данным. Нельзя отправлять тестовые чеки реальным клиентам, менять боевые сделки или создавать документы в рабочей 1С. При этом на staging нужно воспроизводить ошибки: просроченный токен CRM, недоступность 1С, повторный вебхук, платеж с отказом банка, частичный возврат, неверная подпись, дубль заказа.

• Заведите отдельные секреты и запретите использовать production-токены на staging.
• Подготовьте тестовые ИНН, товары, счета, карты и сценарии возврата.
• Перед каждым релизом прогоняйте smoke-тесты по главным цепочкам: заявка, заказ, оплата, CRM, 1С, уведомления.

8. Ошибки и ручной разбор: проектируем заранее

Интеграция без ошибок существует только в презентации. В реальности токены истекают, лимиты API заканчиваются, пользователи вводят странные реквизиты, менеджеры меняют поля в CRM, 1С закрывается на обслуживание, банк отклоняет платеж, а вебхук приходит позже, чем пользователь обновил страницу. Поэтому error handling — это часть функциональных требований.

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

Хорошая интеграция не обещает, что ошибок не будет. Она гарантирует, что ошибка не потеряется и не превратится в хаос для клиента.

9. Мониторинг и наблюдаемость

После релиза главный вопрос меняется: не "работает ли код", а "видим ли мы, что происходит". Для интеграций нужны метрики, логи, трассировка и алерты. Минимум: количество входящих вебхуков, процент успешной обработки, размер очереди, возраст самой старой задачи, ошибки по провайдерам, время ответа 1С/CRM, количество ручных разборов, расхождения оплат и заказов.

Логи должны быть структурированными: correlation_id, order_id, payment_id, crm_deal_id, onec_document_id, user_id, integration_name, event_type. Тогда один инцидент можно проследить от клика пользователя до платежного вебхука и документа в 1С. Без корреляции команда тратит часы на поиск "того самого заказа".

• Aлерт нужен не на каждую ошибку, а на нарушение бизнес-SLO: очередь старше 10 минут, платежи без заказа, рост failed-событий.
• Дашборд должен быть понятен менеджеру проекта и поддержке, не только backend-разработчику.
• Раз в неделю полезно смотреть отчет по ручным разборам: он показывает, где автоматизацию нужно усилить.

10. Российская специфика: документы, персональные данные и операционная реальность

Российский рынок добавляет к интеграциям практические ограничения. Нужно учитывать 152-ФЗ и локализацию персональных данных, онлайн-кассы, НДС, фискальные чеки, юридические реквизиты, ЭДО, закрывающие документы, разные банковские сценарии, работу с самозанятыми и юридическими лицами. Для B2B-порталов часто важнее не "красивый checkout", а корректный счет, договор, лимит, отгрузка, акт и история согласований.

Отдельная тема — эксплуатация 1С. В компании может быть несколько баз, разные подрядчики по сопровождению, регламентные задания, ручные доработки конфигурации и ограничения на доступ извне. Это нужно выяснить до оценки сроков. Иногда интеграционный слой проще и безопаснее делать через промежуточный сервис, который говорит с 1С по согласованному протоколу и не заставляет публичный сайт зависеть от внутренней сети.

• Проверьте, где хранятся персональные данные и кто имеет к ним доступ.
• Согласуйте юридически значимые статусы: счет выставлен, оплачен, документ подписан, возврат выполнен.
• Заранее определите, кто отвечает за изменения в 1С-конфигурации и тестовую базу.

11. План внедрения: от discovery до сопровождения

Практичный план интеграций начинается с discovery: интервью с продажами, бухгалтерией, логистикой, поддержкой и ИТ. Затем появляются карта процессов, модель данных, список систем, контракты API, диаграмма статусов, стратегия staging, план миграции данных и критерии приемки. Только после этого разработка становится прогнозируемой.

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

• Discovery: процессы, владельцы, системы, ограничения, риски.
• Architecture: data model, API contracts, queues, idempotency, saga states.
• Implementation: adapters, admin tools, tests, monitoring, staging.
• Launch: smoke-тесты, rollback-план, дежурство, отчет по первым событиям.
• Support: SLA, разбор ошибок, улучшение автоматизации, новые сценарии.

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