FAQ по API

Быстрый старт

1. Создайте ключ

   Личный кабинет → API → Ключи для /api/task: укажите название, срок действия и отметьте нужные права. Ключ показывается один раз — скопируйте его сразу.

2. Проверьте ключ

   Запрос «кто я» вернёт владельца ключа и список его прав:

   # Ключ подставляется из переменной окружения — так он не попадёт в историю команд
   export DOLINAIS_TOKEN="dls_ваш_ключ"
   
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
        "https://cms.dolinais.ru/api/task/profile"

3. Узнайте project_id

   Все операции с задачами привязаны к проекту — возьмите его id из списка своих проектов.

   # Кто я и что можно этому ключу
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" "https://cms.dolinais.ru/api/task/profile"
   
   # Мои проекты: id нужен для всех остальных запросов
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" "https://cms.dolinais.ru/api/task/projects?limit=100"
   
   # Разделы (колонки) проекта
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
        "https://cms.dolinais.ru/api/task/sections?project_id=81"
   
   # Кого можно назначить исполнителем
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
        "https://cms.dolinais.ru/api/task/users?project_id=81"

4. Читайте и создавайте задачи

   Дальше — обычные запросы к задачам. Понадобится право task.tasks.read (чтение) или task.tasks.create (создание).

   # Открытые задачи проекта, свежие сверху — сортировка задаётся на канбане
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
        "https://cms.dolinais.ru/api/task/tasks?project_id=81&status=open&limit=50"
   
   # Фильтры: раздел, исполнитель, поиск по заголовку, только изменённые после даты
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
        "https://cms.dolinais.ru/api/task/tasks?project_id=81&section_id=187&executor_id=5&search=договор&updated_since=1790000000"
   
   # Подзадачи конкретной задачи
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
        "https://cms.dolinais.ru/api/task/tasks?project_id=81&parent_id=1793396105504"
   
   # Одна задача
   curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
        "https://cms.dolinais.ru/api/task/task?id=1793396105504"

Авторизация

Ключ передаётся в заголовке запроса. Cookie и сессии личного кабинета API не использует, поэтому запросы можно отправлять с сервера, из скрипта или из мобильного приложения.

Пример на JavaScript

Универсальная обёртка над fetch с разбором ошибок:

const API = 'https://cms.dolinais.ru/api/task';
const KEY = process.env.DOLINAIS_TOKEN; // ключ из /account/tokens

async function api(path, options = {}) {
  const response = await fetch(API + path, {
    ...options,
    headers: {
      'Authorization': 'Bearer ' + KEY,
      'Content-Type': 'application/json',
      ...(options.headers || {}),
    },
  });

  const data = await response.json();

  if (!response.ok) {
    // error_code: unauthorized | insufficient_scope | forbidden | rate_limited ...
    throw new Error(data.error_code + ': ' + data.error);
  }

  return data;
}

const { tasks, total } = await api('/tasks?project_id=81&status=open&limit=20');
console.log('Открытых задач:', total);

Права ключа

Права выдаются при создании ключа и меняются в любой момент — сам ключ при этом не меняется. Всего 8 прав, плюс «Полный доступ» (*).

• Любое право task.* открывает список проектов и разделов (task.projects.read): без project_id остальные запросы не выполнить. В списке — только проекты, где вы участвуете.
• Права ключа — первый уровень доступа. Второй — ваши права в самом проекте: наблюдатель не сможет создать задачу, даже если у ключа есть право task.tasks.create.
• Ключ из раздела «Ключи доступа» (account.accessToken) — старый ключ аккаунта: он работает с полным доступом и не имеет настроек прав.

Методы

Маршруты указаны относительно https://cms.dolinais.ru/api. Изменяющие операции выполняются только методом POST.

Примеры запросов

Создание задачи

curl -s -X POST "https://cms.dolinais.ru/api/task/tasks" \
     -H "Authorization: Bearer $DOLINAIS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "project_id": 81,
           "title": "Проверить договор",
           "comment": "Срок — до пятницы",
           "priority": 3,
           "executor_id": 5,
           "time_limit": "2027-01-15"
         }'

{
  "code": 201,
  "success": true,
  "task": {
    "task_id": 1793396105504,
    "project_id": 81,
    "section_id": 187,
    "section_title": "В работе",
    "title": "Проверить договор",
    "comment": "Срок — до пятницы",
    "executor_id": 5,
    "executor_name": "Иван Петров",
    "priority": 3,
    "progress": 0,
    "completed": false,
    "time_limit": 1800057600,
    "time_limit_date": "2027-01-15T00:00:00+03:00",
    "created_at_date": "2026-10-31T00:55:00+03:00"
  }
}

Изменение, перемещение, история и удаление

# Изменение: только переданные поля, остальные не трогаются
curl -s -X POST "https://cms.dolinais.ru/api/task/task?id=1793396105504" \
     -H "Authorization: Bearer $DOLINAIS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"title": "Проверить договор (финал)", "priority": 2, "progress": 50}'

# Перемещение в другой раздел того же проекта
curl -s -X POST "https://cms.dolinais.ru/api/task/move?id=1793396105504&section_id=221" \
     -H "Authorization: Bearer $DOLINAIS_TOKEN"

# История изменений: кто, что и когда менял
curl -s -H "Authorization: Bearer $DOLINAIS_TOKEN" \
     "https://cms.dolinais.ru/api/task/history?task_id=1793396105504&limit=100"

# Удаление
curl -s -X POST "https://cms.dolinais.ru/api/task/delete?id=1793396105504" \
     -H "Authorization: Bearer $DOLINAIS_TOKEN"

Выгрузка задач страницами

За один запрос возвращается не больше 200 задач, поэтому полную выгрузку делают циклом по limit/offset. Пример использует $api из PHP-клиента ниже.

<?php
// Полная выгрузка задач проекта страницами по 200 (лимит API).
$offset = 0;
$all = [];

do {
    $page = $api->request('GET', '/tasks?project_id=81&limit=200&offset=' . $offset);
    $all = array_merge($all, $page['tasks']);
    $offset += 200;
} while (count($page['tasks']) === 200 && $offset < $page['total']);

echo 'Задач выгружено: ' . count($all);

Готовые клиенты

Мини-клиенты без зависимостей: скопируйте и подставьте свой ключ. Для PHP достаточно curl, для Python — requests.

PHP

<?php
declare(strict_types=1);

/**
 * Мини-клиент /api/task: один ключ, один запрос — без зависимостей.
 */
final class TaskApiClient
{
    public function __construct(
        private string $token,
        private string $base = 'https://cms.dolinais.ru/api/task'
    ) {
    }

    /** @return array<string, mixed> */
    public function request(string $method, string $path, ?array $body = null): array
    {
        $curl = curl_init($this->base . $path);
        curl_setopt_array($curl, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST  => $method,
            CURLOPT_TIMEOUT        => 15,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->token,
                'Content-Type: application/json',
            ],
        ]);

        if ($body !== null) {
            curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_UNICODE));
        }

        $raw = curl_exec($curl);
        $status = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);
        curl_close($curl);

        $data = json_decode((string) $raw, true);

        if (!is_array($data)) {
            throw new RuntimeException('Ответ API не JSON (HTTP ' . $status . ')');
        }

        if ($status >= 400) {
            throw new RuntimeException($data['error_code'] . ': ' . $data['error']);
        }

        return $data;
    }
}

$api = new TaskApiClient(getenv('DOLINAIS_TOKEN'));

$projects = $api->request('GET', '/projects');
$projectId = (int) $projects['projects'][0]['id'];

$task = $api->request('POST', '/tasks', [
    'project_id' => $projectId,
    'title'      => 'Проверить договор',
    'priority'   => 3,
    'time_limit' => '2027-01-15', // строка или unix-время
]);

echo $task['task']['task_id'];

Python

import os
import requests

BASE = 'https://cms.dolinais.ru/api/task'
HEADERS = {'Authorization': f"Bearer {os.environ['DOLINAIS_TOKEN']}"}

# Список открытых задач проекта
page = requests.get(
    f'{BASE}/tasks',
    params={'project_id': 81, 'status': 'open', 'limit': 20},
    headers=HEADERS,
    timeout=15,
)

page.raise_for_status()
data = page.json()

for task in data['tasks']:
    print(task['task_id'], task['title'], task['executor_name'])

Ошибки и коды

Ответ всегда JSON. При ошибке приходят HTTP-статус, короткий текст и машинный error_code — по нему удобно строить обработку.

{
  "code": 403,
  "success": false,
  "error": "Недостаточно прав у ключа",
  "error_code": "insufficient_scope",
  "required_scope": "task.tasks.create"
}

Лимиты

Если нужно много данных, выгружайте страницами по 200 записей и используйте фильтр updated_since вместо частых полных выгрузок.

Безопасность

• Ключ — это пароль. Храните его в переменных окружения или в секретах CI, не в коде и не в git.
• Отдельный ключ на каждую интеграцию: отзыв одного не затрагивает остальные.
• Давайте минимальные права: отчёту на чтение не нужен task.tasks.delete.
• Ставьте срок действия (30/90/180/365 дней) — просроченный ключ перестаёт работать сам.
• В базе хранится только SHA-256-хеш ключа, а в списке видно лишь его начало — по дампу базы ключ не восстановить.
• Следите за колонкой «Использован»: время последнего запроса и IP помогают заметить чужое использование.
• Подозрение на утечку — удалите ключ: интеграция сразу получит 401.

Частые вопросы