Python API connector pre superfaktura.sk

Keď som asi pred pol rokom objavil slovenský projekt superfaktura.sk, bol som nadšený. Vystavovanie faktúr sa zrazu stalo radosťou, evidovanie platieb a naháňanie neplatičov sa skrátilo na pár minút týždenne a vždy som mal prehľad o tom, ako si stojím s financiami. Jedinou nevýhodou bola neexistencia API pre spojenie Superfaktúry s ľubovoľným custom projektom.Až donedávna, keď bolo jednoduché API uvoľnené spolu so základným popisom rozhrania a ukážkou implementácie v PHP. A tak som si jedno víkendové ráno skrátil sedenie na zimnom štadióne prepísaním tohto API do Python-u (nakoľko som sa rozhodol robiť čo najviac vecí v Python-e).

Výsledkom je API connector, ktorý si môžete vyklonovať z GitHub-u https://github.com/backslash7/pysuperfaktura. Dopredu upozorňujem, že connector je stále len v silnom vývoji, plánujem doprogramovať nejakú tu funkcionalitu naviac, aby sa práca s faktúrami a platbami čo najviac zjednodušila.

Inštalácia je jednoduchá, stačí spustiť súbor setup.py s parametrom install, asi takto:

python setup.py install

Connector používa skvelú knižnicu Requests a priamo na nej závisí. Preto ju odporúčam dopredu nainštalovať, napríklad cez pip:

pip install requests

Samotné používanie connectora je veľmi priamočiare a jednoduché, nasledujúca ukážka je nehanebný copy&paste&edit príkladu z originál PHP connectora:

from pysuperfaktura import client, invoice, SFClient

api_client = SFClient.SFClient('jar-jar@binks.net', 'meesahungry') // Použite svoj SF login a API key
client_params = {
    'name': 'Janko Hrasko',
    'ico': '12345678',
    'dic': '12345678',
    'ic_dph': 'SK12345678',
    'email': 'janko@hrasko.sk',
    'address': 'adresa',
    'city': 'mesto',
    'zip': 'psc',
    'phone': 'telefon',
}

invoice_params = {
    'name': 'nazov faktury',
    'variable': '123456',
    'constant': '0308',
    'specific': '2012',
    'already_paid': True,
    'invoice_no_formatted': '2012001',
    'created': '2012-03-28',
    'delivery': '2012-03-28',
    'due': '2012-03-28',
    'comment': 'komentar',
}

item_params = {
    'name': 'Superfaktura.sk',
    'description': 'Clenstvo',
    'quantity': 1,
    'unit': 'ks',
    'unit_price': 40.83,
    'tax': 20
}
client = client.Client(client_params)
item = invoice.SFInvoiceItem(item_params)
invoice = invoice.SFInvoice(client,invoice_params,[item])

Ako bolo spomenuté, plánujem dodať o niečo prívetivejšie rozhranie s pokročilejšími funkciami. Keďže víkendové rána stále trávim na zimnom štadióne, času bude dostatok :). Toto je môj prvý projekt, ktorý som zavesil na GitHub. Preto ak nájdete nejakú chybu, alebo máte pripomienku, ako to urobiť lepšie/čistejšie, veľmi rád si ju vypočujem. Ostaňte naladení.

P.S.: Pri testovaní tejto verzie klienta som objavil zraniteľnosť, ktorá za určitých okolností umožňovala získať PDF faktúru, ktorá nepatrí danému užívateľovi. V SF sa k tomu postavili naozaj zodpovedne a problém promptne vyriešili (v sobotu poobede!), za čo im patrí moje uznanie a obdiv. Len tak ďalej, chlapci!