kattatzu/ship-it

用于使用 ShipIt API 的库

维护者

详细信息

github.com/kattatzu/ShipIt

源代码

问题

安装: 769

依赖: 0

建议者: 0

安全: 0

星星: 4

关注者: 5

分支: 6

1.2 2019-02-04 12:26 UTC

Requires

MIT ab8d2927dda4119079caf2d2e75b9db6ba79fa4a

  • Jose Eduardo Rios <kattatzu.woop@gmail.com>

laravelilluminateshipit

This package is auto-updated.

Last update: 2024-09-05 01:13:07 UTC

README

允许通过 ShipIt API（https://developers.shipit.cl/docs）发送配送请求、查询状态和其他操作，以实现与 ShipIt API 的集成。

获取访问凭证

要使用 ShipIt API，您需要一个账户并访问“API”菜单以复制您的电子邮件和访问令牌。

https://clientes.shipit.cl/settings/api

安装

要安装此库，请在控制台执行以下命令

composer require kattatzu/ship-it

在 Laravel 中安装和使用

独立使用

如果您系统不使用 Laravel，可以直接使用它

use Kattatzu/ShipIt/ShipIt;

$shipIt = new ShipIt('EMAIL', 'TOKEN', 'development');
// o
$shipIt = new ShipIt;
$shipIt->email('EMAIL');
$shipIt->token('TOKEN');
$shipIt->environment(ShipIt::ENV_PRODUCTION);

var_export($shipIt->getCommunes());
array:425 [▼
  0 => Commune {#208 ▼
    -data: array:10 [▼
      "id" => 1
      "region_id" => 1
      "name" => "ARICA"
      "code" => "15101"
      "is_starken" => null
      "is_chilexpress" => null
      "is_generic" => true
      "is_reachable" => true
      "couriers_availables" => {#211}
      "is_available" => false
    ]
  },
  ...
]

可用操作

获取地区和市镇

您可以使用该方法列出 ShipIt 已注册的地区和市镇以同步您的系统。

$shipIt->getRegions();
$shipIt->getCommunes()

示例

$regions = $shipIt->getRegions();
echo $regions[0]->name;
// "Arica y Parinacota"

获取报价

您可以发送您的配送数据并获得 ShipIt 提供的承运商选项的报价。

为此，您需要创建一个 QuotationRequest 实例并将其发送到 getQuotation 方法。

示例

$request = new QuotationRequest([
    'commune_id' => 317,    // id de la Comuna en ShipIt
    'height' => 10,         // altura en centimetros
    'length' => 10,         // largo en centimetros
    'width' => 10,          // ancho en centimetros
    'weight' => 1          // peso en kilogramos
]);
$quotationItems = $shipIt->getQuotation($request)->getItems();

foreach($quotationItems as $item){
    echo $item->courier . "<br>";
}

如果您更喜欢将项目作为数组处理，可以使用 toArray() 方法

$request = new QuotationRequest(...);

$quotationItems = $shipIt->getQuotation($request)->toArray();

foreach($quotationItems as $item){
    echo $item['total'] . "<br>";
}

获取最经济的报价

您可以发送您的配送数据并获得最经济的报价。

示例

$request = new QuotationRequest([
    'commune_id' => 317,    // id de la Comuna en ShipIt
    'height' => 10,         // altura en centimetros
    'length' => 10,         // largo en centimetros
    'width' => 10,          // ancho en centimetros
    'weight' => 1          // peso en kilogramos
]);

$quotationItem = $shipIt->getEconomicQuotation($request);
echo $quotationItem->total;

// o como array

$quotationItem = $shipIt->getEconomicQuotation($request)->toArray();
echo $quotationItem['total'];

获取最合适的报价

您可以获取在响应时间（SLA）和价格方面最合适的报价。

示例

$request = new QuotationRequest([
    'commune_id' => 317,    // id de la Comuna en ShipIt
    'height' => 10,         // altura en centimetros
    'length' => 10,         // largo en centimetros
    'width' => 10,          // ancho en centimetros
    'weight' => 1          // peso en kilogramos
]);

$quotationItem = $shipIt->getBestQuotation($request);
echo $quotationItem->total;

// o como array

$quotationItem = $shipIt->getBestQuotation($request)->toArray();
echo $quotationItem['total'];

发送配送请求

要发送配送请求，您需要创建一个 ShippingRequest 实例并将其发送到 requestShipping 方法。

$request = new ShippingRequest([
    'reference' => 'S000001',
    'full_name' => 'José Eduardo Rios',
    'email' => 'cliente@gmail.com',
    'items_count' => 1,
    'cellphone' => '912341234',
    'is_payable' => false,
    'packing' => ShippingRequest::PACKING_NONE,
    'shipping_type' => ShippingRequest::DELIVERY_NORMAL,
    'destiny' => ShippingRequest::DESTINATION_HOME,
    'courier_for_client' => ShippingRequest::COURIER_CHILEXPRESS,
    'approx_size' => ShippingRequest::SIZE_SMALL,
    'address_commune_id' => 317,
    'address_street' => 'San Carlos',
    'address_number' => 123,
    'address_complement' => null,
]);

$response =  $shipIt->requestShipping($request);
echo $response->id; // id de la solicitud en ShipIt

您可以使用 toArray() 方法将其作为数组处理

$request = new ShippingRequest(...);

$response =  $shipIt->requestShipping($request)->toArray();
echo $response['id'];

列出配送请求

您可以使用 getAllShippings 方法查询按天完成的请求的历史记录。

$history = $shipIt->getAllShippings('2017-04-06');

// ó

$history = $shipIt->getAllShippings(Carbon::yesterday());

// ó

$history = $shipIt->getAllShippings(); // Por defecto será la fecha actual

foreach($history->getShippings() as $shipping){
    echo $shipping->id . "<br>";
}

您可以使用 toArray() 方法将结果作为数组处理

$history = $shipIt->getAllShippings();

foreach($history->toArray() as $shipping){
    echo $shipping['id'] . "<br>";
}

获取配送详情

您可以通过发送 ShipIt 提供的 id 并使用 getShipping 方法来查询历史配送数据。

$shipping = $shipIt->getShipping(136107);
echo $shipping->reference;

// o como array

$shipping = $shipIt->getShipping(136107)->toArray();
echo $shipping['reference'];

实用工具

获取跟踪链接

可以轻松生成配送跟踪链接

$url = $shipIt->getTrackingUrl('chilexpress', 72626262);

// o

$url = ShipIt::getShipping(136097)->getTrackingUrl()

估算包裹尺寸

您可以获取 ShipIt 使用的格式中包裹的大致尺寸。

$size = $shipIt->getPackageSize($width = 14, $height = 23, $length = 45);

Resultado: Grande (50x50x50cm)

在 Laravel 中安装和使用

使用 Composer 安装后，您需要在 config/app.php 文件中注册 ServiceProvider 和别名

'providers' => [
    ...
    Kattatzu\ShipIt\Providers\ShipItServiceProvider::class,
],
'aliases' => [
    ...
    'ShipIt' => Kattatzu\ShipIt\Facades\ShipItFacade::class,
]

通过 Artisan 执行以发布配置文件

php artisan vendor:publish --provider="Kattatzu\ShipIt\Providers\ShipItServiceProvider"

现在您可以在 config/shipit.php 文件或 .env 文件中使用 keys 添加凭证

SHIPIT_ENV=development o production
SHIPIT_EMAIL=xxxxxxxx
SHIPIT_TOKEN=xxxxxxxx
SHIPIT_CALLBACK_URL=callback/shipit

门面

您现在可以使用门面快速访问功能

$shipping = ShipIt::getShipping(136107);
$regions = ShipIt::getRegions();
$communes = ShipIt::getCommunes()
$url = ShipIt::getTrackingUrl('chilexpress', 72626262);
$size = ShipIt::getPackageSize(14, 23, 45);

助手

您也可以使用助手

$regions = shipit_regions();
$communes = shipit_communes();
$shippings = shipit_shippings('2017-06-01');
$shipping = shipit_shipping(12322);
$quotationItems = shipit_quotation($request);
$quotationItem = shipit_best_quotation($request);
$quotationItem = shipit_economic_quotation($request);
$response = shipit_send_shipping($request);
$url = shipit_tracking_url('starken', 23312332);
$size = shipit_package_size(14, 23, 45);

回调

ShipIt 发送两个回调，一个用于通知我们一个请求已被注册，另一个用于指示已分配跟踪代码或状态更改。

该库允许监听两个事件以接收这些回调并执行相应的操作。

事件是

  • Kattatzu\ShipIt\Events\ShipItCallbackPostEvent：指示一个请求已被注册
  • Kattatzu\ShipIt\Events\ShipItCallbackPutEvent：指示一个请求已被更新

安装

我们首先需要创建将监听这些事件的 EventListeners 并在 EventServiceProvider（app/Providers/EventServiceProvider.php） 中注册它们。

protected $listen = [
    'Kattatzu\ShipIt\Events\ShipItCallbackPostEvent' => [
        'App\Listeners\ShipItCallbackPostListener',
    ],
    'Kattatzu\ShipIt\Events\ShipItCallbackPutEvent' => [
        'App\Listeners\ShipItCallbackPutListener',
    ],
];

一旦定义了事件监听器，您可以将ShipIt的Webhook（http://clientes.shipit.cl/settings/api）指向url

https://tudominio.cl/callback/shipit

您可以在配置文件shipit.php或.env文件中使用key SHIPIT_CALLBACK_URL来自定义此端点。

请随时向我发送反馈或pull-request来改进这个库。

许可协议

MIT许可协议

版权所有 (c) 2017 José Eduardo Ríos

在此特此授予任何获得本软件及其相关文档副本（“软件”）的个人，在不收取任何费用的情况下，在不受限制的情况下处理软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向软件提供者提供软件的个人这样做，前提是符合以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任承担责任，无论这些责任是基于合同、侵权或其他方式，无论这些责任是否因软件或软件的使用或其他方式而产生。