API-BENZUBER (carwash)

API Benzuber (car wash) – протокол для обеспечения взаимодействия между внешней учетной системой партнера (PS) и сервером Benzuber (BZ).

Протокол позволяет партнёру осуществлять получение информации о доступных станциях моек, их структуре и тарифах, и выполнять операции необходимые для обеспечения обслуживания на автомойке.

Для реализации взаимодействия партнёру необходимо реализовать запросы:

• Получение списка моделей автомобилей;
• Получения списка станций обслуживания;
• Получения информации о структуре/конфигурации станции обслуживания, тарифах;
• Постановки и обработки заказа;

Для обеспечения безопасного доступа и идентификации партнера для работы с протоколом предоставляется уникальный ключ apikey, который используется во всех запросах.

Базовый URL_BZ – адрес для обращения к серверу BZ. Все запросы выполняются HTTPS запросами (GET или POST) вида: URL_BZ + /v1/carwash/команда?apikey={apikey}

HTTP коды ответа:

200 – запрос выполнен успешно
400 – недопустимые параметры запроса
401 – ошибка авторизации, доступ запрещен
404 – автомойка не найдена
503 – автомойка временно не доступна
500 – ошибка обработки запроса

Базовый URL_PS – адрес для обращения к партнеру. Все запросы выполняются HTTPS запросами (GET или POST) вида: URL_PS + /api/carwash/команда?apikey={apikey}

HTTP коды ответа:

200 – запрос выполнен успешно
Любой другой код – ошибка выполнения запроса

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

Типы моек

Автомойка по записи reserve
Для бронирования необходимо запросить и выбрать необходимые услуги и доступный временной слот.

Автомойка самообслуживания deposit
Для начала использования необходимо пополнить баланс выбранного терминала.

Доступные запросы

Для реализации взаимодействия предоставляются возможности:

/carwash/cars Получение информации о поддерживаемых в системе моделях автомобилей

/carwash/list Получение списка моек доступных партнеру, с гео-данными, типом автомойки.

Автомойка по записи reserve

/carwash/{CarwashId}/services Получение списка услуг автомойки по записи

/carwash/{CarwashId}/times Получение списка доступных свободный временных слотов автомойки по записи

/carwash/reserve Оформление записи на автомойку

/carwash/cancel Запрос на отмену записи

/carwash/status Получение информации статусе бронирования

Автомойка самообслуживания deposit

/carwash/{CarwashId}/posts Получение списка терминалов самообслуживания

/carwash/debit Пополнение баланса терминала самообслуживания

/carwash/status Получение информации статусе пополнения баланса

Получение списка поддерживаемых в системе моделях автомобилей.

Получение информации о моделях автомобилей доступных для партнера. Данные необходимо использовать для идентификации автомобиля клиента.

В ответе массив объектов по бренда, для каждого бренда список возможных моделей, для каждой модели - вариации кузова.

Совокупность бренда "BrandName", модели "ModelName" и типа кузова "BodyName" определяет комплектацию автомобиля, которая закрепляется за идентификатором автомобиля "CarId".

Список моделей автомобилей меняется редко, поэтому рекомендуется запрашивать обновление не чаще одного раза в сутки.

Запрос

(GET) URL_BZ + /v1/carwash/cars?apikey={apikey}

Ответ

Content type: application/json
[
  {
    "BrandName": "Tesla",
    "ModelList": [
        {
          "ModelName": "Cybertruck",
          "BodyList": [
            {
              "CarId": 123,
              "BodyName": "Пикап"
            },
            ...
          ]
        },
        {
          "ModelName": "Model X",
          "BodyList" :[ ... ]
        },
        ...
    ]
  },
  {
    "BrandName": "Lada (ВАЗ)",
    "ModelList": [ ... ]
  },
  ...
]

Получение списка моек

Получение информации об автомойках доступных партнеру, с указанием типа автомойки, названием и гео-данными.

Запрос

(GET) URL_BZ + /v1/carwash/list?apikey={apikey}

Ответ

Content type: application/json
[
  {
    "CarwashId": "15649",
    "Name": "Автомоечный комплекс",
    "Brand": "Чистота",
    "City": "Москва",
    "Address": "ул. Чистопольская 36",
    "Enable": true,
    "Mode": "deposit",
    "Location" : {
        "Lat": 34.123,
        "Lon": 64.27
    },
    "MaxTotal": 9900
  },
  ...
]

Работа с автомойками по записи

Получение списка услуг/тарифов.

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

Для оформления записи в дальнейшем нужно выбрать только одну из обязательных услуг Required, и любое количество необязательных Optional.

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

Запрос

(POST) URL_BZ + /v1/carwash/{CarwashId}/services

Request body schema application/json

{
  "CarId": 1654,
  "Lpn": "A123BC45"
  "apikey": "fdh32498"
}

Ответ

Content type: application/json
[
  {
    "Required": [
      {
        "GroupName": "Тарифы",
        "GroupItems": [
          {
            "ServiceId": "prostaya",
            "ServiceName": "Простая",
            "ServiceDescr": "Мойка кузова с шампунем, бесконтактная сушка",
            "ServiceDuration": "30",
            "ServicePrice": "300.00"
          },
          ... 
        ]
      },
      ...
    ]
    ,
    "Optional": [
      {
        "GroupName": "Доп. услуги",
        "GroupItems": [
          {
            "ServiceId": "dop-543",
            "ServiceName": "Воск",
            "ServiceDescr": "Нанесение воска на кузов",
            "ServiceDuration": "15",
            "ServicePrice": "500.00"
          },
          ... 
        ]
      },
      ...
    ],
  },
  ...
]

Получение списка доступного времени.

Для автомойки по записи возможно получения списка временных слотов доступных для записи. Для получения информаиции требуется передать сформированную "корзину услуг" Cart.

В корзине должна находится только одна обязательная услуга, и любое количество необязательных.

В ответе будут представлены доступные временные слоты на 7 ближайших дней.

Запрос

(POST) URL_BZ + /v1/carwash/{CarwashId}/times

Request body schema application/json

{
  "Cart":  [
    {
      "ServiceId": "prostaya",
      "Price": 300,
      "Quantity": 1,
      "Amount" : 300
    },
    ...
  ],
  "CarId": 1654,
  "Lpn": "A123BC45"
  "apikey": "fdh32498"
}

Ответ

Content type: application/json
[
  {
    "DateName": "21.02.2022",
    "DateItems": [
      {
        "TimeId": "3215123",
        "TimeName": "09:00"
      },
      ...
    ]
  },
  {
    "DateName": "22.02.2022",
    "DateItems": [...]
  },
  ...
]

Запись на автомойку.

Для записи необходимо передать "корзину" услуг, слот времени, параметры автомобиля и данные клиента.

Запрос

(POST) URL_BZ + /v1/carwash/reserve

Request body schema application/json

{
  "OrderId": "j432-3dfr-3132-134f",
  "CarwashId": "16546",
  "Cart":  [
    {
      "ServiceId": "prostaya",
      "Price": 300,
      "Quantity": 1,
      "Amount" : 300
    },
    ...
  ],
  "CarId": 1654,
  "Lpn": "A123BC45"
  "TimeId": "3215123",
  "Sum": 450,
  "UserName": "Иван Петров",
  "UserPhone": "79222222222",
  "UserEmail": "mail@mail.ru",
  "Description": "Перезвоните для уточнения деталей заказа",
  "ContractId": "Сorporation',
  "apikey": "fdh32498"
}

Ответ

HTTP коды ответа:

200 – Успешный ответ. Принят новый заказ, либо заказ с указанным `OrderId` уже существует.

Запрос отмены записи

Возможность инициировать отмену ранее созданного бронирования на автомойке по записи. При получении от партнёра запроса на отмену заказа, сервер Benzuber пытается отменить бронировани на автомойке.

Запрос

(POST) URL_BZ + /v1/carwash/cancel 

Request body schema application/json

{
  "OrderId": "f329g-3dsf-2dsf-dsgg",
  "apikey": "fdh32498"
}

Ответ

HTTP коды ответа:

200 – бронирование отменёно, либо запрос пришел уже на отменное бронирование
202 - запрос на отмену зарегистрирован, в дальнейшем будет передан callback об отмене, либо завершении заказа, состояние заказа так же можно узнать из запроса состояния заказа

400 - заказ отменить нельзя
404 - заказ не найден

Запрос получение информации о бронировании

Запрос для получения актуальной информации по созданному ранее бронированию.

Запрос

(POST) URL_BZ + /v1/carwash/status 

Request body schema application/json

{
  "OrderId": "f329g-3dsf-2dsf-dsgg",
  "apikey": "fdh32498"
}

Ответ

HTTP коды ответа:

200 – успешный ответ, с информацией о заказе

400 - неверные параметры заказа
404 - заказ не найден

Content type: application/json
{
  "OrderId": "f329g-3dsf-2dsf-dsgg",
  "Status": "Progress",
  "DateCreate": "2025-03-01T12:00:00",
  "DateEnd": "2025-03-02T19:00:00",
  "CarwashId": "12345",
  "CarId": "2453",
  "TimeId": "133521",
  "DateTimeName": "21.02.2026 09:30:00",
  "Cart":  [
    {
      "ServiceId": "prostaya",
      "Price": 300,
      "Quantity": 1,
      "Amount" : 300
    },
    ...
  ],
  "Description": "Перезвоните для уточнения деталей заказа",
  "Sum": "1500.00",
  "SumCompleted": "1233.74",
  "ReasonId": "22",
  "Reason": "Причина отмены заказа"
}

Работа с автомойками самообслуживания

Получение списка терминалов самообслуживания

Информация о терминалах (постах) самообслуживания на автомойке, параметры и доступность терминалов для пополнения баланса.

Запрос

(GET) URL_BZ + /v1/carwash/{CarwashId}/posts?apikey={apikey}

Ответ

Content type: application/json
[
  {
    "PostId": "1",
    "PostName": "Терминал А",
    "PostLocked": false,
    "PostDebitStep": 10,
    "PostDebitMin": 10,
    "PostDebitMax": 2000
  },
  ...
]

Пополнение баланса терминала самообслуживания

Для пополнения баланса терминала необходимо передать выбранную автомойку и терминал с указанием суммы пополенения.

Запрос

(GET) URL_BZ + /v1/carwash/debit

Request body schema application/json

{
  "OrderId": "j432-3dfr-3132-134f",
  "CarwashId": "16546",
  "PostId": "1",
  "Sum": 540,
  "UserPhone": "79222222222",
  "UserEmail": "mail@mail.ru",
  "ContractId": "Сorporation',
  "apikey": "wfgsdg32498"
}

Ответ

HTTP коды ответа:

200 – Успешный ответ. Принят новый заказ, либо заказ с указанным `OrderId` уже существует.

Запрос получение информации о пополнении

Запрос для получения актуальной информации по созданному ранее пополнению баланса терминала.

Запрос

(POST) URL_BZ + /v1/carwash/status 

Request body schema application/json

{
  "OrderId": "f329g-3dsf-2dsf-dsgg",
  "apikey": "fdh32498"
}

Ответ

HTTP коды ответа:

200 – успешный ответ, с информацией о заказе

400 - неверные параметры заказа
404 - заказ не найден

Content type: application/json
{
  "OrderId": "f329g-3dsf-2dsf-dsgg",
  "Status": "Progress",
  "DateCreate": "2025-03-01T12:00:00",
  "DateEnd": "2025-03-02T19:00:00",
  "CarwashId": "12345",
  "PostId": "1",
  "Sum": "1500.00",
  "SumCompleted": "1233.74",
  "ReasonId": "22",
  "Reason": "Причина отмены заказа"
}

Передача состояния заказа партнеру

Сервер Benzuber выполняет запросы, для передачи статусов заказов партнеру на согласованный адрес:

URL_PS + /api/carwash/команда?apikey={apikey}&параметры

• Подтверждение заказа: команда Accept
• Завершение заказа: команда Completed
• Отмена заказа: команда Canceled

Подтверждение заказа (Статус: accept)

Данный запрос отправляет после того, как были произведены определённые действия с полученным заказом, проверено соответствие параметров, заказ сохранен в базе данных, и система готова перейти на следующий шаг. Запрос необходим, чтобы удостовериться что полученный заказ от партнёра действительный.

Запрос

(GET) URL_PS + /api/carwash/accept?apikey={apikey}&OrderId={OrderId}

Ответ

HTTP коды ответа:

200 – Заказ подтверждён партнером

любой другой код - запрос на подтверждение повторяется 5 раз с интервалом 5 секунд, затем отменяется. Устанавливается статус заказа = StationCanceled

Уведомление о завершении заказа (Статус: completed)

Запрос сообщает партнёру о том, что заказ выполнен.

Запрос

(GET) URL_PS + /api/carwash/completed?apikey={apiKey}&OrderId={OrderId}&SumCompleted={SumCompleted}

Ответ

HTTP коды ответа:

200 – Информация о завершении заказа принята партнёром

любой другой код - уведомление о завершении заказа повторяется до получения ответа с кодом 200 с увеличивающимся интервалом

Уведомление об отмене заказа (Статус: canceled)

Запрос сообщает партнёру о том, что заказ не может быть исполнен и его следует отменить.

Запрос

(GET) URL_PS + /api/charge/canceled?apikey=[apiKey]&OrderId=[OrderId]&Reason=[Reason]&ReasonId=[ReasonId]

Ответ

HTTP коды ответа:

200 – Информация об отмене заказа принята партнёром

любой другой код - уведомление об отмене заказа повторяется до получения ответа с кодом 200 с увеличивающимся интервалом

Список изменений