Skip to content

superfaktura/apiclient

BranchesTags

Repository files navigation

SuperFaktúra PHP API Client 2

Overview

The SuperFaktúra API enables the integration of external applications, allowing the remote creation of documents and retrieval of data about them. It also enables the sending of invoices via email or regular mail.

Requirements

To use this package, you will need at least PHP 8.2.

Quickstart

In order to make it easier to integrate your application with SuperFaktúra, we've prepared a simple API client for you, which allows you to issue your invoices remotely with minimal effort.

However, if you wish to create your own API client, we also provide general documentation.

If you want to try out API integration, we have a testing environment (sandbox) for Slovak and Czech market available for you.

Installation

Simply run this composer command:

$ composer require superfaktura/apiclient

Examples

Starting with API

To use this API client, you need to first:

1. Create an account in SuperFaktúra

2. Set up an Api Client instance with given credentials

<?php
include_once __DIR__ . '/vendor/autoload.php';

$api = new \SuperFaktura\ApiClient\ApiClient(
    new \SuperFaktura\ApiClient\Authorization\SimpleProvider(
        '[email protected]',
        'YOUR_APIKEY',
        'Example s.r.o.',
        1,
    ),
    \SuperFaktura\ApiClient\MarketUri::SLOVAK,
);

As an alternative, you can authorize through .env configuration.

3. Usage

$response = $api->invoices->create(
    invoice: [
        'name' => 'Test API',
        'variable' => '12345',
    ],
    items: [
        [
            'name' => 'item name',
            'description' => 'item description',
            'tax' => 20,
            'unit_price' => 10,
        ],
    ],
    client: [
        'name' => 'Client name',
        'ico' => '44981082',
        'comment' => 'Client comment',
        'update_addressbook' => 1,
    ],
);
var_dump($response->data);

Error handling

try {
    $response = $api->invoices->create(
        invoice: [
            'name' => 'Test API',
            'variable' => '12345',
        ],
        items: [
            [
                'name' => 'item name',
                'description' => 'item description',
                'tax' => 20,
                'unit_price' => 10,
            ],
        ],
        client: [
            'name' => 'Client name',
            'ico' => '44981082',
            'comment' => 'Client comment',
            'update_addressbook' => 1,
        ],
    );
    
    var_dump($response->data);
} catch (\SuperFaktura\ApiClient\Contract\Invoice\CannotCreateInvoiceException $exception) {
    echo 'Cannot create invoice: ' . $exception->getMessage() . PHP_EOL;
} catch (\SuperFaktura\ApiClient\Request\CannotCreateRequestException $exception) {
    echo 'Cannot create request: ' . $exception->getMessage() . PHP_EOL;
}

Use cases samples

Bank accounts

1. BankAccounts::getAll

Returns list of bank accounts.

$response = $api->bank_accounts->getAll();
var_dump($response->data);

For more information check API documentation.

2. BankAccounts::create

Creates a bank account and returns its data

$response = $api->bank_accounts->create([
    'bank_name' => 'NovaBanka',
    'iban' => 'SK000011112222333344',
    'swift' => 'suzuki',
    'default' => 1,
    'show' => 1,
    'show_account' => 1,
]);
var_dump($response->data);

For more information check API documentation.

3. BankAccounts::update

Updates an existing bank account and returns its data.

$response = $api->bank_accounts->update(
    id: 1,
    bank_account: [
        'bank_name' => 'StaroNovaBanka',
        'swift' => '777777',
    ],
);
var_dump($response->data);

For more information check API documentation.

4. BankAccounts::delete

Deletes an existing bank account.

$api->bank_accounts->delete(1);

For more information check API documentation.

Cash registers

Returns list of cash registers.

1. CashRegisters::getAll
$response = $api->cash_registers->getAll();
var_dump($response->data);

For more information check API documentation.

2. CashRegisters::getById

Returns details of cash register.

$response = $api->cash_registers->getById(1);
var_dump($response->data);

For more information check API documentation.

Cash register items

1. CashRegister\Items::create

Creates a new cash register item and returns its data.

$response = $api->cash_registers->items->create(
    cash_register_id: 1,
    data: [
        'amount' => 9.99,
        'currency' => \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
    ],
);
var_dump($response->data);

For more information check API documentation.

Clients

1. Clients::getAll

Returns list of clients filtered by given query object.

$response = $api->clients->getAll(new \SuperFaktura\ApiClient\UseCase\Client\ClientsQuery(
    full_text: 'Test',
    created: new \SuperFaktura\ApiClient\Filter\TimePeriod(
        period: \SuperFaktura\ApiClient\Filter\TimePeriodEnum::THIS_YEAR
    ),
));
var_dump($response->data);

For more information check API documentation.

2. Clients::getById

Returns details of client.

$response = $api->clients->getById(4);
var_dump($response->data);

For more information check API documentation.

3. Clients::create

Creates a client record and returns its data.

$response = $api->clients->create([
    'name' => 'SuperFaktúra s.r.o',
]);
var_dump($response->data);

For more information check API documentation.

4. Clients::update

Updates an existing client record and returns its data.

$response = $api->clients->update(
    id: 1,
    data: [
        'name' => 'SuperFaktúra s.r.o',
    ]
);
var_dump($response->data);

For more information check API documentation.

5. Clients::delete

Deletes an existing client.

$api->clients->delete(1);

For more information check API documentation.

Client's contact people

1. Client\Contact\Contacts::getAllByClientId

Returns list of contact people for a given client id.

$response = $api->clients->contacts->getAllByClientId(1);
var_dump($response->data);

For more information check API documentation.

2. Client\Contact\Contacts::create

Creates a contact person and returns its data.

$response = $api->clients->contacts->create(
    client_id: 1,
    contact: [
        'name' => 'Joe Doe',
        'email' => '[email protected]',
    ],
);
var_dump($response->data);

For more information check API documentation.

3. Client\Contact\Contacts::delete

Deletes an existing contact person.

$api->clients->contacts->delete(1);

For more information check API documentation.

Countries

1. Countries::getAll

Returns list of available countries.

$response = $api->countries->getAll();
var_dump($response->data);

For more information check API documentation.

Expenses

1. Expenses::getAll

Returns list of expenses filtered by given query object.

$response = $api->expenses->getAll(
    new \SuperFaktura\ApiClient\UseCase\Expense\ExpensesQuery(
        full_text: 'SuperFaktura',
        type: \SuperFaktura\ApiClient\Contract\Expense\ExpenseType::INVOICE,
        created: new \SuperFaktura\ApiClient\Filter\TimePeriod(
            period: \SuperFaktura\ApiClient\Filter\TimePeriodEnum::THIS_YEAR
        ),
    )
);
var_dump($response->data);

For more information check API documentation.

2. Expenses::getById

Returns details of expense.

$response = $api->expenses->getById(1);
var_dump($response->data);

For more information check API documentation.

3. Expenses::getAllCategories

Returns available expense categories.

$response = $api->expenses->getAllCategories();
var_dump($response->data);

For more information check API documentation.

4. Expenses::create

Creates an expense and returns its data.

$response = $api->expenses->create(
    expense: [
        'name' => 'Foo bar',
        'currency' => \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
    ],
    items: [
        [
            'description' => 'description of item 1',
            'name' => 'item 1',
            'tax' => 20,
            'unit_price' => 10,
        ]
    ],
    client: [
        'ico' => '46655034',
    ],
    extra: ['vat_transfer' => 1],
    tags: [1, 2],
);
var_dump($response->data);

For more information check API documentation.

5. Expenses::update

Updates an existing expense and returns its data.

$response = $api->expenses->update(
    id: 1,
    expense: [
        'name' => 'Foo',
    ],
);
var_dump($response->data);

For more information check API documentation.

6. Expenses::delete

Deletes an existing expense.

$api->expenses->delete(1);

For more information check API documentation.

Expense payments

1. Expense\Payment\Payments:create

Creates a new expense payment and returns its data.

$response = $api->expenses->payments->create(
    id: 95,
    payment: new \SuperFaktura\ApiClient\UseCase\Expense\Payment\Payment(
        amount: 10,
        currency: \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
        payment_type: \SuperFaktura\ApiClient\Contract\PaymentType::CASH,
    ),
);
var_dump($response->data);

For more information check API documentation.

2. Expense\Payment\Payments:delete

Deletes an existing expense payment.

$api->expenses->payments->delete(1);

For more information check API documentation.

Invoices

1. Invoices::getById

Returns details of invoice.

$response = $api->invoices->getById(1);
var_dump($response->data);

For more information check API documentation.

2. Invoices::getByIds

Returns details of multiple invoices.

$response = $api->invoices->getByIds([1,2,3]);
var_dump($response->data);

For more information check API documentation.

3. Invoices::getAll

Returns list of invoices filtered by given query object.

$query = new \SuperFaktura\ApiClient\UseCase\Invoice\InvoicesQuery(
    sort: new \SuperFaktura\ApiClient\Filter\Sort('created', \SuperFaktura\ApiClient\Filter\SortDirection::DESC),
    client_id: 172,
    created: new \SuperFaktura\ApiClient\Filter\TimePeriod(
        \SuperFaktura\ApiClient\Filter\TimePeriodEnum::FROM_TO,
            new DateTimeImmutable('2023-11-01'),
            new DateTimeImmutable('2023-11-08'),
    ),
);
$response = $api->invoices->getAll($query);
var_dump($response->data);

For more information check API documentation.

4. Invoices::downloadPdf

Returns PDF export of invoice.

$response = $api->invoices->downloadPdf(372, \SuperFaktura\ApiClient\Contract\Language::SLOVAK);
file_put_contents(__DIR__ . '/invoice.pdf', $response->data);

For more information check API documentation.

5. Invoices::create

Creates an invoice and returns its data.

$response = $api->invoices->create(
    invoice: [
        'name' => 'Test API',
        'variable' => '12345',
    ],
    items: [
        [
            'name' => 'item name',
            'description' => 'item description',
            'tax' => 20,
            'unit_price' => 10,
        ],
    ],
    client: [
        'name' => 'Client name',
        'ico' => '44981082',
        'comment' => 'Client comment',
        'update_addressbook' => 1,
    ],
    settings: [
        'language' => \SuperFaktura\ApiClient\Contract\Language::SLOVAK,
        'signature' => true,
    ],
    extra: [
        'pickup_point_id' => 23,
    ],
    my_data: [
        'address' => 'Fiktivna 1',
        'business_register' => "-",
        'city' => 'Prague',
        'company_name' => 'MyData Inc.',
        'country_id' => 191,
        'dic' => 'SK99999999',
        'ic_dph' => 'ABCDE',
        'zip' => '999 88',
    ],
    tags: [4],
);
var_dump($response->data);

For more information check API documentation.

6. Invoices::update

Updates an existing invoice and returns its data.

$response = $api->invoices->update(
    id: 1,
    invoice: [
        'name' => 'Test API updated',
        'variable' => '12345',
    ],
    items: [
        [
            'name' => 'item name',
            'description' => 'item description',
            'tax' => 20,
            'unit_price' => 10,
        ],
    ],
    client: [
        'name' => 'Client name',
        'ico' => '44981082',
        'comment' => 'Client comment',
        'update_addressbook' => 1,
    ],
    settings: [
        'language' => \SuperFaktura\ApiClient\Contract\Language::SLOVAK,
        'signature' => true,
    ],
    extra: [
        'pickup_point_id' => 23,
    ],
    my_data: [
        'address' => 'Fiktivna 1',
        'business_register' => "-",
        'city' => 'Prague',
        'company_name' => 'MyData Inc.',
        'country_id' => 191,
        'dic' => 'SK99999999',
        'ic_dph' => 'ABCDE',
        'zip' => '999 88',
    ],
    tags: [4],
);
var_dump($response->data);

For more information check API documentation.

7. Invoices::delete

Deletes an existing invoice.

$api->invoices->delete(1);

For more information check API documentation.

8. Invoices::changeLanguage

Changes language on an existing invoice.

$api->invoices->changeLanguage(1, \SuperFaktura\ApiClient\Contract\Language::CZECH);

For more information check API documentation.

9. Invoices::markAsSent

Toggles invoice mark as sent status.

$api->invoices->markAsSent(1);

For more information check API documentation.

10. Invoices::markAsSentViaEmail

Marks invoice as sent via email.

$api->invoices->markAsSentViaEmail(1, '[email protected]', 'Subject', 'Message');

For more information check API documentation.

11. Invoices::sendViaEmail

Sends invoice via email.

$email = new \SuperFaktura\ApiClient\UseCase\Invoice\Email(
    email: '[email protected]',
    pdf_language: \SuperFaktura\ApiClient\Contract\Language::CZECH,
    bcc: ['[email protected]'],
    cc: ['[email protected]'],
    subject: 'Subject of email',
    message: 'Message',
);
$api->invoices->sendViaEmail(1, $email);

For more information check API documentation.

12. Invoices::sendViaPostOffice
$address = new \SuperFaktura\ApiClient\UseCase\Invoice\Address(
    name: 'John Doe',
    address: 'Vymyslena 1',
    city: 'Bratislava',
    country_id: 191,
    state: 'Slovakia',
    zip: '99999',
);
$api->invoices->sendViaPostOffice(372, $address);

For more information check API documentation.

Invoice\Items

1. Invoice\Item::delete

Deletes invoice items with given ids.

$api->invoices->items->delete(1, [1,2,3]);

For more information check API documentation.

Invoice\Payments

1. Invoice\Payment::markAsUnPayable

Marks invoice as "will not be paid".

$api->invoices->payments->markAsUnPayable(1);

For more information check API documentation.

2. Invoice\Payment::create

Adds payment to invoice.

$payment = new \SuperFaktura\ApiClient\UseCase\Invoice\Payment\Payment(
    amount: 6.00,
    currency: \SuperFaktura\ApiClient\UseCase\Money\Currency::EURO,
    payment_type: \SuperFaktura\ApiClient\Contract\PaymentType::CARD,
    document_number: '123',
    payment_date: new DateTimeImmutable('now'),
);
$api->invoices->payments->create(1, $payment);

For more information check API documentation.

3. Invoice\Payment::delete

Deletes payment from invoice.

$api->invoices->payments->delete(123);

For more information check API documentation.

Related documents

1. RelatedDocuments::link

Adds link between two documents.

$relation = new \SuperFaktura\ApiClient\UseCase\RelatedDocument\Relation(
    parent_id: 1,
    parent_type: \SuperFaktura\ApiClient\Contract\RelatedDocument\DocumentType::INVOICE,
    child_id: 1,
    child_type: \SuperFaktura\ApiClient\Contract\RelatedDocument\DocumentType::EXPENSE,
);
$response = $api->related_documents->link($relation);
var_dump($response->data);

For more information check API documentation.

2. RelatedDocuments::unlink

Removes link between two documents.

$api->related_documents->unlink(1);

For more information check API documentation.

Exports

1. Exports::exportInvoices

Export multiple invoices with possible configuration.

$response = $api->exports->exportInvoices(
    [1,2,3],
    \SuperFaktura\ApiClient\Contract\Export\Format::PDF,
    new \SuperFaktura\ApiClient\UseCase\Export\PdfExportOptions(
        language: \SuperFaktura\ApiClient\Contract\Language::SLOVAK,
        hide_signature: true,
    ),
);
var_dump($response->data);
2. Exports::getStatus

Returns progress of the export.

$response = $api->exports->getStatus(1);
var_dump($response->data);
3. Exports::download

Download completed export.

$response = $api->exports->download(1);
file_put_contents(__DIR__ . '/export.zip', $response->data);

Stock items

1. Stock\Items::create

Creates a new stock item.

$response = $api->stock_items->create([
    'name' => 'Cake - red velvet',
    'sku'  => 'CK-RV',
    'unit_price' => 30.99,
    'purchase_unit_price' => 39.99,
]);
var_dump($response->data);

For more information check API documentation.

2. Stock\Items::getById

Returns details of stock item.

$response = $api->stock_items->getById(1);
var_dump($response->data);

For more information check API documentation.

3. Stock\Items::getAll

Returns list of stock items filtered by given query object.

$query = new \SuperFaktura\ApiClient\Contract\Stock\ItemsQuery(
    price_from: 30.99,
    price_to: 39.99,
);
$response = $api->stock_items->getAll($query);
var_dump($response->data);

For more information check API documentation.

4. Stock\Items::update

Updates an existing stock item.

$response = $api->stock_items->update(1, [
    'name' => 'Updated name',
]);
var_dump($response->data);

For more information check API documentation.

5. Stock\Items::delete

Deletes an existing stock item.

$api->stock_items->delete(1);

For more information check API documentation.

Stock movements

1. Stock\Movements::create

Creates multiple stock logs for an existing stock item id.

$response = $api->stock_items->movements->create(1, [
    ['quantity' => 5, 'note' => 'Restocking the supplies'],
    ['quantity' => -5, 'note' => 'I must eat something for dinner'],
]);
var_dump($response->data);

For more information check API documentation.

2. Stock\Movements::createWithSku

Creates multiple stock logs for an existing stock item SKU.

$response = $api->stock_items->movements->createWithSku('CK-RV', [
    ['quantity' => 5, 'note' => 'Restocking the supplies'],
    ['quantity' => -5, 'note' => 'I must eat something for dinner'],
]);
var_dump($response->data);

For more information check API documentation.

Tag

1. Tags::getAll

Returns list of tags.

$response = $api->tags->getAll();
var_dump($response->data);

For more information check API documentation.

2. Tags::create

Creates a tag and returns its data

$response = $api->tags->create('my-tag');
var_dump($response->data);

For more information check API documentation.

3. Tags::update

Updates an existing tag and returns its data.

$response = $api->tags->update(1, 'my-updated-tag');
var_dump($response->data);

For more information check API documentation.

4. Tags::delete

Deletes an existing tag.

$api->tags->delete(1);

For more information check API documentation.

Enumerations

Authorization with .env file

1. Create .env file:

SF_APICLIENT_EMAIL=[email protected]
SF_APICLIENT_KEY=YOUR_APIKEY
SF_APICLIENT_APP_TITLE='Example s.r.o.'
SF_APICLIENT_COMPANY_ID=1

And then use in your code:

$api = new \SuperFaktura\ApiClient\ApiClient(
    new \SuperFaktura\ApiClient\Authorization\EnvFileProvider(__DIR__ . '/.env'),
    'https://moja.superfaktura.sk',
);

About

SuperFaktúra oficiálny PHP-API klient.

Resources

Readme

License

MIT license
Activity

Stars

18 stars

Watchers

7 watching

Forks

18 forks
Report repository

Releases 25

Add setCompanyId method Latest
May 31, 2022
+ 24 releases

Packages

No packages published

Contributors 10

Languages