README

一个PHP库，用于向Easyship API发起PHP调用。此库封装了一些重复的/丑陋的工作，如创建HTTP客户端、构建和发送请求。最终用户只需要组装适当的负载数据数组，然后评估响应。

此软件包包含两组不同的功能。第一组是API通信组件，允许用户轻松编写代码以向Easyship API发送出站API调用。第二组是接收Easyship的入站webhook posts的功能，允许用户轻松将这些调用传递给分发处理器，并将负载传递给处理器附加的定制代码。Webhooks是Easyship API的可选功能，如果它不是您的实现计划的一部分，您完全可以忽略它们。

API版本

在v1.4之前，此库仅支持Easyship API v1。由于长时间不完整且标记为不稳定，因此从未支持过v2。自v1.4版本的此库以来，v2023-01是唯一支持版本。如果您需要出于某种原因使用旧调用，则可以安装早期版本。

安装
使用方法
配置
Webhooks
路线图
支持
许可证

安装

除非使用Laravel，否则使用composer正常安装

composer require jrebs/easyship-php

如果在一个Laravel应用程序中使用此库，那么您可能会发现安装配套包easyship-laravel（该包也需要此包作为依赖项）更方便。

在这种情况下，请运行以下命令：

composer require jrebs/easyship-laravel

请参阅easyship-laravel页面以获取此方法的具体文档。

使用方法

// Create the EasyshipAPI object
$token = getenv('EASYSHIP_TOKEN');
$api = new Easyship\EasyshipAPI($token);

// Get a list of categories
$response = $api->categories()->list();

// Get a shipment
$response = $api->shipments()->get('ESTEST10001');

// Buy a label for a shipment
$response = $api->labels()->request(['easyship_shipment_id' => 'ESTEST10001']);

所有方法都返回实现Psr\Http\Message\ResponseInterface的对象实例，通常是GuzzleHttp\Psr7\Response，可根据需要进行使用请参阅Guzzle文档以获取更多信息。

默认情况下，所有调用都使用请求选项'http_errors' => true进行，这意味着如果任何请求失败，将抛出异常。可以在EasyshipAPI::request()方法的docblock中查看可以抛出的异常。此库允许所有异常向上冒泡到应用程序，以便开发者在实现中决定如何处理它们。如果您更喜欢，可以在传递给EasyshipAPI构造函数的选项数组中覆盖此选项。

/**
 * @throws \GuzzleHttp\Exception\ConnectException on network error
 * @throws \GuzzleHttp\Exception\ClientException on 400-level errors
 * @throws \GuzzleHttp\Exception\ServerException on 500-level errors
 */

当然，如果您使用的是其他PSR7兼容的客户端，那么您可能会基于\RuntimeException得到一些异常。使用其他客户端尚未完全测试，但从理论上讲应该可以工作。

配置

通常您只需要配置一个API密钥，您可以从easyship账户界面获得。如果您还没有创建一个，请转到https://app.easyship.com/connect并查找列表底部的API Integration。

为您创建的每个集成，将创建两个访问令牌，一个以prod_开头，另一个以sand_开头。后者是您的沙箱密钥，您应该使用它来测试和开发集成。它使用相同的实时端点，但工作在单独的仅测试数据集上。

EasyshipAPI上的apiToken是可选的，因为单个客户可能经常使用不同的令牌进行API调用。

向HTTP客户端提供请求选项

EasyshipAPI构造函数接受一个请求选项数组，这些选项将被合并到传递给HTTP客户端的选项中，以便向API端点发送请求。有关可能性，请参阅guzzle请求选项文档。

// Pass custom options that will be used by the client
$api = new Easyship\EasyshipAPI($token, [
    'verify' => false, // don't verify ssl certificate
    'connect_timeout' => 30, // wait maximum 30 seconds before giving up
]);

覆盖API主机

对于测试/开发，您可能想覆盖目标主机，以便您提交的调用将被发送到您自己的服务器进行审查。

// Force all the calls from this API object to a localhost server
$api->setApiHost('https://:8080/');

Webhooks

请参阅WEBHOOKS.md。

路线图

更完整/有用的测试。

支持

如果您从API调用中获得了意外的结果，最可能的情况是您的有效负载无效，您应该查阅Easyship参考文档。请注意，您可以将值插入该页面上的表单中，包括您的沙箱令牌，并从界面运行测试。如果您发现存在一个问题，即相同的调用在Easyship的测试页面上工作但在此库中失败，请提出一个详细说明问题的issue，并包括正在运行的精确代码副本（至少是测试数据的有效负载），以便可以轻松重现问题。请还包括您收到的错误响应的副本。

许可证

此软件由我，Justin Rebelo编写，并发布在MIT许可证下。

jrebs / easyship-php

维护者

详细信息