README.rst

📢 This package started in 2013 but is still working. In early 2024 it got an update (https://github.com/illagrenan/ares_util/releases/tag/v0.3.0) to work with the new API. At the moment, neither CI nor tests are working, I know that. I will set aside time this year for a bigger update (Github actions, pyproject.toml, ...).

Ares_util

Latest release
CI
Dependencies

Představení

Jednoduchý nástroj pro validaci¹ českého IČ. U předaného IČ je nejdříve ověřen jeho kontrolní součet (viz Reference) a dle výsledku se následně zasílá požadavek na ARES XML API.

Pokud je IČ validní, vrací nástroj dict se základními údaji o firmě (obchodní název, adresa).

Podmínky provozu ARES API

Ministerstvo financí vyhrazuje právo omezit nebo znemožnit přístup k www aplikaci ARES uživatelům, kteří:

• odešlou k vyřízení více než 1000 dotazů v době od 8:00 hod. do 18:00 hod.,
• odešlou k vyřízení více než 5000 dotazů v době od 18:00 hod. do 8:00 hod. rána následujícího dne,
• opakovaně posílají nesprávně vyplněné dotazy,
• opakovaně posílají stejné dotazy,
• mají větší počet současně zadaných dotazů (pro automatizované XML dotazy),
• obcházejí povolené limity využíváním dotazování z většího množství IP adres, -
• automatizovaně propátrávají databázi náhodnými údaji nebo generují většinu nesprávných dotazů.

—Zdroj: Podmínky provozu ARES API.

Instalace

Podporované verze Pythonu jsou pypy, pypy3, 2.7, 3.5, 3.6 a 3.7.

pip install --upgrade ares-util

Použití

python
>>> from ares_util.ares import call_ares
>>> call_ares(42)
False
>>> call_ares('68407700')
{
    u'legal': {
        u'company_vat_id': u'CZ68407700',
        u'company_name': u'České vysoké učení technické v Praze',
        u'legal_form': u'601',
        u'company_id': u'68407700'
    },
    u'address': {
        u'city': u'Praha',
        u'region': u'Hlavní město Praha',
        u'street': u'Zikova 1903/4',
        u'city_part': u'Dejvice',
        u'zip_code': u'16000'
    }
}

Django podpora

Podporované verze Djanga jsou 1.11.x (LTS), 2.0.x a 2.1.x.

K dispozi jsou dva Django validátory formulářových polí:

• czech_company_id_numeric_validator - Ověřuje, zda IČ splňuje statické parametry, tj. 7 nebo 8 číslic a kontrolní součet.
• czech_company_id_ares_api_validator - Platnost IČ ověřuje pomocí ARES API. Tento validátor před ARES požadavkem rovněž ověřuje statické parametry, proto by neměly být použity oba validátory zároveň.

Použití ve formuláři

from ares_util.validators import czech_company_id_numeric_validator, czech_company_id_ares_api_validator
from django import forms

# forms.py
class DemoForm(forms.Form):
    company_id = forms.IntegerField(required=True, validators=[czech_company_id_ares_api_validator])

Reference

1. http://www.abclinuxu.cz/blog/bloK/2008/10/kontrola-ic, http://latrine.dgx.cz/jak-overit-platne-ic-a-rodne-cislo

Lokální vývoj

Chcete-li upravit doplněk lokálně, jednoduše stáhněte zdrojové kódy a nainstalujte závislosti:

pip install -r requirements.txt --upgrade

Testy spustíte pomocí tox nebo inv test. Využít můžete i přibalený Flask server pro lokální testování. Stačí spustit:

python .\server.py
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat

a v prohlížeči otevřít např.: http://127.0.0.1:5000/42.

Technické informace

XML response z ARESu je zpracována pomocí xmltodict.

Licence

The MIT License (MIT)

Copyright (c) 2013–2019 Vašek Dohnal (@illagrenan)