API: компания, сотрудники, интеграции и профиль

Всё, что администратор делает в «Настройках компании», а сотрудник в «Профиле», доступно и через API: настройки компании, права доступа, сотрудники и приглашения, услуги и быстрые ссылки, API-ключи, подключение и настройка Telegram, MAX и виджета, профиль, уведомления, компании и приглашения, обращения в поддержку. Заявки, звонки, почта и чаты описаны в документации API; там же общие правила: аутентификация, формат, ошибки, лимиты и идемпотентность.

Содержание

1. Общие правила
2. Области
3. Компания
4. Сотрудники
5. Приглашения
6. Права доступа
7. Быстрые ссылки и услуги
8. API-ключи
9. Интеграции: Telegram, MAX, виджет
10. Профиль, уведомления, компании
11. Поддержка
12. Примеры

1. Общие правила

• Все адреса работают только с ключом сотрудника и от его имени: те же проверки прав, что в кабинете. Ключ компании (выпущенный до появления ключей сотрудников) получает 403 SCOPE_REQUIRED.
• Адреса компании, сотрудников, приглашений, прав, ключей компании и интеграций доступны только администратору или владельцу компании. Ключ менеджера получает 403 PERMISSION_DENIED с полем permission: "company.admin" и текстом «Действие доступно только администратору компании». Передача владения доступна только владельцу (permission: "company.owner").
• Ключ привязан к одной компании. Данные других компаний сотрудника видны только в профиле: их список (название, роль) и приглашения этого человека.
• Тело записи: JSON-объект. Неуказанные поля в PATCH не меняются. Неизвестное поле тела в адресах компании и интеграций: 400 VALIDATION_ERROR с перечнем допустимых полей в details. Логические поля принимают true/false, 1/0, "true"/"false".
• Необратимые действия (передача владения, уход из компании, исключение сотрудника, отключение канала, новый код виджета, завершение сессий) требуют в теле "confirm": true. Без него: 400 CONFIRM_REQUIRED «Действие необратимо: передайте confirm: true».
• Сотрудники, приглашения, ключи и каналы обозначаются uuid. Время в ответах: ISO-8601 в UTC с Z.
• Ошибки: 400 VALIDATION_ERROR с текстом, который видит кабинет; 403 PERMISSION_DENIED с полем permission; 404 NOT_FOUND (чужое и несуществующее неотличимы); 409 CONFLICT (потолки, гонки, уже сделано); 503 SERVICE_UNAVAILABLE (временный сбой, повторите позже).
• Токены ботов, пароли и сырые ключи не попадают в ответы и журналы никогда.

2. Области

Новые области выдаются только по выбору при выпуске ключа: прежние ключи их не получают. Полная таблица областей: раздел 1 документации API.

Только себе. Области управления компанией и профилем сотрудник выпускает только себе: в профиле или администратор себе на вкладке «API-ключи». Выпуск такой области на ключ другого сотрудника отклоняется (в API: 403 PERMISSION_DENIED, permission: "keys.self_only"), а у ключа, выпущенного за другого, эти области не действуют и при вызове. Так никто не действует через API от чужого имени.

Ключ не выпускает ключ шире себя. Ключ с keys:write выпускает ключи только с теми областями, которые есть у него самого (с учётом включённых). Иначе 403 PERMISSION_DENIED, permission: "keys.scopes", «Ключ не может выпустить ключ с областями шире своих».

3. Компания

4. Сотрудники

Права действий: leads.create, leads.edit, leads.status, leads.archive, leads.reassign, leads.merge, leads.comment, leads.export, leads.import (действия с заявками) и api.keys («Выпускать себе API-ключи в профиле»). Права компании, от которых считаются личные: раздел 6.

5. Приглашения

6. Права доступа

7. Быстрые ссылки и услуги

8. API-ключи

Свои ключи сотрудник выпускает и отзывает адресами /api/v1/me/api-keys (раздел 10), если у него есть право «Выпускать себе API-ключи в профиле».

9. Интеграции: Telegram, MAX, виджет

Каналы, которые компания может подключать, перечислены в поле kinds ответа GET /api/v1/integrations; канал другого вида отвечает 404. Токены ботов передаются только в теле запроса и в ответах не возвращаются.

Объект канала: uuid, kind (telegram, max, widget), status (состояние как на вкладке «Интеграции»: status, status_text, last_error и др.), bot_username, bot_url, deep_link_template (ссылка с меткой: {param} подставляет клиент), settings; у виджета ещё widget (key, embed_code, chat_url, avatar_url, settings), у MAX max (состояние подписки).

Настройки Telegram и MAX: title, default_manager (uuid или null), greeting (enabled, text), offhours (enabled, text), schedule (timezone, week: {"mon": [["09:00","18:00"]], ...}, exceptions: [{date, intervals}]), contact_button (enabled, text: просьба поделиться номером, caption: подпись кнопки). У виджета дополнительно appearance (title, color, position, offset_y, welcome, offline_text, operator_name), prechat (name, phone, email), consent (mode: notice, checkbox, off; policy_url), files (enabled, max_mb), visitor_mail (enabled), sites (mode: soft, strict; domains). Тексты согласия на обработку персональных данных сохраняются как переданы, без подстановки умолчаний.

10. Профиль, уведомления, компании

Покинуть компанию: POST /api/v1/company/leave (раздел 3). Вход по коду, выход из текущей сессии и переключение компании через API не делаются: ключ работает без сессии и привязан к одной компании.

11. Поддержка

12. Примеры

Переименовать компанию и сменить часовой пояс

curl -X PATCH https://crm.linkodium.com/api/v1/company \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Окна Урала", "timezone": "Asia/Yekaterinburg"}'

Пригласить сотрудника

curl -X POST https://crm.linkodium.com/api/v1/invites \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-0d4b-4b8e-9a37-2f5c8d1e7b40" \
  -d '{"email": "manager@example.com", "role": "manager"}'

# 201 Created
{ "success": true, "data": { "invite": { "uuid": "...", "email": "manager@example.com", "role": "manager", ... },
  "renewed": false, "deduped": false, "mailed": true, "mail_capped": false, "cap_reason": null } }

Включить приветствие бота Telegram

curl -X PATCH https://crm.linkodium.com/api/v1/integrations/0b8e4f3a-6c1d-4e2b-9f7a-3d5c8e1b2a90/settings \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"greeting": {"enabled": true, "text": "Здравствуйте! Ответим в течение 10 минут."}}'

Остальные настройки канала остаются прежними.

Выпустить ключ для формы сайта

curl -X POST https://crm.linkodium.com/api/v1/api-keys \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Форма на сайте", "user": "5d2f8a1c-3b4e-4f6a-8c9d-1e2f3a4b5c6d", "scopes": ["leads:create"]}'

# 201 Created
{ "success": true, "data": { "key": "crm_3f9a...", "uuid": "..." } }

Сохраните key сразу: показать его ещё раз CRM не сможет.