README

通过 InvoiceXpress 的 API 集成您的 Laravel 应用程序

概念

此包可以在 2 个不同的层面上使用

• 通过提供的模型。
• 直接与 API 端点交互。

使用前者可以在您的应用程序数据库和 InvoiceXpress 中透明地创建、更新和删除实体。

安装

您可以通过 composer 安装此包

composer require square-bit/invoicexpress-for-laravel

可选，您可以发布并运行迁移

php artisan vendor:publish --tag="invoicexpress-for-laravel-migrations"
php artisan migrate

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

php artisan vendor:publish --tag="invoicexpress-for-laravel-config"

这是已发布的配置文件的内容

return [
    'account' => [
        'name' => env('IX_ACCOUNT_NAME'),
        'api_key' => env('IX_API_KEY'),
    ],
    'service_endpoint' => 'app.invoicexpress.com',
    'eloquent' => [
        'persist' => false,
    ],
];

IX_ACCOUNT_NAME 是您的 InvoiceXpress 账户名称（https://XXX.app.invoicexpress.com 中的 XXX）。

IX_API_KEY 是您可以从 InvoiceXpress 账户设置页面获取的 API 密钥。

persist 定义了在 "模型" 层上使用时是否将实体存储在您的数据库中。默认为 false。如果将其设置为 true，请确保您已运行迁移。

使用方法

选项 1 - 通过模型层

此方法处理实体的本地和远程更改。

但是，默认情况下它不是启用的。要启用它

• 发布并运行迁移（参见 安装）
• 在配置文件中将 persist => true 设置为 安装

您可以获取一个特定的项目并更新它

use Squarebit\InvoiceXpress\API\Data\ItemData;
use Squarebit\InvoiceXpress\Model\IxItem;

$item = IxItem::find(1234);
$item->description = "a serious description";
$item->save();

或者您可以创建一个

$data = ItemData::from([...]);
$item = (new IxItem())->fromData($data)
    ->save();

或者甚至删除它

$item->delete();

发票生命周期

use Squarebit\InvoiceXpress\API\Data\PdfData;

$invoice = (new IxInvoice())
    ->setClient(IxClient::findOrFail(1234)) // set the invoice's client
    ->addItem(IxItem::find(2345)) // add an IxItem model
    ->addItem(ItemData::from([....])) // you can also add from an ItemData
    ->addItems([  // or from an array
        ItemData::from([...]),
        IxItem::find(3579),
        ...
    ])
    ->save(); // creates the new invoice (locally and in InvoiceXpress)
    ->finalizeDocument() // formally registers the invoice
    ->email(); // email the invoice to the client

// Store the pdf locally
$pdf = $invoice->getPdf()->pdfUrl;
Storage::put('file.jpg', $pdf);

// Pay the invoice and email the receipt
$receipt = $invoice
    ->pay()
    ->email();

选项 2 - 直接使用端点

此方法仅处理远程更改。如果您想的话，您将不得不手动管理本地更改（在您的数据库中）。

您可以获取一个特定的项目并更新它

use Squarebit\InvoiceXpress\Facades\InvoiceXpress;

$itemsEndpoint = InvoiceXpress::items();

$itemData = $itemsEndpoint->get(1234);
$itemData->description = "a serious description";
$itemsEndpoint->update($itemData);

或者您可以创建一个

$data = ItemData::from([...]);
$itemData = InvoiceXpress::items()->create($itemData);

或者甚至删除它

InvoiceXpress::items()->delete(1234);

发票生命周期

use Squarebit\InvoiceXpress\API\Data\ClientData;
use Squarebit\InvoiceXpress\API\Data\EmailClientData;
use Squarebit\InvoiceXpress\API\Data\EmailData;
use Squarebit\InvoiceXpress\API\Data\InvoiceData;
use Squarebit\InvoiceXpress\API\Data\ItemData;
use Squarebit\InvoiceXpress\API\Data\PartialPaymentData;
use Squarebit\InvoiceXpress\API\Data\StateData;
use Squarebit\InvoiceXpress\Enums\DocumentEventEnum;
use Squarebit\InvoiceXpress\Enums\EntityTypeEnum;
use Squarebit\InvoiceXpress\Facades\InvoiceXpress;

$invoiceEndpoint = InvoiceXpress::invoices();

// Create an Invoice
$invoiceData = $invoiceEndpoint->create(
    EntityTypeEnum::SimplifiedInvoice,
    InvoiceData::from([
        ...
        'client' => ClientData::from([
            ...
        ]),
        'items' => [
            ItemData::from([])
        ]
    ])
);

// Formally register it
$invoiceEndpoint->changeState(
    EntityTypeEnum::SimplifiedInvoice,
    $invoiceData->id,
    StateData::from([
        'state' => DocumentEventEnum::Finalized
    ])
);

// Email the Invoice
$invoiceEndpoint->sendByEmail(
    EntityTypeEnum::SimplifiedInvoice,
    $invoiceData->id,
    EmailData::from([
        'client_data' => EmailClientData::from([
            'email' => 'someone@somewhere.com'
        ]),
        'subject' => '...',
        'body' => '...',
        'cc' => '...',
        'bcc' => '...',
    ])
);

// Get the pdf
$pdfData = $invoiceEndpoint->generatePDF($invoiceData->id)

// Pay the invoice (in total)
$receiptData = $invoiceEndpoint->generatePayment([
    EntityTypeEnum::SimplifiedInvoice,
    $invoiceData->id,
    PartialPaymentData::from([
        'amount' => $invoiceData->total,
    ])
])

 

如果您想的话，可以混合这两种选项

$itemsEndpoint = InvoiceXpress::items();

// get an Item by querying the endpoint directly
$itemData = $itemsEndpoint->get(1234);

// create an IxItem model with that data and update it
$item = (new IxItem())->fromData($itemData);
$item->description = 'a more serious description';

// send the modifed data to InvoiceXpress
$itemsEndpoint->update($item->getData());

可用的实体

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全漏洞

请参阅 我们的安全策略 了解如何报告安全漏洞。

鸣谢

• Squarebit, Lda
• 所有贡献者
• Spatie's Laravel 数据

许可证

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件。