API-интеграция: как связать сайт, CRM, 1С и оплату без ручного переноса

API-интеграция это связь между программами, при которой одна система сама отправляет запросы другой и получает ответ без участия человека. Сайт передаёт заявку в CRM, CRM создаёт заказ в 1С, платёжный сервис сообщает об оплате. Чтобы такая связь работала годами, мало «подключить API»: нужно правильно выдать и хранить ключи, учесть лимиты запросов, обработать ошибки и следить за обменом после запуска. Ниже разберём всё это простыми словами и на примерах из небольшого бизнеса.

Что такое API-интеграция простыми словами

API (Application Programming Interface) это набор правил, по которым к программе можно обратиться из другой программы. Похоже на окно выдачи: вы не заходите на кухню, а отдаёте заказ по форме и получаете результат. Программа сама решает, что разрешено: получить список заказов, создать сделку, узнать статус оплаты.

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

Способ	Как выглядит	Скорость	Главный риск
Вручную	Менеджер копирует заявку с почты в CRM, а потом в 1С	Когда дойдут руки	Опечатки, пропуски, потерянные заявки
Файлом	Выгрузка из одной системы, загрузка в другую раз в день	Раз в сутки или реже	Устаревшие данные, ручной шаг
По API	Система сама отправляет запрос и проверяет ответ	Секунды или минуты	Без журнала ошибок сбой можно не заметить

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

Из чего состоит запрос к API

Любой запрос к современному веб-API состоит из четырёх частей: адреса, метода, заголовков и тела. Ответ состоит из кода и тела. Если понимать эти части, проще разговаривать с разработчиком и читать документацию сервисов.

• Адрес (эндпоинт). Куда обращаемся: например, раздел сделок в CRM или раздел платежей в платёжном сервисе.
• Метод. Что хотим сделать: получить, создать, изменить или удалить.
• Заголовки. Служебные данные, главное из них ключ или токен доступа.
• Тело. Сами данные, чаще всего в формате JSON: это текст из пар «название поля: значение».

Так может выглядеть тело запроса, который сайт отправляет в CRM после заявки (пример, названия полей у каждой системы свои):

{ "name": "Ирина", "phone": "+7 900 000-00-00", "source": "форма на странице доставки", "comment": "нужен расчёт на 3 точки" }

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

Методы: что можно делать через API

Методы говорят системе, какое действие выполнить. В большинстве веб-API их четыре основных, и по ним легко понять, что умеет интеграция.

Метод	Действие	Пример	Можно ли безопасно повторить
GET	Получить данные	Узнать статус оплаты или остатки на складе	Да, данные не меняются
POST	Создать запись	Создать сделку из заявки, создать платёж	Нет, без защиты появится дубль
PATCH или PUT	Изменить запись	Перевести сделку в статус «Оплачено»	Обычно да, если передаётся итоговое значение
DELETE	Удалить запись	Убрать отменённый товар из заказа	Зависит от системы

Последний столбец важен. Если связь оборвалась и непонятно, дошёл ли запрос, повтор GET ничего не испортит, а повтор POST может создать вторую сделку или второй платёж. О том, как от этого защищаются, ниже в разделе об ошибках.

Ключи и токены: как устроен доступ

Ключ API это пароль для программы: по нему система понимает, кто обращается и что ему разрешено. Сервисы выдают доступ по-разному.

• Постоянный ключ. Длинная строка, которую создают в настройках сервиса. Действует, пока её не отзовут.
• Идентификатор и секретный ключ. Например, в API ЮKassa идентификатор магазина передаётся как имя пользователя, а секретный ключ как пароль.
• Токены OAuth. Пользователь разрешает доступ приложению, а оно получает токен с ограниченным сроком и обновляет его само.
• Адрес со встроенным ключом. Некоторые CRM дают готовую ссылку для входящих запросов. Её нужно беречь так же, как пароль.

Правила хранения одинаковы для всех вариантов:

1. Ключ лежит только на сервере, в настройках окружения. Никогда в коде страницы, который видит браузер, и никогда в общем чате.
2. У каждой интеграции свой ключ с минимальными правами. Если сайту нужно только создавать сделки, удалять он не должен.
3. Ключи оформлены на учётную запись компании, а не на личный аккаунт подрядчика или сотрудника.
4. Есть список: какой ключ, где используется, кто выпустил, когда истекает.
5. Когда уходит сотрудник или меняется подрядчик, ключи перевыпускают.

Лимиты: сколько запросов можно отправить

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

Сервис	Что сказано в документации	Что будет при превышении
amoCRM	Не более 7 запросов в секунду на одну интеграцию и до 50 на аккаунт	Ответ 429; при повторных нарушениях блокировка с ответом 403 на любой запрос
Битрикс24, облако	Счётчик запросов уменьшается на 2 в секунду, порог 50 (на тарифе Энтерпрайз 5 и 250); запрос должен уложиться в 60 секунд	Ответ 503 с кодом QUERY_LIMIT_EXCEEDED; для тяжёлых методов отдельный лимит по времени и ответ 429

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

Ошибки и коды ответов: что делать с каждым

Код ответа подсказывает, что случилось и стоит ли повторять запрос. Коды начинаются с цифры, которая обозначает класс: 2 значит успех, 4 ошибку в самом запросе, 5 сбой на стороне сервиса.

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

Три правила, которые чаще всего упускают:

• Пауза растёт. Если сервис ответил 429 или 503, повтор через секунду только продлит проблему. Пауза увеличивается с каждой попыткой. Если в ответе есть заголовок Retry-After, ждите столько, сколько он говорит.
• Повтор без дублей. Для создания записей используют ключ идемпотентности: уникальную метку операции. Например, ЮKassa принимает её в заголовке Idempotence-Key и в течение 24 часов на повтор с тем же ключом возвращает результат первого запроса, а не создаёт второй платёж.
• Код 500 не всегда значит «не получилось». В документации ЮKassa прямо сказано, что 500 не говорит об успехе или неуспехе операции. Сначала узнайте статус, потом решайте, повторять ли.

Как связать сайт, CRM, 1С и оплату: пример схемы

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

Поток	Откуда и куда	Когда	На что обратить внимание
Заявка	С сайта в CRM	Сразу после отправки формы	Проверка дублей по телефону, источник заявки
Платёж	С сайта в платёжный сервис	Когда клиент нажал «Оплатить»	Ключ идемпотентности, сумма и состав заказа
Статус оплаты	Из платёжного сервиса на сайт и в CRM	По уведомлению о событии, плюс сверка	Проверка статуса запросом к API, а не только по уведомлению
Заказ и документы	Из CRM в 1С	Когда сделка оплачена	Справочники товаров и контрагентов должны совпадать
Остатки и цены	Из 1С на сайт	По расписанию, например раз в час	Пачки и очередь, если товаров много

У 1С:Предприятия есть автоматический REST-интерфейс по протоколу OData, его включают при публикации базы на веб-сервере. Будет ли он доступен у вас, зависит от конфигурации и того, где работает база: в облаке или на своём сервере. Это выясняют до оценки проекта вместе с тем, кто сопровождает вашу 1С.

Уведомления о событиях, как в строке про статус оплаты, обычно приходят вебхуками: сервис сам отправляет запрос на ваш адрес, когда что-то произошло. Это дополняет API, а не заменяет его.

Сколько экономит интеграция по API

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

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

Сопровождение: что происходит после запуска

API-интеграция это не разовая настройка. Сервисы выпускают новые версии API, меняют поля и правила, истекают токены, уходят сотрудники с доступами. Без присмотра интеграция однажды тихо перестанет работать, и вы узнаете об этом от клиента.

• Журнал обмена. Каждый запрос с временем, кодом ответа и номером записи. Без него непонятно, где потерялась заявка. Что именно писать в журнал и как настроить оповещения, разобрано в статье о журнале ошибок интеграции.
• Оповещения. Если обмен остановился или ошибок стало больше обычного, ответственный узнаёт в течение минут.
• Контрольная сверка. Раз в сутки сравнить количество заявок на сайте и в CRM, оплат в платёжном сервисе и в учёте.
• Изменения API. Кто-то читает новости сервисов и проверяет интеграцию после обновлений. Как к этому подготовиться, рассказано в статье об изменениях API внешних сервисов.
• Документация. Схема потоков, список полей, список ключей. Чтобы новый разработчик разобрался за день, а не за месяц.

Удобнее всего, когда за всё это отвечает один человек или подрядчик со сроками реакции в договоре. Так интеграция остаётся рабочей частью бизнеса, а не проектом, о котором вспоминают при аварии.

С чего начать: пять шагов к первой интеграции

1. Найдите самый болезненный поток. Где больше всего ручного копирования или потерь: заявки, заказы, оплаты, остатки.
2. Проверьте документацию. Есть ли у обеих систем нужные методы, какие лимиты и как выдаётся доступ. Иногда нужный метод доступен только на старшем тарифе.
3. Опишите поток. Какие поля передаются, какая система главная по каждому полю, что делать с дублями и ошибками.
4. Сделайте первую версию на одном потоке. С журналом и оповещениями с первого дня, а не «потом допишем».
5. Примите на контрольных примерах. Обычная запись, запись с ошибкой, повтор, недоступность одной из систем. Только после этого подключайте следующий поток.

Чек-лист: готова ли интеграция к запуску

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

Типичные ошибки

• Ключ в коде страницы. Любой посетитель может его увидеть и получить доступ к вашей CRM.
• Один ключ на всё с полными правами. Утечка одного ключа открывает все данные.
• Доступы на личном аккаунте подрядчика. Ушёл подрядчик, остановилась интеграция.
• Повторы без паузы. Интеграция сама себя блокирует по лимитам.
• Повторы POST без ключа идемпотентности. Дубли сделок и платежей.
• Нет журнала и оповещений. О сбое узнают через неделю по жалобе клиента.
• Нет сверки. Пропущенные записи копятся незаметно.
• Никто не следит за новостями сервисов. Старая версия API отключилась, обмен встал.