=== ARES Company Lookup ===
Contributors: socionet
Tags: ares, ico, czech, company, autofill
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Type an IČO and the company name, DIČ and address fill in from ARES. Works in any form. No API key.

== Description ==

Czech business customers do not like typing company details twice. ARES Company Lookup fills them in from ARES, the public register of economic entities run by the Czech Ministry of Finance: the visitor types an IČO and the company name, DIČ and registered office appear in your form.

Plugins that do this exist for WooCommerce checkouts. This one works in **any form** on any WordPress site, with no add-on for your form builder: you just give the fields CSS classes.

**What you get**

* **Autofill for any form.** Contact Form 7, WPForms, Fluent Forms, Gravity Forms, Elementor forms or a plain HTML form. Add the class `ares-ico` to the IČO field and `ares-name`, `ares-dic`, `ares-street`, `ares-city`, `ares-zip` or `ares-address` to the fields to fill.
* **Never overwrites the visitor.** A field the visitor edited by hand is left alone.
* **IČO checked at once.** The check digit is verified in the browser and on the server, so a typo is caught before ARES is asked.
* **Company card.** `[ares_firma ico="45274649"]` shows name, IČO, DIČ (and whether the company is a VAT payer), registered office, legal form and the date it was established, with a warning for a company that no longer exists.
* **Public lookup field.** `[ares_firma]` without an IČO shows a field where your visitors look up any company, for example on a page about invoicing.
* **Blocks.** The block "ARES company" does the same in the block editor.
* **Czech and English interface** (cs_CZ translation included).

**Built to be a good neighbour**

* The free public ARES API, no key and no account.
* Your visitors never talk to ARES. The browser asks your site and your site asks ARES, so a visitor's address is not passed on, and answers are cached (7 days by default) which is also kind to ARES.
* Rate limit of 30 lookups per visitor per 5 minutes, so the route cannot be used as an open proxy. Only a salted hash of the address is kept, for the length of that window.
* No tracking, no ads, no upsell. Everything stored (settings and cached companies) is removed when you delete the plugin.

**Contact Form 7 example**

`[text* ico class:ares-ico]`
`[text* firma class:ares-name]`
`[text dic class:ares-dic]`
`[text ulice class:ares-street]`
`[text mesto class:ares-city]`
`[text psc class:ares-zip]`

The plugin is made by [Socionet](https://socionet.cz/), a Czech web design studio.

== External services ==

This plugin asks one external service: ARES (Administrativní registr ekonomických subjektů), the public register of economic entities run by the Czech Ministry of Finance, at `https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/`.

* **What is sent:** only the IČO (company number) a visitor typed, from your server, when the company is not in the cache yet. No visitor address, cookie or site detail is sent; the user agent is the plugin's name and version.
* **When:** at the first lookup of an IČO, and again after the cache period (7 days by default), or when a card shortcode is rendered for an IČO that is not cached.
* **Terms:** the data in ARES is public; see the [ARES site](https://ares.gov.cz/) and the [Ministry of Finance's terms for the ARES API](https://ares.gov.cz/stranky/vyvojari-info).

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`, or install it from Plugins > Add New.
2. Activate it.
3. Give your form fields the CSS classes listed under Settings > ARES, or place `[ares_firma]` on a page.

== Frequently Asked Questions ==

= Do I need an API key? =

No. The plugin uses the public ARES REST service of the Ministry of Finance, which needs no registration.

= Where does the data come from, and how current is it? =

From ARES at the moment of the first lookup. Answers are cached for 7 days (1 to 30 in the settings) and you can clear the cache with one button.

= How do I add the classes in Contact Form 7, WPForms, Elementor? =

Contact Form 7: add `class:ares-ico` to the tag. WPForms and Fluent Forms: the field's "CSS Classes" setting. Gravity Forms: "Custom CSS Class" under Appearance. Elementor: the field's "CSS Classes" under Advanced.

= Does it work for sole traders (OSVČ)? =

Yes, ARES lists them too. Their DIČ is shown as ARES publishes it.

= What if ARES is down? =

The visitor sees a short message and fills in the details by hand. A failed lookup is remembered for a minute only.

= Does it conflict with my cache plugin? =

No. The lookup is a live request to your site's REST API and is not page cached.

= Is the IP address of my visitors sent to ARES? =

No. Only your server contacts ARES, and it sends nothing but the IČO.

== Screenshots ==

1. A company form filled from ARES after typing the IČO.
2. The company card shortcode.
3. Settings: the CSS classes, options and a test lookup.
4. The public lookup field on a phone.

== Changelog ==

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.0.0 =
First release.
