{"openapi":"3.1.0","info":{"title":"ePošťák SAPI-SK API","description":"Peppol Access Point API pre elektronickú fakturáciu. SAPI-SK kompatibilné.\n\nDokumentácia: https://epostak.sk/api/docs\n\nŠtandardné SAPI-SK rozhranie. Pre rozšírené funkcie (JSON mode, webhooky, OCR) použite Enterprise API: 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","description":"Production"}],"paths":{"/auth/token":{"post":{"tags":["Autentifikácia"],"summary":"Získať prístupový token","description":"OAuth2 client_credentials grant. Vráti access_token (15 min) a refresh_token (30 dní).","operationId":"getToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"Token vydaný","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"description":"Neplatné credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"423":{"description":"Účet dočasne zablokovaný","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/auth/token/status":{"get":{"tags":["Autentifikácia"],"summary":"Skontrolovať platnosť tokenu","operationId":"tokenStatus","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Stav tokenu","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenStatus"}}}},"401":{"description":"Neplatný token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/auth/renew":{"post":{"tags":["Autentifikácia"],"summary":"Obnoviť tokeny","description":"Vymení refresh_token za nový pár tokenov. Starý refresh token sa zneplatní.","operationId":"renewToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewRequest"}}}},"responses":{"200":{"description":"Tokeny obnovené","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"description":"Neplatný refresh token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/auth/revoke":{"post":{"tags":["Autentifikácia"],"summary":"Zrušiť refresh token","operationId":"revokeToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeRequest"}}}},"responses":{"200":{"description":"Token zrušený","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeResponse"}}}}}}},"/document/send":{"post":{"tags":["Dokumenty"],"summary":"Odoslať dokument cez Peppol","description":"Odošle UBL XML dokument (faktúra, dobropis, samozdanenie) cez Peppol sieť.","operationId":"sendDocument","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID pre deduplikáciu (platnosť 24h)"},{"name":"X-Peppol-Participant-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Peppol ID odosielateľa (napr. 0245:12345678)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDocumentRequest"}}}},"responses":{"202":{"description":"Dokument prijatý na odoslanie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDocumentResponse"}}}},"400":{"description":"Neplatný request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicitný Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"UBL validácia zlyhala","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Chyba Peppol siete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/document/receive":{"get":{"tags":["Dokumenty"],"summary":"Zoznam prijatých dokumentov","description":"Vráti stránkovaný zoznam dokumentov prijatých cez Peppol.","operationId":"listReceivedDocuments","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Peppol-Participant-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"status","in":"query","schema":{"type":"string","enum":["RECEIVED","ACKNOWLEDGED"]}},{"name":"pageToken","in":"query","schema":{"type":"string"},"description":"Kurzor pre ďalšiu stránku"}],"responses":{"200":{"description":"Zoznam dokumentov","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceivedDocumentList"}}}}}}},"/document/receive/{documentId}":{"get":{"tags":["Dokumenty"],"summary":"Detail prijatého dokumentu","description":"Vráti kompletný dokument vrátane XML payloadu.","operationId":"getReceivedDocument","security":[{"bearerAuth":[]}],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Peppol-Participant-Id","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detail dokumentu","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceivedDocumentDetail"}}}},"404":{"description":"Dokument neexistuje","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/document/receive/{documentId}/acknowledge":{"post":{"tags":["Dokumenty"],"summary":"Potvrdiť prijatie dokumentu","description":"Označí dokument ako spracovaný (idempotentná operácia).","operationId":"acknowledgeDocument","security":[{"bearerAuth":[]}],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Peppol-Participant-Id","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dokument potvrdený","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcknowledgeResponse"}}}},"404":{"description":"Dokument neexistuje","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TokenRequest":{"type":"object","required":["client_id","client_secret"],"properties":{"client_id":{"type":"string","example":"your_client_id"},"client_secret":{"type":"string","example":"sk_..."},"grant_type":{"type":"string","default":"client_credentials"}}},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","default":"Bearer"},"expires_in":{"type":"integer","default":900},"scope":{"type":"string","example":"document:send document:receive"}}},"TokenStatus":{"type":"object","properties":{"valid":{"type":"boolean"},"client_id":{"type":"string"},"issued_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"expires_in_seconds":{"type":"integer"},"should_refresh":{"type":"boolean"}}},"RenewRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string"}}},"RevokeRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"token_type_hint":{"type":"string","default":"refresh_token"}}},"RevokeResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"DocumentMetadata":{"type":"object","required":["documentId","senderParticipantId","receiverParticipantId","creationDateTime"],"properties":{"documentId":{"type":"string","example":"INV-2026-001"},"documentTypeId":{"type":"string","example":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"},"processId":{"type":"string","example":"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"},"senderParticipantId":{"type":"string","example":"0245:12345678"},"receiverParticipantId":{"type":"string","example":"0245:87654321"},"creationDateTime":{"type":"string","format":"date-time"}}},"SendDocumentRequest":{"type":"object","required":["metadata","payload","payloadFormat"],"properties":{"metadata":{"$ref":"#/components/schemas/DocumentMetadata"},"payload":{"type":"string","description":"UBL XML obsah dokumentu","maxLength":10485760},"payloadFormat":{"type":"string","enum":["XML"],"default":"XML"},"checksum":{"type":"string","description":"SHA-256 hash payloadu (hex, voliteľné)"}}},"SendDocumentResponse":{"type":"object","properties":{"providerDocumentId":{"type":"string"},"status":{"type":"string","enum":["ACCEPTED"]},"receivedAt":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time"}}},"ReceivedDocumentList":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedDocumentSummary"}},"nextPageToken":{"type":"string","nullable":true}}},"ReceivedDocumentSummary":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/DocumentMetadata"},"status":{"type":"string","enum":["RECEIVED","ACKNOWLEDGED"]},"receivedAt":{"type":"string","format":"date-time"}}},"ReceivedDocumentDetail":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/DocumentMetadata"},"payload":{"type":"string","description":"Pôvodný UBL XML"},"payloadFormat":{"type":"string","default":"XML"},"status":{"type":"string","enum":["RECEIVED","ACKNOWLEDGED"]}}},"AcknowledgeResponse":{"type":"object","properties":{"documentId":{"type":"string"},"status":{"type":"string","default":"ACKNOWLEDGED"},"acknowledgedDateTime":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["category","code","message"],"properties":{"category":{"type":"string","enum":["AUTH","VALIDATION","PROCESSING","TEMPORARY","PERMANENT"]},"code":{"type":"string","example":"SAPI-AUTH-001"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"issue":{"type":"string"}}}},"retryable":{"type":"boolean","default":false},"correlation_id":{"type":"string","format":"uuid"}}}}}}