API Reference

This reference documents the public PHP API exposed by Laravel BusSystem API. For installation and complete workflows, start with the README.

Client access

The client is available through dependency injection:

use Nikba\LaravelBussystemApi\Contracts\BusSystemClientInterface;

final class TransportService
{
    public function __construct(
        private readonly BusSystemClientInterface $busSystem,
    ) {}
}

Every client operation is also exposed statically by the facade:

use Nikba\LaravelBussystemApi\Facades\BusSystem;

$status = BusSystem::ping();

All operations return an array containing the decoded BusSystem response. The package does not map remote responses into value objects, so applications should validate required keys and types at their boundary.

Client methods

getPoints()

Retrieves cities, stations, and airports.

public function getPoints(array $parameters = []): array

$points = BusSystem::getPoints([
    'lang' => 'en',
]);

Responses are cached when point caching is enabled.

getRoutes()

Searches for available routes using a SearchCriteria instance.

public function getRoutes(SearchCriteria $criteria): array

$routes = BusSystem::getRoutes(
    SearchCriteria::create()
        ->date('2026-09-15')
        ->from(3)
        ->to(7)
        ->bus(),
);

The configured partner ID is added automatically when present. Responses are cached when route caching is enabled.

getAllRoutes()

Retrieves detailed routes for a timetable.

public function getAllRoutes(string $timetableId, string $language = 'en'): array

$routes = BusSystem::getAllRoutes('timetable-id', 'en');

getFreeSeats()

Retrieves available seats for an interval. Additional parameters can identify a train or wagon when required by the remote endpoint.

public function getFreeSeats(string $intervalId, array $parameters = []): array

$seats = BusSystem::getFreeSeats('interval-id', [
    'vagon_id' => 'wagon-id',
]);

getSeatPlan()

Retrieves a seat-plan layout.

public function getSeatPlan(array $parameters = []): array

$plan = BusSystem::getSeatPlan([
    'bustype_id' => 'bus-type-id',
    'position' => 'h',
]);

Responses are cached when seat-plan caching is enabled.

getDiscounts()

Retrieves discounts available for an interval.

public function getDiscounts(string $intervalId, array $parameters = []): array

$discounts = BusSystem::getDiscounts('interval-id');

getBaggage()

Retrieves baggage options available for an interval.

public function getBaggage(string $intervalId, array $parameters = []): array

$baggage = BusSystem::getBaggage('interval-id');

createOrder()

Creates a new order from a BookingData instance.

public function createOrder(BookingData $bookingData): array

$order = BusSystem::createOrder($booking);

Call BookingData::validate() before this method when you want local validation. createOrder() sends the generated parameters directly and relies on the remote API for any additional validation.

buyTickets()

Purchases tickets for an existing order.

public function buyTickets(int $orderId, string $language = 'en'): array

$tickets = BusSystem::buyTickets(12345, 'en');

cancelTickets()

Cancels an order or selected tickets using remote API parameters.

public function cancelTickets(array $parameters): array

$result = BusSystem::cancelTickets([
    'order_id' => 12345,
    'security' => 'security-code',
    'lang' => 'en',
]);

The configured default API version is added automatically.

getOrder()

Retrieves an order by its BusSystem identifier.

public function getOrder(
    int $orderId,
    ?string $security = null,
    string $language = 'en',
): array

$order = BusSystem::getOrder(12345, 'security-code', 'en');

getTicket()

Retrieves ticket information using remote API parameters.

public function getTicket(array $parameters): array

$ticket = BusSystem::getTicket([
    'ticket_id' => 67890,
    'security' => 'security-code',
    'lang' => 'en',
]);

reserveTickets()

Reserves tickets for payment on boarding.

public function reserveTickets(int $orderId, array $parameters = []): array

$reservation = BusSystem::reserveTickets(12345, [
    'phone' => '+37360000000',
    'email' => 'passenger@example.com',
    'lang' => 'en',
]);

The order ID and configured default API version are added automatically.

validateReservation()

Checks whether a phone number is eligible for payment-on-boarding reservation.

public function validateReservation(
    string $phoneNumber,
    string $language = 'en',
): array

$validation = BusSystem::validateReservation('+37360000000', 'en');

validateSms()

Sends or verifies an SMS validation code using remote API parameters.

public function validateSms(array $parameters): array

Send a code:

$result = BusSystem::validateSms([
    'sid_guest' => session()->getId(),
    'phone' => '+37360000000',
    'send_sms' => 1,
    'lang' => 'en',
]);

Verify a code:

$result = BusSystem::validateSms([
    'sid_guest' => session()->getId(),
    'phone' => '+37360000000',
    'check_sms' => 1,
    'validation_code' => $code,
    'lang' => 'en',
]);

The configured default API version is added automatically.

ping()

Checks whether the API can be reached and its response can be decoded.

public function ping(): array

$status = BusSystem::ping();

SearchCriteria

Create an instance with SearchCriteria::create() and chain any relevant setters. Calling toArray() produces the remote API parameters.

Method	Accepted value	API parameter
date()	Date string	date
from()	City ID	id_from
to()	City ID	id_to
trainFrom()	Train-station ID	point_train_from_id
trainTo()	Train-station ID	point_train_to_id
airportFrom()	IATA code	id_iata_from
airportTo()	IATA code	id_iata_to
stationFrom()	Station ID	station_id_from
stationTo()	Station ID	station_id_to
transport()	TransportType or string	trans
allowTransfers()	Remote change mode	change
directOnly()	No argument	change=0
period()	Integer, clamped to -3…14	period
sortBy()	SortType or string	sort_type
includeSoldOut()	Boolean	get_all_departure
currency()	Currency code	currency
language()	Language code	lang
airPassengers()	Adult, child, infant counts	adt, chd, inf
airServiceClass()	Service-class code	service_class
airDirect()	Boolean	direct
airBaggage()	Boolean	baggage_no
addParam()	Arbitrary key and value	Given key

bus(), train(), and air() are shortcuts for transport(). sortByTime() and sortByPrice() are shortcuts for sortBy().

Custom values added with addParam() are merged last and can override generated parameters. Only use this intentionally.

BookingData

Create a booking with BookingData::create($currency, $language). Calling toArray() produces the remote order parameters.

Routes

$booking->addRoute(
    date: '2026-09-15',
    intervalId: 'interval-id',
    stationFromId: 101,
    stationToId: 202,
);

Call the method once per journey leg. Route indexes used elsewhere are zero-based and correspond to insertion order.

Passengers

$booking->addPassenger(
    firstName: 'John',
    lastName: 'Doe',
    birthDate: '1990-01-15',
    docType: 1,
    docNumber: 'AB123456',
    gender: 'M',
    middleName: null,
    citizenship: 'MD',
    docExpireDate: '2030-01-15',
);

Document types, gender values, and date formats must follow the BusSystem API contract.

Route and passenger selections

$booking
    ->addSeat(routeIndex: 0, seat: '12')
    ->addSeats(routeIndex: 1, seats: ['8'])
    ->addDiscount(routeIndex: 0, passengerIndex: 0, discountId: 'discount-id')
    ->addBaggage(routeIndex: 0, passengerIndex: 0, baggageIds: ['baggage-id'])
    ->addWagon(routeIndex: 0, wagonId: 'wagon-id');

Contact and metadata

$booking
    ->setContactInfo('+37360000000', 'passenger@example.com')
    ->setAdditionalInfo('Accessibility assistance requested')
    ->setPromocode('PROMO')
    ->setCurrency('EUR')
    ->setLanguage('en');

Validation

$errors = $booking->validate(); // list<string>
$passengers = $booking->getPassengerCount();
$routes = $booking->getRouteCount();

Local validation requires at least one route, one passenger, matching route/date counts, passenger names and birth dates, and a contact phone number. Remote validation may impose additional requirements.

Exceptions

Exception	Meaning
BusSystemException	Abstract base for package exceptions
BusSystemApiException	Transport, HTTP, parsing, or general remote API failure
BusSystemAuthenticationException	Authentication or inactive-dealer response
BusSystemValidationException	Local booking or remote input validation failure
BusSystemBookingException	Available for application booking workflows
BusSystemPaymentException	Available for application payment workflows
BusSystemCancellationException	Available for application cancellation workflows

BusSystemException::getContext() returns structured context attached to an exception. setContext() can enrich an exception before it is reported or rethrown.

Models

Order

The Order model uses the bussystem_orders table, supports soft deletes, and exposes a tickets() relationship.

Order::query()->active();
Order::query()->reserved();
Order::query()->paid();
Order::query()->expired();
Order::query()->forUser($userId);

status() returns OrderStatus|null; isReserved(), isPaid(), isCancelled(), and isExpired() provide boolean checks.

Ticket

The Ticket model uses the bussystem_tickets table, supports soft deletes, and exposes an order() relationship.

Ticket::query()->active();
Ticket::query()->reserved();
Ticket::query()->paid();
Ticket::query()->forPassenger($firstName, $lastName);
Ticket::query()->forRoute($from, $to);
Ticket::query()->departingAfter($date);
Ticket::query()->departingBefore($date);

status() returns TicketStatus|null; isReserved(), isPaid(), and isCancelled() provide boolean checks. Accessors are available for passenger_full_name, route_description, departure_date_time, and arrival_date_time.

Configuration reference

Key	Environment variable	Default
api_url	BUSSYSTEM_API_URL	Test API URL
login	BUSSYSTEM_LOGIN	null
password	BUSSYSTEM_PASSWORD	null
partner_id	BUSSYSTEM_PARTNER_ID	null
timeout	BUSSYSTEM_TIMEOUT	120 seconds
retry_attempts	BUSSYSTEM_RETRY_ATTEMPTS	3
retry_delay	BUSSYSTEM_RETRY_DELAY	1000 milliseconds
default_currency	BUSSYSTEM_DEFAULT_CURRENCY	EUR
default_language	BUSSYSTEM_DEFAULT_LANGUAGE	en
default_api_version	BUSSYSTEM_DEFAULT_API_VERSION	1.1
cache.enabled	BUSSYSTEM_CACHE_ENABLED	true
cache.prefix	BUSSYSTEM_CACHE_PREFIX	bussystem
cache.ttl.points	BUSSYSTEM_CACHE_POINTS_TTL	3600 seconds
cache.ttl.routes	BUSSYSTEM_CACHE_ROUTES_TTL	300 seconds
cache.ttl.plans	BUSSYSTEM_CACHE_PLANS_TTL	86400 seconds
logging.enabled	BUSSYSTEM_LOGGING_ENABLED	true
logging.channel	BUSSYSTEM_LOG_CHANNEL	daily
logging.level	BUSSYSTEM_LOG_LEVEL	info
response_format	BUSSYSTEM_RESPONSE_FORMAT	json

Publish the configuration with php artisan vendor:publish --tag=bussystem-config when you need to customize these settings.