README

Laravel包，用于与Xero API交互

观看视频教程 https://www.youtube.com/watch?v=sORX2z-AH1k

Xero API文档可在以下位置找到：https://developer.xero.com/documentation/

在您能够与Xero集成之前，您需要创建一个应用，请访问 https://developer.xero.com/myapps 以注册一个新应用。

对于授权类型选择，选择“授权码（网络应用）”

对于OAuth 2.0重定向URI，输入您想要从应用程序连接到Xero的完整URL，例如 https://domain.com/xero/connect

安装

您可以通过composer安装此包

composer require Kurtnoone/laravel-xero

配置

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Kurtnoone\Xero\XeroServiceProvider" --tag="config"

迁移

您可以使用以下命令发布迁移

php artisan vendor:publish --provider="Kurtnoone\Xero\XeroServiceProvider" --tag="migrations"

迁移发布后，您可以运行迁移来创建tokens表

php artisan migrate

.ENV配置确保您已在您的.env文件中设置了以下内容

XERO_CLIENT_ID=
XERO_CLIENT_SECRET=
XERO_REDIRECT_URL=https://domain.com/xero/connect
XERO_LANDING_URL=https://domain.com/xero
XERO_WEBHOOK_KEY=

中间件

为了仅允许认证用户访问路由，有一个名为XeroAuthenticated的中间件路由

将XeroAuthenticated添加到路由中以确保用户已认证

Route::group(['middleware' => ['web', 'XeroAuthenticated'], function()

要访问令牌模型，请引用此ORM模型

use Kurtnoone\Xero\Models\XeroToken;

多租户

要设置租户，请调用setTenantId并传递您的tenant_id

设置后，所有调用都将使用设置的租户。

setTenantId($tenant_id)

命令

刷新令牌

当使用Xero作为后台进程时，需要刷新令牌，可以使用以下命令自动化此过程

php artisan xero:keep-alive

这将在令牌到期时刷新令牌。建议将其添加到计划任务中，例如在App\Console\Kernal.php中添加到计划任务。

protected function schedule(Schedule $schedule)
{
    $schedule->command('xero:keep-alive')->everyFiveMinutes();
}

用法

路由示例

Route::group(['middleware' => ['web', 'auth']], function(){
    Route::get('xero', function(){

        if (! Xero::isConnected()) {
            return redirect('xero/connect');
        } else {
            //display your tenant name
            return Xero::getTenantName();
        }

    });

    Route::get('xero/connect', function(){
        return Xero::connect();
    });
});

或者使用中间件路由，如果用户没有令牌，则自动重定向到认证页面

Route::group(['middleware' => ['web', 'XeroAuthenticated']], function(){
    Route::get('xero', function(){
        return Xero::getTenantName();
    });
});

Route::get('xero/connect', function(){
    return Xero::connect();
});

认证后，您可以使用以下动词调用Xero::

Xero::get($endpoint, $array = [])
Xero::post($endpoint, $array = [])
Xero::put($endpoint, $array = [])
Xero::patch($endpoint, $array = [])
Xero::delete($endpoint, $array = [])

数组第二个参数不一定需要，其需求取决于被调用的端点，请参阅API文档以获取更多详细信息。

这需要传递API端点，提供的URL为https://api.xero.com/api.xro/2.0/，仅应使用此URL之后的端点，例如

Xero::get('contacts')

已连接

任何时候需要检查Xero是否已认证，都可以调用一个 ->isConnected 方法。该方法返回一个布尔值。

要执行Xero未连接时的操作，可以这样做

if (! Xero::isConnected()) {
    return redirect('xero/connect');
}

断开连接

要断开与Xero的连接，请调用 ->disconnect() 方法。

断开连接将向Xero发送POST请求以撤销连接，此外，将删除存储的令牌。

Xero::disconnect();

通常仅在存在连接时才运行此操作，因此将其包裹在 ->isConnected() 检查中是有意义的

if (Xero::isConnected()) {
    Xero::disconnect();
}

联系人

Xero提供了一个干净的方式来处理Xero联系人。

要处理联系人，首先调用 ->contacts()，然后调用一个方法。

Xero::contacts()

列出联系人

要列出联系人，请调用contacts()->get()方法。

Xero关于列出联系人的文档 - https://developer.xero.com/documentation/api/contacts#GET

可选参数是 $page 和 $where。$page 默认为 1，表示返回第一页。对于其他页码，请输入更高的页码，直到没有可返回的页码为止。API 不提供用于确定页数的计数。

Xero::contacts()->get(int $page = 1, string $where = null)

$where 允许传递过滤选项，最常见的过滤选项已经优化，以确保不同规模的组织都能保持性能。我们建议您将过滤限制以下优化参数。

按名称过滤

Xero::contacts()->get(1, 'Name="ABC limited"')

按电子邮件过滤

Xero::contacts()->get(1, 'EmailAddress="email@example.com"')

按账号号过滤

Xero::contacts()->get(1, 'AccountNumber="ABC-100"')

查看联系人

要查看单个联系人，可以通过传递联系人 ID 调用查找方法。

Xero::contacts()->find(string $contactId)

创建联系人

要创建联系人，请调用存储方法并传递联系人数据数组。

有关数组内容规范的详细信息，请参阅 https://developer.xero.com/documentation/api/contacts#POST。

Xero::contacts()->store($data)

更新联系人

要更新联系人，需要两个参数：联系人 ID 和要更新的数据数组。

有关可以更新的字段的详细信息，请参阅 https://developer.xero.com/documentation/api/contacts#POST。

Xero::contacts()->update($contactId, $data);

发票

Xero 提供了一种简洁的方法来处理 Xero 发票。

要处理发票，首先调用 ->invocies() 方法，然后调用另一个方法。

Xero::invoices()

列出发票

要列出发票，请调用 invoices()->get() 方法。

有关列出发票的 Xero 文档 - https://developer.xero.com/documentation/api/invoices#get

Xero::invoices()->get(int $page = 1, string $where = null)

$where 允许传递过滤选项，最常见的过滤选项已经优化，以确保不同规模的组织都能保持性能。我们建议您将过滤限制以下优化参数。

按状态过滤

Xero::invoices()->get(1, 'Status="AUTHORISED"')

按联系人 ID 过滤

Xero::invoices()->get(1, 'Contact.ContactID=guid("96988e67-ecf9-466d-bfbf-0afa1725a649")')

按联系人编号过滤

Xero::invoices()->get(1, 'Contact.ContactNumber="ID001"')

按参考号过滤

Xero::invoices()->get(1, 'Reference="INV-0001"')

按日期过滤

Xero::invoices()->get(1, 'Date=DateTime(2020, 01, 01)')

按类型过滤

Xero::invoices()->get(1, 'Type="ACCREC"')

查看发票

要查看单个发票，可以通过传递发票 ID 调用查找方法。

Xero::invoices()->find(string $invoiceId)

在线发票

对于状态为已提交、已授权或已付款的发票，可以通过调用 onlineUrl 并传递 invoiceId 来查看在线发票。

Xero::invoices()->onlineUrl($invoiceId)

创建发票

要创建发票，请调用存储方法并传递发票数据数组。

有关数组内容规范的详细信息，请参阅 https://developer.xero.com/documentation/api/invoices#post。

Xero::invoices()->store($data)

更新发票

要更新发票，需要两个参数：发票 ID 和要更新的数据数组。

有关可以更新的字段的详细信息，请参阅 https://developer.xero.com/documentation/api/invoices#post。

Xero::invoices()->update($invoiceId, $data);

PDF 资源

一些 Xero 资源支持下载为 PDF。为此，您可以

$pdfInvoice = Xero::get("invoices/{$invoiceId}", null, true, 'application/pdf');
$pdfInvoice['body']; // will be the pdf as a pdf string for you to write out to storage etc.

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

欢迎贡献，并将得到充分认可。

通过 Github 上的拉取请求接受贡献。

拉取请求

记录任何行为变更 - 确保更新 readme.md 和任何其他相关文档。
考虑我们的发布周期 - 我们尽量遵循 SemVer v2.0.0。随机破坏公共 API 不是可选项。
每个功能一个拉取请求 - 如果您要完成多项操作，请发送多个拉取请求。

安全

如果您发现任何安全相关的问题，请通过电子邮件 dave@dcblog.dev 而不是使用问题跟踪器。

许可

许可。请参阅许可文件获取更多信息。

kurtnoone / laravel-xero

维护者

详情