nette-ares

nette-ares je rozšíření pro Nette, které podle IČO nebo názvu načte firmu z ARES: obchodní jméno, sídlo, DIČ a právní formu. Doplní nuly v IČO, umí ověřit kontrolní součet a drží výsledky v cache.

nette-ares: vyhledání Ministerstva financí podle IČO 6947 v ARES, odpověď z cache a hledání podle názvu

nette-ares je rozšíření pro Nette, které podle IČO nebo názvu stáhne údaje o firmě z ARES, státního registru ekonomických subjektů. Typická situace: zákazník se registruje do velkoobchodu a v objednávkovém formuláři vyplňuje obchodní jméno, sídlo, PSČ a DIČ. Opíše je z faktury nebo z hlavy, prohodí číslo popisné s orientačním, zapomene „s.r.o.“ a chyba pak putuje na každý další doklad. Když formulář vezme jen IČO a zbytek doplní z ARES, píše uživatel osm číslic místo šesti polí a údaje odpovídají tomu, co o firmě vede stát.

Co z ARES přijde do formuláře

Metoda findByIco() vrátí objekt AresResult s obchodním jménem, DIČ, kódem právní formy, ulicí, číslem popisným i orientačním včetně písmene, obcí, částí obce, PSČ, kódem státu, celou adresou jako text a daty vzniku a zániku. Pro formulář jsou připravené pomocné metody: getStreet() složí „Letenská 525/15“, getFormattedPsc() vrátí „118 00“ a getCity() přidá k obci její část, pokud se liší. toArray() dá totéž jako pole s anglickými klíči (company, street, city, zip) a s příznakem isPhysicalPerson, který podle kódu právní formy 100 až 109 pozná podnikající fyzickou osobu. To se hodí, když se formulář pro živnostníka ptá na jiné věci než pro akciovou společnost.

Hledání podle názvu (searchByName()) chce aspoň tři znaky a vrátí nejvýš tolik firem, kolik určí limit, výchozí je deset, strop sto. Na snímku nahoře vrátil dotaz „Ministerstvo“ s limitem pět pět ministerstev i s jejich IČO.

Uživatel napíše 6947, knihovna se zeptá na 00006947

IČO státních institucí a starších firem začíná nulami a lidé je vynechávají. Knihovna před dotazem odstraní mezery a doplní nuly zleva na osm číslic, takže „6947“ i „00 006 947“ najdou Ministerstvo financí. Cokoli, co ani potom není osm číslic, skončí výjimkou AresException dřív, než se odešle požadavek. Kontrolní součet findByIco() neověřuje, ten hlídá samostatná statická metoda AresClient::isValidIco() (modulo 11, bez volání sítě), takže překlep jde odmítnout dřív, než se zeptá ARES. Neexistující číslo se správným součtem pozná až ARES a vrátí 404, kterou knihovna převede na tutéž výjimku s kódem 404.

Druhý dotaz už nejde do sítě

Výsledky se ukládají do úložiště Nette Caching na dobu nastavenou v cacheTtl, výchozí je jeden měsíc. Při zkoušce na PHP 8.4 trval první dotaz na ARES 213 až 430 ms, opakovaný dotaz na totéž IČO ze souborové cache kolem 5 ms. Cache se dá smazat pro jedno IČO (clearCacheByIco()) nebo celá (clearCache()), což se hodí po změně sídla. Neúspěšné dotazy se neukládají, takže překlep v IČO nezůstane v cache jako „nenalezeno“.

Napojení na formulář

Rozšíření se zaregistruje samo přes extra.nette.extensions v composer.json a do kontejneru přidá službu AresClient. Nejčastější použití je obsluha AJAXového požadavku, kterou volá skript formuláře po vyplnění IČO:

public function handleAresLookup(string $ico): void
{
    try {
        $this->sendJson($this->ares->findByIco($ico)->toArray());
    } catch (AresException $e) {
        $this->sendJson(['error' => $e->getMessage()]);
    }
}

Chybové zprávy jsou česky („Neplatné IČO“, „Subjekt s IČO '12345678' nebyl nalezen v ARES“), takže je jde rovnou ukázat uživateli. Pro kontrolu plátce DPH stačí getDic().

Zaniklá firma a výpadek ARES

isActive() vrací false pro firmu s datem zániku, pro IČO, které ARES nezná (HTTP 404), i pro chybně napsané IČO. Když je ARES nedostupný, vyprší čas nebo odpoví chybou serveru, metoda vyhodí AresException, takže výpadek se nezamění se zánikem firmy. Výjimka „nenalezeno“ má kód 404, ostatní chyby API nesou HTTP stav a výpadek spojení kód 0.

Bez další závislosti

Knihovna volá REST API ARES verze 3 (GET /ekonomicke-subjekty/{ico} a POST /ekonomicke-subjekty/vyhledat) vestavěnými funkcemi PHP. Nepotřebuje Guzzle ani jiného HTTP klienta, jen balíčky Nette pro DI, cache, schéma konfigurace a JSON. Spojení ověřuje certifikát serveru a na odpověď čeká nejvýš 10 sekund. ARES nevyžaduje přihlášení ani API klíč.

Na co si dát pozor

  • Výsledek findByIco() se drží v cache po dobu cacheTtl (výchozí měsíc), takže i isActive() vidí zánik firmy až po vypršení cache nebo po clearCacheByIco().
  • searchByName() hledá jen podle obchodního jména; podle adresy ani DIČ vyhledávat nejde.

Testy

Od verze 1.1.0 má repozitář testy v Nette Tester. HTTP vrstvu nahrazují připravenou odpovědí, takže běží bez sítě a pokrývají isActive() (aktivní, zaniklá, neznámá a chybná firma, výpadek, chyba serveru), text výjimky „nenalezeno“ a kontrolní součet. Prošly na PHP 8.1 i 8.4. Snímek vznikl ručním během proti živému ARES 6. listopadu 2026.

Jak začít

composer require nks-hub/nette-ares

Potřeba je PHP 8.1 nebo novější a Nette 3.1 nebo 4. Konfigurace je volitelná, jediný parametr je doba platnosti cache (ares: cacheTtl: '1 week'). Poslední verze je 1.1.0 z 6. listopadu 2026.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/nette-ares pod licencí MIT. Balíček je na Packagistu jako nks-hub/nette-ares. Pro adresy osob a doručovací adresy, které v ARES nejsou, je tu sesterská knihovna nette-ruian.

← Všechny reference