API token
Pro zobrazení Vašeho tokenu je nutné se přihlásit. Přihlásit se
Autorizace
Každý požadavek na API musí obsahovat hlavičku `Authorization` s platným tokenem:
`Authorization: Bearer <váš_token>`
Všechny endpointy jsou verzované a dostupné pod prefixem `/v1/api/`.
Zpracování dokumentů
Tato sekce se věnuje nahrávání, kontrole a správě souborů.
Upload souborů
[POST] /v1/api/file/upload
Slouží k nahrání jednoho nebo více souborů ke zpracování.
Request
+ Parameters
+ `files` (array, required) - Pole jednoho nebo více souborů určených k nahrání. Každá položka v poli musí být soubor odeslaný jako součást multipart/form-data požadavku. Pro správné zpracování by měl každý soubor obsahovat svůj původní název a MIME typ (např. application/pdf).
- Maximální počet souborů: 10
- Maximální velikost jednoho souboru: 25 MB
- Povolené MIME typy: application/pdf, image/jpeg, image/png, DOCX, XLSX, CSV
+ `hook` (string, required) - URL adresa, na kterou bude po dokončení zpracování odeslán POST požadavek s informacemi o výsledku.
+ `balance` (integer, optional) - Režim porovnání cen energií. Výchozí `0`. Pouze pro dokumenty klasifikované jako `energy_invoice` s komoditou `gas` nebo `electricity` — u ostatních typů je parametr ignorován.
- `0` — žádné porovnání cen energií, hook se odešle hned po zpracování dokumentu (výchozí chování).
- `1` — **automatické porovnání**. Evidoo synchronně získá srovnání cen, uloží jej jako `FileData` typu `balance` a vloží jej do těla původního hook callbacku pod klíč `balance`.
- `2` — **odložené porovnání**. Po zpracování dokumentu se původní hook NEODESÍLÁ — Evidoo čeká, až externí systém zpětně zavolá `POST /v1/api/hook/file/send-hook/{id}` s JSON tělem obsahujícím výsledek porovnání. To se uloží 1:1 jako `FileData(balance)` a teprve poté Evidoo odešle původní upload-hook s vloženým srovnáním (payload je identický jako u `balance=1`). Opakované volání `send-hook` je idempotentní.
+ `force` (boolean, optional) - Vynucené nahrání duplikátu. Výchozí `false`.
- `false` — standardní upload.
- `true` — soubor se uloží jako nový záznam i kdyby šlo o duplikát již nahraného obsahu (`content_hash`). Navíc se všechny existující `parent_id` reference jiných souborů se stejným `content_hash` přesměrují na tento nový soubor — slouží pro re-upload, kdy klient chce přepnout odkazy na čerstvě nahraný originál.
- Kombinace `balance=1` + `force=1` resp. `balance=2` + `force=1`: porovnání cen energií se počítá z **forcovaného** souboru. Pokud má zdrojový (původní) duplikát již dříve vypočtené `balance` `FileData`, použije se beze změny a další volání API porovnávače se přeskočí; jinak se srovnání získá standardně dle režimu `balance` (synchronně pro `1`, odloženě pro `2`).
Příklad CURL:
curl --location --request POST 'https://www.evidoo.cz/v1/api/file/upload' \
--header 'Authorization: Bearer VÁŠ_BEARER_TOKEN' \
--header 'Accept: application/json' \
--form 'files[0]=@"/cesta/k/souboru/faktura.pdf"' \
--form 'hook="https://vas-webhook.url/endpoint"' \
--form 'balance="1"' \
--form 'force="1"'
Response 200 (application/json)
Odpověď serveru
{
"status": 200,
"payload": {
"files": {
"list": [
{
"id": "1shp17",
"parent_id": null,
"originalFileName": "I3XCOY59014.pdf",
"supplierId": null,
"supplierName": null,
"fileName": "EV_68790256879a6742278220.pdf",
"fileType": "invoice",
"type": "application/pdf",
"commodity": [
"service"
],
"size": 1015955,
"name": "Název dokumentu",
"note": null,
"status": 400,
"icon": {
"icon": "other",
"color": "#333333"
},
"createdDt": 1752760918000,
"priceExcludingVat": 1623,
"price": 2000,
"currency": "CZK",
"property": [],
"group": []
}
]
}
}
}
Hook callback
[POST] na adresu z parametru hook
Po dokončení zpracování každého souboru (nebo po obdržení odloženého balance při balance=2) Evidoo odešle POST request na URL zadanou v parametru hook při uploadu. Request je idempotentní — při neúspěchu (HTTP != 2xx nebo timeout) probíhá retry.
Hlavičky:
Content-Type: application/json
User-Agent: Evidoo-Hook/1.0
Tělo požadavku je pole objektů – jeden objekt na každý výsledný soubor (pokud byl původní upload rozdělen splittingem, hook obsahuje všechny děti). Každý objekt má stejnou strukturu jako prvek payload.files.list z odpovědi na upload, plus tyto klíče navíc:
fileData.classification.data– výsledek klasifikace dokumentu (univerzální schéma pro všechny typy dokumentů –document_type,commodity,supplier,customer, datumy, atd.).fileData.data.data– výsledek parsování dokumentu. Schéma se liší podlefileType(např.energy_invoice,hoa_billing,lease_agreement, …). Kompletní JSON schémata jednotlivýchfileTypejsou na samostatné stránce – viz JSON schémata dat per fileType (bude doplněn odkaz).balance– pouze pokud byl upload volán sbalance=1nebobalance=2a dokument jeenergy_invoices komoditouelectricity/gas. Obsahuje JSON odpověď z porovnávače cen ve tvaru{ "code": 200, "message": [ <nabídka_dodavatele>, ... ] }.
Příklad těla hook callbacku (zkráceno):
[
{
"id": "1shp17",
"parentId": null,
"originalFileName": "faktura-pre-2026-03.pdf",
"fileName": "EV_68790256879a6742278220.pdf",
"fileType": "energy_invoice",
"mimeType": "application/pdf",
"commodity": ["electricity"],
"size": 1015955,
"status": 200,
"postprocessStatus": 200,
"extractionStatus": "completed",
"createdDt": 1716288000000,
"issuedDt": 1709251200000,
"startDt": 1704067200000,
"endDt": 1706659199000,
"fileData": {
"classification": {
"id": "abc123",
"status": 4,
"data": {
"document_type": "energy_invoice",
"commodity": "electricity",
"supplier": { "name": "PRE", "id_number": "27376516", "id_type": "ICO" },
"customer": { "name": "Jan Novák", "id_number": "7501010001", "id_type": "RC" },
"issued_dt": "2026-03-01",
"start_dt": "2026-01-01",
"end_dt": "2026-01-31"
},
"createdDt": 1716288000000
},
"data": {
"id": "def456",
"status": 4,
"data": {
"// pozn.": "Tvar tohoto objektu závisí na fileType – viz samostatná stránka JSON schémat.",
"info": {
"billing_from_dt": "2026-01-01",
"billing_to_dt": "2026-01-31",
"consumption_place_address": "Příkladová 1, 110 00 Praha 1"
},
"item": [
{ "description": "Silová elektřina VT", "quantity": 91, "unit": "kWh", "unit_price_without_vat": 3.227, "total_price_without_vat": 293.66 }
],
"total": {
"total_price_without_vat": 1623,
"total_price_of_vat": 377,
"total_price_include_vat": 2000
}
},
"createdDt": 1716288000000
},
"amendment": null
},
"balance": {
"code": 200,
"message": [
{
"nl_id_list__company": 16741,
"s_pricelist": "Utylis Energie - Standard",
"s_dodavatel_name": "Utylis Energie",
"s_dodavatel_url_logo": "https://porovnanienergii.cz/file/show?nl_id=165442",
"nd_spotreba_v": 0.091,
"nd_spotreba_n": 0,
"nd_dph": 21,
"s_distributor": "PRE distribuce",
"s_rate": "D02d",
"s_breaker": "jistič nad 3x20 A do 3x25 A včetně",
"nd_price_fixed": 89,
"nd_price_tarif_high": 3227,
"nd_price_tarif_low": 0,
"nd_pay_fix": 1068,
"nd_pay_trade_vt": 293.657,
"nd_pay_trade_nt": 0,
"nd_pay_trade": 1361.657,
"nd_pay_dst": 2742.04,
"s_garance": "NE",
"s_delka_smlouvy": "12 měsíců",
"s_vypoved_smlouvy": "dle VOP",
"s_typ_nabidky": "cenik",
"trade_vt_dph": 355.32,
"trade_nt_dph": 0,
"fix_dph": 1292.28,
"dstr_dph": 3317.86
}
]
}
}
]
Význam vybraných klíčů balance nabídky (jedna položka message[]):
nl_id_list__company– interní ID dodavatele v porovnávačis_dodavatel_name,s_dodavatel_url_logo– název a logo dodavateles_pricelist– název konkrétního ceníku/produktus_distributor,s_rate,s_breaker– distribuční oblast, sazba a hodnota jističe použité pro výpočetnd_spotreba_v,nd_spotreba_n– předpokládaná spotřeba (VT / NT) ve stejné jednotce jako zdrojový dokumentnd_price_fixed,nd_price_tarif_high,nd_price_tarif_low– jednotkové ceny bez DPH (paušál / VT / NT)nd_pay_trade_vt,nd_pay_trade_nt,nd_pay_trade– platby za silovou elektřinu (VT, NT, součet) bez DPHnd_pay_fix– pevná složka platby (paušál × měsíce) bez DPHnd_pay_dst– platba za distribuci bez DPHtrade_vt_dph,trade_nt_dph,fix_dph,dstr_dph– analogické součty s DPHs_garance,s_delka_smlouvy,s_vypoved_smlouvy– smluvní podmínky nabídkys_typ_nabidky–cenik/individualni(typ porovnávané nabídky)nd_dph– sazba DPH (%)
Pro plyn (commodity: ["gas"]) má message[] analogickou strukturu s plynařskými ekvivalenty distribučních klíčů.
Pokud byl použit balance=2 (odložené porovnání), hook se odesílá až po obdržení balance dat přes POST /v1/api/hook/file/send-hook/{id} – tvar payloadu je v obou režimech identický.
Kontrola stavu souborů
[GET] /v1/api/file/check/{ids}
Umožňuje zkontrolovat stav zpracování jednoho nebo více souborů na základě jejich ID. ID souborů se vkládají do URL a oddělují se čárkou.
Request
+ Parameters
+ ids (string, required) - ID souborů oddělené čárkou (např. `xxx,yyy`).
Response 200 (application/json)
Struktura odpovědi je stejná jako u uploadu. Pokud je soubor rozdělen (status = 100), v odpovědi se objeví nové soubory, které mají parent_id odkazující na původní dokument.
{
"status": 200,
"payload": {
"files": {
"list": [
{
"id": "1shp17",
"parent_id": null,
"originalFileName": "I3XCOY59014.pdf",
"supplierId": null,
"supplierName": null,
"fileName": "EV_68790256879a6742278220.pdf",
"fileType": "invoice",
"type": "application/pdf",
"commodity": [
"service"
],
"size": 1015955,
"name": "Původní dokument",
"note": null,
"status": 100,
"icon": {
"icon": "other",
"color": "#333333"
},
"createdDt": 1752760918000,
"priceExcludingVat": 1623,
"price": 2000,
"currency": "CZK",
"property": [],
"group": []
},
{
"id": "2newid",
"parent_id": "1shp17",
"originalFileName": "I3XCOY59014.pdf",
"supplierId": null,
"supplierName": null,
"fileName": "EV_part1_68790256879a6742278220.pdf",
"fileType": "invoice",
"type": "application/pdf",
"commodity": [
"service"
],
"size": 501342,
"name": "Rozdělený dokument 1",
"note": null,
"status": 200,
"icon": {
"icon": "other",
"color": "#333333"
},
"createdDt": 1752760919000,
"priceExcludingVat": 800,
"price": 1000,
"currency": "CZK",
"property": [],
"group": []
}
]
}
}
}
Seznam zpracovaných souborů
[GET] /v1/api/file/list
Vrací seznam souborů s možností filtrování a stránkování. V tomto seznamu se nezobrazují původní rozdělené soubory se statusem 100.
Request
+ Parameters (všechny jsou nepovinné )
+ `page` (number, optional) - Číslo stránky, výchozí je `1`.
+ `limit` (number, optional) - Počet položek na stránku. Výchozí i maximální hodnota je `50`.
+ `search` (string, optional) - Text pro vyhledávání.
+ `sort` (string, optional) - Řazení výsledků (např. `createdDt DESC`).
+ `type` (string, optional) - Filtrování podle typu dokumentu z `filterOptions.type`.
+ `propertyIds` (string, optional) - ID nemovitostí oddělené čárkou z `filterOptions.property`.
+ `groupIds` (string, optional) - ID skupin oddělené čárkou z `filterOptions.group`.
Response 200 (application/json)
{
"status": 200,
"payload": {
"files": {
"list": [
{
"id": "1shp17",
"parent_id": null,
"originalFileName": "I3XCOY59014.pdf",
"supplierId": null,
"supplierName": null,
"fileName": "EV_68790256879a6742278220.pdf",
"fileType": "invoice",
"type": "application/pdf",
"commodity": ["service"],
"size": 1015955,
"name": "Název dokumentu",
"note": "Chyba při zpracování",
"status": 400,
"icon": { "icon": "other", "color": "#333333" },
"createdDt": 1752760918000,
"priceExcludingVat": 1623,
"price": 2000,
"currency": "CZK",
"property": [],
"group": []
}
],
"filter": {
"from": null,
"to": null,
"search": null,
"status": null,
"type": null,
"sort": ["createdDt", "DESC"],
"propertyIds": "",
"groupIds": ""
},
"pagination": {
"page": 1,
"limit": 50,
"count": 43
},
"filterOptions": {
"type": [
"energy_invoice",
"accounting_document",
"price_list",
"power_of_attorney",
"lease_agreement",
"handover_protocol",
"contract_addendum",
"terms_and_conditions",
"purchase_agreement",
"checklist",
"hoa_billing",
"bank_statement",
"death_certificate",
"contract_termination",
"other",
"electricity_contract",
"gas_contract",
"statement_of_contract_details",
"advance_payment_schedule",
"contractual_penalty",
"identity_card",
"marriage_certificate",
"parking",
"instruction_on_contract_withdrawal",
"insurance_contract",
"land_register_extract",
"purchase_agreement_real_estate",
"donation_agreement_real_estate",
"purchase_agreement_car"
],
"property": [
{ "id": "68g4k", "name": "Dům Liberecká", "icon": { "icon": "apartment", "color": "#007bff" } },
{ "id": "4csm3", "name": "Dům Na Výšině", "icon": { "icon": "apartment", "color": "#007bff" } },
{ "id": "2h53m", "name": "Můj byt č. 5", "icon": { "icon": "residential", "color": "#985d90" } }
],
"group": [
{ "id": "2h53m", "name": "MSFA", "icon": { "icon": "0", "color": "#db0000" } }
]
}
}
}
}
Detail souboru
[GET] /v1/api/file/get/{id}
Získá kompletní detailní informace o konkrétním souboru.
Request
+ Parameters
+ `id` (string, required) - ID dokumentu.
Response 200 (application/json)
Odpověď obsahuje securityHash pro stažení/zobrazení. fileData.data má pro každý typ dokumentu jinou strukturu.
{
"status": 200,
"payload": {
"file": {
"id": "c8cbnn",
"cdnId": "lhl5",
"supplierId": "126jul",
"supplierName": "Firma s.r.o.",
"originalFileName": "resized_img_33t406e3ff6p1hlHaji.webp",
"fileName": "EV_68a17cf336705495728213.webp",
"shareType": null,
"fileType": "ucetni_doklad",
"mimeType": "image/webp",
"commodity": ["sluzba"],
"size": 126408,
"name": "🧾 Účtenka za služby",
"note": null,
"status": 200,
"createdDt": 1755413747000,
"removedDt": null,
"icon": {
"icon": "ucetni_doklad",
"color": "#8338EC"
},
"securityHash": "WFZvdVZ0b3JPMEIwMHgrS1FiOG4wSmJlVmYzVWx6RUU2SXVVVm56S2c1ditGQkZobTI5Ry9uWng0RVloMWZUSGhaFZHTGFlZXVScGhjRTNCQXBKQnc9PQ==",
"fileData": {
"classification": {
"id": "6yjcty",
"note": null,
"data": {}
},
"data": {
"id": "6yjcty",
"note": null,
"data": {}
},
"amendment": {
"id": "6yjcty",
"note": null,
"data": {
"file_name": "name_of_file",
"content": "<html>content</html>"
}
}
},
"additionalPrompt": [
{
"id": "6yjcty",
"prompt": "zaslaný požadavek",
"status": 4,
"createdDt": 1755413747000
}
],
"property": [
{
"id": "2d5voe",
"propertyId": "2h53m",
"role": 1,
"name": "Byt č. 5"
},
{
"id": "2f1j6v",
"propertyId": "68g4k",
"role": 1,
"name": "Dům Liberecká"
}
],
"group": [
{
"id": "fmpox",
"groupId": "2h53m",
"role": 1,
"name": "Název skupiny"
}
],
"hierarchy": [
{
"id": "fmpox",
"groupHierarchyId": "2h53m",
"role": 1,
"name": "Název hierarchické skupiny"
}
],
"user": [],
"chat": [
{
"id": "l9o8c",
"parentId": null,
"fileId": "ak7f8j",
"userId": "2h53m",
"message": "Zpráva ostatním uživatelů, kteří vidí dokument",
"createdDt": 1755685785000,
"user": {
"id": "2h53m",
"firstName": "Jan",
"lastName": "Pabyska",
"nickName": "JP",
"email": "jan@pabyska.cz"
}
}
]
}
}
}
Stažení souboru
[GET] /v1/api/file/download/{securityHash}
Umožní stáhnout fyzický soubor na základě jeho securityHash.
Request
+ Parameters
+ `securityHash` (string, required) - Bezpečnostní hash získaný z detailu souboru.
Response 200
Vrací přímo soubor ke stažení.
Zobrazení souboru
[GET] /v1/api/file/display/{securityHash}
Zobrazí soubor v prohlížeči (pokud to typ souboru umožňuje).
Request
+ Parameters
+ `securityHash` (string, required) - Bezpečnostní hash získaný z detailu souboru.
Response 200
Zobrazí obsah souboru.
Smazání souboru
[DELETE] /v1/api/file/delete/{id}
Smaže dokument na základě jeho ID.
Request
+ Parameters
+ `id` (string, required) - ID dokumentu ke smazání.
Response 200 (application/json)
Odpověď má stejnou strukturu jako `/v1/api/file/check/list`.
Úpravy PDF (anonymizace a podpisy)
Synchronní endpointy pro úpravu PDF pomocí AI. Na rozdíl od ostatních endpointů nevrací JSON, ale přímo binární PDF (Content-Type: application/pdf). Vstupní PDF se posílá přímo v requestu jako multipart/form-data — nepracují s ID již nahraných souborů. Každý request je evidován (operace, uživatel, SHA‑256 zdroje, počet stran, model, počty úprav i souřadnice). Zdrojové PDF se neukládá.
Anonymizace PDF
[POST] /v1/api/file/anonymize
AI najde v dokumentu zadané citlivé údaje a začerní je tak, aby nebyly strojově čitelné (stránka se pod překryvy rasterizuje, text pod nimi zaniká). Vrací nové, anonymizované PDF.
Request
+ Parameters (multipart/form-data)
+ `file` (file, required) - PDF dokument k anonymizaci. Akceptováno pouze PDF.
+ `keys` (string, required) - Které typy citlivých údajů začernit. Buď čárkou oddělený seznam, nebo JSON pole (např. `name,price,email,bank_account` nebo `["name","email"]`). Podporované hodnoty:
- `name` — jméno a příjmení fyzické osoby
- `surname` — příjmení fyzické osoby
- `birth_date` — datum narození fyzické osoby
- `birth_number` — rodné číslo
- `id_card` — číslo občanského průkazu nebo jiného dokladu totožnosti
- `address` — poštovní adresa fyzické osoby (ulice, č.p./č.o., PSČ, obec)
- `phone` — telefonní číslo (včetně mezinárodní předvolby)
- `email` — e-mailová adresa
- `bank_account` — číslo bankovního účtu (včetně kódu banky) nebo IBAN
- `price` — jakákoliv finanční částka, cena, sazba nebo procentní hodnota (nájem, zálohy, jistota, poplatky, dílčí i celkové částky); nezahrnuje nefinanční čísla (m², PSČ, roky, …)
- `ico` — IČO (identifikační číslo osoby)
- `dic` — DIČ (daňové identifikační číslo)
- Lze zadat i vlastní klíč — pak je vhodné doplnit jeho význam přes parametr `definitions`.
+ `definitions` (string, optional) - JSON objekt `{klíč: popis}` upřesňující sémantiku klíčů (co přesně daný typ znamená).
+ `additional_prompt` (string, optional) - Individuální instrukce pro AI (např. „nezakrývej prvního majitele").
+ `color` (string, optional) - HEX barva překryvu. Výchozí `#000000`.
+ `high_accuracy` (integer, optional) - `1` = přesnější (ale pomalejší) model. Výchozí `0`.
+ `dpi` (integer, optional) - Rozlišení renderu stránek. Výchozí `150`.
+ `snap_to_text` (integer, optional) - `1` = přichycení překryvu na textovou vrstvu pro přesnější pokrytí hodnoty. Výchozí `1`.
Příklad CURL:
curl --location --request POST 'https://www.evidoo.cz/v1/api/file/anonymize' \
--header 'Authorization: Bearer VÁŠ_BEARER_TOKEN' \
--form 'file=@"/cesta/k/souboru/smlouva.pdf"' \
--form 'keys="name,price,email,bank_account"' \
--output smlouva_anonymized.pdf
Response 200 (application/pdf)
Vrací přímo anonymizované PDF ke stažení. Doplňující informace jsou v hlavičkách odpovědi:
Content-Type: application/pdf
Content-Disposition: attachment; filename="smlouva_anonymized.pdf"
X-Anonymize-Applied: 7 (počet začerněných míst)
X-Anonymize-Pages: 3 (počet stran dokumentu)
Chybové odpovědi
+ `400` - chybí `file` nebo `keys`, soubor není PDF, nebo je PDF chráněné heslem / poškozené. Tělo je JSON `{ "status": 400 }`.
+ `502` - Document Service je dočasně nedostupná nebo selhala neočekávaně.
Vložení podpisů do PDF
[POST] /v1/api/file/sign
AI spáruje osobu (odvozenou z názvu PNG nebo z mapy names) se správným podpisovým slotem v dokumentu podle role a jména a posadí podpis na detekovanou podpisovou linku. Textová vrstva dokumentu zůstává zachována. Vrací podepsané PDF.
Request
+ Parameters (multipart/form-data)
+ `file` (file, required) - PDF dokument k podpisu.
+ `signatures` (array, required) - Jeden či více obrázků podpisů (ideálně PNG s průhledným pozadím). Osoba se odvodí z názvu souboru — např. `podpis-novak.png` → „novak".
+ `names` (string, optional) - JSON objekt `{název_souboru: jméno osoby}` pro explicitní mapování podpisu na osobu. Má přednost před odvozením z názvu souboru.
+ `additional_prompt` (string, optional) - Individuální instrukce pro umístění podpisu (má přednost).
+ `high_accuracy` (integer, optional) - `1` = přesnější (pomalejší) model. Výchozí `0`.
+ `dpi` (integer, optional) - Rozlišení renderu. Výchozí `150`.
+ `max_height_pt` (number, optional) - Maximální výška vloženého podpisu v PDF bodech. Výchozí `50`.
+ `snap_to_line` (integer, optional) - `1` = přichycení podpisu na podpisovou linku. Výchozí `1`.
Příklad CURL:
curl --location --request POST 'https://www.evidoo.cz/v1/api/file/sign' \
--header 'Authorization: Bearer VÁŠ_BEARER_TOKEN' \
--form 'file=@"/cesta/k/souboru/smlouva.pdf"' \
--form 'signatures[]=@"/cesta/k/podpisum/podpis-novak.png"' \
--form 'signatures[]=@"/cesta/k/podpisum/podpis-svoboda.png"' \
--output smlouva_signed.pdf
Response 200 (application/pdf)
Vrací přímo podepsané PDF. Doplňující informace jsou v hlavičkách odpovědi:
Content-Type: application/pdf
Content-Disposition: attachment; filename="smlouva_signed.pdf"
X-Sign-Placed: 2 (počet vložených podpisů)
X-Sign-Pages: 1 (počet stran dokumentu)
Chybové odpovědi
+ `400` - chybí `file` nebo `signatures`, soubor není PDF, podpis není obrázek, nebo je PDF chráněné heslem / poškozené.
+ `502` - Document Service je dočasně nedostupná nebo selhala neočekávaně.