README

Это PHP KIT API клиент. Эта библиотека позволяет использовать актуальную версию API. Вы можете найти больше информации в документации.

Требования

PHP 7.4 и выше
поддержка PHP CURL
поддержка PHP JSON
Любой HTTP-клиент, совместимый с PSR-18 (см. инструкции по установке).
Любая реализация HTTP-фабрик, совместимая с PSR-17 (см. инструкции по установке).
Любая реализация HTTP-сообщений, совместимая с PSR-7 (см. инструкции по установке).
Другие зависимости, перечисленные в composer.json (см. инструкции по установке)

Установка

Выполните следующие шаги, что бы установить библиотеку:

Скачайте и установите Composer package manager.
composer require "kitdelivery/sdk-kit-api":"*"

Примечание: API клиент использует php-http/curl-client и nyholm/psr7 для реализации PSR-18, PSR-17 и PSR-7. Вы можете заменить эти реализации во время установки, заменив библиотеку на реализацию по вашему выбору.

Использование

Первое, вы должны инициализировать клиента. Самый простой способ сделать это - использовать SimpleClientFactory:

$client = \service\KitAPI\Factory\SimpleClientFactory::createClient('https://capi.tk-kit.com', 'token');

Клиент разделен на несколько групп, которые доступны через публичные свойства клиента. Вы можете вызывать методы API из этих групп следующим образом:

$client->profile->getList();

Для примера, вы можете получить список всех городов:

$client = \service\KitAPI\Factory\SimpleClientFactory::createClient('https://capi.tk-kit.com', 'token');
$client->tdd->getListCity();

или список всех стран:

$client = \service\KitAPI\Factory\SimpleClientFactory::createClient('https://capi.tk-kit.com', 'token');
$client->tdd->getListCountry();

Для обработки ошибок вы можете использовать два типа исключений:

service\KitAPI\Interfaces\ClientExceptionInterface для ошибок сети и других ошибок.
service\KitAPI\Interfaces\ApiExceptionInterface для ошибок из API.

Список ресурсных групп и методов

Примеры

Получение списка всех стран:

<?php

namespace Test;

use service\KitAPI\Factory\SimpleClientFactory;
use service\KitAPI\Interfaces\ApiExceptionInterface;
use service\KitAPI\Interfaces\ClientExceptionInterface;

require_once(__DIR__ . '/../vendor/autoload.php');

$client = SimpleClientFactory::createClient('https://capi.tk-kit.com', 'token');

try {
    $response = $client->tdd->getListCountry();
} catch (ApiExceptionInterface|ClientExceptionInterface $exception) {
    echo $exception;
    exit(-1);
}

foreach ($response->countries as $country) {
    printf("Название страны - '%s'. Код страны - '%s'", $country->name, $country->code);
    echo PHP_EOL;
}

Вывод терминалов для города c id = 699:

<?php

namespace Test;

use service\KitAPI\Factory\SimpleClientFactory;
use service\KitAPI\Interfaces\ApiExceptionInterface;
use service\KitAPI\Interfaces\ClientExceptionInterface;
use service\KitAPI\Model\Entity\Geography\Phone;
use service\KitAPI\Model\Request\Geography\GetListAddressRequest;

require_once(__DIR__ . '/../vendor/autoload.php');

$client = SimpleClientFactory::createClient('https://capi.tk-kit.com', 'token');

try {
    $response = $client->geography->getListAddress(new GetListAddressRequest("699", true, true));
} catch (ApiExceptionInterface|ClientExceptionInterface $exception) {
    echo $exception;
    exit(-1);
}

foreach ($response->addreses as $address) {
    printf("ID адреса - %d. Адрес терминала - %s. ", $address->id, $address->value);
    if ($address->phone) {
        echo PHP_EOL;
        /** @var Phone $value */
        foreach ($address->phone as $value) {
            printf("Номер телефона - %s", $value->value);
            echo PHP_EOL;
        }
        echo PHP_EOL;
    }
}

Расчет стоимости доставки груза:

<?php

namespace Test;

use service\KitAPI\Factory\SimpleClientFactory;
use service\KitAPI\Interfaces\ApiExceptionInterface;
use service\KitAPI\Interfaces\ClientExceptionInterface;
use service\KitAPI\Model\Entity\Order\Place;
use service\KitAPI\Model\Request\Order\CalculateRequest;

require_once(__DIR__ . '/../vendor/autoload.php');

$client = SimpleClientFactory::createClient('https://capi.tk-kit.com', 'token');

$request = new CalculateRequest();
$request->city_pickup_code = '770000000000';
$request->city_delivery_code = '390000100000';
$request->declared_price = '10000';
$request->confirmation_price = 1;

$request->places = [];

$place = new Place();
$place->height = 100;
$place->width = 60;
$place->length = 80;
$place->weight = 50;
$place->volume = round(1*0.6*0.8, 3);
$place->count_place = 1;
$place->service = ['S089'];

$request->places[] = $place;
$request->delivery = 1;
$request->pick_up = 0;
$request->insurance = 1;
$request->insurance_agent_code = '8000152423';
$request->have_doc = 1;
$request->cargo_type_code = '03';
$request->currency_code = ['RUB'];
$request->all_places_same = 1;

try {
    $response = $client->order->calculate($request);
} catch (ApiExceptionInterface|ClientExceptionInterface $exception) {
    echo $exception;
    exit(-1);
}

$result = $response->getResult();

printf("Тип доставки груза: %s", $result->standart->name);
echo PHP_EOL;
printf("Время доставки груза: %s", $result->standart->time);
echo PHP_EOL;
printf("Общая стоимость доставки груза: %s", $result->standart->cost);
echo PHP_EOL;
echo 'Детальная информация по стоимости доставки:';
echo PHP_EOL;
foreach ($result->standart->detail as $value) {
    printf("- услуга '%s', стоимостью %s рублей", $value->name, $value->price);
    echo PHP_EOL;
}

Обработка ошибок в приведенных выше примерах хороша для реального использования в проектах. Вы можете с уверенностью сказать, ApiExceptionInterface - это ошибка API, а ClientExceptionInterface - ошибка клиента. (например, сетевая ошибка или любая ошибка времени выполнения, используйте HttpClientException, чтобы перехватывать только ошибки клиента PSR-18). При желании вы можете реализовать свою обработку ошибок.

Так же, ApiExceptionInterface и ClientExceptionInterface реализуют магический метод __toString(). Это означает, что вы можете просто преобразовать эти исключения в строку и поместить их в журнал логов без какой-либо обработки.

kitdelivery / sdk-kit-api

Maintainers

Details