#Карта статусов

Статус: Планируется. Канонические статусы лидов существуют в платформе уже сегодня; публичная настройка соответствия PUT /crm/status-map и проверка допустимых значений статуса — нет. Готовых интеграций с amoCRM, Bitrix24 и HubSpot нет: примеры на этой странице показывают, как можно настроить карту, а не поставляемую функцию. Сроки не обещаются.

В каждой CRM свои названия статусов: «Новая заявка», «Переговоры», «Успешно реализовано». Платформа хранит лиды в канонических статусах, а карта статусов переводит ваши названия в канонические и обратно. Это нужно, чтобы события и запросы действий агентов говорили на одном языке с вашей CRM.

Доступ: leads:write (настройка карты). Платно: нет. ПДн: нет.

#Канонические статусы

Канонических статусов шесть. Архив — не статус, а флаг лида.

Архив устроен как отметка на лиде: поля archived (boolean) и archived_reason, например ai_not_client. В карту статусов архив не входит (API лидов).

#Связь со сделками

Лид и сделка — разные объекты. Сделка живёт в воронке и стоит на стадии; статус лида переводится в роль стадии, а не в её название. Стадия воронки имеет роль (stage_key): new, qualified, proposal, negotiation, won, lost. Название стадии арендатор меняет свободно и на своём языке (например, «Консультация» вместо qualified), роль остаётся, и автоматика продолжает работать. Исход сделки определяется стадией, отмеченной как выигрышная или проигрышная.

Пример для воронки записи на курс (названия стадий настраиваются, здесь — исходные русские):

Стадии «Частично оплачено» и «Оплачено» в воронках обучения находятся по названию, а не по роли; на карту статусов лида они не влияют.

#PUT /crm/status-map

Задаёт соответствие статусов вашей CRM каноническим. Карта хранится по интеграции: у каждой интеграции своя. Область — leads:write. PUT идемпотентен по природе: повторный запрос с той же картой даёт тот же результат, а заголовок Idempotency-Key принимается и игнорируется. Запрос заменяет карту целиком.

Формат тела (обёртка map или плоский объект) в проекте записан как {external_status → canonical}. Ниже используется обёртка map; уточняется при выпуске.

Правила:

• Несколько внешних статусов могут вести в один канонический ("В работе" и "Звонок" → qualified).
• Канонический статус должен быть из списка, иначе 422 validation_failed; errors[].field указывает на ключ карты, например /map/Новая заявка. Значение archived недопустимо: архив — не статус.
• Нераспознанный внешний статус при PATCH получит 422 validation_failed.
• Нет leads:write — 403 scope_missing.

Ответ 200 OK: сохранённая карта ({"map": {…}}).

{
  "map": {
    "Новая заявка": "new",
    "Квалификация": "qualified",
    "Коммерческое предложение": "proposal",
    "Переговоры": "negotiation",
    "Успешно реализовано": "won",
    "Закрыто и не реализовано": "lost"
  }
}

#Примеры

curl -X PUT https://formula-cream.pro/api/public/v1/crm/status-map \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"map":{"Новая заявка":"new","Успешно реализовано":"won"}}'
# API_KEY=sap_ru_test_EXAMPLE0KEYID_… (пример, не настоящий ключ)

await fetch("https://formula-cream.pro/api/public/v1/crm/status-map", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ map: { "Новая заявка": "new", "Успешно реализовано": "won" } }),
});

httpx.put(
    "https://formula-cream.pro/api/public/v1/crm/status-map",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"map": {"Новая заявка": "new", "Успешно реализовано": "won"}},
)

$ch = curl_init("https://formula-cream.pro/api/public/v1/crm/status-map");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(
        ["map" => ["Новая заявка" => "new", "Успешно реализовано" => "won"]],
        JSON_UNESCAPED_UNICODE
    ),
]);

#Примеры карт для популярных CRM

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

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

#Заметки

• Сегодня статус в базе — свободный текст без проверки. Один из путей записывает значение in_progress, которого нет в канонических; перед выпуском его нужно вычистить и добавить проверку допустимых значений.
• Несколько частей кода меняют статус лида самостоятельно (ручная правка, кнопка «Оценить», анализ диалога, события воронки, движок продаж, автопотеря через 30 суток без активности, архив). В режимах external и both они должны проходить через единый сервис записи лида, который проверяет владение.
• Смена статуса внешней CRM идёт через PATCH /leads/{id} с If-Match (API лидов); событие lead.status_changed сообщает о смене на нашей стороне.

#Открытые вопросы

• Формат тела PUT /crm/status-map: обёртка map или плоский объект (техническое).
• Обратная сторона: при отправке событий платформа переводит канонический статус в ваш; нужна однозначность, если несколько внешних статусов ведут в один канонический (техническое).
• Точка чтения карты (GET /crm/status-map) в проекте не названа (техническое).
• Будет ли карта стадий сделок настраиваться отдельно от карты статусов лида (к владельцу).