rshop/superfaktura

Superfaktura API client

Superfaktura API PHP klient

, _(*1)

PHP klient k API rozhraniu online ekonomického systému SuperFaktúra., _(*2)

Inštalácia

Jednoducho cez command line: composer require rshop/superfaktura, _(*3)

Alebo pridaním do composer.json:, _(*4)

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

Úvodom

Jednotlivé entity je možné vytvárať prostredníctvom triedy Superfaktura., _(*5)

use Rshop\Synchronization\Superfaktura;

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

Vytvorenie faktúry

Novú faktúru je možné vytvoriť metódou createInvoice., _(*6)

$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, _(*7)

Nastavenie zákazníka

Zákazníka na faktúru je možné pridať metódou setClient., _(*8)

$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Č, _(*9)

Pridanie položky

Položku na faktúru je možné pridať metódou addItem., _(*10)

$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, _(*11)

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., _(*12)

$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., _(*13)

// 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., _(*14)

$invoice->markAsSent([
    'email' => 'email@zakaznika.sk'
]);

Dostupné atribúty: * email - mailová adresa, kam bola faktúra odoslaná * subject - predmet emailu * body - text emailu, _(*15)

Odoslanie faktúry emailom

Odoslanie metódou sendByEmail. Nenastavené atribúty sa nastavia automaticky podľa nastavení v SuperFaktúre., _(*16)

$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, _(*17)

Zaplatenie faktúry

Pridanie úhrady k faktúre metódou pay., _(*18)

$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, _(*19)

Získanie linky k PDF

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

$invoice->getPdf();

Zmazanie faktúry

Odstránenie faktúry je možné metódou delete., _(*21)

$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:, _(*22)

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