Перейти к основному содержимому

External API v1 — быстрый старт

Версия документа: 1.0 Версия API: v1 (это первая версия публичного External API; в будущем рядом появятся v2 и далее, документация по которым будет лежать отдельно) Дата: 29.04.2026 Статус: Готов к обсуждению

Контекст: analytics.vitrip.store

Этот документ — короткая практическая инструкция для быстрого старта.

Если нужен полный разбор API, используйте:

Что нужно сделать​

  1. Войти в систему
  2. Открыть Профиль
  3. Создать External API токен
  4. Скопировать токен
  5. Вставить его во внешнее приложение
  6. Проверить соединение через auth/me
  7. Получить список проектов
  8. Открыть проект
  9. Найти нужный пункт
  10. Выполнить действие

Базовый URL​

https://analytics.vitrip.store/api/external/v1/

Шаг 1. Получить токен​

Где​

В системе:

Профиль → External API токени

Что выбрать​

Минимальный набор scope для чтения:

  • auth:me
  • projects:read
  • projects:search
  • items:read

Если нужно писать комментарии:

  • comments:write

Если нужно менять статус:

  • items:status.write

Если нужно менять дедлайн и приоритет:

  • items:planning.write

Если нужно добавлять ответы:

  • answers:write

Если нужны ссылки и изображения:

  • items:materials.write

Важно​

Токен показывается только один раз после создания.

Шаг 2. Настроить внешнее приложение​

Во внешнем приложении сохраните:

Base URL​

https://analytics.vitrip.store/api/external/v1/

Authorization header​

Authorization: Bearer YOUR_TOKEN_HERE

Шаг 3. Проверить токен​

Метод​

GET /api/external/v1/auth/me.php

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/auth/me.php' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Что должно получиться​

API должен вернуть:

  • user.id
  • user.name
  • user.role
  • token.label
  • token.scopes

Шаг 4. Получить список проектов​

Метод​

GET /api/external/v1/projects/list.php

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/projects/list.php?limit=20&offset=0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Шаг 5. Открыть проект​

Когда известен project_id, используйте:

Карточка проекта​

GET /api/external/v1/projects/get.php?id=PROJECT_ID

Дерево проекта​

GET /api/external/v1/projects/tree.php?id=PROJECT_ID

Шаг 6. Найти нужный пункт​

Самый правильный путь:

Метод​

GET /api/external/v1/projects/search.php?id=PROJECT_ID&q=QUERY

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/projects/search.php?id=17&q=Тест' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Ищите в ответе:

  • item_id
  • entity_type
  • entity_id

Шаг 7. Прочитать пункт​

Метод​

GET /api/external/v1/items/get.php?id=ITEM_ID

Что вернётся​

  • статус
  • дедлайн
  • приоритет
  • комментарии
  • ответы
  • document links
  • вложения

Шаг 8. Сделать действие​

Ниже самый нужный минимум.

8.1. Сменить статус​

PATCH /api/external/v1/items/status.php
{
  "id": 299,
  "status": "in_progress"
}

Разрешённые статусы:

  • pending
  • in_progress
  • done
  • blocked

8.2. Изменить дедлайн / приоритет / requires_answer​

PATCH /api/external/v1/items/planning.php
{
  "id": 299,
  "priority": "high",
  "requires_answer": true
}

Три каноничные формы передачи deadline:

  • ISO-строка YYYY-MM-DD — устанавливает дедлайн ("deadline": "2026-05-15");
  • null — очищает дедлайн ("deadline": null);
  • пустая строка "" — также очищает (эквивалент null).

Если хочешь убрать дедлайн — используй явный null, это самая каноничная форма.

Поле description в v1 — read-only. Текст пункта поменять через API нельзя, только через веб-интерфейс. Запись description отложена в roadmap post-v1.

8.3. Добавить комментарий​

POST /api/external/v1/comments/create.php
{
  "item_id": 299,
  "text": "Проверили, идём дальше"
}

8.4. Добавить ответ​

POST /api/external/v1/answers/create.php
{
  "item_id": 299,
  "text": "Работа завершена",
  "document_links": [
    {
      "kind": "document",
      "title": "Отчёт",
      "url": "https://example.com/report"
    }
  ]
}

8.5. Обновить ссылки пункта​

PUT /api/external/v1/items/links.php
{
  "id": 299,
  "document_links": [
    {
      "kind": "document",
      "title": "ТЗ",
      "url": "https://example.com/spec"
    }
  ]
}

Важно:

этот метод заменяет весь список ссылок целиком.

8.6. Загрузить изображение в пункт​

POST /api/external/v1/items/attachments.php

Формат:

multipart/form-data

Поля:

  • item_id
  • attachments[]

Минимальный рабочий размер изображения — 16×16 пикселей. Изображения меньше отвергаются с 422 validation_error («Запрос содержит невалидные данные»).

Принимаются: PNG, JPG, GIF, WebP. Рантайм всегда конвертирует в WebP при сохранении в Cloudflare R2.

Пример:

curl -X POST \
  'https://analytics.vitrip.store/api/external/v1/items/attachments.php' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'item_id=299' \
  -F 'attachments[]=@image.png'

8.7. Загрузить изображение в answer​

POST /api/external/v1/answers/attachments.php

Поля:

  • answer_id
  • attachments[]

В ответе содержится поле status_reset: boolean — если true, статус ответа был сброшен в pending при загрузке (например, если ответ был approved/rejected и теперь требует повторного review).

Какие ошибки самые важные​

401 unauthorized​

Токен не передан.

401 token_invalid​

Токен неверный.

401 token_revoked​

Токен отозван.

401 token_expired​

Токен истёк.

403 scope_missing​

У токена нет нужного scope.

403 forbidden​

У пользователя нет права на это действие.

404 not_found​

Проект / пункт / answer не найдены или недоступны.

422 validation_error​

Неправильные данные в запросе.

Самый короткий правильный сценарий внешнего приложения​

Если упростить до минимума, внешнее приложение должно делать так:

  1. Получить Bearer token от пользователя
  2. Выполнить GET /auth/me.php
  3. Выполнить GET /projects/list.php
  4. Пользователь выбирает проект
  5. Выполнить GET /projects/search.php?id=...&q=...
  6. Найти item_id
  7. Выполнить GET /items/get.php?id=...
  8. Выполнить нужное действие:
    • статус
    • planning
    • comment
    • answer
    • links
    • attachments

Каноничные границы v1 — что НЕЛЬЗЯ через API​

Первая версия API — это operational layer (управление состоянием существующих сущностей), не structural editing layer. По архитектурному решению в v1:

Можно:

  • читать структуру (проекты, разделы, чек-листы, пункты);
  • менять status, priority, deadline, requires_answer пункта;
  • добавлять comments, answers, attachments, links к пункту;
  • замещать document_links пункта целиком.

Нельзя:

  • создавать или переименовывать проекты, разделы, чек-листы, пункты;
  • менять text или description уже существующего пункта (read-only в v1);
  • управлять verdict-ом и возвратом на доработку (verdict, rework_* поля видны, но управляются только через веб-интерфейс);
  • удалять созданные comments, answers, attachments, links (в системе нет понятия удаления — soft-archive / inactive в roadmap post-v1).

Для всего что в списке «нельзя» — используется веб-интерфейс. Эти направления зафиксированы как post-v1 слой в roadmap API.

Если нужен полный документ​

Для полного описания всех методов, логики, ограничений и подробного сценария используйте:

Связанная документация​