# 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.

class superfaktura.bank_account.BankAccountModel(account: str | None, bank_code: str | None, bank_name: str | None, default: int | None, iban: str | None, show: int | None, swift: str | None, id: int | None)

  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.

class superfaktura.client_contacts.ClientContactModel(name: str, address: str | None = None, 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, iban: str | None = None, ic_dph: str | None = None, ico: str | None = None, match_address: int | None = None, phone: str | None = None, swift: str | None = None, tags: str | None = None, uuid: str | None = None, zip: str | None = None, update: bool | None = None, id: int | None = None)

  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=superfaktura.invoice.InvoiceModel(

  >   type=superfaktura.invoice.InvoiceType.PROFORMA, name=”Invoice 3”, due=superfaktura.invoice.Date(“2025-02-01”), invoice_currency=superfaktura.invoice.Currencies.CZK, header_comment=”We invoice you for services”, bank_accounts=[bank.default().as_dict()],

  > ), items=[

  > > superfaktura.invoice.InvoiceItem(name=”Services”, unit_price=100, quantity=1,

  > >   unit=”ks”, tax=21),

  > > superfaktura.invoice.InvoiceItem(name=”SIM card”, unit_price=50, quantity=1,

  > >   tax=21, unit=”ks”),

  > > superfaktura.invoice.InvoiceItem(

  > >   name=”SIM card 2”, unit_price=75, quantity=1, tax=21, unit=”ks”

  > > ),

  > ], contact=superfaktura.client_contacts.ClientContactModel(

  > > name=”Richard Kubíček”, email=”kubicekr@eledio.com”, phone=”+420 123 456 789”, address=”Jaroslava Foglara 861/1”, ico=”123”, update=True, country_id=57,

  > ),

  )

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=InvoiceModel(

    >   type=InvoiceType.PROFORMA, name=”Invoice 3”, due=Date(“2025-02-01”), invoice_currency=Currencies.CZK, header_comment=”We invoice you for services”, bank_accounts=[bank.default().as_dict()],

    > ), items=[

    > > InvoiceItem(name=”Services”, unit_price=100, quantity=1, unit=”ks”, tax=21), InvoiceItem(name=”SIM card”, unit_price=50, quantity=1, tax=21, unit=”ks”), InvoiceItem(

    > > > name=”SIM card 2”, unit_price=75, quantity=1, tax=21, unit=”ks”

    > > ),

    > ], contact=ClientContactModel(

    > > name=”Richard Kubíček”, email=”kubicekr@eledio.com”, phone=”+420 123 456 789”, address=”Jaroslava Foglara 861/1”, ico=”123”, update=True, country_id=57,

    > ),

    )

  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. :param invoice_settings: :param contact: :param items: :param invoice_model:

    Return type:

      InvoiceRespModel

  get_pdf(invoice: InvoiceRespModel, language: str = 'cze') → bytes

    Retrieves the PDF of the invoice.

    Parameters:

      - invoice (InvoiceRespModel) – The response model for the invoice.

      - language (str) – The language for the PDF.

    Returns:

      A bytes containing the PDF data.

    Return type:

      bytes

class superfaktura.invoice.InvoiceItem(name: str, unit_price: float, description: str | None = None, discount: float | None = 0, discount_description: str | None = None, load_data_from_stock: int = 0, quantity: float | None = 1, sku: str | None = None, stock_item_id: int | None = None, tax: float | None = None, unit: str | None = None, use_document_currency: int | None = 0)

  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

class superfaktura.invoice.InvoiceModel(add_rounding_item: int | None = 0, already_paid: int | None = None, 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, type: str | None = None, variable: str | None = None, vat_transfer: int | None = None)

  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

    Type:

      Optional[str]

  error: int
  error_message: str
  invoice_id: int | None = None
  invoice_token: str | None = None

class superfaktura.invoice.InvoiceSettings(language: str | None = None, bysquare: bool | None = None, callback_payment: 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)

  Bases: `object`

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

  as_dict() → dict

    Returns a dictionary representation of the ClientContactModel.

  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 data = api.get(‘endpoint’)

  # Create or update data in the SuperFaktura API api.post(‘endpoint’, data)

class superfaktura.superfaktura_api.SuperFakturaAPI

  Bases: `object`

  Base class for working with the SuperFaktura API.

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

    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 bytes.

    Return type:

      bytes

    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.