Superfaktura API PHP klient

PHP klient k API rozhraniu online ekonomického systému SuperFaktúra.

Inštalácia

Jednoducho cez command line: composer require rshop/superfaktura

Alebo pridaním do composer.json:

{
    "require": {
        "rshop/superfaktura": "~1.0"
    }
}

Úvodom

Jednotlivé entity je možné vytvárať prostredníctvom triedy Superfaktura.

use Rshop\Synchronization\Superfaktura;

$superfaktura = new Superfaktura('EMAIL', 'API_KEY');

Vytvorenie faktúry

Novú faktúru je možné vytvoriť metódou createInvoice.

$invoice = $superfaktura->createInvoice([
    'name' => 'Názov faktúry',
    'invoice_no_formatted' => '12345'
]);

// parametre je možné nastaviť aj zadaním požadovaného atribútu
$invoice['already_paid'] = true;

Dostupné atribúty:

• already_paid - bola už faktúra uhradená? true/false
• created - dátum vystavenia
• comment - komentár
• constant - konštantný symbol
• delivery - dátum dodania
• delivery_type - spôsob dodania, číselník hodnôt
• deposit - uhradená záloha
• discount - zľava v %
• due - dátum splatnosti
• estimate_id - ID cenovej ponuky, na základe ktorej je faktúra vystavená
• header_comment - text nad položkami faktúry
• internal_comment - interná poznánka, nezobrazuje sa klientovi
• invoice_currency - mena, v ktorej je faktúra vystavená. Možnosti: EUR, USD, GBP, HUF, CZK, PLN, CHF, RUB
• invoice_no_formatted - číslo faktúry
• issued_by - faktúru vystavil
• issued_by_phone - faktúru vystavil telefón
• issued_by_email - faktúru vystavil email
• name - názov faktúry
• payment_type - spôsob úhrady, číselník hodnôt
• proforma_id - ID proforma faktúry, na základe ktorej sa vystavuje ostrá faktúra (ostrá faktúra tak preberie údaje o uhradenej zálohe)
• rounding - spôsob zaokrúhľovania DPH: document - za celý dokument, item - po položkaćh (predvolená hodnota)
• specific - špecifický symbol
• sequence_id - ID číselníka
• tax_document - jedná sa o daňový doklad k prijatej platbe? true/false
• type - typ faktúry: regular - bežná faktúra, proforma - zálohová faktúra, cancel - dobropis, estimate - cenová ponuka, order - prijatá objednávka
• variable - variabilný symbol

Nastavenie zákazníka

Zákazníka na faktúru je možné pridať metódou setClient.

$invoice->setClient([
    'name' => 'Meno zákazníka'
]);

// parametre je možné nastaviť aj zadaním požadovaného atribútu
$client = $invoice->getClient();
$client['city'] = 'Mesto';

Dostupné atribúty:

• address - adresa
• bank_account - bankový účet
• city - mesto
• comment - komentár
• country_id - ID krajiny, číselník krajín
• country - vlastný názov krajiny
• delivery_address - dodacia adresa
• delivery_city - dodacie mesto
• delivery_country - vlastná dodacia krajina
• delivery_country_id - ID dodacej krajiny
• delivery_name - názov klienta pre dodanie
• delivery_zip - dodacie PSČ
• dic - DIČ
• email - email
• fax - fax
• ic_dph - IČ DPH
• ico - IČO
• name - názov klienta
• phone - telefón
• zip - PSČ

Pridanie položky

Položku na faktúru je možné pridať metódou addItem.

$invoice->addItem([
    'name' => 'Názov položky',
    'quantity' => 1,
    'unit_price' => 40.83,
    'tax' => 20
]);

Dostupné atribúty:

• name - názov položky
• description - popis
• quantity - množstvo
• unit - jednotka
• unit_price - cena bez DPH
• tax - sadzba DPH v %
• stock_item_id - ID skladovej polozky
• sku - skladove oznacenie

Uloženie

try {
    $invoice->save();

    // $invoice obsahuje všetky parametre uloženej faktúry
    var_dump($invoice['token'], $invoice->getSummary());
}
catch (Exception $e) {
    // chyby, ktoré nastali pri komunikácii, je možné získať metódou getErrors
    var_dump($e->getErrors());
}

Získanie existujúcej faktúry

Existujúcu faktúru je možné stiahnuť prostredníctvom jej ID metódou getInvoice.

$invoice = $superfaktura->getInvoice(616575);

Editácia faktúry

Pri editácii načítanej faktúry je možné postupovať rovnako, ako pri vytváraní novej.

// zmena variabilného symbolu faktúry
$invoice['variable'] = '12345';

// pridanie položky
$invoice->addItem([
    'name' => 'Názov pridávanej položky',
    'quantity' => 2,
    'unit_price' => 5.11,
    'tax' => 20
]);

try {
    $invoice->save();

    // $invoice obsahuje všetky parametre uloženej faktúry
    var_dump($invoice['token'], $invoice->getSummary());
}
catch (Exception $e) {
    // chyby, ktoré nastali pri komunikácii, je možné získať metódou getErrors
    var_dump($e->getErrors());
}

Označenie faktúry ako odoslanej

Označenie metódou markAsSent. Užitočné, pokiaľ vytvorené faktúry odosielate vlastným systémom, avšak chcete toto odoslanie evidovať aj v SuperFaktúre.

$invoice->markAsSent([
    'email' => '[email protected]'
]);

Dostupné atribúty:

• email - mailová adresa, kam bola faktúra odoslaná
• subject - predmet emailu
• body - text emailu

Odoslanie faktúry emailom

Odoslanie metódou sendByEmail. Nenastavené atribúty sa nastavia automaticky podľa nastavení v SuperFaktúre.

$invoice->sendByEmail([
    'to' => '[email protected]'
]);

Dostupné atribúty:

• to - na akú emailovú adresu sa má faktúra odoslať (povinné)
• cc - otvorená kópia (array)
• bcc - skrytá kópia (array)
• subject - predmet emailu
• body - text emailu

Zaplatenie faktúry

Pridanie úhrady k faktúre metódou pay.

$invoice->pay([
    amount' => 10.34
]);

Dostupné atribúty:

• amount - uhradená suma (povinné)
• currency - mena úhrady, predvolené EUR
• date - dátum úhrady, predvolený aktuálny dátum
• payment_type - spôsob úhrady, predvolený typ transfer, možné hodnoty cash, transfer, credit, paypal, cod

Získanie linky k PDF

Adresu, na ktorej je možné stiahnuť PDF faktúru, je možné získať metódou getPdf.

$invoice->getPdf();

Zmazanie faktúry

Odstránenie faktúry je možné metódou delete.

$invoice->delete();

Spustenie testov

Pre testovanie je potrebné najprv skopírovať súbor TestConfig.php.tpl na TestConfig.php a vyplniť testovací email a API kľúč. Následne cez command line:

$ cd path/to/rshop/superfaktura
$ composer install
$ vendor/bin/phpspec run