External Integrations — ARES

Business Context

Business-Level Definition

ARES (Administrativní registr ekonomických subjektů) is a publicly accessible Czech business registry operated by the Ministry of Finance. It aggregates data from multiple Czech administrative registries (OR, RES, RŽP) and provides a single lookup point for identifying legal entities by company name or tax ID (IČO).

EM3 uses ARES wherever a form field requires identifying a legal entity — building owners, managers, delegated managers, and organisations in the client registry. The integration removes the need for manual data entry of company name and IČO, reduces transcription errors, and ensures that the data matches the official registry.

Link: https://ares.gov.cz/

Requirements Definition

• Any form field that captures a legal entity must offer ARES autocomplete as the primary input method
• The integration must degrade gracefully — if ARES is unavailable, the user can enter data manually without losing any functionality
• Natural persons (fyzické osoby) without IČO must be supported alongside legal entities
• Fields that link to the organisation registry (building owner/manager/delegated manager; the organisation form) must combine internal organisation matches with live ARES results in a single dropdown, preferring the internal match when both represent the same subject

Acceptance Criteria

• Any form field capturing a legal entity offers ARES autocomplete
• The autocomplete degrades gracefully to manual entry if ARES is unavailable or times out
• A natural person can be entered as free text without an IČO
• Organisation-linked fields merge live ARES results with existing internal organisation records, deduplicating by exact IČO match

Loom Link

N/A — not available in the source material.

Technical Context

User Stories / Use Cases

Look up an organisation by name or IČO: A user starts typing a company name (min. 3 characters) or an 8-digit IČO into an ARES-enabled field. After a debounce, the system queries ARES and shows a ranked dropdown. Selecting a result populates the entity's *name and *ico fields automatically.

Enter a natural person without IČO: A user types a person's name as free text without selecting an ARES result. The *ico field remains null; this is always a valid entry path.

ARES unavailable: ARES does not respond within 3 seconds, or errors. The autocomplete dropdown does not appear; the user enters name and IČO manually in separate inputs.

Link to an existing organisation: On an organisation-linked field (building owner/manager/delegated manager, client organisation form), the dropdown merges live ARES results with existing internal organisation records matched by IČO. Selecting the internal result links to it without creating a duplicate; selecting an ARES-only result or free text creates a new organisation record.

UI/UX Design

Not covered in source material.

Functional Requirements

What ARES provides

For each registered legal entity, the ARES v3 REST API returns: IČO (8-digit identifier), official company name, registered address, legal form, and activity status (active / dissolved). Natural persons without IČO are not searchable and must be entered as free text.

Behaviour specification

Each form field that uses ARES lookup is implemented as a single autocomplete input. The complete behaviour:

• The user types either a company name (minimum 3 characters) or an IČO (8 digits).
• The system queries ARES in real time with debounce (≥300 ms after the last keystroke) and displays a ranked dropdown of matching results.
• When the user selects a result, the corresponding *name and *ico fields on the entity are populated automatically. The display format in the input is: NázevFirmy (IČO).
• If the user does not select a result (natural person, unregistered entity, or manual entry preference), they type the name as free text. The *ico field remains null. Free text is always valid — there is no requirement to select from ARES.
• If ARES is unavailable or the request times out (threshold: 3 seconds), the field degrades gracefully: the autocomplete dropdown is not shown, and the user can enter both name and IČO manually in separate inputs.
• Organisation-linked fields (building.owner/.manager/.delegatedManager; the organisation form) extend this behaviour:
  • the dropdown merges live ARES results with existing organisation records matched by IČO
  • when an internal record and an ARES result represent the same subject, only the internal record is shown
  • selecting an internal result links to the existing organisation without creating a new one
  • selecting an ARES-only result or free-text entry creates a new organisation record
  • deduplication is by exact IČO match only — natural persons without an IČO are not deduplicated and may produce multiple organisation records for the same underlying person

Non-Functional Requirements

Not covered in source material beyond the timeout/debounce thresholds captured under Functional Requirements above.

Implementation Notes

• The backend proxies to the ARES v3 REST API at https://ares.gov.cz/ekonomicke-subjekty-v-be/rest and normalises the response into the schema described below.
• Error handling: if ARES returns a non-2xx response or times out, the endpoint returns an empty result array (not an error status) so the UI can fall back to manual entry without displaying an error to the user.
• ARES results are not cached persistently — each lookup queries the live API. UI-level debounce (≥300 ms) prevents excessive requests during typing.
• Timeout threshold: 3 seconds. If the ARES request does not complete within this window, the backend returns an empty array and logs a timeout event.

API Analysis

The backend exposes a single shared proxy endpoint used by all features:

GET /v1/ares/lookup?q=:query

query — IČO (8 digits) or company name substring (min 3 chars)
Returns: ranked array of { ico, name, address, legalForm }

Used by: Building Management (owner, manager, delegated manager fields), Client Management (client identification, organisation registry). For organisation-linked fields, this endpoint is combined with an internal organisation lookup as described above.

Domain Model (ER diagram) & Data Attribute Table

No dedicated entity — ARES is a stateless proxy integration. Fields it populates (*name, *ico) live on the consuming entities (building, organisation, client) — see Building Management and Client Management.

Data

Not covered in source material.

Test Data

N/A — not covered in source material.

Logging

.debug

• ARES lookup triggered (query string, source field, calling feature)
• ARES lookup result: success (number of results returned) / timeout / not found / ARES error (HTTP status)

Monitoring

N/A — not covered in source material.

Caching

Not cached persistently — see Implementation Notes above.

Backward Compatibility and Migration

N/A — not addressed in the source Confluence page.

Legal Context

N/A — not addressed in the source Confluence page; migrated as a reference copy without new legal analysis.

Cybersecurity Considerations

N/A — not addressed in the source Confluence page; migrated as a reference copy without new security analysis. Note: ARES lookups pass company-name/IČO query strings to a third-party (Czech government) service, and results include registered-address data for legal entities — this should be reviewed when Cybersecurity/Data Privacy is formally analysed for this integration.

Risk Assessment

N/A — not addressed in the source Confluence page; migrated as a reference copy without new risk analysis.

Auditing, Reporting & Measurement

N/A — not addressed in the source Confluence page; migrated as a reference copy without new analysis.

---