Maps Booking Car Washes Partner API (1.0.0)

Download OpenAPI specification:Download

API спецификация для партнеров, интегрирующихся с сервисом бронирования автомоек в Яндекс Картах.

После создания бронирования партнер обязан обновлять статусы бронирования через API сервиса бронирования (partner.maps.yandex.net), используя эндпоинт /v1/partners/{partnerId}/{bookingId}. Это необходимо для синхронизации статусов между системами и корректного отображения информации пользователям.

Authentication

RequestJWT

https://jwt.io/introduction
header: {"alg": "HS256","typ": "JWT"}
payload: Обязательные поля указаны в описании каждого эндпоинта. Необходимо проверять соответствие полей в payload и данных в самом запросе. В payload могут добавляться дополнительные поля, они не должны влиять на проверку.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

Фид автомоек

JWT payload: {}
Timeout: 60s

Authorizations:

RequestJWT

query Parameters

cursor	string Example: cursor=company_123 Курсор для пагинации (идентификатор последнего элемента из предыдущего запроса)
count	integer [ 1 .. 500 ] Default: 100 Example: count=50 Количество организаций для получения (по умолчанию 100, максимум 500)

Responses

Response samples

200
500

Content type

application/json

{"companies": [{"id": "company_123",
"name": "Автомойка Чистюля",
"address": "ул. Ленина, 15, Москва",
"coordinates": {"lat": 55.75582,
"lon": 37.617633
},
"phones": ["+74951234567"
],
"urls": ["https://chistula-wash.ru"
],
"workingTime": "Пн-Вс 08:00-22:00",
"rubrics": ["Автомойка"
],
"services": [{"id": "car-wash",
"title": "Обычная мойка",
"description": "Мойка снаружи + ковры",
"price": {"currencyCode": "RUB",
"range": [300,
455
]
},
"durationSeconds": 2100
}
]
}
],
"pagination": {"cursor": "company_456",
"hasMore": true
}
}

Список услуг автомойки

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

JWT payload: {"companyId": "{companyId}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

companyId

required

string

Example: company_123

Идентификатор автомойки

query Parameters

carModelId

string

Example: carModelId=42

Идентификатор модели автомобиля. Если указан, возвращаются услуги с ценами для конкретной модели.

Responses

Response samples

200
422
500

Content type

application/json

{"services": [{"id": "car-wash",
"title": "Обычная мойка",
"description": "Мойка снаружи + ковры",
"price": {"currencyCode": "RUB",
"range": [300,
455
]
},
"durationSeconds": 2100
},
{"id": "vacuum",
"title": "Пылесос салона",
"description": "Пылесос салона, ковриков, сидений",
"price": {"currencyCode": "RUB",
"range": [140,
195
]
},
"durationSeconds": 900
}
]
}

Список постов/боксов автомойки

Возвращает список доступных постов или боксов для мойки. Реализация опциональна — если партнер не поддерживает выбор конкретного поста, эндпоинт может возвращать пустой список.

JWT payload: {"companyId": "{companyId}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

companyId

required

string

Example: company_123

Идентификатор автомойки

query Parameters

serviceIds

Array of strings

Example: serviceIds=car-wash&serviceIds=vacuum

Фильтрация по идентификаторам услуг

Responses

Response samples

200
422
500

Content type

application/json

{"resources": [{"id": "box_1",
"title": "Пост №1"
},
{"id": "box_2",
"title": "Пост №2"
}
]
}

Получение доступных дат

JWT payload: {"companyId": "{companyId}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

companyId

required

string

Example: company_123

Идентификатор автомойки

query Parameters

from required	string <date> Example: from=2025-03-16 Начальная дата (YYYY-MM-DD)
to required	string <date> Example: to=2025-03-30 Конечная дата (YYYY-MM-DD)
serviceIds	Array of strings Example: serviceIds=car-wash Идентификаторы выбранных услуг
resourceId	string Example: resourceId=box_1 Идентификатор поста/бокса
carModelId	string Example: carModelId=42 Идентификатор модели автомобиля

Responses

Response samples

200
422
500

Content type

application/json

{"availableDates": [{"date": "2025-03-16"
},
{"date": "2025-03-17"
},
{"date": "2025-03-18"
}
]
}

Получение доступных временных слотов

JWT payload: {"companyId": "{companyId}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

companyId

required

string

Example: company_123

Идентификатор автомойки

query Parameters

date required	string <date> Example: date=2025-03-16 Дата (YYYY-MM-DD)
serviceIds	Array of strings Example: serviceIds=car-wash&serviceIds=vacuum Идентификаторы выбранных услуг
resourceId	string Example: resourceId=box_1 Идентификатор поста/бокса
carModelId	string Example: carModelId=42 Идентификатор модели автомобиля

Responses

Response samples

200
422
500

Content type

application/json

{"availableTimeSlots": [{"datetime": "2025-03-16T10:00:00+03:00"
},
{"datetime": "2025-03-16T10:30:00+03:00"
},
{"datetime": "2025-03-16T11:00:00+03:00"
},
{"datetime": "2025-03-16T11:30:00+03:00"
}
]
}

Получение специальных условий

JWT payload: {"companyId": "{companyId}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

companyId

required

string

Example: company_123

Идентификатор автомойки

query Parameters

datetime required	string <date-time> Example: datetime=2025-03-16T10:00:00+03:00 Дата и время в формате ISO 8601
serviceIds required	Array of strings Example: serviceIds=car-wash Идентификаторы выбранных услуг
resourceId	string Example: resourceId=box_1 Идентификатор поста/бокса

Responses

Response samples

200
422
500

Content type

application/json

{"specialConditions": [{"title": "Скидка участникам программы лояльности",
"value": "10%"
}
]
}

Создать предбронирование (временно занять слот)

Временно резервирует выбранный временной слот на время заполнения формы бронирования. Если бронирование не будет создано, предбронирование необходимо отменить через DELETE /prebookings/{id}.

JWT payload: {"companyId": "{companyId}"}
Timeout: 5s

Authorizations:

RequestJWT

Request Body schema: application/json

required

object (PrebookingInput)

Responses

Request samples

Payload

Content type

application/json

{"prebooking": {"companyId": "company_123",
"appointment": {"serviceIds": ["car-wash"
],
"resourceId": "box_1",
"carModelId": "42",
"datetime": "2025-03-16T10:00:00+03:00"
}
}
}

Response samples

200
422
500

Content type

application/json

{"prebooking": {"id": "prebooking_789"
}
}

Отмена предбронирования

JWT payload: {"prebookingId": "{id}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

id

required

string

Example: prebooking_789

Идентификатор предбронирования

Responses

Response samples

500

Content type

application/json

{"code": "string"
}

Создать бронирование

JWT payload: {"companyId": "{companyId}", "userPhone": "{phone}"}
Timeout: 5s

Идемпотентность: Для предотвращения дублирующихся бронирований клиент обязан передавать уникальный заголовок Idempotency-Key в формате UUID v7. При повторном запросе с тем же ключом сервер возвращает результат первого успешно обработанного запроса, не создавая новое бронирование.

Authorizations:

RequestJWT

header Parameters

Idempotency-Key

required

string <uuid>

Example: 01234567-89ab-7def-8123-456789abcdef

Уникальный ключ идемпотентности в формате UUID v7. Позволяет избежать создания дублирующихся бронирований при повторных запросах (ретраях) из-за сетевых ошибок.

Request Body schema: application/json

required

object (BookingInput)

Responses

Request samples

Payload

Content type

application/json

{"booking": {"companyId": "company_123",
"user": {"name": "Иван",
"lastName": "Петров",
"phone": "+79991234567",
"email": "ivan.petrov@example.com"
},
"comment": "Хотелось бы пост у выезда",
"appointment": {"serviceIds": ["car-wash",
"vacuum"
],
"resourceId": "box_1",
"carModelId": "42",
"carRegistrationNumber": "А123ВС77",
"datetime": "2025-03-16T10:00:00+03:00"
},
"prebookingId": "prebooking_789"
}
}

Response samples

200
422
500

Content type

application/json

{"booking": {"id": "booking_456",
"status": "confirmed",
"serviceIds": ["car-wash",
"vacuum"
],
"resourceId": "box_1",
"carModelId": "42",
"carRegistrationNumber": "А123ВС77",
"datetime": "2025-03-16T10:00:00+03:00"
}
}

Получение информации о бронировании

JWT payload: {"bookingId": "{id}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

id

required

string

Example: booking_456

ID бронирования

Responses

Response samples

200
404

Content type

application/json

{"booking": {"id": "booking_456",
"status": "confirmed",
"serviceIds": ["car-wash",
"vacuum"
],
"resourceId": "box_1",
"carModelId": "42",
"carRegistrationNumber": "А123ВС77",
"datetime": "2025-03-16T10:00:00+03:00"
}
}

Обновить бронирование (перенести на другое время)

JWT payload: {"bookingId": "{id}"}
Timeout: 5s

При изменениях в бронировании, которые совершаются внутри системы партнера (не инициированы описанным здесь запросом), необходимо отправить PUT-запрос https://partner.maps.yandex.net/v1/partners/{partnerId}/{bookingId} чтобы синхронизировать состояние с личным кабинетом пользователя в Картах.

Authorizations:

RequestJWT

path Parameters

id

required

string

Example: booking_456

ID бронирования

Request Body schema: application/json

companyId required	string ID автомойки
comment	string Комментарий к бронированию
datetime	string <date-time> Новые дата и время в формате ISO 8601
prebookingId	string Идентификатор предбронирования нового слота

Responses

Request samples

Payload

Content type

application/json

{"companyId": "company_123",
"datetime": "2025-03-16T11:00:00+03:00",
"prebookingId": "prebooking_999"
}

Response samples

200
404
422

Content type

application/json

{"booking": {"id": "booking_456",
"status": "confirmed",
"serviceIds": ["car-wash",
"vacuum"
],
"resourceId": "box_1",
"carModelId": "42",
"carRegistrationNumber": "А123ВС77",
"datetime": "2025-03-16T11:00:00+03:00"
}
}

Отмена бронирования

JWT payload: {"bookingId": "{id}"}
Timeout: 5s

Authorizations:

RequestJWT

path Parameters

id

required

string

Example: booking_456

ID бронирования

Responses

Response samples

200
404
422

Content type

application/json

{"id": "booking_456",
"status": "cancelled"
}

Обновление информации о бронировании партнером

JWT payload: {"bookingId": "{bookingId}"}
Timeout: 5s

Обновляет данные существующего бронирования у партнера.

Партнер обязан обновлять статус бронирования в следующих случаях:

При подтверждении бронирования (статус 'confirmed')
При выполнении услуги (статус 'visited')
При неявке клиента (статус 'not visited')
При отмене бронирования (статус 'cancelled')

Статус должен быть обновлен не позднее 15 минут после изменения соответствующего статуса в системе партнера.

Authorizations:

RequestJWT

path Parameters

partnerId required	string Идентификатор партнера
bookingId required	string Идентификатор бронирования

Request Body schema: application/json

status	string Enum: "created" "confirmed" "visited" "not visited" "cancelled" "unknown" Статус бронирования
datetime	string Время бронирования в формате ISO 8601
comment	string or null Комментарий к бронированию

Responses

Request samples

Payload

Content type

application/json

Example

{"status": "confirmed",
"datetime": "2025-03-16T10:00:00+03:00"
}