API и вебхуки: связать CRM с 1С, сайтом и аналитикой своими силами
Ключ API даёт вашей программе прямой доступ к данным пространства по HTTP: читать, создавать и обновлять записи. Вебхуки — обратное направление: CRM сама сообщает вашей системе, что произошло. Подпись, журнал доставок и честный список того, чего в первой версии нет.
У Ани автосервис. Заказ-наряды живут в CRM, бухгалтерия — в 1С, а между ними работает Костя: раз в неделю
он выгружает одно, открывает другое и переносит руками. Ошибается редко, но метко — то контрагент
задвоится, то оплата не доедет.
Просьба «сделайте нам интеграцию» обычно упирается в одно: интеграция есть, но её продаёт кто-то третий,
за отдельные деньги и со своим сроком. У нас другой ответ: вы получаете ключ, и дальше ваш программист
или знакомый подрядчик делает обмен сам — на обычном HTTP, по опубликованной схеме.
Что меняется
Перенос руками
CraftYourCRM
Кто делает обмен
сотрудник по расписанию
ваша программа, сама
Доступ для программы
чей-то личный логин
отдельный ключ с ограниченными правами
Утёк доступ
меняют пароль человеку
отзывают один ключ, остальное работает
Повтор при обрыве связи
задвоенные записи
тот же ответ, второй записи нет
«Что изменилось со вчера»
выгружают всё заново
запрос за изменения с момента
Реакция на событие
узнают на следующей выгрузке
CRM сама вызывает ваш адрес
Ключ — это пароль для программы
Ключи живут в «Настройки → API и вебхуки». Выпустить ключ может владелец или администратор
пространства — рядовому сотруднику этот раздел не откроется.
При выпуске вы отвечаете на три вопроса:
Новый ключ API
┌──────────────────────────────────────────────────────────────┐
│ Название Обмен с 1С │
│ Что разрешено ☑ Просмотр записей │
│ ☑ Создание и изменение записей …и другие │
│ Срок действия 90 дней ▼ │
└──────────────────────────────────────────────────────────────┘
cyc_live_3f9a1c04e8… ← показывается ОДИН раз
Название нужно вам: по нему вы через полгода поймёте, какую интеграцию отключаете. Права — тот же
список, что у ролей сотрудников; по умолчанию отмечен только «Просмотр записей». Срок предлагается на
90 дней, чтобы утёкший ключ не жил вечно; бессрочный оставляйте только для того, за чем следите.
Три вещи про безопасность стоит знать сразу. Ключ показывается ровно один раз — в базе лежит не он, а
его отпечаток, поэтому «покажите ещё раз» технически невозможно. Ключ не получит прав больше, чем есть
у того, кто его выпустил: лишнее отклоняет сервер, а не только форма. Отзыв срабатывает мгновенно —
отозванность проверяется на каждом запросе.
Что программа может делать вашими данными
Адрес обмена — /api/v1, ключ передаётся заголовком Authorization: Bearer. Ни cookie, ни отдельного
«входа» программе не нужно.
Доступны записи ваших разделов — тех самых, которые вы собрали в конструкторе: карта разделов и
полей, список записей страницами, сложная выборка с фильтрами, чтение одной записи, создание, изменение,
удаление и пакетная запись до ста строк за вызов.
Схема со всеми параметрами открыта на /api/v1/openapi.json и листается в браузере на /api/v1/docs —
без ключа и без регистрации. Это контракт: подрядчику достаточно дать ссылку.
Темп ограничен честно: 300 запросов в минуту на ключ и 3000 записываемых строк в минуту. Живой
обмен потолка не замечает: полная выгрузка двух тысяч записей страницами по сто — это двадцать запросов.
Обмен, который не теряет и не задваивает
Три механизма, из-за отсутствия которых самодельные обмены обычно и ломаются.
«Что изменилось с момента». Запрос с updated_since отдаёт только то, что менялось после указанного
времени, — перечитывать базу целиком каждый цикл не нужно. Добавьте include_deleted, и приедут
«надгробия» удалённых записей: ваша копия узнает не только о новом, но и об исчезнувшем.
Повтор не задваивает. Создание записи с заголовком Idempotency-Key при повторе после обрыва связи
вернёт тот же самый ответ, а второй записи не появится. Ключи помнятся сутки. Тот же ключ с другим
телом запроса мы не примем: тихо подменять ответ нельзя.
Адресация по вашему идентификатору. Обновлять запись можно не по нашему номеру, а по своему внешнему
ключу — тогда таблицу соответствий «наш id ↔ ваш id» держать не нужно вовсе. Нет записи — создастся,
есть — обновится слиянием: присылаете только те поля, которыми владеете, а стадию и ответственного
продолжает вести менеджер в CRM.
И про конфликты: у каждой записи есть версия, и изменение требует указать ту, которую вы видели. Успели
поменять раньше вас — придёт отказ с просьбой перечитать, а не молчаливое затирание чужой правки.
Вебхуки: CRM сама звонит вашей программе
Обратное направление. Вы добавляете адрес на своей стороне, готовый принимать сообщения, и
указываете, что именно на него уезжает:
«Только ссылка на запись» (так по умолчанию) — событие, раздел, номер записи и её версия. Данных
записи в сообщении нет вовсе: нужные поля программа дочитает через API своим ключом, и персональные
данные периметр не покидают;
«Полные данные записи» — удобнее, но это осознанный вынос содержимого записи на чужой сервер.
Какие события уедут на адрес, решает правило автоматизации — это главное, что нужно понять про наши
вебхуки. Собственной подписки «шли мне всё про сделки» у адреса нет; вместо неё вы заводите правило
«Когда → Если → То» с действием «Вызвать вебхук» и получаете то, чего подписка не умеет: «только
сделки дороже ста тысяч», «только при переходе в стадию Готово». Пока правила нет, адрес молчит.
Событий пять: запись создана, изменена, удалена, правило сработало не от правки записи (наступила дата,
отработало расписание) и тестовое — его шлёт кнопка «Отправить тестовое событие», чтобы проверить
приёмник заранее.
Подпись, повторы и журнал
POST https://obmen.anin-service.ru/hooks/crm
webhook-id: 1f3c7e58-9a2b-4e01-8f6d-2c5a91b7e004
webhook-timestamp: 1786012932
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{"event":"record.created","entity":"deal","record_id":1001,
"version":1,"occurred_at":"2026-08-09T09:22:12+00:00","tenant":42}
Подпись. Каждое сообщение подписано секретом вашего адреса — получатель проверяет, что событие
действительно от нас. Схема стандартная (Standard Webhooks), готовая библиотека проверки есть почти на
любом языке. Секрет, в отличие от ключа API, можно посмотреть повторно: он вычисляется из мастер-ключа
сервера и в базе не хранится. Смена секрета проходит без простоя — двое суток мы отправляем и новую
подпись, и предыдущую.
Повторы. Ваш сервер полежал — событие не пропадёт: даётся восемь попыток с растущей паузой
(первая через полминуты, дальше вдвое реже, но не реже раза в час), и это перекрывает несколько часов
недоступности. Успехом считается любой ответ 2xx; на «временно не могу» мы вернёмся, на «запрос
отклонён» — нет. За переадресациями не ходим: ответ-редирект считается провалом доставки.
Журнал. По каждому адресу видно все попытки — время, номер попытки, код ответа, человеческая причина
сбоя («получатель не ответил за отведённое время») и длительность. Оттуда же — кнопка
«Переотправить». Журнал хранится 30 дней.
Куда мы не пойдём по вашему адресу
Адрес вводите вы, а запрос по нему делает наш сервер — это классическая дыра, через которую в чужих
системах достают внутренние службы. Поэтому проверки срабатывают и при сохранении адреса, и перед
каждой отправкой: только https, без логина-пароля внутри ссылки, только адрес, доступный из
интернета — на внутреннюю сеть, на localhost и на служебные адреса облаков мы не ходим. Отказ
объясняется по-человечески: «домен ведёт во внутреннюю сеть», а не «ошибка 400».
Кому это нужно в первую очередь
Торговле и складам — где номенклатура ведётся в учётной системе, а работа с клиентом в CRM, и обе
половины обязаны видеть одно и то же. Компаниям с обменом по документам — тем, у кого 1С считает
деньги, а CRM ведёт сделку. Всем, у кого есть сайт или личный кабинет, — заявку удобнее класть прямо
в воронку. Тем, кто строит отчётность вовне, — выгрузка в аналитику это ключ только на чтение и один
запрос по расписанию.
Сколько это стоит
Сам API бесплатен. Как и везде у нас, платный тариф продаёт объём, а не доступ к возможности: на
бесплатном тарифе у пространства один ключ и один адрес вебхука, на «Расти» — по десять. Ни
«коннектора» за отдельные деньги, ни платы за вызов, ни обязательного партнёра-внедренца у нас нет.
Честные ограничения
Ключи, права, публичный API, вебхуки с подписью и журнал доставок работают полностью. Границы первой
версии называем поимённо — чтобы подрядчик узнал о них до оценки, а не после.
Через API доступны только записи разделов. Файлы, документы, чат и календарь своих адресов в
публичном API не имеют. Права на них ключу выдать можно, но на /api/v1 они сегодня не влияют — это
задел, а не работающая возможность.
Права ключа не делятся по разделам. Ключ умеет «читать записи» и «изменять записи» — целиком по
пространству. Ключа «только на раздел Клиенты» пока нет, поэтому отдавать ключ наружу стоит с той же
осторожностью, что доступ администратора.
Порядок доставки вебхуков не гарантирован. Повторы сдвигают время, и изменение третьей версии
может прийти раньше второй. В сообщении есть номер версии — применяйте событие, только если версия
больше уже применённой.
Мёртвый адрес мы не выключаем сами. Исчерпались восемь попыток — доставка помечается
несостоявшейся и остаётся в журнале, но адрес продолжает работать: следить за журналом придётся вам.
Ключ нельзя изменить и нельзя перевыпустить. Ни права, ни срок после выпуска не правятся; забыли
сохранить или подозреваете утечку — выпускаете новый и отзываете старый. Ротация есть только у секрета
вебхука.
Тестового контура нет. Ключ работает с вашими боевыми данными — отлаживайте обмен на записи,
которую не жалко.
Входящих вебхуков нет. Направление «ваша система сообщает нам» — это обычные запросы публичного
API вашим ключом; отдельного приёмника чужих событий мы не строим.
Что дальше
Настройте правило, которое будет вызывать ваш адрес, — правила автоматизации;
разберитесь, кому в команде вообще открывать этот раздел, — роли и права; если
данные нужно перенести один раз, а не обменивать постоянно, начните с
импорта из Excel — он не требует ни программиста, ни ключа.