Assist API

v1.0

REST API OAuth 2.0

Обзор

REST API для управления страховыми заявками (assists). API использует OAuth2 аутентификацию через Laravel Passport.

Базовый URL

https://assistapi.medlabel.ru/api

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

Схема работы

  1. 1

    Регистрация

    Создайте учетную запись через POST /register

  2. 2

    Активация

    Дождитесь активации аккаунта администратором

  3. 3

    Авторизация

    Получите токен через POST /login

  4. 4

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

    Передавайте токен в заголовке Authorization: Bearer {token}

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

Personal Access Token: 1 год (по умолчанию)

При истечении токена необходимо выполнить повторный вход через POST /login

Заголовки ответов

Все авторизованные запросы возвращают дополнительный заголовок с информацией о токене:

Заголовок Описание Пример
X-Token-Expires-At Дата истечения токена в формате ISO 8601 2026-12-10T23:59:59+00:00

Клиентское приложение должно отслеживать дату истечения токена и своевременно выполнять повторную аутентификацию.

Коды ошибок

Код Описание Пример
401 Не авторизован Неверный email или пароль
403 Доступ запрещен Доступ к ресурсу запрещен
404 Не найдено Ресурс не найден
422 Ошибка валидации {"message": "...", "errors": {...}}
POST /register

Регистрация нового пользователя API. После регистрации требуется активация администратором.

Запрос

{
    "email": "user@example.com",
    "password": "minimum6chars"
}

Параметры

Поле Тип Обязательное Описание
email string Да Уникальный email
password string Да Минимум 6 символов

Ответ 201 Created

{
    "message": "Регистрация успешна! Ожидайте активации администратором.",
    "user": {
        "id": 1,
        "email": "user@example.com",
        "is_active": false
    },
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "token_expires_at": "2026-12-10T23:59:59+00:00"
}
POST /login

Аутентификация пользователя и получение OAuth2 токена.

Запрос

{
    "email": "user@example.com",
    "password": "password123"
}

Ответ 200 OK

{
    "message": "Успешный вход",
    "user": {
        "id": 1,
        "email": "user@example.com",
        "is_active": true
    },
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "token_expires_at": "2026-12-10T23:59:59+00:00"
}

Ошибки

401 Неверный email или пароль
403 Ваш аккаунт еще не активирован администратором
GET /api-user Требует авторизации

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

Заголовки

Authorization: Bearer {token}

Ответ 200 OK

{
    "id": 1,
    "email": "user@example.com",
    "is_active": true
}
POST /tokens/revoke-all Требует авторизации

Отзыв всех токенов пользователя. Используется в случае компрометации токена или необходимости принудительного завершения всех сессий.

Заголовки

Authorization: Bearer {token}

Логика

Отзывает все активные OAuth2 токены текущего пользователя, устанавливая флаг revoked = true в таблице oauth_access_tokens.

Ответ 200 OK

{
    "message": "Все токены успешно отозваны"
}

Важно

После отзыва токенов необходимо выполнить повторную аутентификацию через POST /login для получения нового токена.

GET /request Требует авторизации

Получение списка заявок с пагинацией.

Query-параметры

Параметр Тип По умолчанию Описание
limit integer 10 Количество записей (макс. 100)
page integer 1 Номер страницы

Ответ 200 OK

{
    "data": [
        {
            "id": 12345,
            "EventDateUtc": "2024-01-15 10:30:00",
            "CountryIsoCode": "TUR",
            "City": "Анталья",
            "Hotel": null,
            "Room": null,
            "TouristSurname": "Иванов",
            "TouristName": "Петр",
            "TouristBirthDate": "1985-05-20",
            "TouristPhone": "+79001234567",
            "Declarant": null,
            "PolicyNumber": "POL-123456",
            "InsuranceCompany": "Страховая Компания",
            "PolicyStartDate": "2024-01-01",
            "PolicyEndDate": "2024-12-31",
            "InsuranceAmount": null,
            "DeductibleAmount": null,
            "CurrencyIsoCode": null,
            "Operator": null,
            "Description": "Описание случая",
            "Note": "Дополнительные заметки",
            "InsuranceCompanyRequestId": "EXT-001",
            "RequestCreationDateUtc": "2024-01-15 10:00:00",
            "RequestStatus": "В работе",
            "RequestStatusDateUtc": "2024-01-15 12:00:00",
            "RequestStatusNote": null
        }
    ],
    "links": {
        "first": "https://api.example.com/request?page=1",
        "last": "https://api.example.com/request?page=5",
        "prev": null,
        "next": "https://api.example.com/request?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "path": "https://api.example.com/request",
        "per_page": 10,
        "to": 10,
        "total": 50
    }
}
POST /request Требует авторизации

Создание новой заявки. Если передан InsuranceCompanyRequestId и заявка с таким ID уже существует, возвращается её внутренний ID.

Запрос

{
    "EventDateUtc": "2024-01-15T10:30:00.000Z",
    "CountryIsoCode": "TUR",
    "City": "Анталья",
    "TouristSurname": "Иванов",
    "TouristName": "Петр",
    "TouristBirthDate": "1985-05-20",
    "TouristPhone": "+79001234567",
    "Declarant": "Иванова Мария",
    "PolicyNumber": "POL-123456",
    "InsuranceCompany": "Страховая Компания",
    "PolicyStartDate": "2024-01-01",
    "PolicyEndDate": "2024-12-31",
    "Description": "Описание страхового случая",
    "Hotel": "Hotel Antalya",
    "Room": "305",
    "InsuranceAmount": 50000.00,
    "DeductibleAmount": 100.00,
    "CurrencyIsoCode": "USD",
    "Operator": "TUI",
    "Note": "Дополнительная информация",
    "InsuranceCompanyRequestId": "EXT-001",
    "RequestCreationDateUtc": "2024-01-15T10:00:00.000Z",
    "RequestStatus": "Новая",
    "RequestStatusDateUtc": "2024-01-15T10:00:00.000Z",
    "RequestStatusNote": "Создана через API"
}

Обязательные поля

Поле Формат Описание
EventDateUtcY-m-d\TH:i:s.v\ZДата страхового случая (ISO 8601)
CountryIsoCode3 буквы [A-Z]ISO код страны (например TUR)
Citystring, max:100Название города
TouristSurnamestring, max:500Фамилия туриста
TouristNamestring, max:500Имя туриста
TouristBirthDateY-m-dДата рождения
TouristPhonestring, max:500Контактный телефон
Declarantstring, max:500ФИО заявителя
PolicyNumberstring, max:100Номер полиса
InsuranceCompanystring, max:400Страховая компания
PolicyStartDateY-m-dДата начала полиса
PolicyEndDateY-m-dДата окончания полиса
Descriptionstring, max:4000Описание обстоятельств

Необязательные поля

Поле Формат Описание
Hotelstring, max:4000Отель
Roomstring, max:500Номер комнаты
InsuranceAmountnumeric, min:0Сумма покрытия
DeductibleAmountnumeric, min:0Сумма франшизы
CurrencyIsoCode3 буквы [A-Z]Код валюты (USD, EUR)
Operatorstring, max:500Туроператор
Notestring, max:4000Примечание
InsuranceCompanyRequestIdstring, max:100Внешний ID заявки
RequestCreationDateUtcY-m-d\TH:i:s.v\ZДата создания
RequestStatusНовая|В работе|Обработана|ОтказанаСтатус
RequestStatusDateUtcY-m-d\TH:i:s.v\ZДата статуса
RequestStatusNotestring, max:4000Комментарий к статусу

Ответ 200 OK

12345

Возвращается внутренний ID заявки как plain text.

GET /request/{assist_id} Требует авторизации

Получение одной заявки по внутреннему ID.

Параметры пути

Параметр Тип Описание
assist_id integer Внутренний ID заявки

Ответ 200 OK

Формат аналогичен одному элементу из GET /request

Ошибки

403 Нет доступа к заявке
404 Заявка не найдена
GET /request-changes Требует авторизации

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

Query-параметры

Параметр Тип Описание
from date Фильтр по дате создания (от)
to date Фильтр по дате создания (до)

Ответ 200 OK

[
    {
        "id": 12345,
        "EventDateUtc": "2024-01-15 10:30:00",
        // ... остальные поля как в GET /request
    }
]

Массив объектов без пагинации.

PATCH /request-changes/{change_id} Требует авторизации

Фиксация обработки изменения. После вызова заявка исключается из GET /request-changes до следующего изменения.

Параметры пути

Параметр Тип Описание
change_id string ID изменения во внешней системе

Запрос

{
    "InsuranceCompanyRequestId": "EXT-001"
}

Ответ 200 OK

{
    "message": "OK"
}

Ошибки

403 Нет доступа к заявке
404 Маппинг не найден
GET /countries Требует авторизации

Получение справочника стран для валидации CountryIsoCode.

Ответ 200 OK

[
    {
        "isoCode": "ABW",
        "name": "Аруба"
    },
    {
        "isoCode": "AFG",
        "name": "Афганистан"
    },
    {
        "isoCode": "TUR",
        "name": "Турция"
    }
]

Статусы заявок

Статус API Описание
В работе Заявка открыта или на удержании
Обработано Заявка закрыта или в процессе выставления счета
Отказано Заявка отклонена