{ "openapi": "3.0.3", "info": { "title": "ePostak Enterprise API", "description": "Enterprise REST API pre e-fakturaciu cez Peppol. API key auth, JSON aj XML mode, multi-tenant.\n\nDocs: https://epostak.sk/api/docs/enterprise", "version": "1.0.0", "contact": { "email": "info@epostak.sk", "url": "https://epostak.sk" } }, "servers": [ { "url": "https://epostak.sk/api/enterprise", "description": "Production" } ], "tags": [ { "name": "Documents", "description": "Odosielanie dokumentov cez Peppol" }, { "name": "Inbox", "description": "Prijate dokumenty" }, { "name": "Account", "description": "Informacie o ucte a firme" }, { "name": "Extraction", "description": "OCR extrakcia faktur z PDF/obrazkov (Enterprise only)" }, { "name": "Webhooks", "description": "Sprava webhook odberov (Enterprise only)" }, { "name": "Firms", "description": "Sprava firiem a Peppol identifikatorov" }, { "name": "Peppol", "description": "SMP lookup a Peppol directory" }, { "name": "Reporting", "description": "Statistiky a reporty" }, { "name": "OAuth", "description": "OAuth 2.0 token exchange" } ], "security": [ { "apiKeyAuth": [] } ], "paths": { "/documents/send": { "post": { "tags": [ "Documents" ], "summary": "Odoslat dokument cez Peppol", "description": "Odosle fakturu cez Peppol siet. Podporuje dva rezimy:\n\n**JSON mode** — poskytnete strukturovane data (`items`), UBL XML sa vygeneruje automaticky.\n\n**XML mode** — poskytnete hotove UBL XML (`xml`), odosle sa priamo.\n\nV oboch pripadoch je `receiverPeppolId` povinne.", "operationId": "sendDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SendDocumentJsonRequest" }, { "$ref": "#/components/schemas/SendDocumentXmlRequest" } ] }, "examples": { "json_mode": { "summary": "JSON mode", "value": { "receiverPeppolId": "0245:12345678", "invoiceNumber": "FAK-2026-0001", "issueDate": "2026-04-01", "dueDate": "2026-04-15", "currency": "EUR", "iban": "SK1234567890123456789012", "items": [ { "description": "Konzultacne sluzby", "quantity": 10, "unit": "HUR", "unitPrice": 50.0, "vatRate": 23 } ] } }, "xml_mode": { "summary": "XML mode", "value": { "receiverPeppolId": "0245:12345678", "xml": "..." } } } } } }, "responses": { "201": { "description": "Dokument uspesne odoslany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendDocumentResponse" } } } }, "400": { "description": "Chybajuce alebo neplatne polia", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Firma nenajdena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Peppol validacia zlyhala", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolValidationErrorResponse" } } } } } } }, "/documents/inbox": { "get": { "tags": [ "Inbox" ], "summary": "Zoznam prijatych dokumentov", "description": "Vrati strankovany zoznam dokumentov prijatych cez Peppol pre vasu firmu.", "operationId": "listInbox", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Pocet preskocenych zaznamov" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Pocet vratenych zaznamov" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "RECEIVED", "ACKNOWLEDGED" ] }, "description": "Filter podla stavu dokumentu" } ], "responses": { "200": { "description": "Zoznam prijatych dokumentov", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxListResponse" } } } }, "400": { "description": "Neplatny filter status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/inbox/{id}": { "get": { "tags": [ "Inbox" ], "summary": "Detail prijateho dokumentu", "description": "Vrati kompletne data prijateho dokumentu vratane UBL XML payloadu (ak je dostupny).", "operationId": "getInboxDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "responses": { "200": { "description": "Detail dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDocumentDetailResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Dokument nepatri vasej firme", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny alebo nie je inbound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/inbox/{id}/acknowledge": { "post": { "tags": [ "Inbox" ], "summary": "Potvrdit prijatie dokumentu", "description": "Oznaci dokument ako spracovany (`ACKNOWLEDGED`). Ak bol dokument uz potvrdeny, vrati chybu.", "operationId": "acknowledgeDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "responses": { "200": { "description": "Dokument potvrdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeResponse" } } } }, "400": { "description": "Dokument bol uz potvrdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Dokument nepatri vasej firme", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny alebo nie je inbound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/account": { "get": { "tags": [ "Account" ], "summary": "Informacie o ucte", "description": "Vrati zakladne informacie o firme, stav Peppol registracie, aktivny plan a statistiky odoslanych/prijatych dokumentov.", "operationId": "getAccount", "responses": { "200": { "description": "Informacie o ucte", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Firma nenajdena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/extract": { "post": { "tags": [ "Extraction" ], "summary": "Extrahovat fakturu z PDF alebo obrazka", "description": "Nahra PDF alebo obrazok faktury, extrahuje data pomocou AI (Claude Vision) a vrati strukturovane data spolu s vygenerovanym UBL XML.\n\n**Vyzaduje plan `api-enterprise`.**\n\nPovolene typy: `application/pdf`, `image/jpeg`, `image/png`, `image/webp`. Max. velkost: 20 MB.", "operationId": "extractDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "PDF alebo obrazok faktury (max 20 MB)" } } } } } }, "responses": { "200": { "description": "Extrakcia uspesna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } } } }, "400": { "description": "Chybajuci subor, nepodporovany typ alebo prilis velky subor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan api-enterprise je vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleErrorResponse" } } } }, "422": { "description": "Extrakcia alebo UBL generovanie zlyhalo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractErrorResponse" } } } } } } }, "/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Vytvorit webhook", "description": "Zaregistruje novu webhook URL pre vybrane udalosti. URL musi byt HTTPS a nesmie byt localhost ani privatna siet.\n\n**Vyzaduje plan `api-enterprise`.**\n\nPodporovane udalosti: `document.created`, `document.sent`, `document.received`, `document.validated`.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "example": { "url": "https://vas-system.sk/webhooks/epostak", "events": [ "document.received", "document.sent" ] } } } }, "responses": { "201": { "description": "Webhook vytvoreny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDetailResponse" } } } }, "400": { "description": "Neplatna URL alebo udalosti", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan api-enterprise je vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } } } }, "get": { "tags": [ "Webhooks" ], "summary": "Zoznam webhookov", "description": "Vrati vsetky webhook odoberania pre vasu firmu.\n\n**Vyzaduje plan `api-enterprise`.**", "operationId": "listWebhooks", "responses": { "200": { "description": "Zoznam webhookov", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan api-enterprise je vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } } } } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Detail webhooku", "description": "Vrati detaily webhooku vratane poslednych 20 doruceni.\n\n**Vyzaduje plan `api-enterprise`.**", "operationId": "getWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID webhooku" } ], "responses": { "200": { "description": "Detail webhooku", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithDeliveriesResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook nenajdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Upravit webhook", "description": "Aktualizuje URL, zoznam udalosti alebo aktivny stav webhooku. Vsetky polia su volitelne.\n\n**Vyzaduje plan `api-enterprise`.**", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID webhooku" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook aktualizovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Neplatna URL alebo udalosti", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty alebo plan api-enterprise vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook nenajdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Zmazat webhook", "description": "Natrvalo zmaze webhook.\n\n**Vyzaduje plan `api-enterprise`.**", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID webhooku" } ], "responses": { "200": { "description": "Webhook zmazany", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty alebo plan api-enterprise vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook nenajdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/{id}/status": { "get": { "tags": [ "Documents" ], "summary": "Stav dokumentu — uplny lifecycle", "description": "Vrati aktualny stav dokumentu vratane kompletnej historie stavov.", "operationId": "getDocumentStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "responses": { "200": { "description": "Stav dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentStatusResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/{id}/evidence": { "get": { "tags": [ "Documents" ], "summary": "Dokazy o doruceni dokumentu", "description": "Vrati AS4 receipt, Message Level Response (MLR) a invoice response pre odoslany dokument.", "operationId": "getDocumentEvidence", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "responses": { "200": { "description": "Dokazy o doruceni", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentEvidenceResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/{id}/pdf": { "get": { "tags": [ "Documents" ], "summary": "Stiahnut PDF dokumentu", "description": "Vrati PDF verziu faktury ako binarny subor.", "operationId": "getDocumentPdf", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "responses": { "200": { "description": "PDF subor", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny alebo PDF nie je dostupne", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/{id}/ubl": { "get": { "tags": [ "Documents" ], "summary": "Stiahnut UBL XML dokumentu", "description": "Vrati UBL XML reprezentaciu dokumentu.", "operationId": "getDocumentUbl", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "responses": { "200": { "description": "UBL XML subor", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny alebo UBL nie je dostupne", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/{id}/responses": { "get": { "tags": [ "Documents" ], "summary": "Zoznam invoice responses dokumentu", "description": "Vrati zoznam invoice responses (AP/RE/UQ) pre odoslany dokument.", "operationId": "listDocumentResponses", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "responses": { "200": { "description": "Zoznam invoice responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponsesListResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/{id}/respond": { "post": { "tags": [ "Documents" ], "summary": "Odoslat invoice response", "description": "Odosle invoice response (AP — accepted, RE — rejected, UQ — under query) pre prijaty dokument.", "operationId": "respondToDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID dokumentu" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRespondRequest" }, "example": { "responseCode": "AP", "note": "Faktura akceptovana" } } } }, "responses": { "201": { "description": "Invoice response odoslana", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRespondResponse" } } } }, "400": { "description": "Neplatny responseCode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dokument nenajdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/validate": { "post": { "tags": [ "Documents" ], "summary": "Validovat dokument bez odoslania", "description": "Overi UBL XML alebo JSON data voci Peppol pravidlam bez skutocneho odoslania. Vhodne pre testovanie integracie.", "operationId": "validateDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SendDocumentJsonRequest" }, { "$ref": "#/components/schemas/SendDocumentXmlRequest" } ] } } } }, "responses": { "200": { "description": "Validacia uspesna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateDocumentResponse" } } } }, "400": { "description": "Chybajuce alebo neplatne polia", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Peppol validacia zlyhala", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolValidationErrorResponse" } } } } } } }, "/documents/preflight": { "post": { "tags": [ "Documents" ], "summary": "Pred-odosielacia validacia", "description": "Skontroluje, ci je prijemca registrovany v Peppol sieti a podporuje dany typ dokumentu, este pred odoslanim.", "operationId": "preflightDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "receiverPeppolId" ], "properties": { "receiverPeppolId": { "type": "string", "example": "0245:12345678", "description": "Peppol ID prijemcu" }, "documentTypeId": { "type": "string", "example": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2", "description": "Typ dokumentu (volitelne, default: Invoice)" } } } } } }, "responses": { "200": { "description": "Vysledok preflight kontroly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightResponse" } } } }, "400": { "description": "Chybajuce polia", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/convert": { "post": { "tags": [ "Documents" ], "summary": "Konverzia formatov dokumentu", "description": "Konvertuje medzi JSON a UBL XML formatmi. Smer urcite parametrom `direction`: `json_to_ubl` alebo `ubl_to_json`.", "operationId": "convertDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertDocumentRequest" }, "examples": { "json_to_ubl": { "summary": "JSON → UBL", "value": { "direction": "json_to_ubl", "data": { "invoiceNumber": "FAK-001", "items": [] } } }, "ubl_to_json": { "summary": "UBL → JSON", "value": { "direction": "ubl_to_json", "xml": "..." } } } } } }, "responses": { "200": { "description": "Konverzia uspesna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertDocumentResponse" } } } }, "400": { "description": "Neplatny vstup alebo direction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Konverzia zlyhala", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/peppol/participants/{scheme}/{identifier}": { "get": { "tags": [ "Peppol" ], "summary": "SMP lookup ucastnika", "description": "Vyhlada Peppol ucastnika v SMP (Service Metadata Publisher) podla scheme a identifikatora.", "operationId": "smpLookup", "parameters": [ { "name": "scheme", "in": "path", "required": true, "schema": { "type": "string", "example": "0245" }, "description": "ICD scheme kod (napr. 0245 pre slovenske ICO)" }, { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "example": "12345678" }, "description": "Identifikator v danej scheme" } ], "responses": { "200": { "description": "Ucastnik najdeny", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmpLookupResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Ucastnik nie je registrovany v Peppol sieti", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/peppol/directory/search": { "get": { "tags": [ "Peppol" ], "summary": "Prehladavat Peppol directory", "description": "Prehladava Peppol Business Card directory podla nazvu firmy, krajiny a inych kriterii.", "operationId": "peppolDirectorySearch", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "example": "Moja firma" }, "description": "Vyhladavaci vyraz (nazov firmy, ICO)" }, { "name": "country", "in": "query", "schema": { "type": "string", "example": "SK" }, "description": "Filtrovanie podla kodu krajiny (ISO 3166-1 alpha-2)" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Cislo strany" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Pocet vysledkov na stranu" } ], "responses": { "200": { "description": "Vysledky vyhladavania", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolDirectorySearchResponse" } } } }, "400": { "description": "Neplatne parametre", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/company/lookup/{ico}": { "get": { "tags": [ "Peppol" ], "summary": "Vyhladanie firmy podla ICO", "description": "Vyhlada verejne informacie o firme podla ICO (slovensky obchodny register).", "operationId": "companyLookup", "parameters": [ { "name": "ico", "in": "path", "required": true, "schema": { "type": "string", "example": "12345678" }, "description": "ICO firmy (8 cislic)" } ], "responses": { "200": { "description": "Informacie o firme", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookupResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Firma s danym ICO nenajdena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/firms": { "get": { "tags": [ "Firms" ], "summary": "Zoznam pristupnych firiem", "description": "Vrati zoznam firiem, ku ktorym ma API kluc pristup. Relevantne pre multi-tenant API kluce.", "operationId": "listFirms", "responses": { "200": { "description": "Zoznam firiem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmsListResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/firms/{id}": { "get": { "tags": [ "Firms" ], "summary": "Detail firmy", "description": "Vrati detailne informacie o konkretnej firme vratane Peppol statusu.", "operationId": "getFirm", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID firmy" } ], "responses": { "200": { "description": "Detail firmy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmDetailResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Firma nenajdena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/firms/{id}/documents": { "get": { "tags": [ "Firms" ], "summary": "Dokumenty firmy", "description": "Vrati strankovany zoznam dokumentov (odoslanych aj prijatych) pre danu firmu.", "operationId": "listFirmDocuments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID firmy" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Pocet preskocenych zaznamov" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Pocet vratenych zaznamov" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "description": "Filter podla smeru" } ], "responses": { "200": { "description": "Zoznam dokumentov firmy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxListResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Firma nenajdena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/firms/{id}/peppol-identifiers": { "post": { "tags": [ "Firms" ], "summary": "Registrovat Peppol identifikator", "description": "Zaregistruje novy Peppol identifikator (scheme:identifier) pre firmu v SMP.", "operationId": "registerPeppolIdentifier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID firmy" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheme", "identifier" ], "properties": { "scheme": { "type": "string", "example": "0245", "description": "ICD scheme kod" }, "identifier": { "type": "string", "example": "12345678", "description": "Identifikator v danej scheme" } } }, "example": { "scheme": "0245", "identifier": "12345678" } } } }, "responses": { "201": { "description": "Peppol identifikator zaregistrovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolIdentifierResponse" } } } }, "400": { "description": "Neplatny scheme alebo identifikator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Pristup odmietnuty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Identifikator uz existuje", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook-queue": { "get": { "tags": [ "Webhooks" ], "summary": "Nacitat neuznane udalosti", "description": "Vrati zoznam neuznanych (nepotvrdenych) udalosti z webhook frontu. Alternativa k push webhookom pre polling pristup.\n\n**Vyzaduje plan `api-enterprise`.**", "operationId": "getWebhookQueue", "responses": { "200": { "description": "Zoznam cakajucich udalosti", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookQueueResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan api-enterprise je vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } } } } }, "/webhook-queue/{eventId}": { "delete": { "tags": [ "Webhooks" ], "summary": "Potvrdit jednu udalost", "description": "Potvrdi (acknowledge) jednu udalost a odstrani ju z frontu.\n\n**Vyzaduje plan `api-enterprise`.**", "operationId": "acknowledgeWebhookEvent", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID udalosti" } ], "responses": { "200": { "description": "Udalost potvrdena", "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledged": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan api-enterprise je vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "Udalost nenajdena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook-queue/batch-ack": { "post": { "tags": [ "Webhooks" ], "summary": "Hromadne potvrdenie udalosti", "description": "Potvrdi (acknowledge) viacero udalosti naraz.\n\n**Vyzaduje plan `api-enterprise`.**", "operationId": "batchAcknowledgeWebhookEvents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "eventIds" ], "properties": { "eventIds": { "type": "array", "items": { "type": "string" }, "example": [ "evt_1", "evt_2", "evt_3" ], "description": "Zoznam ID udalosti na potvrdenie" } } } } } }, "responses": { "200": { "description": "Udalosti potvrdene", "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledged": { "type": "integer", "example": 3, "description": "Pocet potvrdenych udalosti" } } } } } }, "400": { "description": "Chybajuci alebo prazdny zoznam eventIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan api-enterprise je vyzadovany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } } } } }, "/reporting/statistics": { "get": { "tags": [ "Reporting" ], "summary": "Statistiky dokumentov", "description": "Vrati agregovane statistiky odoslanych a prijatych dokumentov za zvolene obdobie.", "operationId": "getStatistics", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-01-01" }, "description": "Zaciatok obdobia (YYYY-MM-DD)" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-03-31" }, "description": "Koniec obdobia (YYYY-MM-DD)" } ], "responses": { "200": { "description": "Statistiky dokumentov", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatisticsResponse" } } } }, "401": { "description": "Neplatny alebo chybajuci API kluc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/extract/batch": { "post": { "tags": [ "Extraction" ], "summary": "Batch OCR extraction", "description": "Extract invoice data from multiple PDF/image files (max 50, 20MB each)", "operationId": "extractBatch", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 50 } }, "required": [ "files" ] } } } }, "responses": { "200": { "description": "Batch extraction results" }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error" } } } }, "/firms/assign": { "post": { "tags": [ "Firms" ], "summary": "Assign firm by ICO", "description": "Assign a firm to the enterprise account by its ICO. Requires a Bearer sk_int_* token. No X-Firm-Id header needed.", "operationId": "assignFirmByIco", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignFirmRequest" }, "example": { "ico": "12345678" } } } }, "responses": { "201": { "description": "Firm assigned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignFirmResponse" } } } }, "404": { "description": "Firm not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Already assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid ICO", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/firms/assign/batch": { "post": { "tags": [ "Firms" ], "summary": "Batch assign firms by ICO list", "description": "Assign multiple firms at once. Maximum 50 ICOs per request.", "operationId": "batchAssignFirms", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAssignFirmsRequest" }, "example": { "icos": [ "12345678", "87654321" ] } } } }, "responses": { "200": { "description": "Batch assign results (per-ICO success or error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAssignFirmsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/documents/inbox/all": { "get": { "tags": [ "Inbox" ], "summary": "Cross-firm bulk inbox", "description": "Returns received documents across all assigned firms. No X-Firm-Id header needed. Requires Bearer sk_int_* token.", "operationId": "getCrossFirmInbox", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Pagination offset" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum number of documents to return (max 200)" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "RECEIVED", "ACKNOWLEDGED" ] }, "description": "Filter by document status" }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return only documents received after this ISO 8601 timestamp" }, { "name": "firm_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by firm UUID" } ], "responses": { "200": { "description": "List of received documents across all firms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrossFirmInboxResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook-queue/all": { "get": { "tags": [ "Webhooks" ], "summary": "Cross-firm webhook queue poll", "description": "Poll pending webhook events across all assigned firms. No X-Firm-Id header needed. Requires Bearer sk_int_* token.", "operationId": "getCrossFirmWebhookQueue", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Maximum number of events to return (max 500)" }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return only events created after this ISO 8601 timestamp" } ], "responses": { "200": { "description": "Pending webhook events across all firms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrossFirmWebhookQueueResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook-queue/all/batch-ack": { "post": { "tags": [ "Webhooks" ], "summary": "Cross-firm batch acknowledge webhook events", "description": "Acknowledge multiple webhook events across all firms in a single request. Maximum 1000 event IDs.", "operationId": "batchAckCrossFirmWebhookEvents", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAckWebhookRequest" }, "example": { "event_ids": [ "uuid-1", "uuid-2" ] } } } }, "responses": { "200": { "description": "Number of events acknowledged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAckWebhookResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/oauth/token": { "post": { "tags": [ "OAuth" ], "summary": "OAuth 2.0 token exchange", "description": "Exchange an authorization code for an access token (Bearer sk_int_*). Supports PKCE via code_verifier.", "operationId": "oauthTokenExchange", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" }, "example": { "grant_type": "authorization_code", "code": "auth_code_here", "client_id": "client_id_here", "client_secret": "client_secret_here", "redirect_uri": "https://example.com/callback", "code_verifier": "pkce_verifier_here" } } } }, "responses": { "200": { "description": "Access token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "Invalid grant or request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid client credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Enterprise API kluc. Generujte v nastaveniach firmy." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_int_*", "description": "Internal bearer token (sk_int_*). Used for cross-firm endpoints and OAuth flow." } }, "schemas": { "LineItem": { "type": "object", "required": [ "description", "quantity", "unitPrice", "vatRate" ], "properties": { "description": { "type": "string", "example": "Konzultacne sluzby" }, "quantity": { "type": "number", "example": 10 }, "unit": { "type": "string", "example": "HUR", "description": "Jednotka (UN/CEFACT kod). Napr. HUR=hodiny, C62=kusy, KGM=kg." }, "unitPrice": { "type": "number", "example": 50.0 }, "vatRate": { "type": "number", "example": 23, "description": "DPH sadzba v percentach" }, "discount": { "type": "number", "example": 10, "description": "Zlava v percentach (volitelne)" } } }, "SendDocumentJsonRequest": { "type": "object", "required": [ "receiverPeppolId", "items" ], "description": "JSON mode — UBL XML sa generuje automaticky", "properties": { "receiverPeppolId": { "type": "string", "example": "0245:12345678", "description": "Peppol ID prijemcu" }, "invoiceNumber": { "type": "string", "example": "FAK-2026-0001", "description": "Cislo faktury (ak nie je zadane, generuje sa automaticky)" }, "issueDate": { "type": "string", "format": "date", "example": "2026-04-01" }, "dueDate": { "type": "string", "format": "date", "example": "2026-04-15" }, "currency": { "type": "string", "example": "EUR", "default": "EUR" }, "note": { "type": "string", "example": "Dakujeme za objednavku." }, "iban": { "type": "string", "example": "SK1234567890123456789012" }, "paymentMethod": { "type": "string", "example": "bank_transfer" }, "variableSymbol": { "type": "string", "example": "20260001" }, "buyerReference": { "type": "string", "example": "PO-2026-99" }, "receiverName": { "type": "string", "example": "Zakaznik s.r.o." }, "receiverIco": { "type": "string", "example": "12345678" }, "receiverDic": { "type": "string", "example": "2020123456" }, "receiverIcDph": { "type": "string", "example": "SK2020123456" }, "receiverAddress": { "type": "string", "example": "Hlavna 1, Bratislava, 81101" }, "receiverCountry": { "type": "string", "example": "SK", "default": "SK" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LineItem" } } } }, "SendDocumentXmlRequest": { "type": "object", "required": [ "receiverPeppolId", "xml" ], "description": "XML mode — poskytnute UBL XML sa odosle priamo", "properties": { "receiverPeppolId": { "type": "string", "example": "0245:12345678" }, "xml": { "type": "string", "description": "Kompletne UBL XML (Invoice alebo CreditNote)", "example": "..." } } }, "SendDocumentResponse": { "type": "object", "properties": { "documentId": { "type": "string", "example": "clx1234abcdef", "description": "Interne ID dokumentu" }, "messageId": { "type": "string", "example": "msg-uuid-here", "description": "Peppol messageId" }, "status": { "type": "string", "enum": [ "SENT" ], "example": "SENT" } } }, "PeppolValidationErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_FAILED" }, "message": { "type": "string", "example": "Document failed Peppol validation" }, "details": { "type": "array", "items": { "type": "string" }, "example": [ "[BR-01] An Invoice shall have a Specification identifier." ] } } } } }, "PartyResponse": { "type": "object", "properties": { "name": { "type": "string", "example": "Moja firma s.r.o." }, "ico": { "type": "string", "example": "12345678" }, "dic": { "type": "string", "example": "2020123456" }, "icDph": { "type": "string", "example": "SK2020123456" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Hlavna 1" }, "city": { "type": "string", "example": "Bratislava" }, "zip": { "type": "string", "example": "81101" }, "country": { "type": "string", "example": "SK" } } }, "peppolId": { "type": "string", "example": "0245:12345678" } } }, "LineItemResponse": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unitPrice": { "type": "number" }, "vatRate": { "type": "number" }, "vatCategory": { "type": "string", "example": "S" }, "lineTotal": { "type": "number" } } }, "DocumentResponse": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string", "example": "FAK-2026-0001" }, "status": { "type": "string", "example": "received" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "docType": { "type": "string", "example": "invoice" }, "issueDate": { "type": "string", "format": "date-time" }, "dueDate": { "type": "string", "format": "date-time", "nullable": true }, "currency": { "type": "string", "example": "EUR" }, "supplier": { "$ref": "#/components/schemas/PartyResponse" }, "customer": { "$ref": "#/components/schemas/PartyResponse" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/LineItemResponse" } }, "totals": { "type": "object", "properties": { "withoutVat": { "type": "number" }, "vat": { "type": "number" }, "withVat": { "type": "number" } } }, "peppolMessageId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "InboxListResponse": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResponse" } }, "total": { "type": "integer", "example": 42 }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 } } }, "InboxDocumentDetailResponse": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "documentTypeId": { "type": "string", "nullable": true, "example": "invoice" }, "processId": { "type": "string", "nullable": true, "description": "Peppol messageId" }, "senderPeppolId": { "type": "string", "nullable": true }, "receiverPeppolId": { "type": "string", "nullable": true }, "status": { "type": "string", "example": "received" }, "receivedAt": { "type": "string", "format": "date-time" }, "payload": { "type": "string", "nullable": true, "description": "UBL XML obsah dokumentu (null ak nie je dostupny)" } } } } }, "AcknowledgeResponse": { "type": "object", "properties": { "documentId": { "type": "string" }, "status": { "type": "string", "enum": [ "ACKNOWLEDGED" ] }, "acknowledgedAt": { "type": "string", "format": "date-time" } } }, "AccountResponse": { "type": "object", "properties": { "firm": { "type": "object", "properties": { "name": { "type": "string", "example": "Moja firma s.r.o." }, "ico": { "type": "string", "nullable": true, "example": "12345678" }, "peppolId": { "type": "string", "nullable": true, "example": "0245:12345678" }, "peppolStatus": { "type": "string", "example": "active" } } }, "plan": { "type": "object", "properties": { "name": { "type": "string", "example": "api-enterprise" }, "status": { "type": "string", "enum": [ "active", "expired" ] } } }, "usage": { "type": "object", "properties": { "outbound": { "type": "integer", "description": "Pocet odoslanych dokumentov" }, "inbound": { "type": "integer", "description": "Pocet prijatych dokumentov" } } } } }, "ExtractResponse": { "type": "object", "properties": { "extraction": { "type": "object", "description": "Extrahovane data z dokumentu (struktura zavisi od obsahu suboru)" }, "ubl_xml": { "type": "string", "description": "Vygenerovane UBL XML z extrahovanych dat" }, "confidence": { "type": "number", "description": "Skore spolahlivosti extrakcie (0–1)", "example": 0.92 }, "file_name": { "type": "string", "example": "faktura-2026-001.pdf" } } }, "ExtractErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "Extraction failed" }, "details": { "type": "string" }, "extraction": { "type": "object" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://vas-system.sk/webhooks/epostak", "description": "HTTPS URL pre dorucovanie udalosti" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "document.created", "document.sent", "document.received", "document.validated" ] }, "description": "Zoznam udalosti na odber. Ak nie je zadany, odobera sa vsetko.", "example": [ "document.received", "document.sent" ] } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "document.created", "document.sent", "document.received", "document.validated" ] } }, "isActive": { "type": "boolean" } } }, "WebhookResponse": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookResponse" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "HMAC-SHA256 signing secret (vrateny iba pri vytvoreni)", "example": "a3f8...hex64chars" } } } ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "webhookId": { "type": "string" }, "event": { "type": "string", "example": "document.received" }, "status": { "type": "string", "example": "delivered" }, "attempts": { "type": "integer", "example": 1 }, "responseStatus": { "type": "integer", "nullable": true, "example": 200 }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookWithDeliveriesResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookResponse" }, { "type": "object", "properties": { "deliveries": { "type": "array", "description": "Poslednych 20 doruceni", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] }, "WebhookListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "receiverPeppolId is required" } } } } }, "ForbiddenErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "FORBIDDEN" }, "message": { "type": "string", "example": "Enterprise plan required" } } } } }, "SimpleErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "file is required (multipart/form-data field: file)" } } }, "StatusHistoryEntry": { "type": "object", "properties": { "status": { "type": "string", "example": "SENT" }, "timestamp": { "type": "string", "format": "date-time" }, "detail": { "type": "string", "nullable": true } } }, "DocumentStatusResponse": { "type": "object", "properties": { "documentId": { "type": "string" }, "status": { "type": "string", "example": "DELIVERED" }, "statusHistory": { "type": "array", "items": { "$ref": "#/components/schemas/StatusHistoryEntry" } }, "updatedAt": { "type": "string", "format": "date-time" } } }, "DocumentEvidenceResponse": { "type": "object", "properties": { "documentId": { "type": "string" }, "as4Receipt": { "type": "object", "nullable": true, "description": "AS4 receipt od pristupoveho bodu prijemcu" }, "mlr": { "type": "object", "nullable": true, "description": "Message Level Response" }, "invoiceResponse": { "type": "object", "nullable": true, "description": "Invoice Response od prijemcu" } } }, "InvoiceResponseItem": { "type": "object", "properties": { "id": { "type": "string" }, "responseCode": { "type": "string", "enum": [ "AP", "RE", "UQ" ], "description": "AP=Accepted, RE=Rejected, UQ=Under Query" }, "note": { "type": "string", "nullable": true }, "senderPeppolId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "InvoiceResponsesListResponse": { "type": "object", "properties": { "documentId": { "type": "string" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceResponseItem" } } } }, "InvoiceRespondRequest": { "type": "object", "required": [ "responseCode" ], "properties": { "responseCode": { "type": "string", "enum": [ "AP", "RE", "UQ" ], "description": "AP=Accepted, RE=Rejected, UQ=Under Query" }, "note": { "type": "string", "example": "Faktura akceptovana", "description": "Volitelna poznamka" } } }, "InvoiceRespondResponse": { "type": "object", "properties": { "responseId": { "type": "string" }, "responseCode": { "type": "string", "enum": [ "AP", "RE", "UQ" ] }, "sentAt": { "type": "string", "format": "date-time" } } }, "ValidateDocumentResponse": { "type": "object", "properties": { "valid": { "type": "boolean", "example": true }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Upozornenia (nie fatalne chyby)" }, "ubl": { "type": "string", "nullable": true, "description": "Vygenerovane UBL XML (len pri JSON mode)" } } }, "PreflightResponse": { "type": "object", "properties": { "receiverPeppolId": { "type": "string", "example": "0245:12345678" }, "registered": { "type": "boolean", "example": true, "description": "Ci je prijemca registrovany v Peppol sieti" }, "supportsDocumentType": { "type": "boolean", "example": true, "description": "Ci prijemca podporuje dany typ dokumentu" }, "smpUrl": { "type": "string", "nullable": true, "description": "URL SMP zaznamu prijemcu" } } }, "ConvertDocumentRequest": { "type": "object", "required": [ "direction" ], "properties": { "direction": { "type": "string", "enum": [ "json_to_ubl", "ubl_to_json" ], "description": "Smer konverzie" }, "data": { "type": "object", "description": "JSON data dokumentu (pre json_to_ubl)" }, "xml": { "type": "string", "description": "UBL XML string (pre ubl_to_json)" } } }, "ConvertDocumentResponse": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "json_to_ubl", "ubl_to_json" ] }, "result": { "description": "Vysledok konverzie — string (UBL XML) pre json_to_ubl, objekt pre ubl_to_json" } } }, "SmpParticipantCapability": { "type": "object", "properties": { "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "transportProfile": { "type": "string", "example": "peppol-transport-as4-v2_0" } } }, "SmpLookupResponse": { "type": "object", "properties": { "peppolId": { "type": "string", "example": "0245:12345678" }, "name": { "type": "string", "nullable": true, "example": "Moja firma s.r.o." }, "country": { "type": "string", "nullable": true, "example": "SK" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/SmpParticipantCapability" } } } }, "PeppolDirectoryEntry": { "type": "object", "properties": { "peppolId": { "type": "string", "example": "0245:12345678" }, "name": { "type": "string", "example": "Moja firma s.r.o." }, "country": { "type": "string", "example": "SK" }, "registeredAt": { "type": "string", "format": "date-time", "nullable": true } } }, "PeppolDirectorySearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PeppolDirectoryEntry" } }, "total": { "type": "integer", "example": 42 }, "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 20 } } }, "CompanyLookupResponse": { "type": "object", "properties": { "ico": { "type": "string", "example": "12345678" }, "name": { "type": "string", "example": "Moja firma s.r.o." }, "dic": { "type": "string", "nullable": true, "example": "2020123456" }, "icDph": { "type": "string", "nullable": true, "example": "SK2020123456" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string", "example": "SK" } } }, "peppolId": { "type": "string", "nullable": true, "description": "Peppol ID firmy, ak je registrovana" } } }, "FirmSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Example s.r.o." }, "ico": { "type": "string", "example": "12345678" }, "peppol_id": { "type": "string", "example": "0245:12345678", "nullable": true }, "peppol_status": { "type": "string", "enum": [ "ACTIVE", "PENDING", "NONE" ], "example": "ACTIVE" } } }, "FirmsListResponse": { "type": "object", "properties": { "firms": { "type": "array", "items": { "$ref": "#/components/schemas/FirmSummary" } } } }, "FirmDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/FirmSummary" }, { "type": "object", "properties": { "dic": { "type": "string", "nullable": true }, "icDph": { "type": "string", "nullable": true }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } } }, "peppolIdentifiers": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "identifier": { "type": "string" } } } }, "createdAt": { "type": "string", "format": "date-time" } } } ] }, "PeppolIdentifierResponse": { "type": "object", "properties": { "peppolId": { "type": "string", "example": "0245:12345678" }, "scheme": { "type": "string", "example": "0245" }, "identifier": { "type": "string", "example": "12345678" }, "registeredAt": { "type": "string", "format": "date-time" } } }, "WebhookQueueEvent": { "type": "object", "properties": { "eventId": { "type": "string", "example": "evt_abc123" }, "event": { "type": "string", "example": "document.received" }, "payload": { "type": "object", "description": "Obsah udalosti" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookQueueResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookQueueEvent" } }, "count": { "type": "integer", "example": 5, "description": "Pocet vratenych udalosti" } } }, "StatisticsResponse": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "outbound": { "type": "object", "properties": { "total": { "type": "integer", "example": 120 }, "delivered": { "type": "integer", "example": 115 }, "failed": { "type": "integer", "example": 5 } } }, "inbound": { "type": "object", "properties": { "total": { "type": "integer", "example": 48 }, "acknowledged": { "type": "integer", "example": 40 }, "pending": { "type": "integer", "example": 8 } } } } }, "AssignFirmRequest": { "type": "object", "required": [ "ico" ], "properties": { "ico": { "type": "string", "minLength": 8, "maxLength": 8, "example": "12345678", "description": "8-digit company registration number (ICO)" } } }, "AssignFirmResponse": { "type": "object", "properties": { "firm": { "$ref": "#/components/schemas/FirmSummary" }, "status": { "type": "string", "example": "active" } } }, "BatchAssignFirmsRequest": { "type": "object", "required": [ "icos" ], "properties": { "icos": { "type": "array", "items": { "type": "string", "minLength": 8, "maxLength": 8 }, "maxItems": 50, "example": [ "12345678", "87654321" ] } } }, "BatchAssignFirmsResultItem": { "type": "object", "properties": { "ico": { "type": "string", "example": "12345678" }, "firm": { "$ref": "#/components/schemas/FirmSummary" }, "status": { "type": "string", "example": "active" }, "error": { "type": "string", "example": "not_found", "nullable": true }, "message": { "type": "string", "example": "Firm not found", "nullable": true } } }, "BatchAssignFirmsResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchAssignFirmsResultItem" } } } }, "CrossFirmInboxDocument": { "type": "object", "properties": { "firm_id": { "type": "string", "format": "uuid" }, "firm_name": { "type": "string", "example": "Example s.r.o." }, "id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "example": "FAK-2026-0001" }, "status": { "type": "string", "enum": [ "RECEIVED", "ACKNOWLEDGED" ] }, "sender_peppol_id": { "type": "string", "example": "0245:99887766" }, "sender_name": { "type": "string", "example": "Supplier s.r.o." }, "amount": { "type": "number", "example": 1210.0 }, "currency": { "type": "string", "example": "EUR" }, "received_at": { "type": "string", "format": "date-time" } } }, "CrossFirmInboxResponse": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/CrossFirmInboxDocument" } }, "total": { "type": "integer", "example": 120 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 } } }, "CrossFirmWebhookEvent": { "type": "object", "properties": { "event_id": { "type": "string", "format": "uuid" }, "firm_id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "example": "document.received" }, "payload": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "CrossFirmWebhookQueueResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/CrossFirmWebhookEvent" } }, "count": { "type": "integer", "example": 5 } } }, "BatchAckWebhookRequest": { "type": "object", "required": [ "event_ids" ], "properties": { "event_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000, "example": [ "uuid-1", "uuid-2" ] } } }, "BatchAckWebhookResponse": { "type": "object", "properties": { "acknowledged": { "type": "integer", "example": 42 } } }, "OAuthTokenRequest": { "type": "object", "required": [ "grant_type", "code", "client_id", "client_secret", "redirect_uri" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code" ], "example": "authorization_code" }, "code": { "type": "string", "example": "auth_code_here" }, "client_id": { "type": "string", "example": "client_id_here" }, "client_secret": { "type": "string", "example": "client_secret_here" }, "redirect_uri": { "type": "string", "format": "uri", "example": "https://example.com/callback" }, "code_verifier": { "type": "string", "description": "PKCE code verifier (optional)", "example": "pkce_verifier_here" } } }, "OAuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "example": "sk_int_abc123" }, "token_type": { "type": "string", "example": "bearer" }, "scope": { "type": "string", "example": "enterprise" }, "firm_id": { "type": "string", "format": "uuid" }, "firm_name": { "type": "string", "example": "Example s.r.o." }, "firm_ico": { "type": "string", "example": "12345678" } } } } } }