API интегратора

1. Выпуск токена

Личный кабинет → раздел «API-токены» → «Создать токен». Задайте название, чтобы потом отличать токены друг от друга.

Формат значения — bic_ и случайная строка. Срок действия не ограничен; единственный способ погасить токен — отозвать его в кабинете или методом apiToken/revoke. У каждого токена отображается время последнего использования.

2. Аутентификация

Токен передаётся заголовком:

Authorization: Bearer bic_xxxxxxxxxxxx

Допустим и query-параметр ?api_token=…, но он попадает в логи и историю браузера — используйте заголовок, если есть возможность.

Капча для API не нужна: проверка «Я не робот» применяется только к формам в браузере. По токену все методы работают напрямую.

3. Формат запроса и ответа

• метод — всегда POST;
• маршрут — /api/{контроллер}/{метод};
• параметры — application/x-www-form-urlencoded или query-строка;
• базовый URL — https://api.bic-24.ru/api.

Ответ приходит в конверте JSON-RPC — массив из одного объекта:

[{ "jsonrpc": "2.0", "result": … }]        // успех
[{ "jsonrpc": "2.0", "error": { "message": "…", "code": 401 } }]   // ошибка

Ниже в разделе «Методы» показано значение result — фактическое тело всегда обёрнуто в конверт выше.

4. Быстрый старт

BIC_TOKEN='bic_xxxxxxxxxxxx'
BASE='https://api.bic-24.ru/api'

# Список порталов клиентов
curl -s -X POST "$BASE/apiClient/list" \
  -H "Authorization: Bearer $BIC_TOKEN"

# Один портал по id
curl -s -X POST "$BASE/apiClient/get" \
  -H "Authorization: Bearer $BIC_TOKEN" \
  -d 'id=248'

5. Коды ошибок

Булевы параметры принимают 1, true, on, yes как истину; всё остальное — ложь.

6. Методы

apiAccount — аккаунт, подписка, баланс

apiAccount/summary — профиль интегратора

Параметры: нет.

{
  "integrator_id": 672, "company_name": "ООО Ромашка", "email": "owner@romashka.ru",
  "email_verified": true, "state": "active", "link_token": "xJ2fQ8s7…",
  "subscribed_until": "2026-08-01 00:00:00", "billing_period": "month",
  "auto_renew": true, "notifications_enabled": true, "marketing_enabled": false,
  "inn": "7701234567", "kpp": "770101001", "ogrn": "1157746000000",
  "legal_address": "Москва, ул. Ромашковая, 1", "director_name": "Иванов И. И.",
  "contact_phone": "+7 900 000-00-00", "contact_email": "billing@romashka.ru",
  "balance_kopecks": 120000
}

apiAccount/dashboard — сводка показателей

Параметры: нет.

{
  "subscription": { "state": "active", "subscribed_until": "2026-08-01", "days_left": 23,
                    "auto_renew": true, "billing_period": "month", "balance_kopecks": 120000 },
  "clients":  { "total": 8, "active": 7, "monitored_users": 3 },
  "portals":  { "total": 1 },
  "mappings": { "projects": 12, "tasks": 340 },
  "queue":    { "pending": 2, "failed": 0 },
  "rest_load": { "est_req_min": 118, "live_req_min": 42, "ceiling_req_min": 120,
                 "degraded": false, "kind": "cloud", "domain": "romashka.bitrix24.ru" }
}

apiAccount/transactions — история баланса

{
  "rows": [
    { "id": 45, "type": "charge", "amount_kopecks": -300000, "balance_after_kopecks": 120000,
      "comment": "Списание за подписку (month)", "ref": "", "date_create": "2026-07-01 03:00:05" }
  ],
  "total": 45, "limit": 20, "offset": 0
}

apiAccount/notifications — журнал уведомлений

Метаданные без тела письма. Параметры: limit (1…200, по умолчанию 10), offset.

{
  "rows": [
    { "id": 88, "code": "expiry", "subject": "Подписка истекает 2026-08-01",
      "status": "sent", "error": "", "period_key": "2026-07", "date_create": "2026-07-05 09:00:00" }
  ],
  "total": 88, "limit": 10, "offset": 0
}

status: sent · skipped_by_user_pref (отключены уведомления) · skipped_by_ad_pref (нет согласия на рекламу) · failed.

apiAccount/notification — одно уведомление с телом

{ "id": 88, "code": "expiry", "subject": "Подписка истекает…", "body": "<p>Здравствуйте…</p>",
  "status": "sent", "error": "", "period_key": "2026-07", "date_create": "2026-07-05 09:00:00" }

apiAccount/setPreferences — настройки и реквизиты

Меняет только переданные поля. Хотя бы одно поле обязательно, иначе 400.

{ "success": true }

apiAccount/requestTopUp — заявка на пополнение

Отправляет в поддержку заявку с реквизитами и суммой. Баланс не меняется — средства зачисляются после оплаты. Требуется настроенная почта, иначе 503.

{ "success": true, "email_sent": true }

apiAccount/supportRequest — обращение в поддержку

{ "success": true, "email_sent": true }

apiAccount/portals — свои порталы Bitrix24

Параметры: нет. Секреты не отдаются — вместо ключа возвращается флаг has_hmac.

[
  { "id": 5, "kind": "cloud", "domain": "romashka.bitrix24.ru", "state": "active",
    "installed": true, "local_endpoint_url": "", "has_hmac": false,
    "token_expires_at": "2026-07-09 15:00:00", "last_handshake_at": null }
]

apiAccount/check — проверить связь со своим порталом

{ "connected": true, "kind": "cloud" }

Ошибки: 404 — портал не ваш; 502 — нет связи.

apiAccount/generateLocalSecret · enableLocal · disableLocal

Перевод своего коробочного портала в режим Local App. Параметры и ответы совпадают с клиентскими методами ниже, но id — это id портала интегратора.

apiClient — порталы клиентов

Секреты порталов (настройки, ключи подписи) вырезаны из всех ответов.

apiClient/list — список порталов клиентов

[
  { "id": 248, "state": "active", "domain": "client.bitrix24.ru", "url": "https://client.bitrix24.ru",
    "kind": "cloud", "local_endpoint_url": "", "last_handshake_at": null, "has_hmac": false,
    "tech_user_name": "Админ Клиента", "project_mappings_count": 3, "invite_code_id": 17,
    "rest_load": { "req_min": 18, "limit_req_min": 120, "degraded": false, "kind": "cloud" } }
]

apiClient/get — один портал клиента

Ответ — объект портала в том же виде, что в list. Если портал принадлежит другому интегратору — 404.

apiClient/update — сменить состояние портала

{ "success": true }

apiClient/delete — удалить портал клиента

Необратимо: удаляет портал и все связанные сопоставления. Параметр id (обязателен). В ответе — счётчики удалённых записей.

{ "success": true, "project_mappings": 3, "task_mappings": 40, "chat_mappings": 12,
  "message_mappings": 210, "file_mappings": 8, "checklist_item_mappings": 15,
  "open_line_mappings": 1, "dm_mappings": 6 }

apiClient/check — проверить связь с порталом клиента

Параметр id (обязателен).

{ "connected": true }

Ошибки: 404, 502.

apiClient/users — сотрудники, подключённые к Открытым линиям

Параметр id (обязателен, id портала). Персональные токены не отдаются.

{
  "rows": [
    { "user_id": 31, "name": "Иван Тестов", "consent_state": "connected", "monitored": true,
      "token_expires_at": "2026-07-09 14:00:00", "last_connected_at": "2026-07-08 10:00:00" }
  ]
}

consent_state: connected — доступ активен · revoked — сотрудник отозвал · auth_failed — доступ перестал работать.

apiClient/checkUser — проверить доступ сотрудника

{ "connected": true }

Ошибки: 404 — сотрудник не найден; 502 — доступ мёртв, сотрудник переводится в auth_failed.

apiClient/generateLocalSecret — ключ для Local App

Параметр id (обязателен). Портал пока остаётся на обычном REST.

{ "success": true, "hmac_key": "<64 hex>" }

Ключ показывается один раз — его нужно вставить в config.php на коробке (см. Установка Local App).

apiClient/enableLocal — включить Local-режим

{ "success": true, "kind": "local", "local_endpoint_url": "…/proxy.php" }

Переключение происходит только после реальной проверочной операции через прокси. Если коробка её не выполнила — 502 с подсказкой о причине, портал остаётся на обычном REST.

apiClient/disableLocal — вернуть портал на обычный REST

Параметр id (обязателен).

{ "success": true, "kind": "cloud" }

apiInvite — приглашения клиентов

apiInvite/create — создать код-приглашение

{ "token": "aB7-cd9…", "expires_at": "2026-08-08T09:00:00+00:00" }

apiInvite/list — список приглашений

Параметры: limit (1…200, по умолчанию 10), offset.

{
  "rows": [
    { "id": 17, "token": "aB7-cd9…", "state": "used", "note": "Клиент Ромашка",
      "expires_at": "2026-08-08 09:00:00", "bound_client_portal_id": 248,
      "date_create": "2026-07-09 09:00:00" }
  ],
  "total": 17, "limit": 10, "offset": 0
}

state: pending · used · expired · revoked.

apiInvite/revoke — отозвать приглашение

Гасит только неиспользованный код. Параметр id (обязателен).

{ "success": true }

apiMapping — маппинги проектов

apiMapping/list — список сопоставлений

Только чтение. Параметр client_id (необязательный фильтр по клиенту).

[
  { "id": 90, "client_id": 248, "client_project_id": 15, "integrator_project_id": 4,
    "responsible_user_id": 12, "state": "active", "last_sync_at": "2026-07-09 12:30:00",
    "sync_from": null, "client_user_ids": [1, 31], "date_create": "2026-06-10 10:00:00" }
]

client_user_ids — ID пользователей клиента, чьи задачи синхронизируются.

apiToken — управление токенами

Существующим токеном можно выпускать и отзывать другие — так делается ротация без визита в кабинет.

apiToken/create — выпустить токен

{ "id": 7, "token": "bic_9fQ2…", "token_prefix": "bic_9fQ2xY1z" }

Значение токена возвращается только здесь и только один раз.

apiToken/list — список токенов

Параметры: нет. Сами значения не возвращаются — только префиксы.

[
  { "id": 7, "name": "CI", "token_prefix": "bic_9fQ2xY1z",
    "last_used_at": "2026-07-09 12:00:00", "revoked": false, "date_create": "2026-07-01 08:00:00" }
]

apiToken/revoke — отозвать токен

Параметр id (обязателен). Действует немедленно.

{ "success": true }

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

• Изоляция аккаунта. Каждый запрос фильтруется по вашему тенанту. Обращение к чужому объекту по id вернёт 404, а не чужие данные.
• Область действия. Токен даёт только самообслуживание интегратора. Это не токен Bitrix24 — вызывать им REST портала напрямую нельзя, и прав администратора платформы он не даёт.
• Хранение. На сервере лежит только хеш токена. При подозрении на компрометацию — отзовите токен и выпустите новый; отзыв действует немедленно.
• Секреты не возвращаются. Токены доступа к порталам и ключи подписи никогда не отдаются через API — только признак их наличия (has_hmac) либо разовая выдача при генерации.
• Передавайте токен только по HTTPS и храните его как пароль: в переменных окружения или менеджере секретов, но не в репозитории.

Нужен пример под конкретную задачу — напишите на info@bic-24.ru.