# FirmAPI – Príklady použitia

Praktické scenáre integrácie FirmAPI do vlastných systémov. Free plán obsahuje 20 požiadaviek mesačne – zaregistrujte sa na https://firmapi.sk/registracia a získajte API kľúč.

Base URL: `https://firmapi.sk/v1` · Autentifikácia: hlavička `X-API-Key: fa_your_key` alebo `Authorization: Bearer fa_your_key`.

## Vyhľadávanie firiem s autocomplete

Endpoint `GET /v1/search/autocomplete?q=` je stavaný pre Select2, typeahead a podobné komponenty – vracia výsledky kompatibilné s populárnymi JavaScript knižnicami.

```bash
curl -H "X-API-Key: fa_your_key" \
  "https://firmapi.sk/v1/search/autocomplete?q=version+two"
```

Kompletná integrácia so Select2 cez JS SDK:

```javascript
import { FirmApi } from 'firmapi';

const client = new FirmApi('YOUR_API_KEY');

$('#company-search').select2({
  ajax: {
    transport: async (params, success, failure) => {
      try { success(await client.search.autocomplete(params.data.q)); }
      catch (e) { failure(e); }
    },
    data: (params) => ({ q: params.term }),
    processResults: (data) => ({ results: data.results }),
  },
  minimumInputLength: 2,
});
```

## Získanie údajov o firme podľa IČO

Najčastejšie použitie – kompletné údaje o firme podľa jej IČO. Príklad: IČO 51636549 → „Version Two s. r. o.“, Bratislava.

```bash
curl -H "X-API-Key: fa_your_key" \
  "https://firmapi.sk/v1/company/ico/51636549"
```

JavaScript SDK:

```javascript
import { FirmApi } from 'firmapi';

const client = new FirmApi('YOUR_API_KEY');

const company = await client.companies.byIco('51636549');
console.log(company.name); // "Version Two s. r. o."

const results = await client.search.byName('Version Two');
console.log(results.data); // [{ ico: "51636549", name: "..." }]
```

PHP SDK:

```php
use FirmApi\Client;

$client = new Client('YOUR_API_KEY');

$company = $client->companies->byIco('51636549');
echo $company['name']; // "Version Two s. r. o."
echo $company['city']; // "Bratislava"
```

Rovnaká logika platí pre Dart/Flutter a ľubovoľný jazyk – ide o bežný HTTP GET s API kľúčom v hlavičke.

## Automatické dopĺňanie údajov v CRM

Zákazník zadá IČO, systém doplní názov, adresu, DIČ a IČ DPH. Eliminuje prepisovacie chyby a udržiava CRM aktuálne voči Obchodnému registru.

```bash
curl -H "X-API-Key: fa_your_key" \
  "https://firmapi.sk/v1/company/ico/51636549?scope=tax"
```

Výhody:

- Eliminácia manuálneho zadávania údajov
- Zníženie chýb pri prepise
- Aktuálne údaje priamo z Obchodného registra
- Automatická validácia IČO

## Fakturácia v e-shope (B2B)

Pri checkoute sa po zadaní IČO automaticky vyplnia fakturačné údaje vrátane IČ DPH – overeného cez VIES. Menej opustených košíkov, správne faktúry.

Výhody:

- Rýchlejší checkout pre firemných zákazníkov
- Správne fakturačné údaje bez chýb
- Automatické overenie existencie firmy
- Podpora pre DIČ a IČ DPH (vyššie tarify)

## Ďalšie scenáre

- **Overenie obchodného partnera (KYB)** – pred podpisom zmluvy alebo odoslaním tovaru na faktúru jeden request vráti dlhy voči poisťovniam a Finančnej správe, insolvencie, exekučné poverenia aj sankčné zoznamy. Detailný popis: https://firmapi.sk/overenie-firmy.md
- **Monitoring portfólia zákazníkov** – webhooky doručia zmenu (nový dlh, konkurz, zmena konateľa) do vášho systému v deň, keď ju zachytíme. Detailný popis: https://firmapi.sk/monitoring-firiem.md
- **Hromadné spracovanie (batch)** – `POST /v1/batch/ico` prijme zoznam IČO a spracuje ich naraz; vhodné na počiatočné naplnenie CRM alebo pravidelné čistenie databázy.

---

Kompletná API dokumentácia: https://firmapi.sk/dokumentacia.md · Cenník: https://firmapi.sk/cennik.md