PHP klient k API rozhraniu online ekonomického systému SuperFaktúra
PHP Smarty
Latest commit c343d83 Aug 27, 2015 @segy segy Merge pull request #1 from rekurzia/master
Convert array to short syntax.
Permalink
Failed to load latest commit information.
spec
src
.gitattributes
.gitignore
LICENSE
README.md
composer.json license link Jun 17, 2015
phpspec.yml Initial commit Jan 30, 2015

README.md

Superfaktura API PHP klient

Latest Version Total Downloads Software License

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@zakaznika.sk'
]);

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@zakaznika.sk'
]);

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