vater’s docs

Introduction

vater is python client providing convenient way to access polish VAT payers register API. Currently supported API version is 1.3.0.

Information about API may be found here: https://www.gov.pl/web/kas/api-wykazu-podatnikow-vat

Installation

Basic usage

pip install vater

or

pip install git+https://github.com/myslak71/vater.git

Development

pip install vater[dev]

Usage

Scripts

>>> import vater
>>> client = vater.Client(base_url='https://wl-api.mf.gov.pl')
>>> client.search_nip(nip='1111111111')
(
  Subject(
    name='Beastie Boys',
    nip='1111111111',
    status_vat='Czynny',
    regon='111111111',
    pesel=None,
    krs='1111111111',
    residence_address=None,
    working_address='Brooklyn',
    representatives=[],
    authorized_clerks=[],
    partners=[
      Company(
        company_name='Mike D',
        first_name='Michael',
        last_name='Diamond',
        nip=None,
        pesel=None
      )
    ],
    registration_legal_date=datetime.date(2001, 1, 1),
    registration_denial_basis=None,
    registration_denial_date=None,
    restoration_basis=None,
    restoration_date=None,
    removal_basis=None,
    removal_date=None,
    account_numbers=['11111111111111111111111111'],
    has_virtual_accounts=False
  ),
  'z5x71-85a8gl5'
)

If you want to get raw server json just set raw to True:

>>> client.search_nip(nip='1111111111', raw=True)
{
  'result': {
    'subject': {
        'name': 'Eminem',
        'nip': '6969696969',
        'statusVat': 'Active',
        'regon': '777777777',
        'pesel': '77777777777',
        'krs': '6969696969',
        'residenceAddress': '8 mile',
        'workingAddress': '8 mile',
        'representatives': [
            {
              'companyName': 'Moby Dick Inc',
              'firstName': 'sir Richard',
              'lastName': 'Lion Heart',
              'nip': '6969696969',
              'pesel': '77777777777'
            }
        ],
        'authorizedClerks': [],
        'partners': [],
        'registrationLegalDate': '2001-01-01',
        'registrationDenialBasis': 'Denial Basis',
        'registrationDenialDate': '2002-02-02',
        'restorationBasis': 'Restoration Basis',
        'restorationDate': '2003-03-03',
        'removalBasis': 'Removal Basis',
        'removalDate': '2004-04-04',
        'accountNumbers': ['11111111111111111111111111'],
        'hasVirtualAccounts': False
  },
  'requestId': 'aa111-aa111aaa',
  }
}

By default the data is fetched from today’s date, it can be changed by setting date argument:

>>> import datetime
>>> client.search_nip(nip='1111111111', date=datetime.date(2001, 1, 1))

String may also be passed as a date:

>>> client.search_nip(nip='1111111111', date='2001-01-01')

Keep in mind the API limits maximum number of requested subjects to 30.

CLI

Commands

command
vater search-nip [ACCOUNT]
vater search-nip [ACCOUNTS]
vater search-nip [NIP]
vater search-nips [NIPS]
vater search-nips [REGON]
vater search-nips [REGONS]
vater check-nip [NIP] [ACCOUNT]
vater check-regon [REGON] [ACCOUNT]

Parameters

parameter	default	description
--date	today	date in YYYY-MM-DD format
--url	https://wl-api.mf.gov.pl	vat register API url

Client

Vat register client module.

class vater.client.Client(base_url)

Bases: object

Vat register client class.

Currently the API limits maximum number of requested subjects to 30, therefore if that number is exceeded MaximumParameterNumberExceeded is raised.

Set root API url.

Parameters:base_url (str) – root url of the API

check_nip(nip, account, *, date=None, raw=False)

Check if given account is assigned to the subject with given nip.

Parameters:

• nip (str) – nip number of the subject to check
• account (str) – account number of the subject to check
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[bool, str]

check_regon(regon, account, *, date=None, raw=False)

Check if given account is assigned to the subject with given regon.

Parameters:

• regon (str) – regon number of the subject to check
• account (str) – account number of the subject to check
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[bool, str]

search_account(account, *, date=None, raw=False)

Get detailed vat payer information for given bank account.

Parameters:

• account (str) – account number of the subject to fetch
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[List[Subject], str]

search_accounts(accounts, *, date=None, raw=False)

Get a list of detailed vat payers information.

Parameters:

• accounts (Iterable[str]) – account numbers of the subjects to fetch
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[List[Subject], str]

search_nip(nip, *, date=None, raw=False)

Get detailed vat payer information for given nip.

Parameters:

• nip (str) – nip number of the subject to fetch
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[Optional[Subject], str]

Returns:

subject and request id

search_nips(nips, *, date=None, raw=False)

Get a list of detailed vat payers information.

Parameters:

• nips (Iterable[str]) – nip numbers of the subjects to fetch
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[List[Subject], str]

search_regon(regon, *, date=None, raw=False)

Get detailed vat payer information for given regon.

Parameters:

• regon (str) – regon number of the subject to fetch
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[Optional[Subject], str]

search_regons(regons, *, date=None, raw=False)

Get a list of detailed vat payers information.

Parameters:

• regons (Iterable[str]) – regon numbers of the subjects to fetch
• date (Optional[date]) – date data is acquired from
• raw (bool) – flag indicating if raw json from the server is returned or python object representation

Return type:

Tuple[List[Subject], str]

Models

Schemas and models module.

class vater.models.Company(company_name, first_name, last_name, nip, pesel)

Bases: object

Class representing company in vat payers register.

class vater.models.CompanySchema(*, only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None)

Bases: marshmallow.schema.Schema

Schema for company entity.

make_company(data, **kwargs)

Create a company instance.

Return type:Company

opts = <marshmallow.schema.SchemaOpts object>

class vater.models.Subject(name, nip, status_vat, regon, pesel, krs, residence_address, working_address, representatives, authorized_clerks, partners, registration_legal_date, registration_denial_basis, registration_denial_date, restoration_basis, restoration_date, removal_basis, removal_date, account_numbers, has_virtual_accounts)

Bases: object

Class representing subject in vat payers register.

class vater.models.SubjectSchema(*, only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None)

Bases: marshmallow.schema.Schema

Schema for subject entity.

make_subject(data, **kwargs)

Create a subject instance.

Return type:Subject

opts = <marshmallow.schema.SchemaOpts object>

Indices and tables

• Index
• Module Index
• Search Page