# Aktuálnosť a cache dát

## Slovenské dáta

SK záznamy sa skladajú z RPO, exportov DIČ a platiteľov DPH Finančnej správy a voliteľného DIČ obohatenia z RÚZ.

- GitHub Actions má naplánovanú kontrolu publikovania RPO denne o 03:17 UTC; importuje len zmenený snapshot. GitHub môže spustenie oneskoriť. Denná kontrola zachytí aj oneskorené týždenné vydanie.
- DIČ a registrácie DPH sa zosúlaďujú denne, nezávisle od zmien RPO.
- Hromadný RPO snapshot použitý pipeline je zdrojom publikovaný približne týždenne.
- Čas posledného úspešného importu preto nie je to isté ako čas publikovania zdroja.

Oba údaje vracia health endpoint:

```bash
curl "https://api.subjekt.sk/v1/health"
```

- `last_success_at` / `sk_last_sync` — posledná úspešná fáza synchronizácie (zvyčajne dane),
- `rpo_last_success_at` — posledný úspešný import RPO,
- `tax_last_success_at`, `tax_source_last_modified` — úspešné zosúladenie daní a starší z dátumov publikovania jeho dvoch zdrojov,
- `source_last_modified` — čas publikovania importovaného RPO snapshotu,
- `last_attempt_at`, `last_sync_status`, `last_attempt_error` — výsledok posledného pokusu,
- `sync_lag_seconds` — vek posledného úspešného importu.

Presné podmienky pre `status: "ok"` a `degraded` sú v tabuľke na stránke [GET /v1/health](./api/health.md). Stránka [Stav](/status/) ukazuje, ktorá kontrola neprešla.

## České dáta

CZ dáta sa získavajú z ARES. Detail je v pamäťovej cache Workera najviac šesť hodín, vyhľadávanie názvu 30 minút; navyše platí HTTP cache uvedená nižšie. Chyba ARES vracia `502 upstream_unavailable` alebo `504 timeout`, aj pri `country=both`. Výpadok sa neskrýva za neúplný zoznam.

Health nekontroluje dostupnosť ARES: uvádza `cz_status: "not_checked"`. Pole `updated_at` českého detailu pochádza z ARES `datumAktualizace`, nie z času požiadavky.

Nová slovenská firma sa objaví po zapísaní do RPO, zahrnutí do nasledujúceho týždenného snapshotu a úspešnom importe. Zmeny teda nie sú okamžité; úplnosť závisí od zdrojových registrov. Viac registrácií pod rovnakým IČO zastupuje jeden deterministický záznam: aktívny má prednosť, potom Obchodný register, Živnostenský register a ostatné registre. Zaniknuté subjekty zostávajú vo vyhľadávaní.

## Cache-Control

API momentálne vracia:

| Úspešný endpoint | `Cache-Control` |
|---|---|
| `GET /v1/entity/{ico}` | `public, max-age=3600` |
| `GET /v1/search` | `public, max-age=300` |
| `GET /v1/health` | `public, max-age=30` |

Chybové odpovede používajú `no-store`, aby sa výpadky, 429 alebo dočasné upstream chyby neukladali do cache.

## Príklad kontroly

```js
const response = await fetch("https://api.subjekt.sk/v1/health");
const health = await response.json();

if (!response.ok || health.status !== "ok") {
  console.warn("Subjekt API alebo synchronizácia je degradovaná", health.data);
}
```