# API Автокод ----------------------------------------- <!--title:API Автокод--> > REST API Автокод предназначено для программной интеграции с отчетной системой Автокод (комплексные сведения об автотранспортных средствах) API позволяет выполнять следующие основные операции: 1. Формирование запросов и получение отчетов по автотранспортным средствам 2. Контроль баланса и истории запросов 3. Управление доступом для пользователей При создании API Автокод серьезное внимание уделено вопросам безопасности (защита данных пользователей), но при этом соблюден баланс производительности и удобства интеграции. На настоящий момент опубликована спецификация версии v1.1.0 ## Документация |Документ | Версии | Примечания| |----|----|----| | Руководство по интеграции |[v1.1.0 - текущая](integration.md)| Подключение, авторизация, автоматическое получение отчетов| | Руководство по эксплуатации |[v1.1.0 - текущая](userguide.md)| Инструкция по правильной работе с API при реальной эксплуатации| | Процедура аутентификации |[открыть](authentication.md)| Алгоритм формирования аутентификационного ключа для API| | Дорожная карта развития API |[открыть](roadmap.md)| План развития API Автокод| ## Общее описание - **Тип API** - стандартный **REST** - формат - **JSON** в качестве формата на входе и выходе ([планируется поддержка XML](roadmap.md#xmlplan)) - формат выдачи - унифицированный конверт с содержимым - ошибки - статус HTTP + JSON с подробностями ошибки - **Аутентификация** - аутентифицируется каждый запрос (нет поддержки сессий) - поддерживается хэш паролей (с солью ), включающий метку времени ([планируется поддержка подписи](roadmap.md#signplan)) - токены могут иметь произвольный срок жизни - для доверенных клиентов или при авторизации по IP возможно использование доверенного входа (без пароля) - **Критические операции (оплачиваемые)** - генерация нового отчета - перегенерация имеющегося отчета - совмещено с моделью квот и баланса - работает в транзакционном режиме - **Получение основного контента** - асинхронное - запрос на создание формирует токен - токен отчета используется при получении текущих данных по отчету в произвольное время - отчеты хранятся на серверной стороне и доступны всегда - **Бизнес-модель** - разделение клиентов - функциональное через понятие "домен" - между клиентами нет общих данных, включая отчеты - в системе закреплены настройки типов отчетов для каждого клиента - повторная генерация отчета с одними и теми же настройками (по уже существующему VINГРЗ с тем же типом отчета) - возвращает хранимый отчет (не дублируется) - ранее сформированные отчеты доступны всегда - поддерживается режим принудительной перегенерации существующего отчета (повторный запрос данных у поставщиков, обновляются данные в существующем отчете) - платная операция - модель баланса - натуральная - в единицах запросов данных, исходная квота закрепляется в типе отчета, текущая квота - скользящая с возможностю расширения - **Поддержка клиентов** - горячая линия - поддержка программистов в рабочее время - консультации по интернет - SWAGGER (отладочно-документационный стенд для разработчиков) - SOAPUI (проверка работоспособности) ## Определения 1. **Домен** (`domain`) - обособленная область данных для хранения учетных записей, настроек и отчетов - закреплена за отдельным клиентом. Все ключи объектов в домене имеют в своем составе @DOMAINCODE 2. **Пользватель** (`user`) - отображает субъекта, выполняющего вход - всегда является частью домена - является носителем *ролей* и полномочий - может действовать только в рамках своих полномочий 3. **Группа** (`group`) - набор *пользователей* - пользователи могут быть включены в несколько *групп* - позволяют применить общие настройки ролей и полномочий 4. **Тип отчета** (`report_type`) - описатель отчета, который может быть сформирован в данном *домене* - *домен* может содержать несколько *типов отчета* - отображает условия договора (привязан к срокам действия) - несет в себе информацию об используемых источниках данных и составе отчета по данным - несет в себе информацию о соглашении по квотам (общей, месячной, дневной, срок действия) - является объектом полномочий - *пользователям* тип отчета может быть не доступен, доступен только на чтение или доступен на формирование 5. **Запрос отчета** (`report_request`) - инициируемый *пользователем* сценарий сбора данных, - включает в себя указание на *тип отчета* - включает в себя ключевую информацию об объекте поиска, например VIN/ГРЗ 6. **Отчет** (`report`) - основной "товар" системы, возникает в ответ на *запрос отчета* - всегда доступен (даже если контент еще не собран) - постепенно пополняется данными - содержит информацию по статусу формирования (Progress/DONE) - уникален относительно *типа отчета* и ключевой информации запроса (VIN/ГРЗ) 7. **Баланс** (`balance`) - модель учета действий и контроль квот - опирается на настройки в *типе отчета* - включает в себя контроль общей (для тестовых или временных отчетов), месячной (основное ограничение) и дневной (защита от массовой загрузки данных) квоты Подробнее о работе с API можно узнать в соответствующих разделах справки