{"openapi":"3.0.3","info":{"title":"ePošťák SAPI-SK","description":"Peppol Access Point API pre elektronickú fakturáciu. SAPI-SK kompatibilné.\n\nTáto špecifikácia pokrýva iba štandardné SAPI-SK endpointy. ePošťák Enterprise rozšírenia sú publikované samostatne.\n\nDokumentácia: https://epostak.sk/api/docs","version":"1.0.0","contact":{"email":"info@epostak.sk","url":"https://epostak.sk/support"}},"externalDocs":{"description":"ePošťák Enterprise OpenAPI spec","url":"https://dev.epostak.sk/api/openapi.enterprise.json"},"servers":[{"url":"https://dev.epostak.sk/sapi/v1","description":"Sandbox/test"}],"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/ErrorResponseEnvelope"}}}},"403":{"description":"IP address not allowed for this client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"423":{"description":"Účet dočasne zablokovaný","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}}}}},"/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/ErrorResponseEnvelope"}}}}}}},"/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/ErrorResponseEnvelope"}}}}}}},"/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/ErrorResponseEnvelope"}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"403":{"description":"Authorization error (no organization access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"409":{"description":"Duplicitný Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"422":{"description":"UBL validácia zlyhala","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"502":{"description":"Chyba Peppol siete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}}}}},"/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/ReceivedDocumentListResponse"}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"403":{"description":"Authorization error (no organization access)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}}}}},"/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/ReceivedDocumentDetailResponse"}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"403":{"description":"Authorization error (document belongs to another receiver)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"404":{"description":"Dokument neexistuje","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}}}}},"/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"}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"403":{"description":"Authorization error (document belongs to another receiver)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}},"404":{"description":"Dokument neexistuje","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TokenRequest":{"type":"object","required":["client_id","client_secret","grant_type"],"properties":{"client_id":{"type":"string","description":"Client identifier shown with the key. Must match the API key row UUID or displayed key prefix; it is not the sk_live_*/sk_int_* secret.","example":"b6649c59-2f9d-4ae2-a750-af257c455478"},"client_secret":{"type":"string","description":"Full sk_live_* or sk_int_* API key.","example":"sk_live_..."},"grant_type":{"type":"string","enum":["client_credentials"],"example":"client_credentials"}}},"TokenResponse":{"type":"object","required":["access_token","refresh_token","token_type","expires_in"],"properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"],"default":"Bearer"},"expires_in":{"type":"integer","default":900},"scope":{"type":"string","example":"documents:send documents:read"}}},"TokenStatus":{"type":"object","properties":{"valid":{"type":"boolean"},"token_type":{"type":"string","enum":["access"],"description":"Always 'access' (this endpoint introspects access tokens only). Distinct from POST /auth/token's response.token_type which is the HTTP scheme name 'Bearer'."},"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","description":"True when current time is within 3 minutes of expiry — clients should call /auth/renew"},"refresh_recommended_at":{"type":"string","format":"date-time"}}},"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","documentTypeId","processId","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"},"payloadEncoding":{"type":"string","enum":["UTF-8"],"default":"UTF-8","description":"Optional. Only \"UTF-8\" is supported."},"checksum":{"type":"string","description":"SHA-256 hash payloadu (hex, voliteľné)"}}},"SendDocumentResponse":{"type":"object","required":["providerDocumentId","status","timestamp"],"properties":{"providerDocumentId":{"type":"string"},"status":{"type":"string","enum":["ACCEPTED","REJECTED"]},"receivedAt":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time"}}},"ReceivedDocumentListResponse":{"type":"object","required":["documents"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentMetadata"}},"nextPageToken":{"type":"string","nullable":true}}},"ReceivedDocumentDetailResponse":{"type":"object","required":["metadata","payload","payloadFormat"],"properties":{"metadata":{"$ref":"#/components/schemas/DocumentMetadata"},"payload":{"type":"string","description":"Pôvodný UBL XML"},"payloadFormat":{"type":"string","default":"XML"}}},"AcknowledgeResponse":{"type":"object","required":["documentId","status","acknowledgedDateTime"],"properties":{"documentId":{"type":"string"},"status":{"type":"string","enum":["ACKNOWLEDGED"]},"acknowledgedDateTime":{"type":"string","format":"date-time"}}},"SAPIError":{"type":"object","required":["category","code","message","retryable","correlation_id"],"description":"SAPI v1.0 structured error object. All error responses use this consistent structure for machine-readable error handling, explicit retry behaviour, and Peppol-aligned diagnostics.","properties":{"category":{"type":"string","enum":["AUTH","VALIDATION","PROCESSING","TEMPORARY","PERMANENT"],"description":"Error category. AUTH = authentication/authorization failures. VALIDATION = request validation errors. PROCESSING = server-side processing errors. TEMPORARY = transient failures (retryable). PERMANENT = non-retryable failures.","example":"VALIDATION"},"code":{"type":"string","description":"Stable, implementation-independent error code (e.g. SAPI-AUTH-001, SAPI-VAL-001)","example":"SAPI-AUTH-001"},"message":{"type":"string","description":"Human-readable summary of the error"},"details":{"type":"array","description":"Optional field-level or contextual information to aid diagnostics","items":{"type":"object","properties":{"field":{"type":"string","description":"The field that caused the error"},"issue":{"type":"string","description":"Description of the issue"},"value":{"type":"string","description":"The invalid value that was provided"}}}},"retryable":{"type":"boolean","description":"Explicit indicator whether the request may be retried without modification. Clients MUST implement exponential backoff when true.","example":false},"correlation_id":{"type":"string","format":"uuid","description":"Identifier used for tracing, logging, and support"}}},"ErrorResponseEnvelope":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/SAPIError"}}}}}}