---
name: pachca-tasks
description: >
  Создание, получение, обновление и удаление задач (напоминаний). Используй когда
  нужно: создать задачу, получить список задач, обновить задачу, удалить задачу.
---

# pachca-tasks

Base URL: `https://api.pachca.com/api/shared/v1`
Авторизация: `Authorization: Bearer <ACCESS_TOKEN>`
Токен: бот (Автоматизации → Интеграции → API) или пользователь (Автоматизации → API).
Если токен неизвестен — спроси у пользователя перед выполнением запросов.

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

- создать задачу
- список задач
- напоминание
- обновить задачу
- отметить задачу выполненной
- удалить задачу
- кастомные поля задачи

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

- получить профиль, мой профиль, установить статус → **pachca-profile**
- найти сотрудника, создать пользователя, список сотрудников → **pachca-users**
- создать канал, создать беседу, создать чат → **pachca-chats**
- отправить сообщение, ответить в тред, прикрепить файл → **pachca-messages**
- настроить бота, вебхук, webhook → **pachca-bots**
- показать форму, интерактивная форма, модальное окно → **pachca-forms**
- поиск сообщений, найти сообщение, полнотекстовый поиск → **pachca-search**
- аудит, журнал событий, безопасность → **pachca-security**

## Пошаговые сценарии

### Создать напоминание

1. POST /tasks с `kind`, `content` и `due_at`
2. Чтобы привязать к чату — добавь `chat_id`
3. Чтобы заполнить дополнительные поля — добавь `custom_properties: [{"id": <field_id>, "value": "..."}]` (список полей: GET /custom_properties?entity_type=Task)

```bash
curl "https://api.pachca.com/api/shared/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task":{"kind":"reminder","content":"Позвонить клиенту","due_at":"$DUE_AT","chat_id":$CHAT_ID,"custom_properties":[{"id":78,"value":"Синий склад"}]}}'
```

> Для привязки к чату нужно быть его участником. Если чат не найден — 404. Тип значения `custom_properties[].value` всегда строка (даже для числовых и date-полей). Дополнительные поля настраиваются администратором пространства.

### Получить список предстоящих задач

1. GET /tasks с пагинацией (`limit`, `cursor`)
2. Отфильтруй на клиенте по полю `status`: `"undone"` — не выполнена, `"done"` — выполнена

```bash
curl "https://api.pachca.com/api/shared/v1/tasks?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

> Фильтрация по `status` на стороне API не поддерживается — фильтруй самостоятельно после получения.

### Отметить задачу выполненной

1. PUT /tasks/{id} с `"status": "done"`

```bash
curl -X PUT "https://api.pachca.com/api/shared/v1/tasks/12345" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task":{"status":"done"}}'
```

### Создать серию напоминаний

1. Подготовь список дат (ежедневно, еженедельно и т.д.)
2. Для каждой даты: POST /tasks с нужным `kind`, `content` и `due_at`

## Обработка ошибок

| Код | Причина | Что делать |
|-----|---------|------------|
| 422 | Неверные параметры | Проверь обязательные поля, типы данных, допустимые значения enum |
| 429 | Rate limit | Подожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec |
| 403 | Нет доступа | Недостаточно скоупов (`insufficient_scope`), бот не в чате, или endpoint только для админов/владельцев |
| 404 | Не найдено | Неверный id. Проверь что сущность существует |
| 401 | Не авторизован | Проверь токен в заголовке Authorization |

## Доступные операции

### Новое напоминание

`POST /tasks`

> скоуп: `tasks:create`

```json
{
  "task": {
    "kind": "call"
  }
}
```

### Список напоминаний

`GET /tasks`

> скоуп: `tasks:read`

### Информация о напоминании

`GET /tasks/{id}`

> скоуп: `tasks:read`

### Редактирование напоминания

`PUT /tasks/{id}`

> скоуп: `tasks:update`

```json
{
  "task": {}
}
```

### Удаление напоминания

`DELETE /tasks/{id}`

> скоуп: `tasks:delete`

## Ограничения и gotchas

- `task.kind`: допустимые значения — `call` (Позвонить контакту), `meeting` (Встреча), `reminder` (Простое напоминание), `event` (Событие), `email` (Написать письмо)
- `task.status`: допустимые значения — `done` (Выполнено), `undone` (Активно)
- `limit`: максимум 50
- Пагинация: cursor-based (limit + cursor), НЕ page-based

## Подробнее

см. [references/endpoints.md](references/endpoints.md)