Оглавление / REST-API

REST-API

ПростоСмета предоставляет публичный REST API для автоматизации работы со сметами. API позволяет управлять каталогами, создавать сметы на основе текстового описания или структурированного JSON-массива, отслеживать статус длительных операций и получать готовые расчёты.

Все запросы, кроме /auth/login, требуют авторизации. Взаимодействие построено на HTTP-методах, ответы возвращаются в формате JSON. Для длительных операций используется асинхронная модель с опросом статуса задачи.

Базовый URL

Авторизация

Для авторизации необходимо получить JWT-токен через метод POST /auth/login. Токен передаётся в заголовке каждого последующего запроса:

Authorization: Bearer <access_token>

Токен действителен в течение 1 часа. По истечении срока требуется повторная авторизация.

Формат ответа

Все ответы API приходят в формате JSON. Успешный ответ содержит поле success: true и блок data. В случае ошибки возвращается success: false, поле error с описанием проблемы и соответствующий HTTP-код.

Основные коды ответа:

• 200 OK – запрос успешно обработан
• 201 Created – ресурс успешно создан
• 202 Accepted – запрос принят в обработку (для асинхронных операций)
• 400 Bad Request – ошибка в параметрах запроса
• 401 Unauthorized – отсутствует или недействительный токен
• 402 Payment Required – недостаточно средств, необходимо пополнить баланс
• 403 Forbidden – недостаточно прав для выполнения операции
• 404 Not Found – запрашиваемый ресурс не найден
• 405 Method Not Allowed – метод HTTP не поддерживается для данного эндпоинта
• 429 Too Many Requests – превышен лимит запросов
• 500 Internal Server Error – внутренняя ошибка сервера

Ограничение на число запросов

Для обеспечения стабильности работы API действует ограничение: не более 60 запросов в минуту с одного IP-адреса. При превышении лимита сервер вернёт ответ с кодом 429.

Методы API

Авторизация
Состояние баланса
Работа с каталогами
Опрос статуса выполнения задачи
Расчёт заданной номенклатуры
Создание сметы по описанию работ