## Создать to-do

`POST /v1/activity-todos`

Создаёт дело типа «To-do» у сделки, лида, контакта или компании. Поля передаются плоско в корне JSON, без обёртки `fields`.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `ownerTypeId` | number | да | Тип объекта CRM, к которому относится дело. Для сделки — `2` |
| `ownerId` | number | да | ID объекта CRM. Для сделки — ID из [`GET /v1/deals`](/docs/entities/deals/list) |
| `deadline` | string | да | Срок дела в формате ISO 8601, например `2026-11-02T12:00:00+03:00` |
| `title` | string | нет | Заголовок дела. В ответе приходит в поле `subject` |
| `description` | string | нет | Описание дела |
| `responsibleId` | number | нет | ID ответственного. Список: [`GET /v1/users`](/docs/entities/users/list). Без поля ответственным становится пользователь ключа |
| `parentActivityId` | number | нет | ID дела, к которому привязывается новое. Родитель должен относиться к тому же объекту CRM. Список дел объекта: [`GET /v1/activities`](/docs/entities/activities/list) с фильтром по `ownerTypeId` и `ownerId` |
| `pingOffsets` | number[] | нет | Напоминания: целые числа минут до срока, не меньше `0` |
| `colorId` | string | нет | Цвет дела: `default` или от `1` до `7`. После создания цвет не меняется |

Других полей тело не принимает: неизвестное поле отклоняется с `400 INVALID_PARAMS`.

## Примеры

### curl — личный ключ

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/activity-todos" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerTypeId": 2,
    "ownerId": 8845,
    "deadline": "2026-11-02T12:00:00+03:00",
    "title": "Проверить договор",
    "description": "Позвонить клиенту"
  }'
```

### curl — OAuth-приложение

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/activity-todos" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerTypeId": 2,
    "ownerId": 8845,
    "deadline": "2026-11-02T12:00:00+03:00",
    "title": "Проверить договор",
    "description": "Позвонить клиенту"
  }'
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/activity-todos', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ownerTypeId: 2,
    ownerId: 8845,
    deadline: '2026-11-02T12:00:00+03:00',
    title: 'Проверить договор',
    description: 'Позвонить клиенту',
  }),
})

const { data } = await res.json()
console.log('To-do ID:', data.id)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/activity-todos', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ownerTypeId: 2,
    ownerId: 8845,
    deadline: '2026-11-02T12:00:00+03:00',
    title: 'Проверить договор',
    description: 'Позвонить клиенту',
  }),
})

const { data } = await res.json()
```

## Поля ответа

Ответ — HTTP `201` с созданным делом, прочитанным после записи. Форма та же, что у [`GET /v1/activities/:id`](/docs/entities/activities/get).

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | `true` при успехе |
| `data` | object | Созданное дело, все поля — [Поля дела](/docs/entities/activities/fields) |
| `data.id` | number | ID дела. По нему дело читается через [`GET /v1/activities/:id`](/docs/entities/activities/get) и меняется через [`PATCH /v1/activity-todos/:id`](./update.md) |
| `data.providerId` | string | Всегда `CRM_TODO` |
| `data.subject` | string | Заголовок из поля `title` запроса |
| `data.deadline` | string | Срок дела в UTC |
| `data.associatedEntityId` | number | ID родительского дела из `parentActivityId` или `0` без родителя |
| `data.completed` | boolean | Завершено ли дело. У нового дела — `false` |

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

Показаны основные поля. Полный список: [Поля дела](/docs/entities/activities/fields).

```json
{
  "success": true,
  "data": {
    "id": 8379,
    "ownerId": 8845,
    "ownerTypeId": 2,
    "typeId": 6,
    "providerId": "CRM_TODO",
    "providerTypeId": "TODO",
    "associatedEntityId": 0,
    "subject": "Проверить договор",
    "deadline": "2026-11-02T09:00:00.000Z",
    "completed": false,
    "status": 1,
    "responsibleId": 1317,
    "description": "Позвонить клиенту"
  }
}
```

## Пример ответа при ошибке

400 — родительское дело относится к другому объекту CRM:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Parent activity is not bound to the requested CRM owner"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Нарушена валидация тела: нет `ownerTypeId`, `ownerId` или `deadline`, ID-поле не положительное целое число, `title` или `description` не строка, срок не в формате ISO 8601, цвет вне палитры, `pingOffsets` не массив неотрицательных целых чисел, неизвестное поле |
| 400 | `INVALID_PARAMS` | Родительское дело из `parentActivityId` относится к другому объекту CRM |
| 400 | `MISSING_REQUIRED_FIELDS` | Тело запроса не JSON-объект |
| 422 | `ACTIVITY_PARENT_NOT_APPLIED` | Дело создано, но без привязки к родителю. ID нового дела — в `error.createdId`: проверьте его через [`GET /v1/activities/:id`](/docs/entities/activities/get) и родительское дело, а не отправляйте `POST` снова — повтор создаст второе дело |
| 404 | `ENTITY_NOT_FOUND` | Дела из `parentActivityId` не существует. Дело не создаётся |
| 502 | `BITRIX_ERROR` | Не удалось прочитать привязки родительского дела, или Битрикс24 не вернул ID созданного дела. Во втором случае проверьте список дел объекта, прежде чем повторять запрос |
| 502 | `ACTIVITY_CREATED_READ_FAILED` | Дело создано, но прочитать его после записи не удалось. ID нового дела — в `error.createdId`: проверьте его через [`GET /v1/activities/:id`](/docs/entities/activities/get), а не отправляйте `POST` снова — повтор создаст второе дело |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `crm` |
| 401 | `TOKEN_MISSING` | У ключа нет подключения к Битрикс24 |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Родитель завершается.** Дело, указанное в `parentActivityId`, после создания нового становится завершённым: `completed: true`, `status: 2`.

## Смотрите также

- [Изменить to-do](./update.md)
- [Получить дело](/docs/entities/activities/get)
- [Список дел](/docs/entities/activities/list)
- [Завершить дело](/docs/entities/activities/complete)
- [To-do дела CRM](../todos.md)