Лиды

Лид — заявка от клиента, которого привёл партнёр. Через внешний API её можно создать из своей системы, провести по статусам и зафиксировать сумму сделки.

Все пути ниже даны относительно базового адреса /api/external, каждый запрос требует заголовок x-api-key — см. Внешний API.

Как получить список полей лида

Состав полей у каждого контура свой: их настраивает администратор. Начинать интеграцию нужно с этого метода — из него берутся идентификаторы, которыми потом заполняется заявка.

GET /api/external/lead-fields
x-api-key: ваш-ключ

[
  {
    "id": "0f8c…",
    "systemName": "email",
    "label": "Электронная почта",
    "type": "String",
    "options": null,
    "required": true,
    "hidden": false
  },
  {
    "id": "b31a…",
    "systemName": "city",
    "label": "Город",
    "type": "List",
    "options": [{ "id": "msk", "name": "Москва" }],
    "required": false,
    "hidden": false
  }
]

Поле	Что означает
`id`	идентификатор поля, его же передают в `fields[].fieldTypeId`
`systemName`	имя поля, заданное администратором для интеграции
`label`	подпись поля в интерфейсе
`type`	`String`, `Number`, `Boolean` или `List`
`options`	допустимые значения для `List`, иначе `null`
`required`	без этого поля заявка не создастся

Отдаются только нескрытые поля. Скрытое поле пропадает из ответа, но данные прошлых заявок по нему сохраняются.

Как создать лид

POST /api/external/lead
x-api-key: ваш-ключ
Content-Type: application/json

{
  "sessionId": "3f2a…",
  "fields": [
    { "fieldTypeId": "0f8c…", "value": "ivan@example.com" },
    { "fieldTypeId": "b31a…", "value": "msk" }
  ]
}

Поле	Обязательное	Описание
`fields`	да	значения полей заявки
`sessionId`	нет	переход по партнёрской ссылке
`promocode`	нет	промокод, которым воспользовался клиент

Значение поля передаётся по его типу:

Тип поля	Что передавать в `value`
`String`	строку
`Number`	число
`Boolean`	`true` или `false`
`List`	`id` одной из опций поля

В ответ приходит созданный лид: его id, начальный статус, привязанные партнёр и предложение и все заполненные поля. Начальный статус — тот, который в контуре помечен как первичный.

Как привязать лид к партнёру

Заявку связывают с партнёром sessionId или promocode — одно из двух. Если не передать ни то, ни другое, лид создастся ничьим: вознаграждение по нему никому не начислится.

По ссылке. Партнёр размещает свою короткую ссылку, а мы, отправляя клиента на целевую страницу, дописываем к её адресу параметр session:

https://example.com/landing?session=3f2a…

Задача вашей страницы — сохранить это значение (например, в скрытом поле формы или в cookie) и отдать его как sessionId при создании лида. Одна сессия — один лид: повторный запрос с тем же sessionId вернёт ошибку.

По промокоду. Передайте сам код в promocode. Код должен быть активным: промокоды на проверке и отключённые не принимаются. Одинаковые заявки по одному промокоду в течение суток считаются повтором и отклоняются — так отсекаются дубли от повторной отправки формы.

Как сменить статус лида

PUT /api/external/lead/{id}/status
x-api-key: ваш-ключ
Content-Type: application/json

{ "systemName": "in_progress" }

Статус указывается либо по id, либо по systemName — тому, что задан в настройках статусов вашего контура. Хотя бы одно из двух передать обязательно.

При переводе в целевой статус — тот, что означает состоявшуюся сделку, — нужно передать ещё и amount с суммой. Исключение: в предложении включено «Разрешить сделки по предложению без суммы», тогда сумму можно не передавать.

Смена статуса запускает начисление вознаграждения партнёру, поэтому именно этот метод обычно и вызывается из CRM.

Как добавить сделку к лиду

Если по одной заявке проходит несколько сделок, каждую следующую добавляют отдельно:

PUT /api/external/lead/{id}/add-deal
x-api-key: ваш-ключ
Content-Type: application/json

{ "amount": 15000 }

Сумма должна быть больше нуля. Метод работает только когда лид уже находится в целевом статусе: до этого добавлять сделки не к чему.

Какие ошибки возвращают методы лидов

Ответ	Сообщение	Что делать
`400`	Обязательное поле «…» не заполнено	добавьте поле в `fields`, список — в `GET /lead-fields`
`400`	Тип поля … не найден	`fieldTypeId` устарел, перечитайте список полей
`400`	Лид уже создан для этой сессии	по этому переходу заявка уже есть
`400`	Лид с таким набором полей уже создан	дубль по промокоду за сутки; прежний лид приходит в теле ответа
`400`	Укажите id или systemName статуса	передайте одно из полей
`400`	При переводе в статус «…» необходимо указать сумму сделки	добавьте `amount`
`404`	Сессия не найдена	значение `session` не дошло до вашей формы или было изменено
`404`	Промкод не найден или неактивен	код не существует или ещё не подтверждён
`404`	Предложение недоступно	предложение остановлено или закрыто для этого партнёра
`404`	Добавлять сделки можно только в статусе «…»	сначала переведите лид в целевой статус

Читать также

Внешний API — базовый адрес, ключи и остальные методы
Типы полей лидов — где администратор настраивает состав заявки