{ "openapi": "3.1.0", "info": { "title": "Evidka API", "version": "1.0.0", "description": "REST/JSON brána pro EET 2.0 (zákon č. 180/2026 Sb.). Podpis WS-Security, pokladní certifikáty, fronta a doposílání do 48 h, webhooky. Lidská dokumentace: /docs/" }, "servers": [ { "url": "/" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "trzby", "description": "Evidence tržeb" }, { "name": "certifikaty", "description": "Pokladní certifikáty z DIS+" }, { "name": "ucet", "description": "Účet, klíče, webhooky" }, { "name": "partner", "description": "Pod-účty pro zákazníky partnera" }, { "name": "verejne", "description": "Bez autentizace" } ], "paths": { "/v1/zdravi": { "get": { "tags": [ "verejne" ], "security": [], "summary": "Kontrola dostupnosti brány", "responses": { "200": { "description": "OK" } } } }, "/v1/stav": { "get": { "tags": [ "verejne" ], "security": [], "summary": "Dostupnost EET 2.0 z monitoringu (ověřovací zprávy)", "responses": { "200": { "description": "Stav podle prostředí" } } } }, "/v1/sandbox": { "post": { "tags": [ "verejne" ], "security": [], "summary": "Zkušební účet na 7 dní (playground, veřejný testovací certifikát FS)", "responses": { "201": { "description": "Účet založen: klic, platnostDni, odkazy na pokladnu a dashboard" }, "429": { "$ref": "#/components/responses/Chyba" } } } }, "/v1/sandbox/vypadek": { "post": { "tags": [ "ucet" ], "summary": "Zkušební účet: simulovat výpadek spojení s FS (1–10 minut); tržby jdou do fronty a po skončení se doposílají", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "minut": { "type": "integer", "minimum": 1, "maximum": 10, "default": 2 } } } } } }, "responses": { "200": { "description": "vypadekDo – konec výpadku" }, "403": { "$ref": "#/components/responses/Chyba" } } }, "delete": { "tags": [ "ucet" ], "summary": "Zkušební účet: ukončit simulovaný výpadek, tržby z fronty se hned doposílají", "responses": { "200": { "description": "doposilame – počet tržeb ve frontě" }, "403": { "$ref": "#/components/responses/Chyba" } } } }, "/v1/trzby": { "post": { "tags": [ "trzby" ], "summary": "Zaevidovat tržbu", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrzbaVstup" } } } }, "responses": { "200": { "description": "Tržba se stejným externiId / údaji už existuje – vrací se beze změny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trzba" } } } }, "201": { "description": "Přijato (POK) nebo ověřeno (ověřovací mód)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trzba" } } } }, "202": { "description": "Ve frontě – FS neodpověděla včas, doposílá se (do 48 h)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trzba" } } } }, "400": { "$ref": "#/components/responses/Chyba" }, "409": { "$ref": "#/components/responses/Chyba" }, "422": { "description": "FS odmítla kritickou chybou (stav chyba)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trzba" } } } }, "429": { "$ref": "#/components/responses/Chyba" } } }, "get": { "tags": [ "trzby" ], "summary": "Seznam tržeb", "parameters": [ { "name": "od", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "do", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "stav", "in": "query", "schema": { "$ref": "#/components/schemas/Stav" } }, { "name": "pokladna", "in": "query", "schema": { "type": "string" } }, { "name": "eic", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 1000, "default": 100 } }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "trzby": { "type": "array", "items": { "$ref": "#/components/schemas/Trzba" } } } } } } } } } }, "/v1/trzby/{id}": { "get": { "tags": [ "trzby" ], "summary": "Detail tržby včetně pokusů o odeslání", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/Chyba" } } } }, "/v1/trzby/{id}/opakovat": { "post": { "tags": [ "trzby" ], "summary": "Ručně odeslat znovu (stav chyba / fronta)", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "Aktuální stav", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trzba" } } } } } } }, "/v1/trzby/{id}/storno": { "post": { "tags": [ "trzby" ], "summary": "Storno = záporná tržba (§ 8)", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "castka": { "type": "string", "description": "Částečné storno; výchozí celá částka" }, "idPokl": { "type": "string" } } } } } }, "responses": { "201": { "description": "Storno přijato" }, "202": { "description": "Storno ve frontě" } } } }, "/v1/souhrn": { "get": { "tags": [ "trzby" ], "summary": "Souhrn přijatých tržeb (dny, způsoby platby, pokladny)", "parameters": [ { "name": "od", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "do", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "eic", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "OK" } } } }, "/v1/export.csv": { "get": { "tags": [ "trzby" ], "summary": "CSV pro účetní (středník, desetinná čárka, UTF-8 s BOM)", "parameters": [ { "name": "od", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "do", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "eic", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "CSV", "content": { "text/csv": {} } } } } }, "/v1/vyuziti": { "get": { "tags": [ "ucet" ], "summary": "Využití za měsíc (aktivní pokladny podle EIČ)", "parameters": [ { "name": "mesic", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/ucet": { "get": { "tags": [ "ucet" ], "summary": "Účet a přehled (fronta, chyby, certifikáty před expirací)", "parameters": [ { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "OK" } } } }, "/v1/klice": { "post": { "tags": [ "ucet" ], "summary": "Nový API klíč (zobrazí se jen jednou)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "popis": { "type": "string" }, "test": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Klíč" } } } }, "/v1/webhook": { "put": { "tags": [ "ucet" ], "summary": "Nastavit webhook (null = vypnout)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" } } } } } }, "responses": { "200": { "description": "URL a tajný klíč pro HMAC" } } } }, "/v1/certifikaty": { "get": { "tags": [ "certifikaty" ], "summary": "Seznam certifikátů", "parameters": [ { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "certifikaty": { "type": "array", "items": { "$ref": "#/components/schemas/Certifikat" } } } } } } } } }, "post": { "tags": [ "certifikaty" ], "summary": "Nahrát pokladní certifikát (.p12)", "parameters": [ { "$ref": "#/components/parameters/EvidkaUcet" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "p12Base64" ], "properties": { "p12Base64": { "type": "string", "format": "byte" }, "heslo": { "type": "string" }, "nazev": { "type": "string" }, "prostredi": { "type": "string", "enum": [ "playground", "produkce" ] } } } } } }, "responses": { "201": { "description": "Uloženo (šifrovaně)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certifikat" } } } }, "400": { "$ref": "#/components/responses/Chyba" } } } }, "/v1/certifikaty/{id}": { "delete": { "tags": [ "certifikaty" ], "summary": "Deaktivovat certifikát", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "200": { "description": "OK" } } } }, "/v1/certifikaty/{id}/obnovit": { "post": { "tags": [ "certifikaty" ], "summary": "Obnovit certifikát přes API CA EET", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/EvidkaUcet" } ], "responses": { "201": { "description": "Nový certifikát", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certifikat" } } } }, "409": { "$ref": "#/components/responses/Chyba" }, "502": { "$ref": "#/components/responses/Chyba" } } } }, "/v1/partner/ucty": { "post": { "tags": [ "partner" ], "summary": "Založit pod-účet pro zákazníka", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "nazev" ], "properties": { "nazev": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "Pod-účet a jeho API klíč" }, "403": { "$ref": "#/components/responses/Chyba" } } }, "get": { "tags": [ "partner" ], "summary": "Pod-účty s využitím za měsíc", "parameters": [ { "name": "mesic", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API klíč evk_live_… / evk_test_…" } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Stejný klíč = stejná tržba, nic se neodešle dvakrát" }, "EvidkaUcet": { "name": "Evidka-Ucet", "in": "header", "schema": { "type": "string" }, "description": "Jen partner: jednat za pod-účet (ID ten_…)" } }, "responses": { "Chyba": { "description": "Chyba", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chyba" } } } } }, "schemas": { "Stav": { "type": "string", "enum": [ "odesila", "prijato", "overeno", "fronta", "chyba" ] }, "ZpusobPlatby": { "type": "string", "enum": [ "hotove", "karta", "qr", "stravenky", "jine" ] }, "Chyba": { "type": "object", "properties": { "chyba": { "type": "object", "properties": { "kod": { "type": "string" }, "zprava": { "type": "string" }, "pole": { "type": "string" } }, "required": [ "kod", "zprava" ] } } }, "TrzbaVstup": { "type": "object", "required": [ "idJednotky", "castka" ], "properties": { "idJednotky": { "type": [ "integer", "string" ], "description": "Číslo evidenční jednotky z DIS+" }, "castka": { "type": [ "string", "number" ], "description": "Kč; \"1249.50\" nebo \"1249,50\"; záporná = vrácení" }, "idPokl": { "type": "string", "maxLength": 20, "pattern": "^[0-9a-zA-Z.,:;/#\\-_ ]{1,20}$" }, "poradCis": { "type": "string", "maxLength": 25, "description": "Když chybí, přidělí se RRRR/n" }, "datTrzby": { "type": "string", "format": "date-time" }, "zpusobPlatby": { "$ref": "#/components/schemas/ZpusobPlatby" }, "urcenoCerpZuct": { "type": [ "string", "number" ] }, "cerpZuct": { "type": [ "string", "number" ] }, "eicPoverujiciho": { "type": "string" }, "povereniVicePopl": { "type": "boolean" }, "eic": { "type": "string" }, "certifikatId": { "type": "string" }, "overeni": { "type": "boolean", "description": "Ověřovací mód – neeviduje se" }, "externiId": { "type": "string" }, "poznamka": { "type": "string", "maxLength": 200 } } }, "Trzba": { "type": "object", "properties": { "id": { "type": "string" }, "stav": { "$ref": "#/components/schemas/Stav" }, "pok": { "type": [ "string", "null" ] }, "test": { "type": "boolean" }, "overeni": { "type": "boolean" }, "prostredi": { "type": "string", "enum": [ "playground", "produkce" ] }, "externiId": { "type": [ "string", "null" ] }, "eic": { "type": "string" }, "idJednotky": { "type": "string" }, "idPokl": { "type": "string" }, "poradCis": { "type": "string" }, "datTrzby": { "type": "string" }, "castka": { "type": "string" }, "zpusobPlatby": { "type": [ "string", "null" ] }, "poznamka": { "type": [ "string", "null" ] }, "varovani": { "type": "array", "items": { "type": "object", "properties": { "kod": { "type": "integer" }, "text": { "type": "string" }, "popis": { "type": "string" } } } }, "chyba": { "type": [ "object", "null" ], "properties": { "kod": { "type": "integer" }, "text": { "type": "string" } } }, "pokusy": { "type": "integer" }, "dalsiPokus": { "type": [ "string", "null" ] }, "lhutaDoposlani": { "type": "string" }, "poLhute": { "type": "boolean" }, "prijato": { "type": [ "string", "null" ] }, "transactionId": { "type": [ "string", "null" ] }, "podpisFS": { "type": [ "boolean", "null" ] }, "vytvoreno": { "type": "string" } } }, "Certifikat": { "type": "object", "properties": { "id": { "type": "string" }, "eic": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "prostredi": { "type": "string", "enum": [ "playground", "produkce" ] }, "subject": { "type": [ "string", "null" ] }, "issuer": { "type": [ "string", "null" ] }, "platnostOd": { "type": "string" }, "platnostDo": { "type": "string" }, "dniDoExpirace": { "type": "integer" }, "aktivni": { "type": "boolean" }, "nahrazen": { "type": [ "string", "null" ] }, "obnovaChyba": { "type": [ "string", "null" ] }, "vytvoreno": { "type": "string" } } } } } }