API Docs

Назначение API раздела

Internal API для сайта, партнерских интеграций, AI-агентов и автоматизаций Motiv. Это не публичный consumer API.

Где это в коде: слой API в репозитории см. MSP → Структура кода; карта экранов админки — Структура проекта.

Versioning

• Текущий baseline: v1.
• Breaking изменения — только при смене major версии.
• Новые поля добавляются backward-compatible способом.

Base conventions

Local quick start (без PowerShell/Tinker debug)

1. Поднять проект: composer install, php artisan migrate --seed.
2. Использовать dev admin из seed:
   • email: test@example.com
   • password: admin12345 (или из MOTIV_DEV_ADMIN_PASSWORD)
3. Получить токен в админке: /admin/api-token (рекомендуется) или через POST /api/v1/auth/token с нужными abilities.
4. Передавать Authorization: Bearer <token> в каждом запросе.
5. Проверить базовый flow: GET /applications → POST /applications → POST /analytics/clicks/bulk.

Access model: abilities + role/policy

Итог: для mutating endpoints нужны оба условия: корректная ability + разрешающая policy.

Resource contracts

Common schemas

# Token issue (рабочий локальный пример)
POST /api/v1/auth/token
{
  "email": "test@example.com",
  "password": "admin12345",
  "token_name": "local-dev",
  "abilities": ["apps:read", "apps:write", "analytics:write", "dashboard:read"]
}

201 Created
{
  "token_type": "Bearer",
  "access_token": "1|********************************",
  "abilities": ["apps:read", "apps:write", "analytics:write"]
}

# Applications create (минимальный payload)
POST /api/v1/applications
{
  "name": "My Test App",
  "platform": "ios",
  "status": "active"
}

201 Created
{
  "data": {
    "id": 123,
    "name": "My Test App",
    "platform": "ios",
    "native_id": "api-...",
    "status": "active"
  }
}

Error handling

• 401 unauthenticated — токен не передан или невалиден.
• 422 validation error — ошибки по полям в errors.
• 404 not found — сущность не найдена.
• 403 forbidden — нет прав.
• 500 internal error — fallback response без утечки stacktrace.

# 403 (ability/policy mismatch)
{
  "message": "This action is unauthorized."
}

# 422 (validation)
{
  "message": "Validation failed.",
  "errors": {
    "name": ["The name field is required."]
  }
}

API request logs (operational)

Логи запросов доступны через админку (/admin/api-request-logs) и read-only endpoint GET /api/v1/admin/api-logs.

• Фильтры: status, method, path, user, token, date range, error-only, slow requests.
• Presets в админке: ошибки, 403, 422, 500, медленные, 24ч.
• Summary: requests/4xx/5xx/avg latency за 24ч, top endpoint, top user.

Security: в api_request_logs не пишутся access tokens и Authorization header. Логируются только safe-поля: method/path/status/duration/ip/user/token_id/user_agent.

Compatibility principles

• Не удалять поля без периода депрекации.
• Добавлять поля как optional.
• Статусные значения — из согласованных бизнес-наборов.

Examples

GET /api/v1/applications?status=active&without_owner=1&per_page=20

{
  "data": [
    {
      "id": 41,
      "name": "Motiv App",
      "status": "active",
      "company": {"id": 3, "name": "Farmchel"},
      "owner": {"id": 8, "name": "Ops Manager"}
    }
  ]
}

POST /api/v1/analytics/clicks/bulk
{
  "rows": [
    {
      "date": "2026-04-17",
      "app_id": 41,
      "company_id": 3,
      "clicks": 1290,
      "status": "ok"
    }
  ]
}

{
  "created": 1,
  "updated": 0,
  "skipped": 0,
  "errors": []
}

DELETE /api/v1/auth/token
Authorization: Bearer <token>

GET /api/v1/dashboard/summary
Authorization: Bearer <token>
}