# Carrot quest Web API: Передать данные пользователя с сервера

Сценарий из mcp-everything. Актуально на 2026-10-24.

Обновлять карточку лида в Carrot quest данными из своей системы: имя, email, телефон, тариф, сумма покупок.

1. Создай API-ключ: «Настройки» → «Разработчикам» → «API-ключи». Передавай его в заголовке Authorization: Token <ключ>. Вызывай API только с сервера — из браузерного JavaScript нельзя, для сайта есть JS-библиотека.
2. Запиши свойства: POST /users/{id}/props, где id — твой User ID и by_user_id = true. В operations — список операций с op, key и value; системные свойства начинаются с $ ($name, $email, $phone), свои — без него.
3. Если пользователя с таким User ID ещё нет, Carrot quest его создаст. За запрос — до 250 свойств.
4. Невалидные операции не дают ошибку, а попадают в meta.ignored_operations — проверяй этот список в ответе.
5. Лимит — 60 запросов в минуту на ключ; при превышении придёт 429 TooManyRequests.

```bash
curl -X POST https://api.carrotquest.io/users/user_42/props \
  -H "Authorization: Token $CQ_TOKEN" \
  --data-urlencode 'by_user_id=true' \
  --data-urlencode 'operations=[
    {"op": "update_or_create", "key": "$name", "value": "Иван Петров"},
    {"op": "update_or_create", "key": "$email", "value": "ivan@example.ru"},
    {"op": "update_or_create", "key": "Тариф", "value": "Про"}
  ]'
```

## Базовые URL

- Боевой: `https://api.carrotquest.io`

## Авторизация

Тип: API-ключ

Токен берётся в панели администратора: «Настройки» → «Разработчикам» → «API-ключи». Передаётся в заголовке `Authorization: Token <токен>` (или `Bearer <токен>`) либо параметром `auth_token`.

```
curl -X GET -H "Authorization: Token <ваш_токен>" https://api.carrotquest.io/users/123
```

## Методы сценария

### POST /users/{id}/props — Установка свойств пользователя

Операции выполняются по порядку; невалидные не дают ошибку, а попадают в `meta.ignored_operations`. Если пользователя с таким User ID нет, он создаётся.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `id` | path | string | да | ID в Carrot quest или ваш User ID |
| `by_user_id` | body | boolean | нет | Искать по вашему User ID |
| `operations` | body | array | да | Операции op, key, value, до 250 свойств; системные свойства начинаются с $ |
| `double_subscribe` | body | boolean | нет | Переподписать отписанного при обновлении $email |
| `parse_custom_props_type` | body | boolean | нет | Определять тип пользовательских свойств, по умолчанию true |
| `source` | body | object | нет | Источник контакта для $email/$phone (type, id) |

Пример запроса:

```
curl -X POST \
  --data-urlencode "operations=[{"op": "update_or_create", "key": "$name", "value": "Maks"}]" \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/users/8173131/props
```

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

```json
{
  "meta": {
    "status": 200,
    "affected_props": [],
    "ignored_operations": []
  },
  "data": {
    "id": 123123123,
    "app": 12345
  }
}
```

## Нюансы

- Параметры передаются GET- или POST-параметрами в UTF-8.
- Ответы — JSON с полями `meta` и `data`; `meta.status` дублирует HTTP-код.
- `{id}` пользователя — ID Carrot quest или ваш User ID с `by_user_id=true`; запись свойств и событий по неизвестному User ID создаёт пользователя.
- Токен даёт почти неограниченный доступ к данным приложения — не передавайте его третьим лицам.
- Для получения событий в реальном времени есть вебхуки и Realtime Services API.

## Другие сценарии

- [Записать событие пользователя](https://mcp-everything.ru/integrations/carrot-quest/scenarios/zapisat-sobytie-polzovatelya.md)
- [Написать пользователю в чат](https://mcp-everything.ru/integrations/carrot-quest/scenarios/napisat-polzovatelyu-v-chat.md)
- [Выгрузить неразобранные диалоги](https://mcp-everything.ru/integrations/carrot-quest/scenarios/vygruzit-nerazobrannye-dialogi.md)

---

Если этого недостаточно — официальная документация: https://developers.carrotquest.io/webapi/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/carrot-quest.md