Жизненный цикл лида

Понимание того, что происходит с лидом после POST /v1/inbound/leads, помогает корректно реагировать на callback'и.

Этапы

   принят                  взят в работу       выкуп (FTD)         повторный депозит
inbound → new   ───►   contacted ───►   ftd   ─────────►   rtd
   │                       │
   │                       └─►   trash / no_answer / wrong_number   (terminal без FTD)
   │
   └─►   duplicate / rejected   (так и не дошёл до агента)

Статусы по умолчанию

Код	Scope	Terminal	Значение
new	both	no	Только что принят, ждёт распределения.
assigned	both	no	Закреплён за агентом, ждёт первого контакта.
contacted	both	no	Агент дозвонился / написал.
callback	both	no	Лид попросил перезвонить позже.
interested	both	no	Готов рассмотреть, но не задепал.
no_answer	lead	yes	Не подняли трубку N раз.
wrong_number	lead	yes	Не его номер.
trash	lead	yes	Мусор / троллинг / спам.
ftd	client	no	Сделан первый депозит. Лид → клиент.
rtd	client	no	Повторный депозит.
chargeback	client	yes	Возврат депозита.

Кастомные статусы

Список выше — дефолт. У вашего CRM-партнёра могут быть кастомные коды. Реальный список, который придёт в our_status callback'а, отражает текущую конфигурацию системы. Их можно смаппить на ваши коды через status_mapping (см. ниже).

Status mapping (мы → вы)

Если ваша система оперирует другими кодами (например, у вас won вместо ftd, lost вместо trash), менеджер настроит для вашего партнёра status_mapping:

{
  "ftd": "won",
  "trash": "lost",
  "no_answer": "no_contact"
}

В callback'ах мы пришлём оба значения:

{
  "event": "lead.status_changed",
  "status": "won",        // ← перемаплено по вашей таблице
  "our_status": "ftd"     // ← наш канонический код
}

Если для нашего кода нет записи в status_mapping — отдадим его «как есть».

Когда лид становится клиентом

В Cartel CRM два физических объекта: lead и client. Клиент создаётся в момент первого депозита (FTD). При этом:

• lead.client_id заполняется ссылкой на новый client.
• В callback'е is_depositor становится true.
• Все последующие события (RTD, chargeback) приходят с этим же external_lead_id — с вашей стороны клиент по-прежнему ваш изначальный лид.

Никаких сумм в callback'е о FTD

Факт депозита — да, сумма — нет. По договору. Если вам критична сумма для unit-economics — она будет доступна вам в личном кабинете или через биллинговый API (отдельно).

Что делать при duplicate / rejected

• duplicate: лид уже есть в нашей базе (matched по phone или email в окне дедупликации). На вашей стороне это просто значит «мы такое уже видели». Можно логировать, callback не придёт.
• rejected: лид не прошёл бизнес-правила (страна / тип / источник). Поле reason объясняет конкретно. Это финальное состояние — лид в работу не пойдёт.

Финальный пример

T+0s   POST /v1/inbound/leads        → 200 {id: "le-12345", status: "accepted"}
T+0s   callback: lead.accepted        → ✓
T+5m   агент дозвонился               → callback: lead.status_changed (contacted)
T+1h   первый депозит зафиксирован    → callback: lead.ftd
T+3d   повторный депозит              → callback: lead.rtd

С вашей стороны — простой цикл: храните external_lead_id → internal_id mapping, обновляйте статус по каждому callback'у, и всё.