# Bežné použitia

Praktické návody: [Fakturačné údaje podľa IČO](./fakturacne-udaje.md), [autocomplete firmy](./autocomplete-firiem.md) a [DIČ a IČ DPH](./dic-ic-dph.md).

## Predvyplnenie faktúry

Používateľ zadá názov firmy do formulára, vy zavoláte search a predvyplníte IČO, DIČ, IČ DPH a adresu automaticky.

```js
async function lookupCompany(name) {
  const res = await fetch(
    `https://api.subjekt.sk/v1/search?q=${encodeURIComponent(name)}&country=sk&limit=10`
  );
  if (!res.ok) throw new Error("Vyhľadávanie zlyhalo");
  const data = await res.json();
  return data.results; // zobrazte zoznam, nechajte používateľa vybrať
}

// Po výbere firmy získajte detail:
async function fillInvoice(ico) {
  const res = await fetch(`https://api.subjekt.sk/v1/entity/${ico}?country=sk`);
  if (!res.ok) throw new Error("Firma nenájdená");
  const entity = await res.json();

  return {
    name: entity.name,
    ico: entity.ico,
    dic: entity.dic,
    ic_dph: entity.ic_dph,
    address: `${entity.address.street} ${entity.address.building_no}, ${entity.address.zip} ${entity.address.city}`,
  };
}
```

## Overenie firmy

V dostupnom registrovom zázname môžete skontrolovať sídlo a evidovaný dátum zániku. Nenájdenie záznamu ani chýbajúci dátum zániku nie sú dôkazom aktuálneho stavu firmy; zohľadnite [aktuálnosť dát](./aktualnost-dat.md).

```python
import requests

def verify_company(ico: str) -> dict:
    r = requests.get(
        f"https://api.subjekt.sk/v1/entity/{ico}",
        params={"country": "sk"},
        timeout=8
    )
    if r.status_code == 404:
        return {"found": False, "reason": "Služba záznam nenašla; stav firmy nie je potvrdený"}
    r.raise_for_status()
    entity = r.json()

    return {
        "found": True,
        "termination_recorded": entity.get("terminated") is not None,
        "name": entity["name"],
        "established": entity.get("established"),
        "terminated": entity.get("terminated"),
        "address": entity["address"],
    }

result = verify_company("31322832")
print(result)
```

## Hromadný import

Ak potrebujete importovať väčší počet firiem zo zoznamu názvov, použite cursor stránkovanie. Dávajte pozor na rate limity — odporúčame pridať malé oneskorenie medzi požiadavkami.

```python
import time
import requests

def bulk_search(queries: list[str], country: str = "sk") -> list[dict]:
    base = "https://api.subjekt.sk/v1/search"
    all_results = []

    for query in queries:
        cursor = None

        while True:
            params = {"q": query, "country": country, "limit": 50}
            if cursor:
                params["cursor"] = cursor

            r = requests.get(base, params=params, timeout=10)

            if r.status_code == 429:
                retry_after = int(r.headers.get("Retry-After", 60))
                print(f"Rate limit, čakám {retry_after}s...")
                time.sleep(retry_after)
                continue

            r.raise_for_status()
            data = r.json()
            all_results.extend(data["results"])
            cursor = data.get("next_cursor")

            if cursor is None:
                break

        time.sleep(0.1)  # slušnosť voči serveru

    return all_results
```

## Cezhraničné vyhľadávanie

API podporuje vyhľadávanie v slovenských aj českých firmách súčasne pomocou parametra `country=both`.

```bash
# Hľadať v oboch krajinách, preferovať SK výsledky
curl "https://api.subjekt.sk/v1/search?q=tesla&country=both&prefer=sk"

# Hľadať iba v česku
curl "https://api.subjekt.sk/v1/search?q=skoda&country=cz"

# Detail českej firmy podľa IČO
curl "https://api.subjekt.sk/v1/entity/00177041?country=cz"
```

Pri `country=both` sú výsledky zoradené podľa: presná zhoda IČO → relevancia → krajina podľa `prefer`.

> **Poznámka:** CZ dáta sú informatívne (live proxy cez ARES). Pozri [prehľad](./prehlad.md) pre detaily.