README

这是PHP KIT API客户端。这个库允许使用最新版本的API。您可以在文档中找到更多信息。

要求

• PHP 7.4及以上
• 支持PHP CURL
• 支持PHP JSON
• 任何兼容PSR-18的HTTP客户端（请参阅安装说明）。
• 任何兼容PSR-17的HTTP工厂实现（请参阅安装说明）。
• 任何兼容PSR-7的HTTP消息实现（请参阅安装说明）。
• 在composer.json中列出的其他依赖项（请参阅安装说明）

安装

执行以下步骤以安装库

1. 下载并安装Composer包管理器。
2. 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错误。

资源组和方法列表

• 订单（order）
  • 计算成本（calculate）
  • 计算包裹成本（calculatePost）
  • 创建订单（create）
  • 创建包裹订单（createPost）
  • 订单列表（getListOrder）
  • 配送时间（getTimeDelivery）
  • 订单状态（getStatus）
  • 订单信息（getOrder）
  • 订单货物照片（getPhoto）
  • 订单货物文档（getDocument）
  • 货币列表（getListCurrency）
  • 服务列表（getListService）
• 运输路线（tdd）
  • 城市列表（getListCity）
  • 国家列表（getListCountry）
  • 区域列表（getListRegion）
  • 按名称搜索城市（searchByName）
  • 搜索КЛАДР编号或搜索城市编号（searchCodeCity）
• 地理（geography）
  • 地址列表（getListAddress）
  • 城市列表（getListCity）
  • 电子邮件列表（getListEmail）
  • 电话号码列表（getListPhone）
  • 工作时间列表（getListSchedule）
  • 工作时间类型列表（getListScheduleGroup）
• 配置文件（profile）
  • 注册配置文件（add）
  • 确认配置文件注册（confirm）
  • 配置文件列表（getList）

示例

获取所有国家的列表

<?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;
}

输出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()魔术方法。这意味着您可以简单地转换这些异常为字符串，并将其放入日志记录中而无需任何处理。