# FirmAPI – SDK a knižnice

Oficiálne klientske knižnice na integráciu FirmAPI do vašej aplikácie za pár minút. Obe SDK podporujú sandbox režim na testovanie bez API kľúča.

## Bez API kľúča

Obe SDK obsahujú sandbox režim, ktorý umožňuje testovanie bez API kľúča a bez limitov. Sandbox vracia demo dáta a funguje rovnako ako produkčné API.

```php
use FirmApi\Client;

$client = Client::sandbox();

// Or via env (Laravel):  FIRMAPI_SANDBOX=true
// Or plain PHP:  define('FIRMAPI_SANDBOX', true); before new Client(...)

// Works the same as production
$company = $client->companies->byIco('51636549')->get();
```

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

const client = FirmApi.sandbox();

// Or: new FirmApi({ apiKey, sandbox: true }), or FIRMAPI_SANDBOX=true env (Node)

// Works the same as production
const company = await client.companies.byIco('51636549');
```

Sandbox používa demo dáta a URL adresu firmapi.sk/v1/sandbox. Všetky metódy fungujú rovnako ako v produkcii, takže po dokončení testovania stačí nahradiť Client::sandbox() / FirmApi.sandbox() bežnou inicializáciou s API kľúčom.

## PHP SDK

Oficiálny PHP klient pre FirmAPI. Vyžaduje PHP 8.1+ a podporuje Laravel auto-discovery.

### Inštalácia

```bash
composer require firmapi/phpsdk:^2.0
```

Táto dokumentácia sa vzťahuje na verziu 2.x SDK. Pri prechode z verzie 1.x si pozrite zmeny v súbore CHANGELOG – predvolene rýchle (cache) dáta, typované odpovede a odstránené vyhľadávanie podľa interného ID.

### Rýchly štart

**Vyhľadanie podľa IČO**

```php
use FirmApi\Client;

// Create a client with your API key
$client = new Client('your-api-key');

// Look up a company by ICO (base data only)
$company = $client->companies->byIco('51636549')->get();

echo $company['data']['name'];         // "Version Two s. r. o."
echo $company['data']['address'];       // "Bratislava ..."

// Include enrichment data with fluent methods
$company = $client->companies->byIco('51636549')
    ->withTax()
    ->withFinancials()
    ->withDebtorStatus()
    ->get();

echo $company['data']['tax']['dic'];          // "2120733417"
echo $company['data']['financials']['net_turnover']; // 486210

// Or get everything at once
$full = $client->companies->byIco('51636549')->withAll()->get();
```

**Vyhľadávanie**

```php
// Search by name
$results = $client->search->byName('Version Two');

foreach ($results['data'] as $company) {
    echo $company['ico'] . ' - ' . $company['name'];
}

// Autocomplete (Select2-compatible)
$suggestions = $client->search->autocomplete('vers', limit: 5);

// Advanced multi-field search
$results = $client->search->advanced([
    'name' => 'Version',
    'city' => 'Bratislava',
]);
```

**Hromadné vyhľadávanie** (Vyžaduje plán Starter alebo vyšší)

```php
// Batch lookup by ICO
$batch = $client->batch->byIco(['51636549', '12345678', '87654321']);

// Check batch status
$status = $client->batch->status($batch['id']);

// Get results
$results = $client->batch->results($batch['id']);
```

**Spracovanie chýb**

```php
use FirmApi\Exceptions\AuthenticationException;
use FirmApi\Exceptions\RateLimitException;
use FirmApi\Exceptions\ValidationException;
use FirmApi\Exceptions\ApiException;

try {
    $company = $client->companies->byIco('51636549')->get();
} catch (AuthenticationException $e) {
    // Invalid or missing API key (401)
} catch (RateLimitException $e) {
    // Rate limit exceeded (429)
    $retryAfter = $e->getRetryAfter(); // seconds
} catch (ValidationException $e) {
    // Validation error (422)
    $errors = $e->getErrors();
} catch (ApiException $e) {
    // Other API error
    $statusCode = $e->getCode();
}
```

### Všetky dostupné metódy

| Metóda | Popis | Návratový typ |
|---|---|---|
| `$client->companies->byIco($ico)` | Vyhľadanie firmy podľa IČO (identifikačné číslo) | `CompanyQuery` |
| `$client->companies->byOrsrId($id)` | Vyhľadanie firmy podľa ORSR ID | `CompanyQuery` |
| `->withTax()->withFinancials()->...` | Reťazenie obohatení (daňové údaje, financie, insolvencia, atď.) | `CompanyQuery` |
| `->withAll()` | Zahrnúť všetky dostupné obohatenia | `CompanyQuery` |
| `->get()` | Vykonať dopyt a vrátiť údaje o firme | `array` |
| `$client->search->byName($name)` | Vyhľadávanie firiem podľa názvu | `array` |
| `$client->search->byIco($ico)` | Vyhľadávanie firiem podľa čiastočného IČO | `array` |
| `$client->search->autocomplete($q)` | Automatické dopĺňanie (kompatibilné so Select2) | `array` |
| `$client->search->advanced([...])` | Rozšírené vyhľadávanie podľa viacerých polí | `array` |
| `$client->batch->byIco([...])` | Hromadné vyhľadávanie podľa viacerých IČO | `array` |
| `$client->batch->byNames([...])` | Hromadné vyhľadávanie podľa viacerých názvov | `array` |
| `$client->batch->status($batchId)` | Stav hromadnej úlohy | `array` |
| `$client->batch->results($batchId)` | Výsledky hromadnej úlohy | `array` |
| `$client->account->usage()` | Štatistiky spotreby za aktuálne obdobie | `array` |
| `$client->account->quota()` | Zostávajúca kvóta za aktuálne obdobie | `array` |
| `$client->account->history($days)` | História spotreby | `array` |
| `Client::sandbox()` | Vytvoriť sandbox klienta na testovanie (bez API kľúča) | `Client` |

### Dostupné obohatenia

| Metóda | Popis |
|---|---|
| `withTax()` | Daňové údaje (DIČ, IČ DPH, VIES overenie) |
| `withBankAccounts()` | Bankové účty |
| `withFinancials()` | Finančné údaje (tržby, zisk, počet zamestnancov) |
| `withDebtorStatus()` | Status dlžníka |
| `withFinancialStatements()` | Účtovné závierky |
| `withInsolvency()` | Insolvencia |
| `withCommercialBulletin()` | Obchodný vestník |
| `withPublicContracts()` | Verejné zákazky |
| `withProcurement()` | Verejné obstarávanie |
| `withExecutionAuthorizations()` | Exekučné poverenia |
| `withRpvs()` | Register partnerov verejného sektora |
| `withNbs()` | Regulácia NBS |
| `withTaxReliability()` | Index daňovej spoľahlivosti |
| `withErasedVat()` | Vymazané DPH registrácie |
| `withReges()` | ÚVO – zoznam hospodárskych subjektov (kvalifikovaní dodávatelia) |
| `withSocialEnterprise()` | Register sociálnych podnikov |
| `withGleif()` | GLEIF – identifikátor LEI a väzby na materské spoločnosti |
| `withSanctions()` | Sankčné zoznamy EÚ (FSF) a USA (OFAC) |
| `withTedTenders()` | TED – európske verejné zákazky |
| `withReplikAdministrator()` | REPLIK – správcovia konkurznej podstaty |
| `withSbs()` | Licencie súkromnej bezpečnostnej služby (SBS) |
| `withTransportLicence()` | JISCD – licencie cestných dopravcov |
| `withUtilityLicence()` | ÚRSO – povolenia v sieťových odvetviach |
| `withContractingAuthority()` | ÚVO – status verejného obstarávateľa |
| `withDebarred()` | ÚVO – zákaz účasti vo verejnom obstarávaní |
| `withUvoReferences()` | ÚVO – evidencia referencií z verejných zákaziek |
| `withFsImports()` | Finančná správa – rozšírené daňové registre (odpočty, oslobodenia) |
| `withIllegalEmployment()` | Inšpektorát práce – nelegálne zamestnávanie |
| `withCourtDecisions()` | Súdne rozhodnutia (MS SR) |
| `withEmployerHeadcount()` | Sociálna poisťovňa – registrácia a počet zamestnancov |
| `withSoiTravelAgency()` | SOI – register cestovných kancelárií |
| `withSvpsEstablishments()` | ŠVPS – schválené potravinárske a veterinárne prevádzkarne |
| `withCrpProjects()` | Projekty a dotácie z Centrálneho registra projektov (CRP) |
| `withTradeLicenseActivities()` | Živnostenské oprávnenia a predmety podnikania (ŽRSR) |

## JavaScript / TypeScript SDK

Oficiálny JavaScript klient pre FirmAPI. Funguje v Node.js 18+ aj moderných prehliadačoch s plnou podporou TypeScript.

### Inštalácia

```bash
npm install github:version-two/sk.firmapi.jssdk#v2.0.0
```

SDK zatiaľ nie je publikované v registri npm – inštaluje sa priamo z GitHubu, kde je aj zostavený balík v priečinku dist. Verziu pripnite tagom, aby vám build nepreskočil na novšiu.

### Rýchly štart

**Vyhľadanie podľa IČO**

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

// Create a client with your API key
const client = new FirmApi('your-api-key');

// Look up a company by ICO (base data only)
const company = await client.companies.byIco('51636549');

console.log(company.data.name);    // "Version Two s. r. o."
console.log(company.data.address); // "Bratislava ..."

// Include enrichment data with fluent methods
const detailed = await client.companies.byIco('51636549')
  .withTax()
  .withFinancials()
  .withDebtorStatus();

console.log(detailed.data.tax.dic);          // "2120733417"
console.log(detailed.data.financials?.net_turnover); // 486210

// Or get everything at once
const full = await client.companies.byIco('51636549').withAll();
```

**Konfigurácia**

```javascript
// Full configuration
const client = new FirmApi({
  apiKey: 'your-api-key',
  timeout: 30000,             // ms (default: 30000)
  waitForFreshData: false,    // wait for a queued refresh (default: false)
  maxStaleRetries: 3,         // re-polls when waiting (default: 3)
  maxRetries: 2,              // retry transient 5xx/network (default: 2)
  sandbox: false,             // force sandbox; omit to auto-detect FIRMAPI_SANDBOX env
});

// Fast by default; opt into a completed refresh per query:
const fresh = await client.companies.byIco('51636549').fresh().get();
```

**Vyhľadávanie**

```javascript
// Search by name
const results = await client.search.byName('Version Two');

for (const company of results.data) {
  console.log(`${company.ico} - ${company.name}`);
}

// Autocomplete (Select2-compatible)
const suggestions = await client.search.autocomplete('vers', 5);

// Advanced multi-field search
const advanced = await client.search.advanced({
  name: 'Version',
  city: 'Bratislava',
});
```

**Hromadné vyhľadávanie** (Vyžaduje plán Starter alebo vyšší)

```javascript
// Batch lookup by ICO
const batch = await client.batch.byIco([
  '51636549',
  '12345678',
  '87654321',
]);

// Check batch status
const status = await client.batch.status(batch.id);

// Get results when completed
const results = await client.batch.results(batch.id);
```

**Spracovanie chýb**

```javascript
import {
  FirmApi,
  AuthenticationException,
  RateLimitException,
  ValidationException,
  ApiException,
} from 'firmapi';

try {
  const company = await client.companies.byIco('51636549');
} catch (e) {
  if (e instanceof AuthenticationException) {
    // Invalid or missing API key (401)
  } else if (e instanceof RateLimitException) {
    // Rate limit exceeded (429)
    console.log(e.retryAfter); // seconds
  } else if (e instanceof ValidationException) {
    // Validation error (422)
    console.log(e.errors);
  }
}
```

### Všetky dostupné metódy

| Metóda | Popis | Návratový typ |
|---|---|---|
| `client.companies.byIco(ico)` | Vyhľadanie firmy podľa IČO (identifikačné číslo) | `CompanyQuery` |
| `client.companies.byOrsrId(id)` | Vyhľadanie firmy podľa ORSR ID | `CompanyQuery` |
| `.withTax().withFinancials()....` | Reťazenie obohatení (daňové údaje, financie, insolvencia, atď.) | `CompanyQuery` |
| `.withAll()` | Zahrnúť všetky dostupné obohatenia | `CompanyQuery` |
| `client.search.byName(name, opts?)` | Vyhľadávanie firiem podľa názvu | `Promise<ApiResponse<CompanyData[]>>` |
| `client.search.byIco(ico, opts?)` | Vyhľadávanie firiem podľa čiastočného IČO | `Promise<ApiResponse<CompanyData[]>>` |
| `client.search.autocomplete(q, limit?)` | Automatické dopĺňanie (kompatibilné so Select2) | `Promise<AutocompleteResponse>` |
| `client.search.advanced({...})` | Rozšírené vyhľadávanie podľa viacerých polí | `Promise<ApiResponse<CompanyData[]>>` |
| `client.batch.byIco([...])` | Hromadné vyhľadávanie podľa viacerých IČO | `Promise<BatchResponse>` |
| `client.batch.byNames([...])` | Hromadné vyhľadávanie podľa viacerých názvov | `Promise<BatchResponse>` |
| `client.batch.status(batchId)` | Stav hromadnej úlohy | `Promise<ApiResponse<BatchStatus>>` |
| `client.batch.results(batchId)` | Výsledky hromadnej úlohy | `Promise<BatchResponse>` |
| `client.account.usage()` | Štatistiky spotreby za aktuálne obdobie | `Promise<UsageResponse>` |
| `client.account.quota()` | Zostávajúca kvóta za aktuálne obdobie | `Promise<QuotaResponse>` |
| `client.account.history(days?)` | História spotreby | `Promise<HistoryResponse>` |
| `FirmApi.sandbox()` | Vytvoriť sandbox klienta na testovanie (bez API kľúča) | `FirmApi` |

---

Späť na dokumentáciu: https://api.firmapi.sk/dokumentacia.md · Cenník: https://api.firmapi.sk/cennik.md