SuperFaktura API client

Bank account

Bank Account Module.

This module provides classes and functions for working with bank accounts in the SuperFaktura API. It allows for retrieving, creating, updating, and deleting bank accounts.

Classes:

BankAccountModel: Dataclass representing a bank account.
BankAccount: Class for interacting with bank accounts.

Exceptions:

NoDefaultBankAccountException: Exception for when no default bank account is found.

Functions:

(none)

Usage:

>>> import superfaktura.bank_account
>>> # Create an instance of BankAccount
>>> bank = superfaktura.bank_account.BankAccount()
>>> # Retrieve a list of bank accounts
>>> accounts = bank.list()
>>> # Get the default bank account
>>> default_account = bank.default()
>>> # Create or update a bank account
>>> data = {"account": "1234567890", "bank_code": "1234567890", "default": True}
>>> bank.post(data)

class superfaktura.bank_account.BankAccount

Bases: SuperFakturaAPI

Bank Account Class.

This class provides methods for interacting with bank accounts in the SuperFaktura API. It allows for retrieving, creating, updating, and deleting bank accounts.

- list: Retrieves a list of bank accounts.

- default: Retrieves the default bank account.

- post: Creates or updates a bank account.

Usage:

>>> bank = BankAccount()
>>> accounts = bank.list()
>>> default_account = bank.default()
>>> data = {"account": "1234567890", "bank_code": "1234567890", "default": True}
>>> bank.post(data)

default() → BankAccountModel | None: Retrieves the default bank account.

list() → dict: Retrieves a list of bank accounts.

Bases: object

Dataclass representing a bank account.

account: str | None

as_dict() → dict: Returns a dictionary representation of the BankAccountModel.

bank_code: str | None

bank_name: str | None

default: int | None

static from_dict(data: dict) → BankAccountModel: Creates a BankAccountModel from a dictionary.

iban: str | None

id: int | None

show: int | None

swift: str | None

exception superfaktura.bank_account.NoDefaultBankAccountException

Bases: Exception

Exception for when no default bank account is found.

Client contacts

Module for interacting with client contacts in SuperFaktura.

This module provides classes and functions for working with client contacts, including creating, reading, and updating contact information.

Classes:: ClientException: Base class for client exceptions. ClientContactModel: Dataclass representing a client contact.
Functions:: (none)
Variables:: (none)

Notes

This module uses the SuperFaktura API to interact with client contacts. You must have a valid API key and credentials to use this module.

class superfaktura.client_contacts.ClientContact

Bases: SuperFakturaAPI

Client contact class.

add_contact(contact: ClientContactModel) → bool: Adds a new client contact.

get_client(client_id: int) → ClientContactModel: Gets a client contact by ID.

list() → dict: Lists all exists client contacts.

Bases: object

Client contact model.

address: str | None = None

as_dict() → dict: Returns a dictionary representation of the ClientContactModel.

bank_account: str | None = None

bank_code: str | None = None

city: str | None = None

comment: str | None = None

country: str | None = None

country_id: int | None = None

currency: str | None = None

default_variable: str | None = None

delivery_address: str | None = None

delivery_city: str | None = None

delivery_country: str | None = None

delivery_country_id: int | None = None

delivery_name: str | None = None

delivery_phone: str | None = None

delivery_zip: str | None = None

dic: str | None = None

discount: float | None = None

due_date: int | None = None

email: str | None = None

fax: str | None = None

static from_dict(data: dict) → ClientContactModel: Creates a ClientContactModel from a dictionary.

iban: str | None = None

ic_dph: str | None = None

ico: str | None = None

id: int | None = None

match_address: int | None = None

name: str

phone: str | None = None

swift: str | None = None

tags: str | None = None

update: bool | None = None

uuid: str | None = None

zip: str | None = None

exception superfaktura.client_contacts.ClientException

Bases: Exception

Base class for client exceptions.

Invoice

Invoice Module.

This module provides classes and functions for working with invoices in the SuperFaktura API. It allows for retrieving, creating, updating, and deleting invoices.

Classes:

InvoiceModel: Dataclass representing an invoice.
InvoiceItem: Dataclass representing an invoice item.
Invoice: Class for interacting with invoices.

Exceptions:

NoDefaultBankAccountException: Exception for when no default bank account is found.

Functions:

(none)

Usage:

>>> import superfaktura.invoice
>>> # Create an instance of Invoice
>>> invoice = superfaktura.invoice.Invoice()
>>> # Create an invoice
>>> invoice.add(
    invoice_model=InvoiceModel(
        type=InvoiceType.INVOICE,
        name="My First Invoice",
        due=Date("2025-04-01"),
        invoice_currency=Currencies.EUR,
        header_comment="We invoice you for services",
        bank_accounts=[bank.default().as_dict()],
    ),
    items=[
        InvoiceItem(
            name="Website Development", unit_price=1000.0, quantity=1, tax=20
        ),
        InvoiceItem(
            name="Hosting Service (1 year)", unit_price=500.0, quantity=1, tax=20
        ),
    ],
    contact=ClientContactModel(
        name="John Doe",
        email="john.doe@examle.com",
        phone="+1 555-1234",
        address="123 Main Street, New York",
        ico="987654321",
        update=True,
        country_id=225,
    ),
)

class superfaktura.invoice.Invoice

Bases: SuperFakturaAPI

Invoice Class.

This class provides methods for interacting with invoices in the SuperFaktura API. It allows for retrieving, creating, updating, and deleting invoices.

- add: Creates a new invoice.

- get: Retrieves an invoice by ID.

- list: Retrieves a list of invoices.

- update: Updates an existing invoice.

Usage:

>>> invoice = Invoice()
>>> invoice.add(
    invoice_model=InvoiceModel(
        type=InvoiceType.INVOICE,
        name="My First Invoice",
        due=Date("2025-04-01"),
        invoice_currency=Currencies.EUR,
        header_comment="We invoice you for services",
        bank_accounts=[bank.default().as_dict()],
    ),
    items=[
        InvoiceItem(
            name="Website Development", unit_price=1000.0, quantity=1, tax=20
        ),
        InvoiceItem(
            name="Hosting Service (1 year)", unit_price=500.0, quantity=1, tax=20
        ),
    ],
    contact=ClientContactModel(
        name="John Doe",
        email="john.doe@example.com",
        phone="+1 555-1234",
        address="123 Main Street, New York",
        ico="987654321",
        update=True,
        country_id=225,
    ),
)

add(invoice_model: InvoiceModel, items: List[InvoiceItem], contact: ClientContactModel, invoice_settings: InvoiceSettings | None = None) → InvoiceRespModel

Adds a new invoice.

Parameters:

invoice_model (InvoiceModel) – The invoice model.
items (List[InvoiceItem]) – List of invoice items.
contact (ClientContactModel) – The client contact model.
invoice_settings (Optional[InvoiceSettings]) – The invoice settings.

Returns:

The response model for the invoice.

Return type:

InvoiceRespModel

get_pdf(invoice: InvoiceRespModel, descriptor: IO[bytes], language: str = 'cze') → None

Retrieves the PDF of the invoice.

Parameters:

invoice (InvoiceRespModel) – The response model for the invoice.
descriptor (IO[bytes]) – The descriptor to write the PDF data to.
language (str) – The language for the PDF.

Returns:

None

Bases: object

This dataclass represents an invoice item in the SuperFaktura API.

as_dict() → dict: Returns a dictionary representation of the InvoiceItem.

description: str | None = None

discount: float | None = 0

discount_description: str | None = None

load_data_from_stock: int = 0

name: str

quantity: float | None = 1

sku: str | None = None

stock_item_id: int | None = None

tax: float | None = None

unit: str | None = None

unit_price: float

use_document_currency: int | None = 0

Bases: object

This dataclass represents an invoice in the SuperFaktura API.

add_rounding_item: int | None = 0

already_paid: int | None = None

as_dict() → dict: Returns a dictionary representation of the InvoiceModel.

bank_accounts: List[dict] | None = None

comment: str | None = None

constant: str | None = None

created: Date | None = None

delivery: Date | None = None

delivery_type: str | None = None

deposit: float | None = None

discount: float | None = 0

discount_total: float | None = None

due: Date | None = None

estimate_id: int | None = None

header_comment: str | None = None

internal_comment: str | None = None

invoice_currency: str | None = None

invoice_no_formatted: str | None = None

issued_by: str | None = None

issued_by_email: str | None = None

issued_by_phone: str | None = None

issued_by_web: str | None = None

logo_id: int | None = None

mark_sent: int | None = None

mark_sent_message: str | None = None

mark_sent_subject: str | None = None

name: str | None = None

order_no: str | None = None

parent_id: int | None = None

paydate: Date | None = None

payment_type: str | None = None

proforma_id: str | None = None

rounding: str | None = None

sequence_id: int | None = None

specific: str | None = None

tax_document: int | None = None

to_dict() → dict: Converts the Record object to a dictionary for JSON serialization.

type: str | None = None

variable: str | None = None

vat_transfer: int | None = None

class superfaktura.invoice.InvoiceRespModel(error: int, error_message: str, invoice_id: int | None = None, invoice_token: str | None = None)

Bases: object

This dataclass represents the response model for an invoice in the SuperFaktura API.

- error

The error code.

Type:: int

- error_message

The error message.

Type:: str

- invoice_id

The ID of the invoice.

Type:: Optional[int]

- invoice_token

The token of the invoice.

Type:: Optional[str]

error: int

error_message: str

invoice_id: int | None = None

invoice_token: str | None = None

Bases: object

This dataclass represents the settings for an invoice in the SuperFaktura API.

as_dict() → dict: Returns a dictionary representation of the InvoiceSettings.

bysquare: bool | None = None

callback_payment: str | None = None

language: str | None = None

online_payment: bool | None = None

payment_info: bool | None = None

paypal: bool | None = None

show_prices: bool | None = None

signature: bool | None = None

summary_bg_color: str | None = None

class superfaktura.invoice.InvoiceType

Bases: object

Invoice Type Enumeration.

This enumeration represents the different types of invoices that can be created.

Usage:: invoice_type = InvoiceType.PROFORMA

INVOICE = 'regular'

PROFORMA = 'proforma'

SuperFaktura API

SuperFaktura API Client.

This module provides classes and functions for working with the SuperFaktura API. It allows for reading, creating, updating, and deleting data in SuperFaktura.

Classes:

SuperFakturaAPI: The base class for working with the SuperFaktura API.
SuperFakturaAPIException: An exception for errors when working with the SuperFaktura API.
SuperFakturaAPIMissingCredentialsException: An exception for missing login credentials.

Functions:

get: Retrieves data from the SuperFaktura API.
post: Creates or updates data in the SuperFaktura API.

Usage:

>>> import superfaktura.superfaktura_api
>>> # Create an instance of SuperFakturaAPI
>>> api = superfaktura.superfaktura_api.SuperFakturaAPI()
>>> # Retrieve data from the SuperFaktura API
>>> incoming_data = api.get('endpoint')
>>> # Create or update data in the SuperFaktura API
>>> api.post('endpoint', outgoing_data)

class superfaktura.superfaktura_api.SuperFakturaAPI

Bases: object

Base class for working with the SuperFaktura API.

download(endpoint: str, descriptor: IO[bytes], timeout: int = 5) → None

Download data stream from the SuperFaktura API.

Download data stream from the specified endpoint in the SuperFaktura API.

Parameters:

endpoint (str) – The API endpoint to retrieve data from (e.g. ‘invoices’, ‘clients’, etc.).
descriptor (IO[bytes]) – The descriptor to write the data stream to.
timeout (int, optional) – The timeout for the API request in seconds. Defaults to 5.

Returns:

None

Raises:

SuperFakturaAPIException – If the API request fails or returns an error.

Examples

>>> api = SuperFakturaAPI()
>>> with open("data.pdf", "wb") as f:
>>>     api.download("some/endpoint", descriptor=f)

Notes

The available endpoints can be found in the SuperFaktura API documentation.

get(endpoint: str, timeout: int = 5) → Dict

Retrieves data from the SuperFaktura API.

Retrieves data from the specified endpoint in the SuperFaktura API.

Parameters:

endpoint (str) – The API endpoint to retrieve data from (e.g. ‘invoices’, ‘clients’, etc.).
timeout (int, optional) – The timeout for the API request in seconds. Defaults to 5.

Returns:

The retrieved data in JSON format.

Return type:

Dict

Raises:

SuperFakturaAPIException – If the API request fails or returns an error.

Examples

>>> api = SuperFakturaAPI()
>>> data = api.get('invoices')
>>> print(data)

Notes

The available endpoints can be found in the SuperFaktura API documentation.

post(endpoint: str, data: str, timeout: int = 5) → Dict

Creates or updates data in the SuperFaktura API.

Creates or updates data in the specified endpoint in the SuperFaktura API.

Parameters:

endpoint (str) – The API endpoint to create or update data in (e.g. ‘invoices’, ‘clients’, etc.).
data (str) – The data to be created or updated in JSON format.
timeout (int, optional) – The timeout for the API request in seconds. Defaults to 5.

Returns:

The created or updated data in JSON format.

Return type:

Dict

Raises:

SuperFakturaAPIException – If the API request fails or returns an error.

Examples

>>> api = SuperFakturaAPI()
>>> data = '{"name": "Example Invoice", "amount": 100.0}'
>>> response = api.post('invoices', data)
>>> print(response)

Notes

The available endpoints can be found in the SuperFaktura API documentation. The data should be a valid JSON string.

exception superfaktura.superfaktura_api.SuperFakturaAPIException

Bases: Exception

Exception for errors when working with the SuperFaktura API.

exception superfaktura.superfaktura_api.SuperFakturaAPIMissingCredentialsException

Bases: Exception

Exception for missing login credentials.