API как продуктовая функция

Публичный REST заменяет отвергнутый общий движок задач. От того, насколько дёшево к нему подключиться, зависит, появится ли сквозной список работы через все продукты.

Что заложено в контракт

Версионирование по пути

Все контроллеры живут под /api/v1. Ломающее изменение требует поддержки предыдущей версии в течение переходного периода, старые пути остаются алиасами на два релиза.

Идемпотентность записи

Операции записи принимают ключ идемпотентности. Повторный вызов при обрыве сети обновляет запись, а не создаёт вторую. Это самая частая ошибка в интеграциях такого рода.

Права те же, что в интерфейсе

Аутентификация через A3.ID, проверки доступа совпадают с интерфейсными. Внешнему участнику экономические поля не отдаются, а не скрываются на клиенте.

Отдельный лимит для экосистемы

Интеграционный трафик пиковый по природе, клиентский равномерный. Один лимит на обоих либо задушил бы интеграции, либо не защитил от злоупотреблений.

Группы методов

GET/api/v1/tasksСписок задач с пагинацией, фильтрами и сортировкой
POST/api/v1/tasksСоздание задачи, смена статуса, назначение, массовые операции
POST/api/v1/assignmentsВнешнее назначение с ключом идемпотентности
PUT/api/v1/assignments/{key}Обновление и закрытие по внешнему ключу
GET/api/v1/projectsПроекты, участники, вехи и бюджет
POST/api/v1/time-entriesСписание времени, чтение и утверждение
GET/api/v1/views/overdueГотовые срезы: мои задачи, просроченные, по проекту
POST/api/v1/exportВыгрузка данных организации под правами вызывающего

Внешнее назначение

Продукт-источник передаёт свою сущность и ссылку на неё. Повторный вызов с тем же externalKey обновит задачу, а не создаст вторую.

POST /api/v1/assignments

{
  "externalKey": "legal-case-8421",
  "sourceProduct": "lawyer",
  "sourceEntityType": "LegalCase",
  "sourceEntityId": "8421",
  "deepLink": "https://app.lawyer.a3.solutions/cases/8421",
  "title": "Подготовить исковое заявление",
  "assigneeId": "u-2f9c",
  "dueDate": "2026-10-02"
}

Вебхуки

Подписка на события, чтобы продукт-источник не опрашивал A3.Projects по расписанию.

task.createdЗадача создана в интерфейсе или через API

task.status_changedЗадача сменила состояние, включая возврат на доработку

task.closedЗадача завершена или отменена с указанием причины

time_entry.loggedСписано время, в том числе через встраиваемый виджет

project.status_changedПроект приостановлен, завершён или отменён

budget.threshold_reachedДостигнут порог бюджета, срабатывает один раз на порог

Личные токены доступа

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

Области ограничены явным перечнем, а не выдаются целиком
В базе только SHA-256, показать токен повторно нельзя
Срок действия не больше 180 дней, продление требует новой выдачи
Управление токенами идёт по сессии, а не по самому токену

Доступ для ИИ-агента

Тот же публичный API служит точкой доступа для агента экосистемы через MCP. Агент работает от имени пользователя и с теми же проверками доступа.

Отказ по правам возвращается ошибкой инструмента, а не пустым списком. Иначе агент сказал бы «у вас нет задач» там, где их просто не видно.

Контракт открыт

Схема, примеры запросов и коды ошибок опубликованы. Песочница появится после первой эталонной интеграции: без реального потребителя она обслуживала бы воображаемый сценарий.

Подключиться Интеграции