Внешний API

Внешний API предназначен для CRM, ботов, автоматизаций и собственных скриптов. Он отделён от внутренних маршрутов веб- и мобильного приложения.

Базовый URL: https://api.planovik.pro/api/v1/developer.

Ключ и права

Создайте персональный ключ в Настройки аккаунта → API. Полный секрет показывается один раз. Передавайте его только с сервера интеграции:

curl 'https://api.planovik.pro/api/v1/developer/workspaces' \
  -H 'Authorization: Bearer plk_ваш_секретный_ключ'

Поддерживается и X-API-Key, но Authorization: Bearer — основной вариант контракта. API-ключ не подходит для входа, профиля, резервных копий, ИИ, файлов, CalDAV и синхронизации приложения.

Право	Разрешение
`workspaces:read`	Просмотр доступных рабочих пространств
`projects:read`	Просмотр проектов
`projects:write`	Создание, изменение и удаление проектов
`tasks:read`	Просмотр задач
`tasks:write`	Создание, изменение и удаление задач

У ключа можно ограничить список рабочих пространств и задать срок действия. При отзыве ключа все запросы с ним сразу получают 401.

Типичный сценарий

Сначала получите доступные рабочие пространства, затем проекты нужного пространства, после этого создавайте задачи.

# 1. Рабочие пространства
curl 'https://api.planovik.pro/api/v1/developer/workspaces' \
  -H "Authorization: Bearer $PLANOVIK_TOKEN"

# 2. Проекты в выбранном пространстве
curl "https://api.planovik.pro/api/v1/developer/projects?workspaceId=$WORKSPACE_ID" \
  -H "Authorization: Bearer $PLANOVIK_TOKEN"

# 3. Новая задача. Idempotency-Key обязателен для безопасного retry.
curl -X POST 'https://api.planovik.pro/api/v1/developer/tasks' \
  -H "Authorization: Bearer $PLANOVIK_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7d50e5d3-7f16-4f5a-bbd1-5ea88a8b9bf9' \
  -d "{\"projectId\":\"$PROJECT_ID\",\"content\":\"Позвонить клиенту\",\"priority\":2}"

Сервер сам создаёт идентификатор задачи. Не используйте внутренние /tasks и /sync: они предназначены для local-first клиентов и требуют служебных полей.

Задачи

GET /tasks?workspaceId=<uuid>&limit=50 возвращает объект с data и pagination.nextCursor. Чтобы получить следующую страницу, передайте полученный cursor. Максимальный limit — 100.

POST /tasks принимает как минимум projectId и content. Дополнительно доступны description, priority (0–2), startAt, dueAt, labels, subtasks, assigneeId, recurringSettings.

PATCH /tasks/:id обязательно содержит текущую version, возвращённую сервером. При конкурентном изменении сервер возвращает 409 с актуальными данными — получите задачу заново и явно объедините изменения.

DELETE /tasks/:id выполняет мягкое удаление.

Проекты

Проект соответствует списку задач Planovik.

GET /projects?workspaceId=<uuid>
POST /projects — поля workspaceId, name, необязательный color
PATCH /projects/:id — version и изменяемые name/color
DELETE /projects/:id

Повторные запросы и ошибки

Для всех операций записи рекомендуем уникальный Idempotency-Key до 128 символов. Повтор того же метода и пути с тем же ключом в течение 24 часов вернёт первоначальный ответ, не создавая вторую задачу. Использование ключа для другого запроса вернёт 409.

Код	Значение
`400`	Неверные входные данные
`401`	Ключ отсутствует, отозван или истёк
`403`	Недостаточно прав ключа либо нет доступа к пространству
`404`	Ресурс не найден
`409`	Конфликт версии или `Idempotency-Key` использован с другим запросом
`429`	Превышен лимит запросов

По умолчанию один ключ может выполнить до 600 запросов за 15 минут. В ответе 429 сервер передаёт заголовок Retry-After; повторяйте запрос только после указанной паузы.

Полная машинная спецификация: apps/api/api-contract.yaml в репозитории.