REST · JSON · OAuth 2.0

API BatCRM

Подключайте свой сайт, 1С, BI-отчёты или Make/Albato: забирайте лиды агентства, создавайте новые и назначайте их агентам. Все данные — строго в рамках вашего агентства.

📥 Забирать лидыЗа любой период до года, с агентом и источником — для отчётов и 1С.
📤 Создавать лидыЗаявки с сайта сразу в CRM — с уведомлением руководителю и агенту.
👥 АгентыСписок сотрудников — чтобы назначать лид нужному человеку.

Быстрый старт

1. В CRM откройте Интеграции → API для разработчиков → Выпустить ключ. Ключи выпускает только руководитель агентства. Сохраните client_id и client_secret — секрет показывается один раз.

2. Обменяйте их на токен доступа (живёт 1 час):

curl -X POST https://batcrm.ru/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"bcrm_…","client_secret":"bsec_…"}'

3. Вызывайте методы с заголовком Authorization: Bearer <access_token>:

curl https://batcrm.ru/api/v1/leads?from=2026-10-01 \
  -H "Authorization: Bearer bat_…"

Авторизация

Используется стандартный OAuth 2.0 client credentials. Базовый адрес: https://batcrm.ru/api/v1.

POST/api/v1/oauth/token
ПолеОписание
grant_typeclient_credentials (можно не передавать)
client_idИдентификатор ключа, начинается с bcrm_
client_secretСекрет ключа, начинается с bsec_

Тело — JSON или application/x-www-form-urlencoded. Можно передать пару и в заголовке Authorization: Basic base64(client_id:client_secret).

{
  "access_token": "bat_Xy…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "write"
}

Права ключа: read — только чтение, write — чтение и создание лидов. Когда токен истечёт (ответ 401), просто запросите новый.

Список лидов

GET/api/v1/leads
ПараметрОписание
fromДата начала, ГГГГ-ММ-ДД. По умолчанию — 30 дней назад
toДата конца включительно. По умолчанию — сегодня. Период — не больше 366 дней
limitСколько вернуть, 1–500. По умолчанию 100
offsetСдвиг для постраничной выборки

Лиды отсортированы от новых к старым.

{
  "ok": true, "from": "2026-10-01", "to": "2026-10-10",
  "total": 143, "offset": 0, "limit": 100,
  "items": [ /* объекты «Лид» */ ]
}

Один лид

GET/api/v1/leads/{id}

Возвращает {"ok": true, "lead": {…}}. Лид другого агентства — 404, как будто его нет.

Создать лид

POST/api/v1/leadsправо write
ПолеОписание
phone *Телефон клиента в любом формате: +7 900 000-00-00, 89000000000
nameИмя клиента. По умолчанию «Клиент»
commentКомментарий: что ищет клиент, откуда пришёл (до 2000 символов)
sourceИсточник для метки в CRM, например «Сайт — ипотека». По умолчанию — название ключа
agent_idСразу назначить агенту — id из списка агентов. Агент получит уведомление
curl -X POST https://batcrm.ru/api/v1/leads \
  -H "Authorization: Bearer bat_…" -H "Content-Type: application/json" \
  -d '{"name":"Анна","phone":"+7 900 123-45-67","comment":"2-комн., семейная ипотека","source":"Сайт"}'

Ответ 201 с созданным лидом. Если лид с этим номером уже был за последний месяц — 409 duplicate, новый не создаётся (так заявки с сайта не задваиваются). Руководителям приходит уведомление о новом лиде, как от любой интеграции.

Агенты

GET/api/v1/agents
{ "ok": true, "items": [ { "id": 12, "name": "Иванова Мария" } ] }

Компания и ключ

GET/api/v1/me

Удобно проверить, что ключ работает: вернёт название агентства, имя ключа и его права.

Объект «Лид»

ПолеТипОписание
idчислоНомер лида. Лиды, созданные в CRM и через API, — отрицательные
nameстрокаИмя клиента
phoneстрока | nullТелефон в формате +79001234567
commentстрока | nullКомментарий
sourceстрока | nullИсточник
created_atстрокаКогда пришёл, ГГГГ-ММ-ДДTчч:мм:сс по Москве
agentобъект | null{id, name, assigned_at} — кому назначен
urlстрокаСсылка на карточку лида в CRM
{
  "id": -1042, "name": "Анна", "phone": "+79001234567",
  "comment": "2-комн., семейная ипотека", "source": "Сайт",
  "created_at": "2026-10-10T14:05:12",
  "agent": { "id": 12, "name": "Иванова Мария", "assigned_at": "2026-10-10T14:06:00" },
  "url": "https://batcrm.ru/?lead=-1042"
}

Ошибки

Ошибка — всегда JSON с HTTP-кодом: {"ok": false, "error": {"code": "…", "message": "…"}}. Текст в message — по-русски, его можно показывать человеку.

HTTPcodeКогда
400bad_requestНеверные параметры: дата, телефон, agent_id
401unauthorized / invalid_clientНет токена, истёк, ключ отозван или неверный секрет
403forbiddenКлючу с правом read нельзя создавать лиды
404not_foundЛид не найден (или он другого агентства)
409duplicateЛид с этим номером уже есть за последний месяц
429rate_limitedПревышен лимит запросов

Лимиты и безопасность

• До 600 запросов в час на ключ. Токен живёт 1 час — кэшируйте его, а не запрашивайте перед каждым вызовом.

• До 10 действующих ключей на агентство. Отозвать ключ можно в любой момент — доступ прекращается сразу.

• Ключ видит только данные своего агентства. Секрет хранится у нас только в виде хэша — восстановить его нельзя, только выпустить новый.

🔒 Держите client_secret только на своём сервере. Не вставляйте его в код страницы сайта и мобильного приложения — там его увидит любой.

Примеры кода

import requests

API = "https://batcrm.ru/api/v1"
tok = requests.post(f"{API}/oauth/token", json={
    "client_id": "bcrm_…", "client_secret": "bsec_…",
}).json()["access_token"]
h = {"Authorization": f"Bearer {tok}"}

# лиды за октябрь
leads = requests.get(f"{API}/leads", headers=h, params={"from": "2026-10-01", "limit": 500}).json()["items"]

# новый лид с сайта
requests.post(f"{API}/leads", headers=h, json={"name": "Анна", "phone": "+79001234567", "source": "Сайт"})
const API = "https://batcrm.ru/api/v1";
const { access_token } = await (await fetch(`${API}/oauth/token`, {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ client_id: process.env.BCRM_ID, client_secret: process.env.BCRM_SECRET }),
})).json();

const res = await fetch(`${API}/leads`, {
  method: "POST",
  headers: { Authorization: `Bearer ${access_token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Анна", phone: "+79001234567", comment: "Заявка с сайта" }),
});
console.log(res.status, await res.json());
<?php
$api = "https://batcrm.ru/api/v1";
$ch = curl_init("$api/oauth/token");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => http_build_query(["client_id" => "bcrm_…", "client_secret" => "bsec_…"])]);
$token = json_decode(curl_exec($ch), true)["access_token"];

$ch = curl_init("$api/leads");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["name" => $_POST["name"], "phone" => $_POST["phone"], "source" => "Сайт"])]);
echo curl_exec($ch);