README

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

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

API版本

目前，仅支持API版本v1，因为v2 API仍在测试版，并且尚未完成。一旦v2准备好用于生产使用，我将扩展此库以支持该版本。

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

安装

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

composer require fhferreira/easyship-php

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

在这种情况下，请运行

composer require fhferreira/easyship-laravel

查看[easyship-laravel](https://github.com/

有关此方法的特定文档。

使用

// 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()->buy(['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构造函数接受一个请求选项数组，该数组将合并到发送到API端点的HTTP客户端传递的选项中。有关可能性的说明，请参阅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 v2。

支持

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

许可证

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

#FORK仅为了将Guzzle减少到^6.3