inteliada/yandex-fleet-lib

PHP library to work with Yandex Fleet API

v1.0.0 2026-03-09 05:53 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^7.10
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/log: ^2.0|^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.40
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9.5|^10.0
• squizlabs/php_codesniffer: ^3.7

MIT

• Denis Joloudov

README

A PHP library for integrating with the Yandex Fleet API.

Requirements

• PHP >= 8.1
• Composer
• Guzzle HTTP Client >= 7.10 (or any PSR-18 HTTP client)
• Active Yandex Fleet account with API credentials

Installation

composer require inteliada/yandex-fleet-sdk

Quick Start

use Inteliada\YandexFleetLib\Client;

$client = new Client([
    'client_id' => getenv('YANDEX_CLIENT_ID'),
    'api_key'   => getenv('YANDEX_API_KEY'),
    'park_id'   => getenv('YANDEX_PARK_ID'),
]);

// List drivers
$drivers = $client->contractorProfiles()->getList();

// List vehicles
$vehicles = $client->vehicles()->getList();

Configuration

Credentials

All three credentials are required. Obtain them from your Yandex Fleet account:

Key	Description
client_id	Your application's unique identifier
api_key	API authentication key
park_id	Fleet (park) identifier

Options

$client = new Client($credentials, [
    'timeout'  => 30,                               // seconds (default: 30)
    'retries'  => 3,                                // retries on 5xx / 429 / connection errors (default: 3)
    'base_uri' => 'https://fleet-api.taxi.yandex.net', // override for staging/testing
]);

PSR-18 HTTP client

Inject any PSR-18 compatible HTTP client (e.g. Symfony HttpClient):

use Symfony\Component\HttpClient\Psr18Client;

$client = new Client($credentials, [], httpClient: new Psr18Client());

Logging

Inject any PSR-3 logger (e.g. Monolog):

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('fleet');
$logger->pushHandler(new StreamHandler('php://stdout'));

$client = new Client($credentials, [], logger: $logger);

Rate limit awareness

$client->vehicles()->getList();
$remaining = $client->vehicles()->getList(); // second call
// Access headers from the last request:
$headers   = ... // see HttpClientInterface::getLastResponseHeaders()

API Reference

Endpoint	Client method	Available methods
Contractor Profiles	contractorProfiles()	getList(), get(), create(), update(), createContractor(), createAutoCourierProfile(), createWalkingCourierProfile(), createSelfEmployedWalkingCourierProfile(), bindVehicle(), unbindVehicle(), getSupplyHours(), getBlockedBalance(), listApplications()
Vehicles	vehicles()	getList(), get(), create(), update(), updateRentDetails(), updateRentTerms()
Orders	orders()	getList(), track()
Transactions	transactions()	getList(), listDriverTransactions(), listOrderTransactions(), listCategories(), create(), getStatus()
Driver Work Rules	driverWorkRules()	getList()

Contractor Profiles

$cp = $client->contractorProfiles();

// List driver profiles
$cp->getList();
$cp->getList(['limit' => 50, 'offset' => 100]);

// Get a single driver profile
$cp->get('driver_profile_id');

// Create a driver/courier profile (choose one method based on type)
$cp->create(['person' => ['first_name' => 'Ivan', 'last_name' => 'Petrov']]);

$cp->createContractor([
    'contractor' => ['person' => [...], 'profile' => ['hire_date' => '2026-01-01']],
    'employment' => [...],
    'profession' => 'taxi/driver', // or 'cargo/courier/on-car', 'cargo/courier/on-truck'
]);

$cp->createAutoCourierProfile([
    'order_provider' => ['platform' => true, 'partner' => false],
    'person' => ['full_name' => [...], 'contact_info' => ['phone' => '[phone]'], 'driver_license' => [...]],
]);

$cp->createWalkingCourierProfile([
    'full_name'    => ['first_name' => 'Ivan', 'last_name' => 'Petrov'],
    'phone'        => '[phone]',
    'birth_date'   => '1990-01-01',
    'work_rule_id' => 'rule_id',
]);

// createSelfEmployedWalkingCourierProfile() takes the same fields as createWalkingCourierProfile()
$cp->createSelfEmployedWalkingCourierProfile([...]);

// Update a driver profile
$cp->update(['id' => 'driver_profile_id', 'person' => ['phone' => '[phone]']]);

// Bind / unbind a vehicle
$cp->bindVehicle('car_id', 'driver_profile_id');
$cp->unbindVehicle('car_id', 'driver_profile_id');

// Get driver's online hours for a period
$cp->getSupplyHours('driver_profile_id', '2026-01-01T00:00:00+00:00', '2026-01-31T23:59:59+00:00');

// Get driver's account balance and restrictions
$cp->getBlockedBalance('contractor_id');

// List contractor applications (cursor-based pagination)
$cp->listApplications();
$cp->listApplications(['limit' => 50, 'cursor' => 'next-token']);

Vehicles

$vehicles = $client->vehicles();

// List vehicles
$vehicles->getList();
$vehicles->getList(['limit' => 50, 'offset' => 0]);

// Get a single vehicle
$vehicles->get('car_id');

// Create a vehicle
$vehicles->create(['callsign' => 'A001', 'model' => 'Toyota Camry']);

// Update a vehicle
$vehicles->update('car_id', ['callsign' => 'A002']);

// Modify rental arrangements for a vehicle
$vehicles->updateRentDetails('car_id', [
    'platform_channels_enabled' => true,
    'rent_term_id'              => 'term_id', // optional
]);

// Create or modify rental terms
$vehicles->updateRentTerms([
    'rent_term_id'        => 'term_id',
    'name'                => 'Standard',
    'schemas'             => [
        ['working_days' => 5, 'non_working_days' => 2, 'daily_amount' => '1000.0000'],
    ],
    'minimum_period_days' => 7,
    'is_buyout_possible'  => false,
]);

Orders

$orders = $client->orders();

// List orders — booked_at or ended_at is required
$orders->getList([
    'booked_at' => ['from' => '2026-01-01T00:00:00Z', 'to' => '2026-01-31T23:59:59Z'],
]);

$orders->getList([
    'ended_at' => ['from' => '2026-01-01T00:00:00Z', 'to' => '2026-01-31T23:59:59Z'],
    'limit'    => 50,
    'cursor'   => 'next-page-cursor',
]);

// Get GPS track for an order
$orders->track('order_id');

Transactions

$tx = $client->transactions();

// List park transactions (all filters optional)
$tx->getList();
$tx->getList([
    'event_at'     => ['from' => '2026-01-01T00:00:00Z', 'to' => '2026-01-31T23:59:59Z'],
    'category_ids' => ['bonus', 'penalty'],
    'limit'        => 40,
    'cursor'       => 'next-cursor-token',
]);

// List transactions for a specific driver
$tx->listDriverTransactions('driver_id', [
    'event_at' => ['from' => '2026-01-01T00:00:00Z', 'to' => '2026-01-31T23:59:59Z'],
]);

// List transactions for specific orders
$tx->listOrderTransactions(['order_id_1', 'order_id_2']);
$tx->listOrderTransactions(['order_id_1'], [
    'event_at' => ['from' => '2026-01-01T00:00:00Z', 'to' => '2026-01-31T23:59:59Z'],
]);

// List transaction categories (all filters optional)
$tx->listCategories();
$tx->listCategories(['is_enabled' => true, 'is_creatable' => true]);

// Create a transaction for a driver
$tx->create('driver_profile_id', [
    'amount'      => '500',
    'data'        => ['type' => 'bonus'],
    'description' => 'Top performer bonus',
]);

// Get transaction status
$tx->getStatus('driver_profile_id', 'transaction_id');
$tx->getStatus('driver_profile_id', 'transaction_id', 2); // specific version

Driver Work Rules

// List work rules for the park
$client->driverWorkRules()->getList();

Pagination

All list endpoints return a ListResponse with items, cursor, and total. Use paginate() to iterate all pages automatically — it yields typed DTOs:

// Iterate all vehicles as VehicleDto objects
foreach ($client->vehicles()->paginate() as $vehicle) {
    echo $vehicle->id . ' — ' . $vehicle->callsign . PHP_EOL;
}

// Iterate all orders (booked_at required)
foreach ($client->orders()->paginate(['booked_at' => ['from' => '2026-01-01T00:00:00Z', 'to' => '2026-01-31T23:59:59Z']]) as $order) {
    echo $order->id . ' ' . $order->status . PHP_EOL;
}

// Manual cursor pagination
$page = $client->transactions()->getList(['limit' => 40]);
while (!$page->isLastPage()) {
    foreach ($page->items as $item) { /* ... */ }
    $page = $client->transactions()->getList(['cursor' => $page->cursor]);
}

Error Handling

All API errors throw ApiException. It extends \Exception and adds two methods:

use Inteliada\YandexFleetLib\Exception\ApiException;

try {
    $driver = $client->contractorProfiles()->get('driver_id');
} catch (ApiException $e) {
    echo $e->getStatusCode();   // HTTP status code
    echo $e->getResponseBody(); // raw response body
    echo $e->getMessage();      // error message
}

Transient failures (5xx, 429, connection errors) are retried automatically up to the configured retries limit before an exception is thrown.

Project Structure

src/
├── Client.php
├── Endpoints/
│   ├── BaseEndpoint.php
│   ├── ContractorProfiles.php
│   ├── DriverWorkRules.php
│   ├── Orders.php
│   ├── Transactions.php
│   └── Vehicles.php
├── Exception/
│   └── ApiException.php
└── Http/
    ├── HttpClientInterface.php
    └── Request.php

Testing

composer test

Changelog

See CHANGELOG.md for release history.

License

MIT — see LICENSE.

Author

Denis Joloudov — [e-mail]

This SDK is not officially affiliated with Yandex.