10. ТЗ на коннекторы топ-5 сервисов

Версия: 0.1 Дата: 18.10.2026 Основание: главная страница Albato (albato.ru) и её блоки «Новые интеграции». На главной продвигаются, в частности: Tilda → Битрикс24, Google Sheets → Telegram, amoCRM, Telegram, VK, Яндекс Формы. Для первой волны выбраны пять сервисов, которые чаще всего встречаются в этих сценариях и в каталоге easy-connect:

1. Tilda — источник заявок.
2. Bitrix24 — приёмник лидов/сделок и источник CRM-событий.
3. amoCRM — приёмник лидов/сделок и источник CRM-событий.
4. Telegram — приёмник уведомлений и источник сообщений.
5. Google Sheets — приёмник строк и источник новых строк.

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

---

1. Сводная матрица

---

2. Общие требования к коннекторам

2.1. Контракт

Каждый коннектор реализует манифест и методы из 06-connectors.md:

• auth: OAuth 2.0 / token / bot_token / webhook;
• triggers: типы webhook, polling, schedule;
• actions: одно действие = одна функция;
• outputSchema / inputSchema с типами и semantic;
• allowedHosts и rate limit;
• sample и фикстуры;
• contract-тесты.

2.2. Нормализация

Внутренний payload приводит внешние поля к каноническим:

name, phone, email, message, amount, order_id,
text, row, source, page, utm_*, created_at

Правила:

• телефоны — E.164, email — lower-case;
• даты — ISO 8601 UTC;
• пустые строки не считаются значением;
• вложенные объекты сохраняются в raw для диагностики (с маскированием);
• PII маскируется в логах и UI.

2.3. Webhook-приём

• Поддержать application/json и application/x-www-form-urlencoded (Tilda исторически отправляет form-urlencoded).
• Ограничение тела — 1 МБ.
• Секретный URL: 32+ байта энтропии, в БД только хеш.
• Подпись/секрет — если провайдер поддерживает; иначе секретный URL + rate limit + проверка через API.
• Ответ 2xx быстро, обработка асинхронно.
• Дедупликация: transactionid, update_id, event_id или HMAC payload.

2.4. OAuth

• state + PKCE (если поддерживается), проверка state на callback;
• refresh-токен за 5 минут до истечения;
• invalid_grant → needs_reauth, пауза зависимых активаций;
• минимальные scopes;
• шифрование токенов AES-256-GCM;
• хранение домена/account id (amoCRM, Bitrix24);
• ротация и отзыв.

2.5. Ошибки и лимиты

2.6. Наблюдаемость и приёмка

• Метрики: latency, error rate, 429, reauth, queue.
• Healthcheck каждые 5 минут.
• Contract-тесты: успех, 401, 429, 5xx, timeout, невалидные поля.
• Sandbox-аккаунт и фикстуры.
• Приёмка: тестовый запуск в кабинете + run succeeded + понятная ошибка при неверном токене.

---

3. Tilda

3.1. Роль

Источник заявок из форм на сайте. Tilda не используется как приёмник в MVP: её API предназначен для управления проектами/страницами, а не для создания лидов в CRM.

3.2. Авторизация

• Отдельная авторизация не нужна: пользователь вставляет webhook URL в настройках формы Tilda.
• URL должен быть уникальным и непредсказуемым; в БД хранится хеш.
• Дополнительно можно запросить у пользователя formid/formskey для фильтрации, но MVP принимает все формы проекта.

3.3. Входящие данные (trigger new_lead)

Tilda отправляет POST при отправке формы. Content-Type может быть application/x-www-form-urlencoded или JSON — поддержать оба.

Типовые поля:

Пример (form-urlencoded):

Name=Иван&Phone=%2B7+999+123-45-67&Email=ivan%40example.com
&Comment=Интересует+курс&formid=form1&transactionid=123456789
&utm_source=yandex&utm_medium=cpc

3.4. Ограничения и особенности

• Нет подписи запроса; защита — секретный URL, rate limit, проверка размера.
• Tilda может отправлять повторно при сбое; дедупликация по transactionid/tranid обязательна.
• Поля могут быть пустыми; обязательных полей на стороне Tilda нет.
• Названия полей зависят от настроек формы; поддержать case-insensitive алиасы и raw.
• Телефон может быть в свободном формате — нормализовать.
• HTML/скрипты в комментарии — экранировать при отправке в Telegram/CRM.

3.5. Сценарии easy-connect

• Tilda → Telegram
• Tilda → Bitrix24
• Tilda → amoCRM
• Tilda → Google Sheets
• Tilda → Email/SMS

3.6. Приёмка

1. Отправить тестовую форму Tilda.
2. Webhook принят, поля нормализованы.
3. Дубликат с тем же transactionid не создаёт второй run.
4. Пустой телефон не ломает маппинг.
5. Комментарий с HTML безопасно отображается в Telegram.

---

4. Bitrix24

4.1. Роль

Приёмник лидов, сделок, контактов и комментариев; источник событий CRM.

4.2. Авторизация

Два варианта:

1. OAuth 2.0 (рекомендуется для продукта):
   • приложение Bitrix24 (локальное/облачное), client_id, client_secret;
   • redirect URI — https://easy-connect.ru/api/v1/connections/oauth/bitrix24/callback;
   • scopes: crm, при необходимости tasks, user;
   • access token + refresh token, domain и member_id портала.
2. Inbound webhook (для быстрого подключения):
   • пользователь создаёт входящий webhook в Bitrix24;
   • URL вида https://{portal}/rest/{user_id}/{token}/;
   • проще, но хуже UX и сложнее отзыв.

MVP: OAuth; inbound webhook — как резервный режим.

Токены:

• access token живёт ~1 час, refresh — до 30 дней (уточнить в docs);
• хранить domain, member_id, client_endpoint, server_endpoint;
• refresh через https://oauth.bitrix.info/oauth/token/;
• invalid_grant → reauth.

4.3. Исходящие действия

create_lead — создать лид

crm.lead.add.json

Ответ: { "result": 123, "time": {...} }.

create_deal — создать сделку

crm.deal.add.json — поля TITLE, STAGE_ID, CATEGORY_ID, OPPORTUNITY, CURRENCY_ID, CONTACT_ID, COMPANY_ID, ASSIGNED_BY_ID, UF_CRM_*.

create_contact — создать контакт

crm.contact.add.json — NAME, LAST_NAME, PHONE, EMAIL, COMMENTS.

add_timeline_comment — комментарий в таймлайн

crm.timeline.comment.add — ENTITY_ID, ENTITY_TYPE (lead/deal), COMMENT.

4.4. Входящие события

Варианты:

• Event bind (event.bind) на ONCRMLEADADD, ONCRMLEADUPDATE, ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMCONTACTADD. Payload содержит data[FIELDS][ID], auth[domain], auth[member_id]. После события коннектор делает crm.lead.get/crm.deal.get и отдаёт нормализованные поля.
• Polling crm.lead.list с фильтром >DATE_CREATE и order. Использовать, если event bind недоступен.

Типовые поля лида: ID, TITLE, NAME, LAST_NAME, STATUS_ID, SOURCE_ID, ASSIGNED_BY_ID, OPPORTUNITY, CURRENCY_ID, DATE_CREATE, PHONE, EMAIL, COMMENTS, UF_CRM_*.

4.5. Лимиты

• Ориентир: ~2 запроса/сек на пользователя (облако), burst ограничен.
• Ошибки QUERY_LIMIT_EXCEEDED, OVERLOAD_LIMIT, HTTP 503.
• Использовать batch (batch) для массовых операций.
• 429/503 — backoff с jitter, не более 5 попыток.
• Учитывать Retry-After, если есть.

4.6. Безопасность

• Минимальные scopes; не запрашивать лишнее.
• Проверять member_id/domain при callback.
• Не логировать токены и телефоны.
• Проверять, что сущность принадлежит тому же порталу, перед обновлением.

4.7. Приёмка

1. OAuth-подключение портала.
2. Создание лида с именем, телефоном, email, комментарием.
3. Ошибка 401 → reauth, связка на паузе.
4. Событие ONCRMLEADADD создаёт run и передаёт поля.
5. 429 не теряет событие: retry/backoff.
6. Кастомные поля не ломают маппинг, если не выбраны.

---

5. amoCRM

5.1. Роль

Приёмник сделок/контактов и источник CRM-событий.

5.2. Авторизация

• OAuth 2.0, интеграция в amoMarket.
• client_id, client_secret, redirect_uri.
• Токен-эндпоинт: https://{subdomain}.amocrm.ru/oauth2/access_token.
• Access token ~24 часа, refresh token ~3 месяца (проверить актуальные сроки).
• Хранить subdomain, account_id, токены; refresh заранее.
• Scopes: crm, при необходимости notifications, tasks.
• invalid_grant → reauth.

5.3. Исходящие действия

create_lead — создать сделку (+ контакт)

POST /api/v4/leads/complex — создаёт сделку и контакт одним запросом.

[
  {
    "name": "Заявка с сайта",
    "price": 5000,
    "pipeline_id": 1234567,
    "status_id": 12345678,
    "responsible_user_id": 1234567,
    "_embedded": {
      "contacts": [
        {
          "first_name": "Иван",
          "custom_fields_values": [
            { "field_code": "PHONE", "values": [{ "value": "+79991234567", "enum_code": "WORK" }] },
            { "field_code": "EMAIL", "values": [{ "value": "ivan@example.com", "enum_code": "WORK" }] }
          ]
        }
      ]
    }
  }
]

Альтернатива: POST /api/v4/leads + POST /api/v4/contacts + связывание.

add_note — примечание к сделке

POST /api/v4/leads/{lead_id}/notes с note_type: "common" и params.text.

create_task (P1)

POST /api/v4/tasks — entity_id, entity_type, text, complete_till.

5.4. Входящие события

• Вебхуки amoCRM настраиваются в интеграции/через API: add_lead, update_lead, add_contact, update_contact, add_task, update_task.
• Payload содержит account[subdomain], leads[add][0][id], leads[add][0][status_id] и т. п.
• После вебхука коннектор запрашивает сущность через API v4 и нормализует.
• Проверка: вебхук не подписан; использовать секретный URL + сверять account[subdomain] с подключением. Для критичных действий — повторно запросить сущность.
• Polling GET /api/v4/leads?filter[created_at][from]=... — резервный режим.

Типовые поля сделки: id, name, price, pipeline_id, status_id, responsible_user_id, created_at, updated_at, custom_fields_values (PHONE, EMAIL, UTM_SOURCE, ...), _embedded.contacts.

5.5. Лимиты

• Ориентир: ~7 запросов/сек на аккаунт, burst; уточнять.
• 429 с Retry-After; backoff.
• Batch-эндпоинты для массовых операций.
• Не более 1 запроса на одно событие; кэшировать pipeline/status.

5.6. Безопасность

• Минимальные scopes.
• Проверка subdomain/account_id.
• Токены только в зашифрованном виде.
• Не логировать телефоны/email; маскировать.

5.7. Приёмка

1. OAuth-подключение аккаунта.
2. Создание сделки с контактом, телефоном и email.
3. Примечание к сделке.
4. Вебхук add_lead создаёт run.
5. 401 → reauth, пауза.
6. 429 → backoff, без потери события.

---

6. Telegram

6.1. Роль

Приёмник уведомлений (основной сценарий) и источник сообщений (P1).

6.2. Авторизация

• Bot token от @BotFather.
• Проверка getMe; хранить bot.id, username.
• Для webhook — setWebhook с secret_token (X-Telegram-Bot-Api-Secret-Token).
• Токен шифруется; при 401 — reauth.

6.3. Исходящие действия

send_message

POST https://api.telegram.org/bot{token}/sendMessage

Ответ: result.message_id.

send_photo / send_document (P1)

sendPhoto/sendDocument — файл по URL или multipart/form-data. Ограничения: фото 10 МБ, документ 50 МБ (уточнять).

6.4. Входящие события (P1)

• getUpdates (long polling) или webhook.
• Типы: message, edited_message, callback_query.
• Поля: update_id, message.message_id, chat.id, from.id, from.first_name, text, date, entities, reply_to_message.
• Дедупликация по update_id.
• Игнорировать сообщения ботов (если не нужно иное).
• Webhook secret обязателен; иначе любой может отправить update.

6.5. Лимиты

• ~30 сообщений/сек суммарно; ~1 сообщение/сек в один чат.
• 429 с retry_after; уважать.
• Текст 4096 символов; caption 1024.
• HTML/Markdown — экранировать пользовательские данные.

6.6. Безопасность

• Токен не логировать.
• Проверять chat_id (не отправлять в чужие чаты).
• parse_mode + пользовательский текст = риск HTML-инъекции; экранировать.
• Webhook secret + HTTPS.

6.7. Приёмка

1. Подключение бота, getMe.
2. Тестовое сообщение в чат.
3. 401 → reauth.
4. 429 → retry с retry_after.
5. Webhook secret проверяется.
6. Дубликат update_id не создаёт второй run.

---

7. Google Sheets

7.1. Роль

Приёмник строк (append/update) и источник новых строк (polling).

7.2. Авторизация

• Google Cloud project + OAuth 2.0 client.
• Scopes:
  • https://www.googleapis.com/auth/spreadsheets — чтение и запись;
  • https://www.googleapis.com/auth/spreadsheets.readonly — только источник;
  • https://www.googleapis.com/auth/drive.metadata.readonly — список таблиц.
• Access token ~1 час, refresh token долгоживущий.
• Хранить refresh_token, scopes, email аккаунта.
• invalid_grant → reauth.

7.3. Исходящие действия

append_row

POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS

{
  "values": [["2026-10-18", "Иван", "+79991234567", "ivan@example.com", "Заявка"]]
}

Поля:

update_row (P1)

PUT .../values/{range}?valueInputOption=USER_ENTERED — требует знать строку/диапазон; в MVP не обязательно.

7.4. Входящие события

• У Google Sheets нет нативных вебхуков для «новая строка».
• Основной режим — polling:
  • GET .../values/{range} каждые 1–5 минут;
  • хранить last_row/курсор на активацию;
  • сравнивать с предыдущим снимком по ключу (например, row_number + hash);
  • первая синхронизация — только новые строки после активации (по умолчанию).
• Альтернатива — Google Apps Script onEdit → webhook easy-connect (требует установки скрипта пользователем; P1).
• Заголовки: первая строка листа используется как имена полей; если её нет — col_A, col_B, ...
• Пустые строки пропускаются.

7.5. Лимиты

• Ориентир: 300 запросов/мин на проект, 60/мин на пользователя (проверять квоты Google Cloud).
• 429/403 quota exceeded → backoff, снижение частоты.
• Не более 10 млн ячеек на таблицу.
• Записи батчить, если несколько строк.

7.6. Безопасность

• Минимальные scopes; не запрашивать Drive полностью.
• Хранить refresh token в шифрованном виде.
• Проверять, что таблица доступна пользователю.
• Не логировать содержимое строк (PII).

7.7. Приёмка

1. OAuth-подключение Google.
2. Append строки в тестовую таблицу.
3. Polling находит новую строку и создаёт run.
4. Повторный polling не создаёт дубль.
5. 429 → backoff.
6. Отзыв доступа → reauth.

---

8. Какие данные передаём и получаем (сводно)

---

9. Сценарии easy-connect (маппинг в каталог)

---

10. План реализации

Итого: 6–8 недель на 5 коннекторов с учётом тестов и модерации OAuth.

---

11. Открытые вопросы

1. Актуальные лимиты Bitrix24/amoCRM/Google Sheets на дату реализации.
2. Требования модерации OAuth-приложений и сроки.
3. Нужен ли Tilda API для создания/обновления страниц (вне MVP).
4. Нужны ли вложения (фото/документы) в Telegram и файлы в Sheets.
5. Политика хранения payload с PII: 7 дней для тел, 90 дней для метаданных.
6. Подпись вебхуков: у Tilda/amoCRM её нет — компенсировать секретным URL и проверкой через API.
7. Стоимость и квоты Google Cloud при росте.

---

12. Definition of Done для каждого коннектора

• Манифест и схемы полей.
• Авторизация и refresh/reauth.
• Минимум один триггер и одно действие.
• Нормализация и дедупликация.
• Обработка 401/429/5xx/timeout.
• Contract-тесты и фикстуры.
• Healthcheck и метрики.
• Инструкция «где взять токен/доступ».
• Тестовый запуск в кабинете.
• Ревью безопасности.