README

Fakturownia API client for Laravel: invoices, PDF, e-mail delivery, payments, clients, products and KSeF submission with XML and UPO download.

Polska wersja dokumentacji

Installation

composer require beziworld/laravel-fakturownia
php artisan vendor:publish --tag=fakturownia-config   # optional

FAKTUROWNIA_ACCOUNT=mycompany          # https://mycompany.fakturownia.pl
FAKTUROWNIA_API_TOKEN=your-api-token   # Settings > Account settings > Integration
FAKTUROWNIA_DEPARTMENT_ID=             # optional seller department
FAKTUROWNIA_SEND_TO_KSEF=false         # submit new invoices to KSeF on save

Issue an invoice for an order

use Beziworld\Fakturownia\Data\InvoiceRequest;
use Beziworld\Fakturownia\Data\Position;
use Beziworld\Fakturownia\Facades\Fakturownia;

$invoice = Fakturownia::createInvoice(new InvoiceRequest(
    positions: $order->items->map(fn ($item) => new Position(
        name: $item->name,
        quantity: $item->quantity,
        tax: '23',
        totalGrossPrice: $item->gross_total,
    ))->all(),
    buyerName: $order->company_name,
    buyerTaxNo: $order->nip,
    buyerEmail: $order->email,
    buyerStreet: $order->street,
    buyerPostCode: $order->postal_code,
    buyerCity: $order->city,
    paymentTo: now()->addDays(14),
    attributes: ['oid' => $order->number, 'oid_unique' => 'yes'],   // blocks duplicate invoices for one order
), sendToKsef: true);

$order->update(['invoice_id' => $invoice->id, 'invoice_number' => $invoice->number]);

Fakturownia::sendByEmail($invoice->id);              // to the buyer e-mail, with PDF

Position accepts a net unit price (netPrice) or a gross total (totalGrossPrice); tax is "23", "8", "5", "0", "zw" or "np". Any other invoice or position field can be passed in attributes, e.g. ['split_payment' => 1] or ['gtu_code' => 'GTU_12'].

KSeF

$invoice = Fakturownia::sendToKsef($invoice->id);   // or createInvoice(..., sendToKsef: true)

$invoice->ksefStatus;   // "ok", "processing", "send_error", ...
$invoice->ksefNumber;   // e.g. "5261040828-20261104-..."
$invoice->isInKsef();

Fakturownia::ksefXml($invoice->id);   // structured FA(3) XML
Fakturownia::ksefUpo($invoice->id);   // official acknowledgement of receipt

Other operations

Fakturownia::invoices(['period' => 'this_month', 'kind' => 'vat'], page: 1, perPage: 100);
Fakturownia::invoice($id);
Fakturownia::pdf($id);                         // binary PDF; "copy", "duplicate" options
Fakturownia::markAsPaid($id);                  // or changeStatus($id, 'partial')
Fakturownia::addPayment($id, 123.00, 'Przelew');
Fakturownia::updateInvoice($id, ['buyer_email' => 'new@example.com']);
Fakturownia::clients(['tax_no' => '5261040828']);
Fakturownia::createProduct(['name' => 'Consulting', 'price_net' => 200, 'tax' => '23']);

Download the PDF in a controller:

return response(Fakturownia::pdf($order->invoice_id), 200, [
    'Content-Type' => 'application/pdf',
    'Content-Disposition' => 'inline; filename="invoice.pdf"',
]);

Exceptions

ApiException (errors() with field validation messages, httpStatus(), isRateLimited()) and InvalidConfiguration, both extending FakturowniaException. Fakturownia limits API usage per account; back off on HTTP 429.

Development

composer install
composer ci   # pint --test, phpstan (level 8), pest

Author

Created and maintained by Kamil Ćwiertnia, beziworld.eu.

E-mail: biuro@beziworld.eu
Issues: GitHub issues

Need an invoicing or KSeF integration? Get in touch through beziworld.eu.

Other packages by the author

laravel-infakt · laravel-wfirma · laravel-company-data · laravel-nbp · laravel-przelewy24

License

MIT. See LICENSE.md. This package is not affiliated with Fakturownia.

beziworld / laravel-fakturownia

Package info

Security

Statistics