Гайд по API

Документация по B2B API платформы QuantumHR: аутентификация, основные эндпоинты, идемпотентность и sandbox.

OpenAPI спецификация

Полная спецификация API в формате OpenAPI 3.0:

docs/openapi.yaml

Вы можете импортировать файл в Swagger UI, Postman или другой инструмент для тестирования API.

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

API использует Bearer-токен. В заголовке каждого запроса передайте: 

Authorization: Bearer YOUR_API_TOKEN

Токен получен при создании API-ключа в личном кабинете компании. Все запросы автоматически ограничены данными компании, к которой привязан токен.

Базовый URL

  • Production: https://dev.quantumhr.ru/api/v1
  • UAT (Sandbox): уточните URL у поддержки — обычно https://uat.ваш-домен/api/v1

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

Метод Путь Описание
GET /health Проверка доступности API
GET /company Данные компании
GET /executors Список исполнителей (пагинация)
POST /executors Создать исполнителя
GET /executors/{id} Исполнитель по ID
POST /npd/check Проверка статуса НПД (executor_id, inn)
GET /payouts Список выплат
POST /payouts Создать выплату
POST /payouts/batch Массовое создание выплат (CSV)
GET /payouts/{id} Выплата по ID
GET /documents Список документов
GET /documents/{id} Документ по ID

Идемпотентность

При создании выплаты (POST /payouts) обязательно передайте idempotency_key — уникальный ключ для предотвращения дублирования при повторных запросах. 

{
  "executor_id": "uuid",
  "idempotency_key": "unique-key-123",
  "amount": 1500.00,
  "currency": "RUB",
  "description": "Оплата за март"
}

При повторном запросе с тем же idempotency_key API вернёт уже созданную выплату (без дублирования). Ключ должен быть уникальным в рамках компании, максимум 64 символа.

Sandbox

В UAT-окружении доступен sandbox: используйте тестовый API-ключ и базовый URL UAT. Выплаты не проводятся реально, но проходят полный цикл валидации и проверки НПД.

  • Идеально для интеграции и тестирования перед production
  • UAT-доступ предоставляется при активации компании в production
  • Создайте отдельный API-ключ для sandbox

Ограничения

API применяет rate limiting на токен. При превышении лимита вы получите ответ 429 Too Many Requests. Рекомендуется использовать экспоненциальную задержку при повторных запросах.

Вернуться в базу знаний