# Создать дело у карточки CRM

`POST /v1/deals/{id}/activities`

`POST /v1/leads/{id}/activities`

`POST /v1/contacts/{id}/activities`

`POST /v1/companies/{id}/activities`

Адрес выбирает одного владельца: сделку (`deals`, тип владельца 2), лид (`leads`, 1), контакт (`contacts`, 3) или компанию (`companies`, 4). Скоуп: `crm`. Поддерживаются личные ключи и ключи OAuth-приложений.

## Когда использовать

Этот маршрут создаёт дело с владельцем, выбранным в адресе. Обработчик заменяет camelCase-поля тела `ownerTypeId` и `ownerId` владельцем из адреса. Не передавайте поля владельца в теле. Локально тело необязательно. Итоговые поля проверяет Битрикс24.

Для полного контракта дела в camelCase используйте [POST /v1/activities](./create.md): он принимает `typeId`, `communications` и поля владельца в теле и возвращает дело. Вложенный метод использует `type` для PROVIDER_TYPE_ID, исходные TYPE_ID и COMMUNICATIONS для соответствующих полей и возвращает только `data.id`. Для фильтров и сортировки используйте [GET /v1/activities](./list.md).

## Параметры

| Поле | Тип | Обязательное | Описание |
|------|-----|--------------|----------|
| `id` (путь) | string | Да | ID владельца из [списка сделок](../deals/list.md), [лидов](../leads/list.md), [контактов](../contacts/list.md) или [компаний](../companies/list.md). |
| `subject`, `description` | string | Нет местной проверки | Преобразуются в SUBJECT и DESCRIPTION. Обязательность полей проверяет Битрикс24. |
| `type` | string | Нет | `email`, `call`, `meeting`, `task` → PROVIDER_TYPE_ID. Это не числовой TYPE_ID. |
| `completed` | boolean / string | Нет | `true`/`false` → Y/N. Остальные значения передаются без изменений. |
| `responsibleId` | number / string | Нет | Ответственный сотрудник из [списка пользователей](../users/list.md). |
| `priority`, `direction` | number / string | Нет | Передаются в PRIORITY и DIRECTION. |
| `deadline`, `startTime`, `endTime` | string | Нет | Передаются в DEADLINE, START_TIME, END_TIME. Указывайте смещение часового пояса явно. |
| `id`, `createdAt`, `updatedAt` (тело) | number / string | Нет | Преобразуются в ID, CREATED, LAST_UPDATED, если переданы. Допустимость решает Битрикс24. Обычно эти служебные поля следует опустить. |
| `TYPE_ID` | integer | Нет местной проверки | Исходный числовой тип дела, например 2 для звонка. `typeId` не преобразуется. |
| `COMMUNICATIONS` | array | Нет местной проверки | Исходные объекты коммуникаций: VALUE, ENTITY_TYPE_ID, ENTITY_ID. ID контакта возьмите из [списка контактов](../contacts/list.md). `communications` и вложенные ключи не преобразуются. |
| Остальные ключи | any | Нет | Передаются без изменений. Используйте названия полей Битрикс24. |

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/deals/575/activities" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Позвонить клиенту",
  "type": "call",
  "TYPE_ID": 2,
  "completed": false,
  "responsibleId": 1,
  "COMMUNICATIONS": [
    {
      "VALUE": "+12025550123",
      "ENTITY_TYPE_ID": 3,
      "ENTITY_ID": 17
    }
  ]
}'
```

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/deals/575/activities" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Позвонить клиенту",
  "type": "call",
  "TYPE_ID": 2,
  "completed": false,
  "responsibleId": 1,
  "COMMUNICATIONS": [
    {
      "VALUE": "+12025550123",
      "ENTITY_TYPE_ID": 3,
      "ENTITY_ID": 17
    }
  ]
}'
```

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

```javascript
const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/575/activities', {
  method: 'POST',
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "subject": "Позвонить клиенту",
    "type": "call",
    "TYPE_ID": 2,
    "completed": false,
    "responsibleId": 1,
    "COMMUNICATIONS": [
      {
        "VALUE": "+12025550123",
        "ENTITY_TYPE_ID": 3,
        "ENTITY_ID": 17
      }
    ]
  }),
})
const result = await response.json()
if (!response.ok || !result.success) throw new Error(JSON.stringify(result.error))
console.log(result.data)
```

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

```javascript
const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/575/activities', {
  method: 'POST',
  headers: {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "subject": "Позвонить клиенту",
    "type": "call",
    "TYPE_ID": 2,
    "completed": false,
    "responsibleId": 1,
    "COMMUNICATIONS": [
      {
        "VALUE": "+12025550123",
        "ENTITY_TYPE_ID": 3,
        "ENTITY_ID": 17
      }
    ]
  }),
})
const result = await response.json()
if (!response.ok || !result.success) throw new Error(JSON.stringify(result.error))
console.log(result.data)
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успехе, HTTP 201. |
| `data.id` | number / string | ID созданного дела из Битрикс24 без преобразования. Само дело дополнительно не запрашивается. |

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

Пример структуры ответа:

```json
{
  "success": true,
  "data": {
    "id": 3894
  }
}
```

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

400 — неподдерживаемый тип дела:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_ACTIVITY_TYPE",
    "message": "Invalid activity type 'sms'. Available: email, call, meeting, task"
  }
}
```

## Ошибки

| HTTP | Код | Условие |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Битрикс24 отклонил параметр. |
| 401 | `TOKEN_MISSING` | Не настроены учётные данные Битрикс24. |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `crm`. |
| 404 | `ENTITY_NOT_FOUND` | Битрикс24 сообщил об отсутствии сущности. Отдельной проверки существования владельца нет. |
| 422 | `BITRIX_ERROR` | Отказ Битрикс24 без более точного сопоставления. |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ READONLY не может создавать дела. |
| 400 | `INVALID_ACTIVITY_TYPE` | Непустой type не входит в четыре поддерживаемых значения. |

[Общие ошибки API](../../errors.md).

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

- [Список дел у карточки CRM](./owner-list.md)
- [Создать дело](./create.md)
- [Получить дело](./get.md)