API и вебхуки: связать CRM с 1С, сайтом и аналитикой своими силами

У Ани автосервис. Заказ-наряды живут в CRM, бухгалтерия — в 1С, а между ними работает Костя: раз в неделю он выгружает одно, открывает другое и переносит руками. Ошибается редко, но метко — то контрагент задвоится, то оплата не доедет.

Просьба «сделайте нам интеграцию» обычно упирается в одно: интеграция есть, но её продаёт кто-то третий, за отдельные деньги и со своим сроком. У нас другой ответ: вы получаете ключ, и дальше ваш программист или знакомый подрядчик делает обмен сам — на обычном HTTP, по опубликованной схеме.

Что меняется

Ключ — это пароль для программы

Ключи живут в «Настройки → API и вебхуки». Выпустить ключ может владелец или администратор пространства — рядовому сотруднику этот раздел не откроется.

При выпуске вы отвечаете на три вопроса:

  Новый ключ API
  ┌──────────────────────────────────────────────────────────────┐
  │ Название        Обмен с 1С                                   │
  │ Что разрешено   ☑ Просмотр записей                           │
  │                 ☑ Создание и изменение записей     …и другие │
  │ Срок действия   90 дней                          ▼           │
  └──────────────────────────────────────────────────────────────┘

  cyc_live_3f9a1c04e8…      ← показывается ОДИН раз

Название нужно вам: по нему вы через полгода поймёте, какую интеграцию отключаете. Права — тот же список, что у ролей сотрудников; по умолчанию отмечен только «Просмотр записей». Срок предлагается на 90 дней, чтобы утёкший ключ не жил вечно; бессрочный оставляйте только для того, за чем следите.

Три вещи про безопасность стоит знать сразу. Ключ показывается ровно один раз — в базе лежит не он, а его отпечаток, поэтому «покажите ещё раз» технически невозможно. Ключ не получит прав больше, чем есть у того, кто его выпустил: лишнее отклоняет сервер, а не только форма. Отзыв срабатывает мгновенно — отозванность проверяется на каждом запросе.

Что программа может делать вашими данными

Адрес обмена — /api/v1, ключ передаётся заголовком Authorization: Bearer. Ни cookie, ни отдельного «входа» программе не нужно.

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

  GET /api/v1/records/deal?updated_since=2026-08-09T06:00:00Z&limit=100
  Authorization: Bearer cyc_live_3f9a1c04e8…

  → 200  { "records": [ … ], "next_cursor": "…" }

Схема со всеми параметрами открыта на /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 — он не требует ни программиста, ни ключа.