Партнёрский API

REST-интерфейс BUS.ONLINE для агрегаторов, автовокзалов и агентств: справочники остановок, поиск рейсов, тарифы, свободные места, бронирование, подтверждение оплаты, статус заказа, отмена и возврат билетов.

Быстрый старт

Типичный цикл продажи — шесть шагов:

1. GET /stations — получить id остановок
2. GET /routes-from — куда есть рейсы с выбранной остановки
3. GET /search — рейсы на дату (время, цены, места)
4. GET /free-seats — актуальные свободные места перед выбором
5. POST /book — бронь (заказ ожидает подтверждения оплаты)
6. POST /confirm — подтверждение оплаты и закрепление мест

При необходимости: GET /order, POST /cancel, POST /return.

# 1. Остановки
curl "https://bus.online/api/partner/v1/stations?partnerId=$PID&apiKey=$KEY"

# 2. Куда можно уехать
curl "https://bus.online/api/partner/v1/routes-from?partnerId=$PID&apiKey=$KEY&stationId=76"

# 3. Поиск рейсов
curl "https://bus.online/api/partner/v1/search?partnerId=$PID&apiKey=$KEY&fromId=76&toId=81&date=2026-08-20"

# 4. Свободные места
curl "https://bus.online/api/partner/v1/free-seats?partnerId=$PID&apiKey=$KEY&raceUid=RACE_UID"

# 5. Бронь
curl -X POST "https://bus.online/api/partner/v1/book?partnerId=$PID&apiKey=$KEY" \
  -H "Content-Type: application/json" \
  -d '{"raceUid":"RACE_UID","contactEmail":"agent@example.com","passengers":[{"seatnumber":"12","lastName":"Иванов","firstName":"Иван","middleName":"Иванович","birthDate":"1985-04-12","gender":"M","citizenship":"RU","docTypeCode":"00","document":"4008 644762","mobile":"79001234567"}]}'

# 6. Подтверждение оплаты
curl -X POST "https://bus.online/api/partner/v1/confirm?partnerId=$PID&apiKey=$KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId":123}'

Общие правила

• Базовый URL: https://bus.online/api/partner/v1/
• Протокол: HTTPS, UTF-8, ответы в JSON
• Параметры: query-строка и/или JSON-тело (для POST)
• Авторизация: в каждом запросе (отдельного метода логина нет)
• Доступ к данным: только по направлениям, разрешённым для вашей учётной записи
• Идентификатор рейса: строковый raceUid (поле id в ответе поиска)
• Идентификаторы остановок: числовые id из /stations

Авторизация

Передайте пару учётных данных одним из способов:

• Query: partnerId и apiKey
• Заголовки: X-Partner-Id и X-Api-Key

Если пара неверна или доступ отключён, любой метод вернёт ошибку «Не найден активный ключ пользователя».

Форматы значений

Методы

GET /stations

Справочник остановок, доступных партнёру.

Параметры: только авторизация.

{
  "stations": [
    {
      "id": "76",
      "title": "Москва",
      "name": "Москва. Автовокзал",
      "lngt": "37.6173",
      "ltd": "55.7558"
    }
  ]
}

GET /routes-from

Остановки назначения, связанные с заданной точкой отправления.

Ответ — массив stations в том же формате, что у /stations.

GET /search

Рейсы по паре остановок на дату: расписание, перевозчик, ориентир по местам и тарифам.

{
  "routes": [
    {
      "id": "142177713:0000011547:20260820:000000038:000000014",
      "from": "76",
      "to": "81",
      "name": "Москва — Новомосковск",
      "number": "123",
      "departure": "09:20:00",
      "arrival": "12:45:00",
      "duration": "03:25",
      "carrier": "Перевозчик",
      "carrier_inn": "7700000000",
      "contact": "+7…",
      "freeSeatsCount": 12,
      "bookable": true,
      "price": {
        "parts": [
          { "type": "adult", "value": 1530 },
          { "type": "child", "value": 765 }
        ]
      },
      "ticketTypes": [
        { "code": "FULL", "name": "Полный", "value": 1530 }
      ]
    }
  ]
}

Для дальнейших методов используйте routes[].id как raceUid. Перед бронированием рекомендуется уточнить места через /free-seats и тарифы через /prices.

GET /prices

Типы билетов и цены по конкретному рейсу.

{
  "ticketTypes": [
    { "code": "FULL", "name": "Полный", "type": "adult", "value": 1530, "ticketClass": "CLASS_PASSENGER" },
    { "code": "CHILD", "name": "Детский", "type": "child", "value": 765, "ticketClass": "CLASS_PASSENGER" }
  ]
}

GET /free-seats

Список свободных мест на рейсе.

{
  "freeSeats": [
    { "number": "3", "name": "3", "type": null },
    { "number": "4", "name": "4", "type": null },
    { "number": "12", "name": "12", "type": null }
  ]
}

GET /seat-map

Схема салона (если для рейса настроена раскладка) и коды свободных мест. Если схемы нет, вернутся свободные места без сетки.

POST /book

Создаёт бронь и удерживает места до подтверждения оплаты (или истечения срока брони).

Query / body:

Поля пассажира:

* Обязательность персональных данных зависит от требований конкретного рейса.

POST https://bus.online/api/partner/v1/book?partnerId=…&apiKey=…
Content-Type: application/json

{
  "raceUid": "…",
  "contactEmail": "agent@example.com",
  "contactPhone": "79001234567",
  "passengers": [
    {
      "seatnumber": "12",
      "lastName": "Иванов",
      "firstName": "Иван",
      "middleName": "Иванович",
      "birthDate": "1985-04-12",
      "gender": "M",
      "citizenship": "RU",
      "docTypeCode": "00",
      "document": "4008 644762",
      "mobile": "79001234567",
      "ticketTypeCode": "FULL"
    }
  ]
}

{
  "order": {
    "id": "123",
    "status": "BOOKED",
    "expire": "2026-08-20T10:15:00.000Z",
    "price": { "value": 1530 },
    "raceUid": "…",
    "contactEmail": "agent@example.com"
  },
  "tickets": [
    {
      "id": "456",
      "status": "BOOKED",
      "seat": { "number": "12" },
      "price": { "value": 1530 },
      "passenger": { "lastName": "Иванов", "firstName": "Иван" }
    }
  ]
}

Для /confirm, /order, /cancel используйте order.id.

POST /confirm

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

POST https://bus.online/api/partner/v1/confirm
{ "orderId": 123 }

Ответ — тот же формат, что у /order (заказ и билеты с обновлённым статусом).

GET /order

Текущее состояние заказа и билетов.

POST /cancel

Отмена незавершённого заказа или отдельного билета.

POST /return

Возврат оплаченного билета.

{
  "ok": true,
  "ticket": { "id": "456", "status": "RETURNED", "repayment": 1200 }
}

Ошибки

При ошибке HTTP-статус обычно 400 / 401 / 403 / 404. В теле ответа смотрите сообщение об ошибке. Типичные формулировки:

• «Не найден активный ключ пользователя» — неверные или отключённые учётные данные
• «Направление недоступно для этого ключа» — нет доступа к паре остановок
• «Некорректные параметры запроса» — не хватает обязательных полей
• «В указанную дату автобус по заданному маршруту не ходит»
• «Место повторяется несколько раз»
• «Заказ с таким номером не найден»
• «Заказ не может быть подтвержден.»

Подключение

Чтобы получить partnerId и apiKey, а также согласовать доступные направления, свяжитесь с нами:

• Телефон: 8 800 222 54 61
• Email: regulyar@sotrans.ru
• Контакты: /info/contacts

Храните ключ в защищённом хранилище. Не публикуйте его в клиентском коде и открытых репозиториях.