BINCORT — Публичный API

BINCORT Public API v1

Выгрузка заявок в вашу CRM, вебхуки о событиях и действия над заявками. Одна страница — всё, что нужно, чтобы подключиться.

OpenAPI (JSON) — импорт в Postman, Insomnia или генератор клиентов

1. Попробовать за 10 секунд — без аккаунта

Песочница отвечает на все методы фиктивными данными. Ключ публичный и постоянный, его можно вставить в любой HTTP-клиент прямо сейчас:

curl https://api.bincort.ru/v1/leads?limit=3 \
  -H "X-CRM-API-Key: bic_crm_sandbox_demo_key"

Песочница не касается данных ни одного бизнеса и ничего не сохраняет: методы записи (статус, заметка, вебхук) возвращают успешный ответ с пометкой "sandbox": true, но никуда не пишут. Фильтры since, status и limit работают — на них можно проверить логику инкрементального опроса.

2. Ключ и аутентификация

Боевой ключ создаётся в кабинете: Экспорт → API-ключ для автосинхронизации. Доступен на тарифах Standard и выше. Ключ показывается один раз; при повторной генерации старый отзывается.

Каждый запрос — с заголовком:

X-CRM-API-Key: bic_crm_…

curl "https://api.bincort.ru/v1/leads?since=2026-09-01T00:00:00Z&limit=100" \
  -H "X-CRM-API-Key: bic_crm_ВАШ_КЛЮЧ"

Все даты в API — UTC, ISO 8601. Ключ проверяется на каждый запрос вместе с тарифом и статусом подписки: при даунгрейде ниже Standard или приостановке за неоплату API отвечает 402, сам ключ при этом не удаляется.

3. Методы

Метод	Путь	Что делает	Параметры
`GET`	`/v1/leads`	Выгрузить заявки (инкрементально, по since)	`since`, `limit`, `status`, `mark_exported`
`POST`	`/v1/webhooks/subscribe`	Подписаться на событие	JSON-тело
`DELETE`	`/v1/webhooks/{webhook_id}`	Отписаться	—
`GET`	`/v1/webhooks`	Список подписок	—
`POST`	`/v1/leads/{lead_id}/status`	Сменить статус заявки	JSON-тело
`POST`	`/v1/leads/{lead_id}/note`	Добавить внутреннюю заметку	JSON-тело
`POST`	`/v1/leads/{lead_id}/assign`	Назначить оператора	JSON-тело

Таблица генерируется из спецификации — совпадает с кодом по построению. Точные схемы запросов и ответов — в OpenAPI.

GET /v1/leads — выгрузка заявок

Возвращает заявки бизнеса, отсортированные по времени создания (старые → новые). Параметры: since — ISO-дата, вернуть созданные ПОСЛЕ неё; limit — до 500 (по умолчанию 100); status — один из new, in_progress, completed, spam, duplicate; mark_exported=true — пометить полученные заявки как выгруженные в CRM (видно в кабинете).

Рекомендуемая схема опроса: раз в 5–15 минут, в since передавать created_at последней заявки из предыдущего ответа. Заявка с "locked": true — сверх лимита тарифа Free: сохранена, но контакты и текст скрыты до апгрейда.

Объект заявки:

{
  "id": 1001,
  "created_at": "2026-09-01T09:12:00Z",
  "channel": "Telegram",
  "channel_code": "telegram",
  "client_name": "Анна Петрова",
  "client_phone": "+79001234567",
  "client_email": "anna@example.com",
  "topic": "Доставка в область",
  "message": "Здравствуйте! Довозите ли вы до Подольска и сколько это стоит?",
  "locked": false,
  "status": "Новое",
  "status_code": "new",
  "priority": "Обычный",
  "ai_intent": "Вопрос",
  "ai_tags": ["question"],
  "is_repeat_client": false,
  "utm": {"source": "yandex", "medium": "cpc", "campaign": "dostavka"},
  "crm_exported": false
}

Действия над заявкой

POST /v1/leads/{id}/status с телом {"status": "completed"} — сменить статус (new, in_progress, completed, spam). POST /v1/leads/{id}/note с телом {"text": "…"} — добавить внутреннюю заметку (видна команде, не клиенту). POST /v1/leads/{id}/assign с телом {"operator_id": 7} (или null, чтобы снять) — назначить оператора.

4. Вебхуки — узнавать о событиях сразу

Вместо опроса: POST /v1/webhooks/subscribe с телом {"target_url": "https://…", "event_type": "lead.created"}. До 10 подписок на бизнес. События: lead.created — новая заявка; lead.status_changed — смена статуса любым способом (оператор, правило автоматизации, API, ответ оператора); lead.note_added — новая заметка.

Мы делаем POST на ваш адрес с Content-Type: application/json и User-Agent: BINCORT-Webhook/1.0, таймаут 5 секунд, без повторов. Статус последней доставки по каждой подписке виден в кабинете (Экспорт).

{
  "event": "lead.created",
  "business_id": 42,
  "lead_id": 1001,
  "created_at": "2026-09-01T09:12:00",
  "channel_code": "telegram",
  "client_name": "Анна П.",
  "topic": "Доставка в область",
  "status": "new",
  "priority": "normal"
}

Для lead.status_changed добавляются поля old_status и new_status; для lead.note_added — note_id, author_name, text. В вебхуке имя клиента — маскированное; полные данные забирайте через GET /v1/leads. Адрес должен быть публичным (внутренние и локальные адреса отклоняются).

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

`400`	Неверный параметр: формат `since`, недопустимый статус или событие, небезопасный URL вебхука.
`401`	Нет заголовка ключа, неверный формат (не `bic_crm_…`) или ключ отозван.
`402`	Тариф ниже Standard или подписка приостановлена за неоплату. Ключ сохранён, доступ вернётся после оплаты.
`403`	Аккаунт приостановлен.
`404`	Заявка, оператор или вебхук не найдены (или принадлежат другому бизнесу).
`429`	Превышен лимит запросов или достигнуто максимальное число вебхуков.

Тело ошибки — JSON {"detail": "…"} с пояснением на русском.

Лимиты: 120 запросов в минуту на ключ; до 500 заявок за один запрос; до 10 вебхук-подписок на бизнес.

Вопросы по интеграции — через контакты на сайте. Версия API зафиксирована: изменения, ломающие совместимость, выйдут только как /v2.