Inbound API ДелоВход — приём заявок в CRM «Сделки»

Инструкция для разработчиков, которым нужно программно отправлять заявки (лиды) в нашу CRM «Сделки» — со своего сайта, лендинга (Tilda и т. п.), формы обратной связи или внешней системы.

Во всех примерах https://<ваш-домен> — это домен API нашего сервиса (тот же, на котором открывается личный кабинет). Подставьте реальный адрес, который вам выдали.

1. Что это и когда использовать

Inbound API принимает входящие заявки и кладёт их во внутреннюю CRM «Сделки». Каждая принятая заявка превращается в лид → сделку в той воронке, к которой привязан ваш API-ключ. Дубли по номеру телефона автоматически объединяются — повторная отправка того же телефона не создаёт вторую сделку.

Используйте Inbound API, когда нужно:

принимать заявки с собственного сайта или конструктора (Tilda, Webflow, самописная форма);
переносить заявки из внешней системы (другая CRM, чат-бот, колл-центр);
интегрировать любой источник, который умеет делать HTTP-запрос.

Требуется активная подписка CRM «Сделки». После истечения подписки приём продолжает работать ещё 12 дней (grace-период), затем останавливается, пока подписку не продлят (ответ 403).

2. Получение API-ключа

API-ключ создаётся в личном кабинете: раздел Интеграции → Входящий API → создать ключ.

Ключ строго привязан к одному проекту и одной воронке — заявки по нему попадают только в эту воронку. «Глобальных» ключей на все проекты не бывает.

Формат ключа: dlv_live_ + 32 шестнадцатеричных символа (всего 41 символ), например dlv_live_8f3aabcd1234567890abcdef12345678.

⚠️ Секрет показывается только один раз — в момент создания (поле plaintext_key в ответе). Сохраните его сразу в надёжном месте. Если ключ потерян — его нельзя посмотреть повторно, нужно перевыпустить (regenerate). На сервере хранится только SHA-256-хэш ключа; в интерфейсе виден лишь префикс вида dlv_live_8f3a.

Операции над ключами доступны в личном кабинете:

Операция	Что делает
Создать	Выпускает новый ключ для проекта + воронки, показывает секрет один раз
Переименовать	Меняет отображаемое имя ключа
Перевыпустить (regenerate)	Выдаёт новый секрет; старый сразу перестаёт работать
Отозвать	Отключает один ключ
Отозвать все	Отключает все ключи разом (выключает Входящий API целиком)

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

Передавайте ключ в заголовке запроса — любым из двух способов:

Authorization: Bearer dlv_live_...

или

X-Api-Key: dlv_live_...

Все запросы выполняются по HTTPS. Тело запроса — JSON, заголовок Content-Type: application/json.

🔒 Храните ключ только на сервере. Не вставляйте его в JavaScript на публичной странице — иначе любой посетитель сможет его прочитать. При компрометации немедленно перевыпустите или отзовите ключ в личном кабинете.

4. Отправка заявки — `POST /api/v1/inbound/leads`

Основной эндпоинт. Принимает данные заявки и создаёт лид/сделку.

Поля тела запроса

Поле	Тип	Огр.	Обяз.	Описание
`name`	string \| null	≤ 255	см. ниже	Имя клиента
`phone`	string \| null	≤ 50	см. ниже	Телефон (формат не проверяется)
`email`	string \| null	≤ 255	см. ниже	Email (формат не проверяется)
`message`	string \| null	≤ 5000	нет	Комментарий / текст обращения
`source`	string \| null	≤ 120	нет	Источник заявки (например `tilda`, `landing-contact`). Показывается в карточке сделки
`stageId`	string \| null	≤ 64	нет	Этап воронки, куда положить сделку. Не указан / неизвестен → «Неразобранное»
`utm`	object (string→string)	—	нет	UTM-метки (`{"source":"google","medium":"cpc"}`)
`fields`	object (string→string)	—	нет	Кастомные поля воронки по их `key` (см. §5)
`extra`	object	—	нет	Произвольные дополнительные данные
`positions`	array	≤ 100	нет	Состав заказа (позиции). Попадают в карточку сделки
`amountFromProducts`	bool \| null	—	нет	Считать сумму сделки по позициям. `null` = как настроено в воронке

Обязательное правило: должно быть заполнено хотя бы одно из phone, email, name. Иначе — ответ 422 с сообщением Нужно указать хотя бы одно из: phone, email, name.

Поля позиции (`positions[]`)

Поле	Тип	Огр.	По умолч.	Описание
`name`	string	≤ 255	`""`	Название позиции
`qty`	integer	≥ 1	`1`	Количество
`price`	integer	≥ 0	`0`	Цена за единицу в рублях (целое)
`catalogId`	string \| null	≤ 64	`null`	Ссылка на элемент каталога воронки. Если указан, `name`/`price` можно не передавать — подтянутся из каталога

Поля принимаются в обоих написаниях — camelCase и snake_case: stageId/stage_id, catalogId/catalog_id, amountFromProducts/amount_from_products.

Ответы

Код	Когда	Тело
`201`	Новая заявка принята	`{"id": <lead_id>, "status": "created"}`
`200`	Дубль по телефону (объединён)	`{"id": <lead_id>, "status": "repeat"}`

При 201 запускается обработка: уведомления (email/Telegram) и создание сделки в CRM. При 200 заявка распознана как повтор — в обработку повторно не уходит (защита от дублей в CRM).

Пример: полный запрос

curl -X POST https://<ваш-домен>/api/v1/inbound/leads \
  -H "Authorization: Bearer dlv_live_8f3aabcd1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван Петров",
    "phone": "+79991234567",
    "email": "ivan@example.com",
    "message": "Интересует премиум-пакет",
    "source": "tilda-contact",
    "stageId": "qualified",
    "utm": {"source": "google", "medium": "cpc", "campaign": "summer"},
    "fields": {"promo": "SUMMER50", "city": "Москва"},
    "positions": [
      {"name": "Премиум-пакет", "qty": 1, "price": 99000}
    ],
    "amountFromProducts": true
  }'

Ответ:

{ "id": 12345, "status": "created" }

Пример: минимальный запрос

curl -X POST https://<ваш-домен>/api/v1/inbound/leads \
  -H "X-Api-Key: dlv_live_8f3aabcd1234567890abcdef12345678" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+79991234567" }'

Повторная отправка того же телефона вернёт уже существующую сделку:

{ "id": 12345, "status": "repeat" }

5. Какие поля принимает воронка — `GET /api/v1/inbound/fields`

Вспомогательный эндпоинт для discovery: показывает, какая воронка привязана к ключу, какие этапы (stageId) доступны и какие кастомные поля можно передавать в fields.

Возвращаются только кастом-поля, которые настроены на заполнение через API (режим api или both); поля «только вручную» в список не попадают.

curl -X GET https://<ваш-домен>/api/v1/inbound/fields \
  -H "Authorization: Bearer dlv_live_8f3aabcd1234567890abcdef12345678"

Пример ответа:

{
  "standard": ["name", "phone", "email", "message"],
  "pipeline": { "id": "sales", "name": "Продажи" },
  "stages": [
    { "id": "unsorted", "label": "Неразобранное", "type": "unsorted" },
    { "id": "qualified", "label": "Квалифицирован", "type": "qualified" }
  ],
  "fields": [
    { "id": "f1", "key": "promo", "label": "Промокод", "type": "text", "required": false },
    { "id": "f2", "key": "city",  "label": "Город",    "type": "text", "required": true }
  ]
}

Как это связано с отправкой заявки:

значение stageId в POST — это один из stages[].id;
ключи объекта fields в POST — это значения fields[].key отсюда.

6. Ограничения и лимиты

Частота запросов: не более 60 запросов в минуту (суммарно на оба эндпоинта). При превышении — ответ 429.
Длины полей — см. таблицу в §4.
Позиции — не более 100 в одной заявке.

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

Код	Тело `{"detail": ...}`	Причина и что делать
`401`	`API-ключ не передан.`	Заголовок с ключом отсутствует. Добавьте `Authorization: Bearer …` или `X-Api-Key`.
`401`	`Неверный API-ключ.`	Ключ невалиден или отозван. Проверьте/перевыпустите ключ.
`400`	`Ключ не привязан к проекту. Пересоздайте ключ, указав проект и воронку.`	Старый ключ без привязки. Создайте новый ключ с проектом и воронкой.
`403`	`Подписка CRM неактивна — приём заявок по API остановлен. Продлите подписку CRM «Сделки».`	Подписка истекла (grace-период прошёл). Продлите подписку.
`422`	детали валидации	Ошибка в теле запроса (в т. ч. правило «хотя бы один из phone/email/name»).
`429`	—	Превышен лимит частоты (60/мин). Снизьте темп запросов.

8. Типовой сценарий интеграции

В личном кабинете создайте API-ключ для нужного проекта и воронки. Сразу сохраните plaintext_key — он показывается один раз.
(Опционально) Вызовите GET /api/v1/inbound/fields, чтобы узнать доступные stageId и ключи кастомных полей.
На своём сервере / в обработчике формы отправляйте POST /api/v1/inbound/leads с ключом в заголовке.
Обрабатывайте ответ: 201 created — новая заявка, 200 repeat — повтор; ошибки — по таблице §7.
Храните ключ только на стороне сервера. При компрометации — перевыпустите или отзовите ключ в личном кабинете.

Inbound API — приём заявок в CRM «Сделки»

1. Что это и когда использовать

2. Получение API-ключа

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

4. Отправка заявки — `POST /api/v1/inbound/leads`

Поля тела запроса

Поля позиции (`positions[]`)

Ответы

Пример: полный запрос

Пример: минимальный запрос

5. Какие поля принимает воронка — `GET /api/v1/inbound/fields`

6. Ограничения и лимиты

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

8. Типовой сценарий интеграции

Похожие статьи

Как настроить вебхук-интеграцию: получаем лиды на свой сервер

Inbound API — приём заявок в CRM «Сделки»

1. Что это и когда использовать

2. Получение API-ключа

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

4. Отправка заявки — POST /api/v1/inbound/leads

Поля тела запроса

Поля позиции (positions[])

Ответы

Пример: полный запрос

Пример: минимальный запрос

5. Какие поля принимает воронка — GET /api/v1/inbound/fields

6. Ограничения и лимиты

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

8. Типовой сценарий интеграции

Похожие статьи

Как настроить вебхук-интеграцию: получаем лиды на свой сервер

4. Отправка заявки — `POST /api/v1/inbound/leads`

Поля позиции (`positions[]`)

5. Какие поля принимает воронка — `GET /api/v1/inbound/fields`