API для партнёров

Задачи UniDesk —внутри вашего сервиса

Заводите пользователей без Telegram и MAX, ставьте им задачи и открывайте их доски в браузере по одноразовой ссылке. Простой REST и JSON.

Интеграцию включает администратор UniDesk · help@unidesk.team

Как подключиться

  1. Попросите открыть интеграцию. Напишите на help@unidesk.team: администратор UniDesk включит её вашему аккаунту и поставит лимит пользователей.
  2. Выпустите ключ. В кабинете, раздел «API» → «Интеграция для вашего сервиса». Ключ начинается с udk_ и показывается один раз — сохраните его на сервере.
  3. Отправляйте запросы со своего сервера. Ключ не кладите в код страниц и мобильных приложений: с ним можно управлять всеми вашими пользователями.

Основы

Адрес API: https://api.unidesk.martynov.tech/api/v1. Ключ передаётся в заголовке Authorization: Bearer udk_…. Тело запросов и ответов — JSON в UTF-8.

curl https://api.unidesk.martynov.tech/api/v1/users -H "Authorization: Bearer udk_…"

Пользователя вы указываете своим идентификатором — external_id (в путях — {ext}): 1–128 символов, латиница, цифры и . _ - : @. Например, id из вашей базы или почта. Вы видите только своих пользователей.

Лишние поля в JSON не игнорируются, а дают 400 — так опечатка в названии поля не пройдёт незамеченной.

Ошибка приходит с понятным текстом:

{"error": "пользователь не найден"}
КодКогда
200, 201Готово; 201 — создано новое
400Неверные данные: формат даты, длина текста, external_id
401Нет ключа, ключ неверный, отозван или интеграцию выключили
403Лимит: пользователей интеграции или личных досок на тарифе
404Пользователь, доска или задача не найдены (или они не ваши)

Пользователи

Пользователь интеграции — обычный аккаунт UniDesk без Telegram и MAX. При создании у него появляется основная личная доска.

POST/users

Заводит пользователя. Повторный вызов с тем же external_id не создаёт второго, а возвращает существующего (код 200, "created": false) и обновляет имя и почту, если вы их передали — так их и меняют.

curl -X POST https://api.unidesk.martynov.tech/api/v1/users \
  -H "Authorization: Bearer udk_…" -H "Content-Type: application/json" \
  -d '{"external_id": "crm-1042", "name": "Иван Иванов", "email": "ivan@example.com"}'
HTTP/1.1 201 Created
{
  "created": true,
  "user": {
    "external_id": "crm-1042",
    "uid": 51234,
    "name": "Иван Иванов",
    "email": "ivan@example.com",
    "telegram": false,
    "max": false,
    "created_at": "2026-11-08T10:15:00Z"
  }
}

Обязателен только external_id; name и email — до 200 символов. Когда лимит пользователей исчерпан — 403.

Передавайте почту, если она есть. Если у человека уже есть аккаунт UniDesk с этой почтой (подтверждённой у нас), веб-версия предложит объединить аккаунты. Код из 6 цифр придёт владельцу прежнего аккаунта на почту и в Telegram или MAX; после объединения задачи будут в одном месте, а пользователь останется вашим — с тем же external_id.

GET/users?limit=100&offset=0

Ваши пользователи и общее число. limit — до 500, по умолчанию 100.

{ "users": [ { "external_id": "crm-1042", "uid": 51234, "name": "Иван Иванов", ... } ], "total": 1 }
GET/users/{ext}

Один пользователь: {"user": {…}}.

ПолеТипЧто это
external_idстрокаВаш идентификатор
uidчислоНомер аккаунта в UniDesk
nameстрокаИмя
emailстрокаПочта
telegramда/нетЧеловек привязал Telegram
maxда/нетЧеловек привязал MAX
created_atвремяКогда заведён, RFC 3339 в UTC

Вход в браузере

Человеку не нужны пароль и мессенджер: ваш сервис получает одноразовую ссылку и открывает её — например, по кнопке «Мои задачи» у себя.

POST/users/{ext}/login-link
curl -X POST https://api.unidesk.martynov.tech/api/v1/users/crm-1042/login-link -H "Authorization: Bearer udk_…"
{
  "url": "https://unidesk.team/app/?login=udl_…",
  "expires_at": "2026-11-09T10:15:00Z",
  "note": "Ссылка одноразовая и действует сутки. Открыв её, человек остаётся в досках в этом браузере 30 дней."
}

Ссылка открывает веб-версию UniDesk — задачи, календарь, запись и контакты пользователя. Открыть её можно один раз в течение суток; после этого вход в этом браузере держится 30 дней. Выдавайте новую ссылку каждый раз, когда человек нажимает кнопку.

POST/users/{ext}/logout

Закрывает все входы человека в браузере — например, когда он ушёл из вашей компании. Ответ: {"revoked": 2} — сколько входов закрыто.

Доски

GET/users/{ext}/boards
{
  "boards": [
    { "id": 901, "kind": "personal", "title": "Мои задачи", "is_main": true, "own": true, "open": 3, "mine": 0 }
  ]
}
ПолеТипЧто это
idчислоНомер доски
kindстрокаpersonal — личная, team — доска группы в мессенджере
titleстрокаНазвание
is_mainда/нетОсновная доска
ownда/нетДоску завёл сам пользователь
openчислоНезакрытых задач
mineчислоНезакрытых, назначенных пользователю
POST/users/{ext}/boards

Новая личная доска: {"title": "Проект «Альфа»"}. Ответ 201 с {"board": {…}}. Число личных досок ограничено тарифом пользователя — сверх него 403.

Задачи

Без board_id задачи берутся из основной личной доски и попадают в неё же.

GET/users/{ext}/tasks?board_id=901&done=1

Задачи доски. Без done=1 — только незакрытые, с ним — вместе с выполненными. Ответ: {"board_id": 901, "tasks": [ … ]}.

POST/users/{ext}/tasks
curl -X POST https://api.unidesk.martynov.tech/api/v1/users/crm-1042/tasks \
  -H "Authorization: Bearer udk_…" -H "Content-Type: application/json" \
  -d '{"title": "Сдать отчёт", "priority": 3, "due_date": "2026-12-01", "due_time": "10:00"}'
HTTP/1.1 201 Created
{
  "task": {
    "id": 77120, "board_id": 901, "title": "Сдать отчёт", "notes": "",
    "priority": 3, "due_date": "2026-12-01", "due_time": "10:00",
    "assignee_uid": null, "assignee_name": "", "done": false,
    "created_by": 51234, "creator_name": "Иван Иванов",
    "created_at": "2026-11-08 10:20:00", "updated_at": "2026-11-08 10:20:00"
  }
}
GET/users/{ext}/tasks/{id}

Одна задача: {"task": {…}}.

PATCH/users/{ext}/tasks/{id}

Меняет только переданные поля. Закрыть задачу — {"done": true}, снять срок — {"due_date": ""}. Ответ — задача целиком.

DELETE/users/{ext}/tasks/{id}

Удаляет задачу. Ответ: {"deleted": true}.

Поля задачи

ПолеТипЧто это
board_idчислоДоска; только при создании, по умолчанию основная личная
titleстрокаТекст задачи, до 1000 символов
notesстрокаОписание, до 5000 символов
priority0–30 — нет, 1 — низкий (зелёный), 2 — средний (жёлтый), 3 — высокий (красный)
due_dateГГГГ-ММ-ДДСрок; пустая строка снимает
due_timeЧЧ:ММВремя срока; пустая строка — без времени
doneда/нетВыполнена

Пример целиком

Завести сотрудника, поставить задачу и дать ссылку на доски:

KEY="udk_…"
API="https://api.unidesk.martynov.tech/api/v1"

curl -s -X POST "$API/users" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"external_id": "crm-1042", "name": "Иван Иванов"}'

curl -s -X POST "$API/users/crm-1042/tasks" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Позвонить клиенту", "due_date": "2026-11-10"}'

curl -s -X POST "$API/users/crm-1042/login-link" -H "Authorization: Bearer $KEY"
# → откройте "url" из ответа в браузере человека