rshop/superfaktura

Superfaktura API client

v1.0.1 2015-02-03 15:23 UTC

This package is auto-updated.

Last update: 2024-11-09 13:35:52 UTC


README

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