API

Skóre, scoring a rizika firmy jedním dotazem — strojově čitelně (JSON). Ideální pro napojení do CRM, schvalování objednávek nebo scoring celého portfolia.

API klíče jsou součástí tarifu Enterprise (viz ceník). Klíč si vytvoříte ve svém účtu. Struktura odpovědi níže je ale živá a stejná, jakou dnes vrací web — dokumentaci proto klidně používejte k přípravě napojení už teď.

Prověření firmy

GET /api/firma/{ičo}
X-Api-Key: fs_váš_klíč

Jediný povinný parametr je 8místné IČO v cestě. Autentizace probíhá hlavičkou X-Api-Key (případně parametrem ?apikey=…). Odpověď je JSON v UTF-8.

{
  "ico": "27082440",
  "nazev": "Alza.cz a.s.",
  "adresa": "Jankovcova 1522/53, Holešovice, 17000 Praha 7",
  "score": {
    "value": 54,
    "rating": "C",
    "band": "mid",
    "label": "Zvýšené riziko",
    "omezena": false,
    "parametry": {
      "financni": [
        { "label": "Zadluženost", "hodnota": "83 %", "penalizace": -10, "stav": "bad" }
      ],
      "nefinancni": [
        { "label": "Insolvence", "hodnota": "NE", "penalizace": 0, "stav": "ok" }
      ]
    }
  },
  "rizika": [
    { "id": "isir", "label": "Insolvenční rejstřík",
      "value": "Čistý záznam", "status": "ok" }
  ],
  "profil": { "pravniForma": "…", "obor": "…", "dic": "…", "jednatele": ["…"] },
  "finance": { "zadluzenost": {}, "likvidita": {}, "vlastniKapital": {} }
}

Pole	Význam
`score.value`	Celkové skóre 0–100 (100 mínus penalizace za rizikové ukazatele).
`score.rating`	Písmenný scoring AA–E (AA = plných 100 bez nálezu) podle pásma skóre.
`score.band` / `score.label`	Interní pásmo (`low / mid / high`) a jeho slovní popis.
`score.omezena`	`true`, když firma nemá čitelnou účetní závěrku — skóre je jen z rejstříků, bez finanční části.
`score.parametry.financni[]`	Rozklad finančních ukazatelů (zadluženost, likvidita, vlastní kapitál…): štítek, hodnota, penalizace, stav.
`score.parametry.nefinancni[]`	Rozklad nefinančních ukazatelů (insolvence, DPH, stáří, sídlo…) ve stejném tvaru.
`rizika[]`	Nefinanční ukazatele se statusem `ok / warn / high / info` (`info` = neutrální údaj, ne rizikový nález).
`finance`	Ukazatele z účetní závěrky (je `null`, když firma nemá strojově čitelnou závěrku).

Limity a chyby

Stav	Význam
`200`	OK — report v těle odpovědi.
`404`	Firma s tímto IČO není v obchodním rejstříku.
`401`	Neplatný API klíč, nebo placené členství vypršelo.
`429`	Překročen limit 300 dotazů/min na klíč.
`503`	Zdrojový rejstřík je dočasně nedostupný — zopakujte dotaz později.

Jak získat API klíč: API je součástí tarifu Enterprise; klíč si vytvoříte ve svém účtu. Po jeho spuštění si klíč vygenerujete v aplikaci v sekci Můj účet → Členství — zobrazí se jednou, nový klíč ten předchozí zneplatní.

Příklad (curl)

curl -H "X-Api-Key: fs_váš_klíč" \
  https://scorify.cz/api/firma/27082440

PDF verzi reportu vrátí GET /api/firma/{ičo}/pdf se stejnou autentizací.

Vyzkoušet Scorify zdarma

Časté dotazy

V jakém formátu API odpovídá?

Vrací JSON v kódování UTF-8. Prověření firmy je jediné GET volání na /api/firma/{ičo}, kde jediným povinným parametrem je osmimístné IČO v cestě.

Jak se API autentizuje?

Hlavičkou X-Api-Key s vaším klíčem, případně parametrem ?apikey= v adrese. Klíče jsou součástí tarifu Enterprise.

Je API omezené počtem dotazů?

Ano, s API klíčem platí limit 300 dotazů za minutu na klíč (bez klíče 40 dotazů za minutu z jedné adresy). Chrání to rejstříky, ze kterých data čerpáme, před přetížením. Při hromadném zpracování portfolia proto dotazy rozložte v čase.

Co všechno API vrací?

Skóre 0–100, stupeň AA až E, slovní popis rizika a kompletní rozklad — jednotlivé finanční i nefinanční ukazatele včetně toho, kolik bodů každý z nich ubral. Dále rejstříkové údaje firmy.