README

Неофициальный PHP SDK для API сервиса «Деловые Линии». Он объединяет методы API по предметным группам, автоматически добавляет appkey и sessionID, поддерживает ответы с двоичными данными и не привязывает приложение к конкретному HTTP-клиенту.

Это независимый проект сообщества. Он не связан с ООО «Деловые Линии», не поддерживается, не авторизован и не одобрен им.

Требования

PHP 8.2 или новее;
Composer;
совместимая с PSR-18 реализация HTTP-клиента.

HTTP-клиент и фабрики PSR-17 обнаруживаются автоматически. В новом проекте проще всего установить Guzzle. Если в приложении уже есть совместимые реализации, повторно устанавливать их не нужно.

Установка

composer require webmasterskaya/dellin-php-sdk guzzlehttp/guzzle

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

<?php

require 'vendor/autoload.php';

use Webmasterskaya\DelLinDelivery\Client;

$sdk = new Client((string) getenv('DELLIN_APP_KEY'));

// Расчёт стоимости перевозки
$result = $sdk->calculator()->calculate([
    'version'      => '0.1',
    'derivalPoint' => '7800000000000000000000000', // код КЛАДР города отправки
    'derivalDoor'  => false,                        // забор с терминала отправителя
    'arrivalPoint' => '6600000100000000000000000',  // код КЛАДР города получения
    'arrivalDoor'  => false,                        // выдача на терминал получателя
    'sizedCargo'   => true,
    'packages'     => [
        ['length' => 1, 'width' => 1, 'height' => 1, 'weight' => 10],
    ],
]);

Конструктор

new Client(
    string $appKey,
    ?ClientInterface $httpClient = null,
    string $baseUri = Client::API_BASE_URI,
    ?string $sessionId = null,
    ?RequestFactoryInterface $requestFactory = null,
    ?StreamFactoryInterface $streamFactory = null,
    ?LoggerInterface $logger = null,
);

Ключ приложения — единственный обязательный аргумент. Остальные зависимости и настройки передаются именованными аргументами. Это удобно для контейнера зависимостей и не требует запоминать структуру массива опций:

$sdk = new Client(
    appKey: (string) getenv('DELLIN_APP_KEY'),
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    logger: $logger,
);

Для тестового шлюза или прокси можно указать baseUri. Уже полученный идентификатор сессии передаётся через sessionId.

appkey и sessionID автоматически добавляются в тело каждого запроса, если они не заданы в payload явно.

Доступ к методам

Методы API сгруппированы в объекты-эндпоинты. Получить их можно как геттером, так и через магическое свойство:

$sdk->calculator()->calculate($payload);   // $sdk->calculator->calculate(...) — то же самое
$sdk->auth()->login($payload);
$sdk->book()->counteragentSave($payload);
$sdk->catalogs()->freightTypes();
$sdk->counteragents()->list();
$sdk->marking()->shipmentLabels($payload);
$sdk->orders()->list();
$sdk->orders()->track(['docNumber' => '...']);
$sdk->payment()->mutualCalculations();
$sdk->places()->kladr($payload);
$sdk->requests()->createLtl($payload);
$sdk->terminals()->directory();

Кроме того, есть прямой доступ к транспорту — на случай, если нужного метода в SDK ещё нет (все методы API — POST с JSON-телом):

$data = $sdk->request('v2/public/terminals.json', ['appkey' => '...']);

Авторизация

Методы, требующие авторизации, принимают sessionID. Его можно получить через метод auth/login и передать в клиент иммутабельно:

$session = $sdk->auth()->login([
    'login'    => 'user@example.com',
    'password' => '********',
]);

$sdk = $sdk->withSessionId($session['sessionID']);

// Теперь авторизованные методы доступны:
$counteragents = $sdk->counteragents()->list();

Ошибки

Все ошибки, возвращённые API, бросаются как ApiException (сетевые проблемы — как NetworkException):

use Webmasterskaya\DelLinDelivery\Exception\ApiException;

try {
    $result = $sdk->calculator()->calculate($payload);
} catch (ApiException $e) {
    // $e->getErrors() — массив `errors` в исходном виде (или строка, как вернул API)
    // $e->getCode()  — HTTP-статус ответа
    // $e->getBody()  — исходное тело ответа
    echo $e->getMessage();
}

Печатные формы, этикетки и метки (бинарные ответы)

Методы, возвращающие PDF-файлы, возвращают PSR-7 ответ:

$response = $sdk->orders()->requestPdf([
    'requestID' => '...',
    'form'      => ['name' => 'order'],
]);

file_put_contents('order.pdf', (string) $response->getBody());

Логирование

Любая PSR-3 реализация подключается через конструктор:

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

$logger = new Logger('dellin');
$logger->pushHandler(new StreamHandler('php://stderr', \Monolog\Level::Debug));

$sdk = new Client('APPKEY', logger: $logger);

В лог попадают метод, URI, статус и тело запроса — при этом appkey и sessionID автоматически маскируются.

Адреса методов и форматы payload описаны в официальной документации: https://dev.dellin.ru/api/

Разработка

composer install
composer lint
composer test
composer cs:check
composer cs:fix
composer analyse
composer phpstan
composer psalm

lint проверяет синтаксис всех PHP-файлов без загрузки пользовательского php.ini. cs:check проверяет стиль кода, cs:fix исправляет его, а analyse запускает PHPStan максимального уровня и Psalm с первым уровнем ошибок. CI выполняет lint и тесты на PHP 8.2, 8.3, 8.4 и 8.5, а также отдельно проверяет минимально поддерживаемые версии зависимостей.

Лицензия

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

Подробнее см. в файле LICENSE.

webmasterskaya / dellin-php-sdk

Package info

Security

Statistics