Skip to main content

Python client library for the Fakturownia API

Project description

Python client library for the Fakturownia API Documentation Status coverage CodeCov coverage Maintainability License Tweet about this project!-1EAEDB.svg

If you don’t know it yet be sure to check it out:

Polecam - prosty program do fakturowania online


  • ☑ Invoice CRUD plus send_by_email and ‘mark_paid`
  • ☑ EU member states VAT rate helpers for B2C transactions
  • ☑ ApiClient CRUD
  • ☐ Payments CRUD
  • ☐ Products CRUD
  • ☐ Warehouse documents CRUD
  • ☐ Accounts management

Please refer to the fakturownia APIs for full API features


Install Fakturownia

pip install fakturownia python

Play with fakturownia APIs in python interpreter:

>>> import os
>>> os.environ.get('FAKTUROWNIA_API_TOKEN', 'Missing key')
>>> from fakturownia import get_api_client
>>> api = get_api_client()
>>> invoice = api.invoices.create(
...     seller_name='Kabaret Starszych Panów',
...     buyer_name='Odrażający drab',
...     positions=[{
...         'name': 'Smolna szczapa',
...         'quantity': 5,
...         'total_price_gross': 7.33,
...     }],
... )
>>> invoice.view_url

This instance is only partially updated as create returns only subset of data properties, to get all we need to update our instance.

If you have payments enabled you can call get to fetch all data and check payment_url:

>>> invoice.get()
<fakturownia.endpoints.Invoice object at 0x...>
>>> invoice.payment_url

We can mark this invoice as paid:

>>> invoice.mark_paid()
<fakturownia.endpoints.Invoice object at 0x...>

You can chain your calls:

>>> invoice.put(buyer_email='').send_by_email()
<fakturownia.endpoints.Invoice object at 0x...>

You can play and test your scenarios wih factories:

pip install fakturownia[factories]

Now you can do this:

>>> from fakturownia.factories import InvoiceFactory
>>> InvoiceFactory(api_client='<your api key here>', kind='proforma').post().get().payment_url # doctest: +SKIP

Also checkout VAT tax normalization based on EU country specific VAT rates:

>>> InvoiceFactory(
...     api_client=api,
...     seller_country='PL',
...     buyer_country='DE',
...     buyer_tax_no=None,
... ).normalize_vat().post().view_url

Neat! :)

Running Tests

Does the code actually work?

pipenv install --dev
pipenv shell

We recommend using pipenv but a legacy approach to creating virtualenv and installing requirements should also work. Please install requirements/base.txt and requirements/development.txt to setup virtual env for testing and development.

Help wanted

This library is not yet complete. It does what was needed by up to date contributors, but more can be done. You can implement new api endpoints and write test for them, it’s actually straightforward and new classes will be simple, but tests need some effort. We are lazy test writers and because we don’t want to compromise coverage so we postponed new apis until someone would want to write test.

If want to help please refer to the contributing section in the docs for more info.


This package was created with Cookiecutter and the wooyek/cookiecutter-pylib project template.


0.1.0 (2018-01-03)

  • First release on PyPI.

0.1.2 (2018-01-10)

  • endpoints indexing
  • Robust testing with mocked and real interchangeable backeds .

0.2.1 (2018-01-12)

  • EU member states VAT rate helpers for B2C transactions
  • FAKTUROWNIA_TIMEOUT setting for request timeout

0.2.2 (2018-01-18)

  • Payload data cleanup from readonly fields so get().put() is possible

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for fakturownia, version 0.2.2
Filename, size File type Python version Upload date Hashes
Filename, size fakturownia-0.2.2-py2.py3-none-any.whl (16.0 kB) File type Wheel Python version 3.5 Upload date Hashes View
Filename, size fakturownia-0.2.2.tar.gz (65.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page