API BatCRM
Подключайте свой сайт, 1С, BI-отчёты или Make/Albato: забирайте лиды агентства, создавайте новые и назначайте их агентам. Все данные — строго в рамках вашего агентства.
Быстрый старт
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.
| Поле | Описание |
|---|---|
grant_type | client_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), просто запросите новый.
Список лидов
| Параметр | Описание |
|---|---|
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": [ /* объекты «Лид» */ ]
}
Один лид
Возвращает {"ok": true, "lead": {…}}. Лид другого агентства — 404, как будто его нет.
Создать лид
| Поле | Описание |
|---|---|
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, новый не создаётся (так заявки с сайта не задваиваются). Руководителям приходит уведомление о новом лиде, как от любой интеграции.
Агенты
{ "ok": true, "items": [ { "id": 12, "name": "Иванова Мария" } ] }
Компания и ключ
Удобно проверить, что ключ работает: вернёт название агентства, имя ключа и его права.
Объект «Лид»
| Поле | Тип | Описание |
|---|---|---|
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 — по-русски, его можно показывать человеку.
| HTTP | code | Когда |
|---|---|---|
| 400 | bad_request | Неверные параметры: дата, телефон, agent_id |
| 401 | unauthorized / invalid_client | Нет токена, истёк, ключ отозван или неверный секрет |
| 403 | forbidden | Ключу с правом read нельзя создавать лиды |
| 404 | not_found | Лид не найден (или он другого агентства) |
| 409 | duplicate | Лид с этим номером уже есть за последний месяц |
| 429 | rate_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);