🔌 API документация¶

🎯 Обзор API¶

Система охраны труда предоставляет RESTful API для интеграции с внешними системами и автоматизации процессов. API построен на основе OpenAPI 3.0 спецификации и поддерживает JSON формат данных.

🔗 Базовые URL¶

Production: https://api.safety-system.com/api
Staging: https://staging-api.safety-system.com/api
Development: http://localhost:8000/api

🔐 Аутентификация¶

JWT токены¶

Все API запросы требуют аутентификации через JWT токены.

Получение токена:

POST /api/auth/login
Content-Type: application/json

{
  "username": "your_username",
  "password": "your_password"
}

Ответ:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer"
}

Использование токена:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Время жизни токена¶

Access token: 15 минут
Refresh token: 7 дней (если поддерживается)

📋 Общие принципы¶

HTTP методы¶

GET - получение данных
POST - создание новых ресурсов
PUT - полное обновление ресурса
PATCH - частичное обновление ресурса
DELETE - удаление ресурса

Коды ответов¶

200 - OK (успешный запрос)
201 - Created (ресурс создан)
400 - Bad Request (неверный запрос)
401 - Unauthorized (не авторизован)
403 - Forbidden (нет прав доступа)
404 - Not Found (ресурс не найден)
422 - Unprocessable Entity (ошибка валидации)
500 - Internal Server Error (внутренняя ошибка сервера)

Пагинация¶

Для эндпоинтов, возвращающих списки, используется пагинация:

Параметры: - skip (int): количество записей для пропуска (по умолчанию: 0) - limit (int): максимальное количество записей (по умолчанию: 100, максимум: 1000)

Пример:

GET /api/documents/?skip=20&limit=50

Ответ:

{
  "items": [...],
  "total": 1000,
  "skip": 20,
  "limit": 50,
  "has_next": true,
  "has_prev": true
}

Фильтрация и поиск¶

Многие эндпоинты поддерживают фильтрацию:

GET /api/users/?role=admin&is_active=true&department=IT

Сортировка¶

Сортировка через параметр sort:

GET /api/documents/?sort=created_at:desc

📚 Основные эндпоинты¶

🔐 Аутентификация¶

Вход в систему¶

POST /api/auth/login

Получение информации о текущем пользователе¶

GET /api/auth/me

Установка пароля (первый вход)¶

POST /api/auth/setup-password

👨‍💼 Административные функции¶

Дашборд администратора¶

GET /api/admin/dashboard

Общая статистика¶

GET /api/admin/statistics

Отчеты¶

GET /api/admin/reports/user-activity?days=30
GET /api/admin/reports/document-usage
GET /api/admin/reports/department-stats

Системное администрирование¶

POST /api/admin/cleanup/old-drafts?days_old=30
POST /api/admin/notifications/send-bulk
GET /api/admin/system-info

🏢 Организации¶

Список организаций¶

GET /api/organizations/

Создание организации¶

POST /api/organizations/

Информация об организации¶

GET /api/organizations/{organization_id}

Импорт из ФНС¶

POST /api/organizations/fns/import/{inn}?force_update=true

👥 Сотрудники¶

Список сотрудников организации¶

GET /api/organizations/{organization_id}/employees

Информация о сотруднике¶

GET /api/organizations/{organization_id}/employees/{employee_id}

Статистика сотрудников¶

GET /api/organizations/{organization_id}/employees/stats/summary

Доступные роли¶

GET /api/organizations/{organization_id}/employees/roles/available

📚 Документы¶

Список документов¶

GET /api/documents/

Загрузка документа¶

POST /api/documents/upload
Content-Type: multipart/form-data

file: [binary]
name: "Название документа"
description: "Описание"
document_type: "instruction"
category: "safety"
is_template: true

Информация о документе¶

GET /api/documents/{document_id}

Обновление документа¶

PUT /api/documents/{document_id}

Удаление документа¶

DELETE /api/documents/{document_id}

Генерация документов СИЗ¶

POST /api/documents/generate/ppe-issuance/{organization_id}

📝 Формы¶

Список форм¶

GET /api/forms/

Создание формы¶

POST /api/forms/

Информация о форме¶

GET /api/forms/{form_id}

Обновление формы¶

PUT /api/forms/{form_id}

Генерация заполненного документа¶

POST /api/forms/{form_id}/generate-document

Скачивание заполненного документа¶

GET /api/forms/{form_id}/download

🛡️ СИЗ (Средства индивидуальной защиты)¶

Должности¶

GET /api/ppe/positions?q=инженер&category=engineering

Типы защиты¶

GET /api/ppe/types

Наименования СИЗ¶

GET /api/ppe/items?type_id=1&position_id=5

Нормы выдачи¶

GET /api/ppe/norms?position_id=1&type_id=2

Учет выдачи СИЗ¶

GET /api/ppe/organizations/{organization_id}/ppe-issuance/
POST /api/ppe/organizations/{organization_id}/ppe-issuance/
PUT /api/ppe/organizations/{organization_id}/ppe-issuance/{issuance_id}
DELETE /api/ppe/organizations/{organization_id}/ppe-issuance/{issuance_id}

Учет обеспеченности СИЗ¶

GET /api/ppe/organizations/{organization_id}/ppe-issue-accounts/
POST /api/ppe/organizations/{organization_id}/ppe-issue-accounts/
PUT /api/ppe/organizations/{organization_id}/ppe-issue-accounts/{account_id}
DELETE /api/ppe/organizations/{organization_id}/ppe-issue-accounts/{account_id}

⚠️ Оценка рисков¶

Создание оценки риска¶

POST /api/risk-assessment/

Список оценок рисков¶

GET /api/risk-assessment/

Информация об оценке риска¶

GET /api/risk-assessment/{assessment_id}

Обновление оценки риска¶

PUT /api/risk-assessment/{assessment_id}

Руководящие принципы¶

GET /api/risk-assessment/guidelines

🏥 Медицинские осмотры¶

Создание медосмотра¶

POST /api/medical-examinations/

Список медосмотров¶

GET /api/medical-examinations/?organization_id=1&user_id=5

Информация о медосмотре¶

GET /api/medical-examinations/{examination_id}

Обновление медосмотра¶

PUT /api/medical-examinations/{examination_id}

📊 Дашборд¶

Данные дашборда¶

GET /api/dashboard/

Срочные уведомления¶

GET /api/dashboard/notifications

KPI показатели¶

GET /api/dashboard/kpi

Данные для графиков¶

GET /api/dashboard/chart-data

События¶

GET /api/dashboard/events?limit=10

🆘 Поддержка¶

Создание обращения¶

POST /api/support/tickets/

Список обращений¶

GET /api/support/tickets/

Информация об обращении¶

GET /api/support/tickets/{ticket_id}

Обновление обращения¶

PUT /api/support/tickets/{ticket_id}

Добавление сообщения¶

POST /api/support/tickets/{ticket_id}/messages

Загрузка вложения¶

POST /api/support/tickets/{ticket_id}/attachments

📁 Файловое хранилище¶

Загрузка файла¶

POST /api/storage/upload?subdirectory=documents

Получение файла¶

GET /api/storage/files/{file_path}

Дерево директорий¶

GET /api/storage/directory-tree

Структура директории¶

GET /api/storage/directory-structure?path=/documents

📝 Примеры использования¶

Создание документа с шаблоном¶

import requests

# Аутентификация
auth_response = requests.post('https://api.safety-system.com/api/auth/login', json={
    'username': 'admin',
    'password': 'password'
})
token = auth_response.json()['access_token']
headers = {'Authorization': f'Bearer {token}'}

# Загрузка документа
with open('template.xlsx', 'rb') as f:
    files = {'file': f}
    data = {
        'name': 'Инструкция по охране труда',
        'description': 'Общая инструкция по безопасности',
        'document_type': 'instruction',
        'category': 'general_safety',
        'is_template': True
    }

    response = requests.post(
        'https://api.safety-system.com/api/documents/upload',
        files=files,
        data=data,
        headers=headers
    )

document = response.json()
print(f"Документ создан с ID: {document['id']}")

Создание формы на основе шаблона¶

# Создание формы
form_data = {
    'document_id': document['id'],
    'form_data': {
        'employee_name': 'Иванов И.И.',
        'position': 'Инженер',
        'department': 'Производство',
        'date': '2024-01-15'
    },
    'status': 'draft'
}

response = requests.post(
    'https://api.safety-system.com/api/forms/',
    json=form_data,
    headers=headers
)

form = response.json()
print(f"Форма создана с ID: {form['id']}")

Генерация заполненного документа¶

# Генерация заполненного документа
response = requests.post(
    f'https://api.safety-system.com/api/forms/{form["id"]}/generate-document',
    headers=headers
)

result = response.json()
print(f"Документ сгенерирован: {result['filled_document_path']}")

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

Rate Limiting¶

API имеет ограничения на количество запросов: - Аутентифицированные пользователи: 1000 запросов в час - Неаутентифицированные: 100 запросов в час

Валидация данных¶

Все входные данные проходят валидацию: - Pydantic модели для структурированных данных - Проверка типов и форматов - Санитизация пользовательского ввода

CORS¶

Настроены правила CORS для безопасного взаимодействия с фронтендом: - Разрешенные домены: настраиваются в конфигурации - Методы: GET, POST, PUT, DELETE, OPTIONS - Заголовки: Authorization, Content-Type, X-Requested-With

📊 Мониторинг и логирование¶

Логирование запросов¶

Все API запросы логируются: - Время запроса - IP адрес клиента - Метод и URL - Статус ответа - Время выполнения

Метрики¶

Система собирает метрики: - Количество запросов по эндпоинтам - Время отклика API - Ошибки и исключения - Использование ресурсов

🚀 SDK и библиотеки¶

Python SDK¶

from safety_system_sdk import SafetySystemClient

client = SafetySystemClient(
    base_url='https://api.safety-system.com',
    username='your_username',
    password='your_password'
)

# Создание документа
document = client.documents.create(
    name='Test Document',
    file_path='./document.xlsx'
)

# Создание формы
form = client.forms.create(
    document_id=document.id,
    form_data={'field1': 'value1'}
)

JavaScript SDK¶

import { SafetySystemClient } from '@safety-system/sdk';

const client = new SafetySystemClient({
  baseUrl: 'https://api.safety-system.com',
  username: 'your_username',
  password: 'your_password'
});

// Создание документа
const document = await client.documents.create({
  name: 'Test Document',
  file: fileInput.files[0]
});

// Создание формы
const form = await client.forms.create({
  documentId: document.id,
  formData: { field1: 'value1' }
});

📖 Дополнительные ресурсы¶

OpenAPI спецификация: https://api.vrm-sot.ru/api/docs#/ (Swagger UI)
ReDoc документация: https://api.vrm-sot.ru/api/redoc
Postman коллекция: может быть импортирована напрямую из Swagger UI
В Postman выберите File → Import → Link и укажите ссылку на OpenAPI JSON:
https://api.vrm-sot.ru/api/openapi.json
Примеры кода: в репозитории проекта

API документация обновляется автоматически при изменении кода. Для получения актуальной информации используйте Swagger UI.