Skip to content

Latest commit

 

History

History
419 lines (274 loc) · 11.9 KB

DOCUMENTATION.md

File metadata and controls

419 lines (274 loc) · 11.9 KB
Raw

Documentation (version 1.2)

Table of Contents

  1. Invoices
    1. Creating simple invoice
    2. Using the constructor
    3. Additional functions
      1. FakturowniaInvoice to array
      2. Create FakturowniaInvoice from JSON structure
  2. Positions
    1. Creating a position
    2. Specifying price - net or gross
    3. Calculating net and gross price
    4. Setting tax
    5. Adding position to an invoice
    6. Additional functions
      1. FakturowniaPosition to array
      2. Create FakturowniaPosition from JSON structure
  3. Invoice status
  4. Invoice kind
  5. Payment method
  6. Fakturownia
    1. Retreiving an invoice from Fakturownia
    2. Sending invoice to Fakturownia
    3. Updating specific invoice in Fakturownia
    4. Changing invoice status in Fakturownia
    5. Deleting target invoice from Fakturownia database
    6. Printing invoices
    7. Creating raw print

Invoices

This topic will show how to create invoices and what you can modify using helper class FakturowniaInvoice.

Namespace:

use MattM\FFL\FakturowniaInvoice;

Creating simple invoice

Here's an example for basic usage of creating a simple VAT kind invoice, specifying seller and buyer name and adding a single product into it:

$invoice = new FakturowniaInvoice();

$invoice->seller['name'] = "Seller name";
$invoice->buyer['name'] = "Buyer name";

$product = new FakturowniaPosition("Product ABC", 1, 10.00);
$invoice->addPosition($product);

If we want to specify that buyer is not company - instead of $invoice->buyer['name'] use $invoice->buyer['first_name'] and $invoice->buyer['last_name']:

$invoice = new FakturowniaInvoice();

$invoice->isBuyerCompany = false;
$invoice->buyer['first_name'] = "First name";
$invoice->buyer['last_name'] = "Last name";

$product = new FakturowniaPosition("Product ABC", 1, 10.00);
$invoice->addPosition($product);

Using the constructor

Normally Fakturownia API automatically generates a number for your new invoice, but if you wish to specify the number, kind of invoice and the language, you pass them as optional parameters in the invoice constructor:

$invoice = new FakturowniaInvoice(FakturowniaInvoiceKind::PROFORMA, "FK 123/123/123", "en");

Or you can just set them by using invoice object variables:

$invoice = new FakturowniaInvoice();
$invoice->kind = FakturowniaInvoiceKind::PROFORMA;
$invoice->number = "FK 123/123/123";
$invoice->language = "en";

Additional functions

FakturowniaInvoice to array

In order to convert object of class FakturowniaInvoice into an array, you have to call method toArray():

$invoice = new FakturowniaInvoice();

$invoiceAsArray = $invoice->toArray();

Create FakturowniaInvoice from JSON structure

You can create instance of FakturowniaInvoice class by using it's static function createFromJson() like showed in example below:

$json = Fakturownia::getInvoice(1234567890);

$invoice = FakturowniaInvoice::createFromJson($json);

Positions

This section describes all functionality of FakturowniaPosition class, showing it's main methods for an easy management of the positions objects.

Namespace:

use MattM\FFL\FakturowniaPosition;

Creating a position

Every invoice requires minimum one position added to the invoice. You can create position using helper class called FakturowniaPosition. Here's an example of creating a simple product:

$name = "Product ABC";
$quantity = 1;
$price = 10.00;

$product = new FakturowniaPosition($name, $quantity, $price);

or with all optional parameters:

$name = "Product ABC";
$quantity = 1;
$price = 10.00;
$isNetto = false;
$tax = 23;
$gtu_code = 'GTU_02';

$product = new FakturowniaPosition($name, $quantity, $price, $isNetto, $tax, $gtu_code)

Specifying price - net or gross

By default the price you specify for the position is set to gross price. If you wish to specify net price then you can use one of optional parameters of FakturowniaPosition constructor:

// Creating a new position set with gross price
$product = new FakturowniaPosition("Product A", 1, 12.30);

// Creating a new position set with net price
$product = new FakturowniaPosition("Product B", 1, 10.00, true);

Or you can set variable $isNetto of the position object:

$product = new FakturowniaPosition("Product ABC", 1, 10.00);
$product->isNetto = true;

Calculating net and gross price

If you wish to convert in position object the net price to gross price and vice versa you can do that by using dedicated functions getNetPrice() and getGrossPrice():

// Creating a product with specified net price
$product = new FakturowniaPosition("Product A", 1, 10.00, true);

echo $product->getNetPrice() . '<br>'; // 10.00
echo $product->getGrossPrice() . '<br>'; // 12.30 - due to default tax of 23%

Notice that both of the functions only return specified prices - the $price variable inside of the object won't be changed!


Setting tax

In order to set up or change tax percent you can do that by using one of FakturowniaPosition constructor optional parameters:

// By default tax value is set to 23%
$product = new FakturowniaPosition("Product B", 1, 10.00, true);

// You can change tax value by specifying one of last parameters - remember to give the amount from range 1 - 100!
$anotherProduct = new FakturowniaPosition("Product B", 1, 10.00, true, 18);

You can also do that by using the $tax variable:

$product = new FakturowniaPosition("Product A", 1, 12.00, true);
$product->tax = 18;

Setting GTU Code

In order to set up or change gtu code you can do that by using one of FakturowniaPosition constructor optional parameters with default parameters:

// By default netto and tax set at 23%
$product = new FakturowniaPosition("Product B", 1, 10.00, false, 23, 'GTU_02');

You can also do that by using the $gtu_code variable:

$product = new FakturowniaPosition("Product A", 1, 12.00, true);
$product->gtu_code = "GTU_02";

Adding position to an invoice

To add position object to the invoice object you can use command addPosition() on your invoice object:

$invoice = new FakturowniaInvoice();
$product = new FakturowniaPosition("Product ABC", 1, 10.00);

$invoice->addPosition($product);

Additional functions

FakturowniaPosition to array

In order to convert object of class FakturowniaPosition into an array, you have to call method toArray():

$product = new FakturowniaPosition("Product ABC", 1, 10.00);

$positionAsArray = $product->toArray();

Create FakturowniaPosition from JSON structure

You can create instance of FakturowniaPosition class by using it's static function createFromJson() like showed in example below:

$json = Fakturownia::getInvoice(1234567890);

$position = FakturowniaPosition::createFromJson($json['positions'][0]);

FakturowniaPosition to array

In order to convert object of class FakturowniaPosition into an array, you have to call method toArray():

$product = new FakturowniaPosition("Product ABC", 1, 10.00);

$positionAsArray = $product->toArray();

Invoice status

FakturowniaInvoiceStatus is a static helper class that contains constants for changing invoices status:

use MattM\FFL\Helpers\FakturowniaInvoiceStatus;

// Change specific invoice status to rejected
Fakturownia::changeInvoiceStatus(1234567890, FakturowniaInvoiceStatus::REJECTED);

Invoice kind

There's a FakturowniaInvoiceKind that contains constants for choosing one of existing kind of invoice for Fakturownia service.

use MattM\FFL\Helpers\FakturowniaInvoiceKind;

// Set the invoice kind to proforma
$invoice->kind = FakturowniaInvoiceKind::PROFORMA;

Payment method

Class FakturowniaPaymentMethod has constants for choosing one of existing and acceptable payment methods for the Fakturownia invoices.

use MattM\FFL\Helpers\FakturowniaPaymentMethod;

// Set the payment method to cash option
$invoice->paymentType = FakturowniaPaymentMethod::CASH;

Fakturownia

Fakturownia is a main helper class used to communicate with Fakturownia API servive. This class has been initialized in project using singleton command in Laravel.

Namespace:

use MattM\FFL\Fakturownia;

Retreiving an invoice from Fakturownia

To simply retrieve an existing invoice from Fakturownia service you can use static command getInvoice() specifying an ID of the invoice as a first parameter of the function - see an example below:

$response = Fakturownia::getInvoice(123456789);

var_dump($response);

Sending invoice to Fakturownia

To create the invoice in Fakturownia service you need to call static function createInvoice() using Fakturownia static helper class (remember to have at least one position in your invoice object!):

$invoice = new FakturowniaInvoice();

// Filling up $invoice with data and positions...

Fakturownia::createInvoice($invoice);

Updating specific invoice in Fakturownia

You can update an existing invoice in Fakturownia(InvoiceOcean) system by providing an ID and an array of elements that you would like to update, as parameters into a static function updateInvoice() of Fakturownia static helper class:

Fakturownia::updateInvoice(1234566789, array(
    'kind' => FakturowniaInvoiceKind::PROFORMA,
    'buyer_name' => 'John Wick'
    'buyer_company' => '0'
));

Changing invoice status in Fakturownia

Use Fakturownia helper class to change status of specific invoice by using static function changeInvoiceStatus(). You will have to provide of of the invoice and name of the status you want to set. We recommend using helper class FakturowniaInvoiceStatus to see available options for invoice status. An example below shows how to chance status of the invoice :

use MattM\FFL\Helpers\FakturowniaInvoiceStatus;

// Changing invoice status to issued
Fakturownia::changeInvoiceStatus(1234567890, "issued");

// Changing invoice status to paid with helper class
Fakturownia::changeInvoiceStatus(1234567890, FakturowniaInvoiceStatus::PAID);

Deleting target invoice from Fakturownia database

To simply delete an invoice from your system use deleteInvoice() static function of Fakturownia helper class. Remember to pass an ID of the invoice as a parameter of the function! Have a look at example shown below:

Fakturownia::deleteInvoice(1234566789);

Printing invoices in PDF format

To download a print of your invoice in a PDF format you can use a static method from Fakturownia helper called printInvoice(). This function requires to provide two elements as it's arguments - the invoice ID and name of the printed PDF file:

return Fakturownia::printInvoice(123456789, "Print name");

This method returns a Laravel response object in a form of streamDownload() method.


Creating raw print

You're also able to get the raw data for the print by calling static function printInvoiceRaw() from Fakturownia helper class. Just remember to specify the invoice ID as a first parameter of the function:

$rawData = Fakturownia::printInvoiceRaw(123456789);