README

简单的官方 php 包包装器 https://github.com/fakturoid/fakturoid-php

文档

安装
配置
示例
升级指南

安装

步骤 1：安装包

通过执行以下命令将包添加到您的 composer.json 中。

composer require szymsza/laravel-fakturoid

这将同时更新 composer.json 并将包安装到 vendor/ 目录中。

步骤 2：配置

首先通过运行以下命令初始化配置文件

php artisan vendor:publish --provider="WEBIZ\LaravelFakturoid\FakturoidServiceProvider" --tag="config"

此命令将初始化配置并修改位于 config/fakturoid.php 下的创建的文件。

配置

return [
    'account_name' => env('FAKTUROID_NAME', 'XXX'), // URL slug of your account
    'account_api_id' => env('FAKTUROID_API_ID', 'XXX'), // found in your Fakturoid user account settings
    'account_api_secret' => env('FAKTUROID_API_SECRET', 'XXX'), // found in your Fakturoid user account settings
    'app_contact' => env('FAKTUROID_APP_CONTACT', 'Application <your@email.cz>'), // linked to the application you are developing
];

示例

创建主题，创建发票，发送发票（API v3 风格）

use Fakturoid;

try {
    // create subject
    $subject = Fakturoid::getSubjectsProvider()->create([
        'name' => 'Firma s.r.o.',
        'email' => 'aloha@pokus.cz'
    ]);
    if ($subject->getBody()) {
        $subject = $subject->getBody();

        // create invoice with lines
        $lines = [
            [
                'name' => 'Big sale',
                'quantity' => 1,
                'unit_price' => 1000
            ],
        ];

        $invoice = Fakturoid::getInvoicesProvider()->create(['subject_id' => $subject->id, 'lines' => $lines]);
        $invoice = $invoice->getBody();

        // send created invoice
        Fakturoid::getInvoicesProvider()->fireAction($invoice->id, 'deliver');
    }
} catch (\Exception $e) {
    dd($e->getCode() . ": " . $e->getMessage());
}

创建主题，创建发票，发送发票（旧 API 风格）

use Fakturoid;

try {
    // create subject
    $subject = Fakturoid::createSubject(array(
        'name' => 'Firma s.r.o.',
        'email' => 'aloha@pokus.cz'
    ));
    if ($subject->getBody()) {
        $subject = $subject->getBody();

        // create invoice with lines
        $lines = [
            [
                'name' => 'Big sale',
                'quantity' => 1,
                'unit_price' => 1000
            ],
        ];

        $invoice = Fakturoid::createInvoice(array('subject_id' => $subject->id, 'lines' => $lines));
        $invoice = $invoice->getBody();

        // send created invoice
        Fakturoid::fireInvoice($invoice->id, 'deliver');
    }
} catch (\Exception $e) {
    dd($e->getCode() . ": " . $e->getMessage());
}

升级指南

如果您之前使用的是此包与 Fakturoid API v2（2024 年 3 月之前）通信的旧版本，则在 2025 年 3 月 31 日旧 API 版本关闭之前，需要进行更新。

标准升级指南

使用 Composer 更新包到最新版本。
更新 config/fakturoid.php 中的配置（见配置）或删除您的 config/fakturoid.php 并重新发布配置（见安装：步骤 2）。
编辑 .env 中的配置
- 删除 FAKTUROID_EMAIL 和 FAKTUROID_API_KEY
- 添加 FAKTUROID_API_ID 和 FAKTUROID_API_SECRET，这些凭据可在您的 Fakturoid 用户账户设置中找到

如果您仅使用了基本的 Fakturoid 功能，此时一切可能正常运行。如果不这样做，问题可能有两种类型

底层 API 的变化

Fakturoid API v3 调用的参数和返回类型并不总是与 v2 相同 - 例如，当获取发票时，proforma 布尔值已被 document_type 属性替换。

要查看是否需要提供不同的参数或应期望不同的返回值，请参阅官方 Fakturoid API 变更日志。

底层 PHP 库的变化

此包提供的 PHP 库门面已经发生了显著变化。尽管此包装器试图覆盖大多数这些变化以使您的代码向后兼容，但某些较少使用的方法或通用边缘情况可能会引起问题。这通常可以通过包装器或 PHP 库抛出的类似 BadMethodCallException: Method 'XXX' does not exist on Fakturoid instance. 的异常来识别。

要解决这个问题，请参阅 PHP 库文档以了解如何以新的 API 格式调用您的功能（查看 README diff 可能很有用）。例如，要创建主题，现在应使用以下方法，如 README diff 中的第 27 行和 172 行所示：

Fakturoid::createSubject([...]);

现在应使用以下方法：

Fakturoid::->getSubjectsProvider()->create([...]);

如 README diff 中的第 27 行和 172 行所示。

如果您遇到此类未处理的兼容性问题，请考虑向此包的 V2Compatibility 特性提交拉取请求，或者至少在此存储库中打开一个问题。

szymsza / laravel-fakturoid

维护者

详细信息