README

特性

• 货运
  • 创建货运
  • 列出货运
  • 获取货运
  • 删除货运
• 评分
  • 列出评分
• 承运人
  • 注册承运人
  • 列出承运人
  • 更新承运人
  • 删除承运人
• 跟踪
• 地址
  • 注册地址
  • 列出地址
• 仓库
  • 注册仓库
  • 列出仓库
• 子用户
  • 注册子用户
  • 列出子用户
  • 获取子用户
  • 刷新子用户
  • 删除子用户

这个库远未提供完整的API方法集，但它应该包含最重要的部分。

有什么问题吗？ 告诉我们，或者，更好的是，发送一个PR！

Ship&co API 文档供您参考。请注意，这绝对不是Ship&co的官方SDK，因此他们很可能无法回答有关此SDK的任何问题。

安装

composer require sanmai/shipandco-sdk

此SDK需要至少PHP 7.3。它已在PHP 7.3、7.4和8.0下进行测试，以验证其工作。

概述

主要部分包括

• 客户端。客户端是您发送所有请求的对象。
• 请求。对于API提供的多数请求，有几个请求对象。它们遵循流畅的接口范式，即如果原始请求具有某个属性，则这里的请求也将具有该属性。更多内容见下文。
• 响应。发送请求后，您将获得一个响应对象，它可能是实际响应或错误响应。所有响应都遵循相同的流畅范式。

使用方法

首先，您需要按照文档中的说明获取一个访问令牌。

然后，使用便捷的构建器实例化客户端

$builder = new \ShipAndCoSDK\ClientBuilder();
$builder->setToken($token);

$client = $builder->build();

构建器还有更多便捷方法来设置超时和启用缓存。请查阅源代码。

错误处理

错误处理建立在错误响应之上。几乎从不抛出异常。如果发生异常，这必须是一个真正异常的情况，甚至可能是错误。

$request = new \ShipAndCoSDK\Requests\RatesRequest();

// This requests requires several properties to be set, therefore we'll have an error here.
$response = $client->sendRatesRequest($request);

if (\count($response) > 0) {
    // Will not be printed because count() is zero here.
    echo 'Rates received: ', \count($response), "\n";
}

if ($response->hasErrors()) {
    // Check for exact errors
    foreach ($response->getMessages() as $message) {
        if ($message->getErrorCode() !== '') {
            // That's the error:
            echo "{$message->getErrorCode()}: {$message->getMessage()}\n";
        }
    }

    /** @var \ShipAndCoSDK\Responses\Bad\ErrorResponse $response */
    
    // To get more specific error details use response-specific fields. E.g.:
    foreach ($response->details as $detail) {
        echo "Error code: {$detail->code}\n\tMessage: {$detail->message}\n\tField: {$detail->field}\n";
    }
}

请求

对于每个实现的请求，都有一个可运行的示例。例如，运行此

export SHIPANDCO_ACCESS_TOKEN=... (your token)
php examples/030_CarriersRequest.php

...将输出您的注册承运人。

示例默认启用调试输出，以便您可以自由实验。

显然，要运行示例，您需要签出库

git clone https://github.com/sanmai/shipandco-sdk.git
cd shipandco-sdk
composer install

列出承运人

$request = new \ShipAndCoSDK\Requests\CarriersRequest();

$response = $client->sendCarriersRequest($request);

\var_dump(\count($response)); // Should print the number of configured carriers

foreach ($response as $value) {
    echo "{$value->id}\t{$value->type}\t{$value->state}\t{$value->created_at->format('Y-m-d')}\n";
    
    foreach ($value->credentials as $key => $value) {
        echo "\t$key =\t$value\n";
    }
}

列出地址

$request = new \ShipAndCoSDK\Requests\AddressesRequest();

$response = $client->sendAddressesRequest($request);

\var_dump(\count($response)); // Should print the number of addresses returned

foreach ($response as $value) {
    echo "{$value->id}\t{$value->created_at->format('Y-m-d')}\n";
    
    foreach ($value->address as $key => $value) {
        echo "\t$key =\t$value\n";
    }
}

列出仓库

$request = new \ShipAndCoSDK\Requests\WarehousesRequest();

$response = $client->sendWarehousesRequest($request);

\var_dump(\count($response)); // Should print the number of warehouses returned

foreach ($response as $value) {
    echo "{$value->id}\t{$value->created_at->format('Y-m-d')}\t{$value->company}\n";
    
    foreach ($value->address as $key => $value) {
        echo "\t$key =\t$value\n";
    }
}

列出评分

$request = new \ShipAndCoSDK\Requests\RatesRequest();

$request->from_address->country = 'JP';
$request->from_address->full_name = 'Yamada Taro';
$request->from_address->company = 'World Company';
$request->from_address->email = 'ytaro@example.com';
$request->from_address->phone = '08012341234';
$request->from_address->country = 'JP';
$request->from_address->address1 = 'OSAKAFU';
$request->from_address->address2 = 'OTECHO';
$request->from_address->province = 'OSAKA';
$request->from_address->zip = '5670883';
$request->from_address->city = 'IBARAKI SHI';

$request->to_address->full_name = 'John Doe';
$request->to_address->company = 'ACME';
$request->to_address->email = 'john@example.net';
$request->to_address->phone = '0901231234';
$request->to_address->country = 'PT';
$request->to_address->address1 = 'Rua Maria Matos, 32';
$request->to_address->address2 = '';
$request->to_address->province = 'SETUBAL';
$request->to_address->zip = '2820-344';
$request->to_address->city = 'CHARNECA DA CAPARICA';

$product = $request->addProduct();
$product->quantity = 1;
$product->name = 'Example';
$product->price = 1000;

$parcel = $request->addParcel();
$parcel->weight = 200;
$parcel->width = 10;
$parcel->height = 10;
$parcel->depth = 10;

$request->customs->duty_paid = false;
$request->customs->content_type = 'MERCHANDISE';

$request->setup->date = new DateTime('+1 week');

$response = $client->sendRatesRequest($request);

\var_dump(\count($response));

foreach ($response as $rate) {
    echo "{$rate->carrier}\t{$rate->service}\t{$rate->price} {$rate->currency}\n";

    foreach ($rate->surcharges as $surcharge) {
        echo "\t{$surcharge->type}\t{$surcharge->price}\n";
    }
}

创建货运

就货运而言，重要的是要理解，针对日本国内货运（Sagawa、Yamato、YuPack）的请求与国际货运略有不同

• 对于国内货运，地址（目的地和出发地）应为日文。反之亦然。
• 国内货运不需要城市字段（城市信息包含在address_1中）。
• 对于国际货运，产品细节用于清关目的，而不需要产品的大部分细节。
• 对于国内运输，如果不是货到付款的运输，只需产品名称即可（仅用于在标签上显示盒内物品）。

此SDK对请求中指定的字段数量没有限制（除了它们必须存在之外），因此设置每种请求的正确字段是您的责任。

$request = new \ShipAndCoSDK\Requests\CreateShipmentRequest();

$request->to_address->country = 'JP';
$request->to_address->full_name = 'TEST TARO';
$request->to_address->phone = '1111111111';
$request->to_address->country = 'JP';
$request->to_address->address1 = '京都市中京区八百屋町117';
$request->to_address->zip = '604-8072';
$request->to_address->city = '京都府';

$request->from_address->full_name = 'テスト';
$request->from_address->phone = '08012341234';
$request->from_address->country = 'JP';
$request->from_address->address1 = 'OSAKAFU';
$request->from_address->province = 'OSAKA';
$request->from_address->zip = '1234567';
$request->from_address->city = 'IBARAKI SHI';

$product = $request->addProduct();
$product->name = 'Blue Basketball';
$product->quantity = 2;
$product->price = 4850;
$product->origin_country = 'JP';

$product = $request->addProduct();
$product->name = 'Orange Basketball';
$product->quantity = 1;
$product->price = 7850;
$product->origin_country = 'JP';

$parcel = $request->addParcel();
$parcel->amount = 1; // That's the default.
$parcel->weight = 2000;
$parcel->width = 10;
$parcel->height = 10;
$parcel->depth = 10;
// $parcel->package = 'fedex_envelope';

$request->customs->duty_paid = false;
$request->customs->content_type = 'MERCHANDISE';

$request->setup->carrier = 'sagawa';
$request->setup->service = 'sagawa_regular';
$request->setup->currency = 'JPY';
$request->setup->shipment_date = new DateTime('+1 day');
$request->setup->date = new DateTime('+2 day');
$request->setup->time = '16-18';
$request->setup->insurance = 0;
$request->setup->ref_number = '';
$request->setup->delivery_note = '';
$request->setup->signature = false;
$request->setup->care->fragile = false;
$request->setup->care->side_up = false;
$request->setup->care->valuable_goods = false;
$request->setup->pack_size = '0';
$request->setup->pack_amount = 3;
$request->setup->cash_on_delivery->amount = 1000;
$request->setup->cash_on_delivery->tax = 100;
$request->setup->return_label = false;
$request->setup->print_start_location = 1;
$request->setup->test = true;

$response = $client->sendCreateShipmentRequest($request);

if ($response->hasErrors()) {
    // Check for exact errors
    foreach ($response->getMessages() as $message) {
        if ($message->getErrorCode() !== '') {
            // That's the error
            echo "{$message->getErrorCode()}: {$message->getMessage()}\n";
        }
    }

    return; // This is a failure.
}

/** @var $response \ShipAndCoSDK\Responses\ShipmentResponse */
echo "{$response->id}\t{$response->state}\n";

echo "Shipping Label: {$response->delivery->label}\n";

foreach ($response->delivery->tracking_numbers as $trackingNumber) {
    echo "Tracking Number: {$trackingNumber}\n";
}

为防止您出现意外的账单费用，运输请求默认使用测试环境（因此创建虚拟标签）。请确保在setup部分将test设置为false以接收实时标签。

就像这样

$request->setup->test = false;

许可证

本项目遵循MIT许可证条款授权。