Интеграционное API

Сценарии работы с ЦЛП

Как внешней системе получить потоки и слоты, проверить аккредитации водителя и ТС и оформить визит. Все запросы — REST с JSON.

Открыть Swagger ↗

Окружение

Интеграционное API
—
Swagger ↗

Общий порядок

Сценарии связаны: визит оформляется на слот, а водитель и ТС на визите должны быть аккредитованы. Типичная интеграция проходит шаги по порядку.

  1. 1 Потоки GET/integration-api/Threads
  2. 2 Слоты GET/integration-api/Slots
  3. 3 Проверка аккредитаций GET/integration-api/Accreditations/Driver/SearchGET/integration-api/Accreditations/Vehicle/Search
  4. 4 Визит POST/integration-api/VisitsPOST/integration-api/Visits/WithAccreditations
01

Получение потоков и слотов

Поток — направление работы организации со своими правилами бронирования. Слот — интервал времени в потоке с ограниченным числом мест. Визит всегда оформляется на конкретный слот.

Шаги

  1. Получите потоки. Запросите потоки и запомните id нужного. В ответе есть правила: минимальный и максимальный срок брони, допустимое раннее прибытие и опоздание, смещение часового пояса.
  2. Найдите слоты на период. Запросите слоты потока за интервал startAt–endAt. Подходят слоты, у которых freePlaces больше нуля и не заполнено blockedAt.
  3. Сохраните id слота. Идентификатор слота понадобится при создании визита. Начало слота задаёт начало суточной аккредитации, если она оформляется вместе с визитом.

Методы

  • GET/integration-api/Threads
  • GET/integration-api/Slots
02

Оформление аккредитаций

Допускаются только аккредитованные водители и транспортные средства. Через интеграционное API аккредитацию можно проверить, а новую суточную — оформить вместе с визитом.

Шаги

  1. Проверьте водителя. Найдите аккредитацию по паспорту или ФИО на период визита. Метод вернёт последнюю действующую аккредитацию, а если её нет — последнюю с другим статусом.
  2. Проверьте ТС. Найдите аккредитацию по госномеру. Кириллица и латиница в номере приводятся к одному виду.
  3. Оцените результат. status = ACTIVE и isInBlacklist = false — водителя или ТС можно ставить на визит по id. Другие статусы и попадание в чёрный список приходят с кодом 200, их нужно проверять в ответе.
  4. Нет аккредитации — оформите суточную. Передайте анкету водителя или ТС в методе создания визита с аккредитациями (сценарий 03). Суточная аккредитация действует 24 часа от начала слота, платная, документы не требуются.

Методы

  • GET/integration-api/Accreditations/Driver/Search
  • GET/integration-api/Accreditations/Driver/Search/ByPassport
  • GET/integration-api/Accreditations/Driver/Search/ByName
  • GET/integration-api/Accreditations/Vehicle/Search
  • POST/integration-api/Accreditations/Driver/Search
  • POST/integration-api/Accreditations/Vehicle/Search
03

Создание визита

Визит — заезд конкретного водителя на конкретном ТС в выбранный слот. Если водитель и ТС уже аккредитованы, визит создаётся по их id. Если нет — вместе с визитом оформляются суточные аккредитации по анкетам.

Шаги

  1. Выберите слот. Возьмите id слота со свободными местами из сценария 01.
  2. Соберите водителя и ТС. Для каждого — либо id из проверки аккредитации (сценарий 02), либо анкета для новой суточной аккредитации.
  3. Создайте визит. Есть оба id — POST /integration-api/Visits. Нужна хотя бы одна анкета — POST /integration-api/Visits/WithAccreditations, каждая новая аккредитация списывается с лицевого счёта. В ответе — id визита и данные водителя и ТС.
  4. Обработайте частичную ошибку. Шаги создания не откатываются. Если водитель или ТС уже созданы, а визит нет, ответ 400 или 500 содержит createdDriverId и createdVehicleId — повторите запрос с этими id вместо анкет, чтобы не оплатить аккредитацию дважды.
  5. При необходимости измените визит. PUT /integration-api/Visits/{visitId} заменяет водителя, ТС, телефон или payload. Замена с новой анкетой — PUT /integration-api/Visits/{visitId}/WithAccreditations, слот и пространство берутся из визита.

Методы

  • POST/integration-api/Visits
  • POST/integration-api/Visits/WithAccreditations
  • PUT/integration-api/Visits/{visitId}
  • PUT/integration-api/Visits/{visitId}/WithAccreditations

Все методы

Справочник собирается из OpenAPI-спецификации при открытии страницы: описания, параметры и модели совпадают с выкаченной версией API.

Загружаем спецификацию…

Справочник значений

Статус аккредитации

Значение Описание
ACTIVE Действует — можно ставить на визит
NEW Новая
INACTIVE Не действует

Тип аккредитации

Значение Описание
Daily Суточная — 24 часа от начала слота
Annual Годовая — через личный кабинет