From 316a8908d7608b924969a5013909e1f51b500535 Mon Sep 17 00:00:00 2001 From: smkc Date: Sun, 18 Jan 2026 17:04:37 +0100 Subject: [PATCH 1/7] feat: Implement comprehensive API compliance verification in CI - Add tools/check_coverage.py for deep static analysis of API coverage. - Update CI workflow to fetch official OpenAPI spec and run coverage checks. - Remove undocumented endpoint /public-keys/publicKey.pem from SecurityClient to ensure 100% OpenAPI compliance. - Update tests to reflect removal of undocumented endpoint. --- .github/workflows/validate-models.yml | 48 +++++ src/ksef_client/clients/security.py | 22 --- tests/test_clients.py | 12 +- tools/check_coverage.py | 270 ++++++++++++++++++++++++++ 4 files changed, 320 insertions(+), 32 deletions(-) create mode 100644 .github/workflows/validate-models.yml create mode 100644 tools/check_coverage.py diff --git a/.github/workflows/validate-models.yml b/.github/workflows/validate-models.yml new file mode 100644 index 0000000..8033568 --- /dev/null +++ b/.github/workflows/validate-models.yml @@ -0,0 +1,48 @@ +name: Validate API Compliance + +on: + push: + branches: ["main"] + pull_request: + branches: ["main"] + workflow_dispatch: + +permissions: + contents: read + +jobs: + check-models: + runs-on: ubuntu-latest + + env: + OPENAPI_URL: https://raw.githubusercontent.com/CIRFMF/ksef-docs/main/open-api.json + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Download official open-api.json + run: | + curl -L -o open-api.json "${{ env.OPENAPI_URL }}" + + - name: Generate models + run: | + # Use the downloaded open-api.json as input + python tools/generate_openapi_models.py --input open-api.json --output src/ksef_client/openapi_models.py + + - name: Verify no changes in models + run: | + # Check if the generated file differs from the committed file + if ! git diff --exit-code src/ksef_client/openapi_models.py; then + echo "::error::Generated models do not match the official open-api.json from ${{ env.OPENAPI_URL }}. Please run generation locally with the latest spec and commit changes." + exit 1 + fi + + - name: Check API Coverage + run: | + # Verify that all OpenAPI endpoints are implemented in the client code + python tools/check_coverage.py --openapi open-api.json --src src/ksef_client/clients diff --git a/src/ksef_client/clients/security.py b/src/ksef_client/clients/security.py index fb280ad..2cef4f9 100644 --- a/src/ksef_client/clients/security.py +++ b/src/ksef_client/clients/security.py @@ -9,27 +9,5 @@ class SecurityClient(BaseApiClient): def get_public_key_certificates(self) -> Any: return self._request_json("GET", "/security/public-key-certificates", skip_auth=True) - def get_public_key_pem(self) -> str: - content = self._request_bytes( - "GET", - "/public-keys/publicKey.pem", - headers={"Accept": "application/x-pem-file"}, - skip_auth=True, - expected_status={200}, - ) - return content.decode("utf-8") - - -class AsyncSecurityClient(AsyncBaseApiClient): async def get_public_key_certificates(self) -> Any: return await self._request_json("GET", "/security/public-key-certificates", skip_auth=True) - - async def get_public_key_pem(self) -> str: - content = await self._request_bytes( - "GET", - "/public-keys/publicKey.pem", - headers={"Accept": "application/x-pem-file"}, - skip_auth=True, - expected_status={200}, - ) - return content.decode("utf-8") diff --git a/tests/test_clients.py b/tests/test_clients.py index 1ca6cc3..e340bb0 100644 --- a/tests/test_clients.py +++ b/tests/test_clients.py @@ -198,12 +198,8 @@ def test_limits_clients(self): rate_client.get_rate_limits("token") security_client = SecurityClient(self.http) - with ( - patch.object(security_client, "_request_json", Mock(return_value={"ok": True})), - patch.object(security_client, "_request_bytes", Mock(return_value=b"pem")), - ): + with patch.object(security_client, "_request_json", Mock(return_value={"ok": True})): security_client.get_public_key_certificates() - self.assertEqual(security_client.get_public_key_pem(), "pem") def test_testdata_client(self): client = TestDataClient(self.http) @@ -435,12 +431,8 @@ async def test_async_clients(self): await rate_limits.get_rate_limits("token") security = AsyncSecurityClient(http) - with ( - patch.object(security, "_request_json", AsyncMock(return_value={"ok": True})), - patch.object(security, "_request_bytes", AsyncMock(return_value=b"pem")), - ): + with patch.object(security, "_request_json", AsyncMock(return_value={"ok": True})): await security.get_public_key_certificates() - self.assertEqual(await security.get_public_key_pem(), "pem") testdata = AsyncTestDataClient(http) with patch.object(testdata, "_request_json", AsyncMock(return_value={"ok": True})): diff --git a/tools/check_coverage.py b/tools/check_coverage.py new file mode 100644 index 0000000..62717ad --- /dev/null +++ b/tools/check_coverage.py @@ -0,0 +1,270 @@ +import argparse +import ast +import json +import re +from pathlib import Path +from typing import Set, Tuple, Dict, List, Optional +from collections import defaultdict +from dataclasses import dataclass + + +def normalize_path(path: str) -> str: + # Replace {param} with {} to compare structure + return re.sub(r"{[^}]+}", "{}", path) + + +def extract_path_params(path: str) -> Set[str]: + # Extract parameter names from OpenAPI path: /auth/{referenceNumber} -> {referenceNumber} + return set(re.findall(r"{([^}]+)}", path)) + + +@dataclass +class EndpointSpec: + method: str + path: str + normalized_path: str + path_params: Set[str] + query_params: Set[str] + + +@dataclass +class ImplementedEndpoint: + method: str + path_pattern: str + normalized_path: str + # Parameters detected in the f-string path construction + detected_path_vars: Set[str] + # Parameters passed to params={} argument + detected_query_vars: Set[str] + file_path: str + line_no: int + + +def get_openapi_specs(openapi_path: Path) -> Dict[Tuple[str, str], EndpointSpec]: + """Returns a map of (method, normalized_path) -> EndpointSpec from OpenAPI.""" + with open(openapi_path, "r", encoding="utf-8") as f: + data = json.load(f) + + specs = {} + for path, methods in data.get("paths", {}).items(): + norm_path = normalize_path(path) + path_params = extract_path_params(path) + + for method_name, details in methods.items(): + method = method_name.upper() + + # Extract query parameters defined for this operation + query_params = set() + parameters = details.get("parameters", []) + for param in parameters: + if param.get("in") == "query": + query_params.add(param["name"]) + + spec = EndpointSpec( + method=method, + path=path, + normalized_path=norm_path, + path_params=path_params, + query_params=query_params + ) + specs[(method, norm_path)] = spec + return specs + + +class AdvancedClientVisitor(ast.NodeVisitor): + def __init__(self, filename: str): + self.filename = filename + self.found_endpoints: List[ImplementedEndpoint] = [] + + def visit_Call(self, node): + # Look for self._request_json / self._request_bytes / self._request_raw + if isinstance(node.func, ast.Attribute) and node.func.attr in ("_request_json", "_request_bytes", "_request_no_auth", "_request_raw"): + self._analyze_request_call(node) + self.generic_visit(node) + + def _analyze_request_call(self, node: ast.Call): + if len(node.args) < 2: + return + + method_arg = node.args[0] + path_arg = node.args[1] + + # Extract Method + method = self._extract_string_value(method_arg) + if not method: + return # Could not resolve method statically + + # Extract Path and Path Params (from f-strings) + path_pattern, detected_path_vars = self._extract_path_info(path_arg) + if not path_pattern: + return + + normalized_path = normalize_path(path_pattern) + + # Extract Query Params + detected_query_vars = self._extract_query_params(node) + + self.found_endpoints.append(ImplementedEndpoint( + method=method.upper(), + path_pattern=path_pattern, + normalized_path=normalized_path, + detected_path_vars=detected_path_vars, + detected_query_vars=detected_query_vars, + file_path=self.filename, + line_no=node.lineno + )) + + def _extract_string_value(self, node) -> Optional[str]: + if isinstance(node, ast.Constant) and isinstance(node.value, str): + return node.value + return None + + def _extract_path_info(self, node) -> Tuple[Optional[str], Set[str]]: + if isinstance(node, ast.Constant) and isinstance(node.value, str): + return node.value, set() + + if isinstance(node, ast.JoinedStr): + # Convert f-string f"/auth/{ref}" to pattern "/auth/{}" and extract vars + pattern_parts = [] + vars_found = set() + + for part in node.values: + if isinstance(part, ast.Constant) and isinstance(part.value, str): + pattern_parts.append(part.value) + elif isinstance(part, ast.FormattedValue): + pattern_parts.append("{}") + # Try to get the variable name used in f-string + if isinstance(part.value, ast.Name): + vars_found.add(part.value.id) + + return "".join(pattern_parts), vars_found + + return None, set() + + def _extract_query_params(self, node: ast.Call) -> Set[str]: + # Look for 'params' keyword argument + params_keywords = [kw for kw in node.keywords if kw.arg == "params"] + if not params_keywords: + return set() + + params_value = params_keywords[0].value + + # We handle: params={'page': page, 'limit': 10} + # or params=params (if params is a dict built earlier, hard to track statically perfectly) + + found_keys = set() + if isinstance(params_value, ast.Dict): + for key in params_value.keys: + if isinstance(key, ast.Constant) and isinstance(key.value, str): + found_keys.add(key.value) + + # If params passed as variable (e.g. params=page_params), we assume best effort or specific variable name tracking + # For now, we only statically analyze inline dict definitions or assume manual review if dynamic + return found_keys + + +def get_implemented_endpoints_deep(source_dir: Path) -> List[ImplementedEndpoint]: + endpoints = [] + for py_file in source_dir.rglob("*.py"): + try: + visitor = AdvancedClientVisitor(str(py_file)) + tree = ast.parse(py_file.read_text(encoding="utf-8")) + visitor.visit(tree) + endpoints.extend(visitor.found_endpoints) + except Exception as e: + print(f"Error parsing {py_file}: {e}") + return endpoints + + +def to_camel_case(snake_str: str) -> str: + # reference_number -> referenceNumber + components = snake_str.split('_') + return components[0] + ''.join(x.title() for x in components[1:]) + + +def main(): + import sys + from dataclasses import dataclass + + # Re-declare dataclasses here for standalone script execution context if needed + # (though already defined above, ensuring valid scope) + + parser = argparse.ArgumentParser(description="Deep API coverage check.") + parser.add_argument("--openapi", required=True, type=Path, help="Path to open-api.json") + parser.add_argument("--src", required=True, type=Path, help="Path to source directory containing clients") + args = parser.parse_args() + + # 1. Load OpenAPI Specs + openapi_specs = get_openapi_specs(args.openapi) + + # 2. Analyze Code + implemented_eps = get_implemented_endpoints_deep(args.src) + + # 3. Compare + openapi_keys = set(openapi_specs.keys()) + implemented_keys = set((ep.method, ep.normalized_path) for ep in implemented_eps) + + missing = openapi_keys - implemented_keys + extra = implemented_keys - openapi_keys + + print(f"OpenAPI Endpoints: {len(openapi_keys)}") + print(f"Implemented Endpoints: {len(implemented_keys)}") + + issues_found = False + + if missing: + print("\n[MISSING] The following endpoints are logically missing in code:") + for method, path in sorted(missing): + print(f" - [{method}] {openapi_specs[(method, path)].path}") + issues_found = True + + if extra: + print("\n[EXTRA] The following endpoints found in code but NOT in OpenAPI:") + for method, path in sorted(extra): + # Try to find file info + matches = [x for x in implemented_eps if x.method == method and x.normalized_path == path] + for m in matches: + print(f" - [{method}] {m.path_pattern} (at {m.file_path}:{m.line_no})") + # Extra endpoints might be issues if they are typos + if extra: + print(" (Note: This might be due to typos in URL or unofficial endpoints)") + issues_found = True + + # Deep Analysis: Params + print("\n[DEEP ANALYSIS] Checking Path & Query Parameters...") + + # Map implementation to spec for verification + for impl in implemented_eps: + spec = openapi_specs.get((impl.method, impl.normalized_path)) + if not spec: + continue # Extra endpoint implemented? or ignored + + # Check Path Params + # OpenAPI: {referenceNumber} -> Python: reference_number (snake case conversion usually) + # We try to match count. + if len(impl.detected_path_vars) != len(spec.path_params): + # Heuristic check + print(f" [WARN] Path param mismatch for {impl.method} {spec.path}") + print(f" Expected: {spec.path_params}") + print(f" Found in f-string: {impl.detected_path_vars} at {impl.file_path}:{impl.line_no}") + + # Check Query Params + # We only check if the KEY names used in params={} dictionary exist in OpenAPI definition + # OpenAPI params are usually camelCase (pageSize). Python code should use pageSize key in dict. + for query_key in impl.detected_query_vars: + if query_key not in spec.query_params: + # Common false positive: 'page' vs 'Page', or continuationToken + print(f" [WARN] Unknown query param '{query_key}' used in code for {impl.method} {spec.path}") + print(f" Allowed: {spec.query_params} at {impl.file_path}:{impl.line_no}") + + if issues_found: + print("\nCoverage check FAILED.") + exit(1) + else: + print("\nCoverage check PASSED (Structure Match). Review Warnings above.") + exit(0) + + +if __name__ == "__main__": + from dataclasses import dataclass + main() From e1ef032bf489c64d9da5977d0bb39f9db9826c95 Mon Sep 17 00:00:00 2001 From: smkc Date: Sun, 18 Jan 2026 17:15:10 +0100 Subject: [PATCH 2/7] fix: Restore AsyncSecurityClient class definition missing after refactor --- .github/workflows/validate-models.yml | 3 + open-api.json | 15003 ++++++++++++++++++++++++ src/ksef_client/clients/security.py | 2 + src/ksef_client/openapi_models.py | 625 +- tools/generate_openapi_models.py | 3 +- 5 files changed, 15190 insertions(+), 446 deletions(-) create mode 100644 open-api.json diff --git a/.github/workflows/validate-models.yml b/.github/workflows/validate-models.yml index 8033568..1bed151 100644 --- a/.github/workflows/validate-models.yml +++ b/.github/workflows/validate-models.yml @@ -38,6 +38,9 @@ jobs: run: | # Check if the generated file differs from the committed file if ! git diff --exit-code src/ksef_client/openapi_models.py; then + echo "::group::Diff" + git diff src/ksef_client/openapi_models.py + echo "::endgroup::" echo "::error::Generated models do not match the official open-api.json from ${{ env.OPENAPI_URL }}. Please run generation locally with the latest spec and commit changes." exit 1 fi diff --git a/open-api.json b/open-api.json new file mode 100644 index 0000000..3127eda --- /dev/null +++ b/open-api.json @@ -0,0 +1,15003 @@ +{ + "openapi": "3.0.4", + "info": { + "title": "KSeF API TE", + "description": "**Wersja API:** 2.0.0 (build 2.0.1-te)
\n**Klucze publiczne** Ministerstwa Finansów (dla danego środowiska): [Pobierz klucze](#tag/Certyfikaty-klucza-publicznego)
\n**Historia zmian:** [Changelog](https://github.com/CIRFMF/ksef-docs/blob/main/api-changelog.md)
\n**Rozszerzona dokumentacja API:** [ksef-docs](https://github.com/CIRFMF/ksef-docs/tree/main)\n\n**Adres serwera API:**\n- Środowisko TEST: `https://api-test.ksef.mf.gov.pl/v2`\n- [deprecated] Środowisko TEST: `https://ksef-test.mf.gov.pl/api/v2`\n", + "version": "v2" + }, + "servers": [ + { + "url": "https://api-test.ksef.mf.gov.pl/v2", + "description": "Środowisko TEST" + }, + { + "url": "https://ksef-test.mf.gov.pl/api/v2", + "description": "[deprecated] Środowisko TEST" + } + ], + "paths": { + "/auth/sessions": { + "get": { + "tags": [ + "Aktywne sesje" + ], + "summary": "Pobranie listy aktywnych sesji", + "description": "Zwraca listę aktywnych sesji uwierzytelnienia.\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n", + "parameters": [ + { + "name": "x-continuation-token", + "in": "header", + "description": "Token służący do pobrania kolejnej strony wyników.", + "schema": { + "type": "string" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationListResponse" + }, + "example": { + "continuationToken": "W3siY29tcG9zaXRlVG9rZW4iOnsidG9rZW4iOm51bGwsInJhbmdlIjp7Im1pbiI6IjA1QzFFMCIsIm1heCI6IkZGIn19LCJyZXN1bWVWYWx1ZXMiOlsiMjAyNS0xMC0wM1QxMjoxODo0OS4zNDY2ODQ3WiJdLCJyaWQiOiIzeHd0QVBJWDVRRlVoZ0FBQUFBQUJBPT0iLCJza2lwQ291bnQiOjF9XQ==", + "items": [ + { + "referenceNumber": "20251010-AU-19F5E39000-39B5B182BA-B8", + "isCurrent": false, + "startDate": "2025-10-11T12:23:56.0154302+00:00", + "authenticationMethod": "QualifiedSeal", + "status": { + "code": 200, + "description": "Uwierzytelnianie zakończone sukcesem" + }, + "isTokenRedeemed": true, + "refreshTokenValidUntil": "2025-11-28T09:22:13.388+00:00" + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + } + ] + } + }, + "/auth/sessions/current": { + "delete": { + "tags": [ + "Aktywne sesje" + ], + "summary": "Unieważnienie aktualnej sesji uwierzytelnienia", + "description": "Unieważnia sesję powiązaną z tokenem użytym do wywołania tej operacji.\n\nUnieważnienie sesji sprawia, że powiązany z nią refresh token przestaje działać i nie można już za jego pomocą uzyskać kolejnych access tokenów.\n**Aktywne access tokeny działają do czasu minięcia ich termin ważności.**\n\nSposób uwierzytelnienia: `RefreshToken` lub `AccessToken`.", + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/auth/sessions/{referenceNumber}": { + "delete": { + "tags": [ + "Aktywne sesje" + ], + "summary": "Unieważnienie sesji uwierzytelnienia", + "description": "Unieważnia sesję o podanym numerze referencyjnym.\n\nUnieważnienie sesji sprawia, że powiązany z nią refresh token przestaje działać i nie można już za jego pomocą uzyskać kolejnych access tokenów.\n**Aktywne access tokeny działają do czasu minięcia ich termin ważności.**", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji uwierzytelnienia.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/certificates/limits": { + "get": { + "tags": [ + "Certyfikaty" + ], + "summary": "Pobranie danych o limitach certyfikatów", + "description": "Zwraca informacje o limitach certyfikatów oraz informacje czy użytkownik może zawnioskować o certyfikat KSeF.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CertificateLimitsResponse" + } + } + } + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/certificates/enrollments/data": { + "get": { + "tags": [ + "Certyfikaty" + ], + "summary": "Pobranie danych do wniosku certyfikacyjnego", + "description": "Zwraca dane wymagane do przygotowania wniosku certyfikacyjnego PKCS#10.\n\nDane te są zwracane na podstawie certyfikatu użytego w procesie uwierzytelnienia i identyfikują podmiot, który składa wniosek o certyfikat.\n\n\n> Więcej informacji:\n> - [Pobranie danych do wniosku certyfikacyjnego](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#2-pobranie-danych-do-wniosku-certyfikacyjnego)\n> - [Przygotowanie wniosku](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#3-przygotowanie-csr-certificate-signing-request)", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CertificateEnrollmentDataResponse" + }, + "example": { + "commonName": "Firma Kowalski Certyfikat", + "countryName": "PL", + "serialNumber": "ABC123456789", + "uniqueIdentifier": "d9d22724-4696-460c-9e5e-b9e3aafb0af3", + "organizationName": "Firma Kowalski Sp. z o.o.", + "organizationIdentifier": "7762811692" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|-------------------------------------------------------------------------------------------|---------|\n| 25001 | Brak możliwości pobrania danych do CSR dla wykorzystanego sposobu uwierzytelnienia. | |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/certificates/enrollments": { + "post": { + "tags": [ + "Certyfikaty" + ], + "summary": "Wysyłka wniosku certyfikacyjnego", + "description": "Przyjmuje wniosek certyfikacyjny i rozpoczyna jego przetwarzanie.\n\nDozwolone typy kluczy prywatnych:\n- RSA (OID: 1.2.840.113549.1.1.1), długość klucza równa 2048 bitów,\n- EC (klucze oparte na krzywych eliptycznych, OID: 1.2.840.10045.2.1), krzywa NIST P-256 (secp256r1)\n\nZalecane jest stosowanie kluczy EC.\n\nDozwolone algorytmy podpisu:\n- RSA PKCS#1 v1.5,\n- RSA PSS,\n- ECDSA (format podpisu zgodny z RFC 3279)\n\nDozwolone funkcje skrótu użyte do podpisu CSR:\n- SHA1,\n- SHA256,\n- SHA384,\n- SHA512\n\n> Więcej informacji:\n> - [Wysłanie wniosku certyfikacyjnego](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#4-wys%C5%82anie-wniosku-certyfikacyjnego)", + "requestBody": { + "description": "", + "content": { + "application/json": { + "schema": { + "required": [ + "certificateName", + "certificateType", + "csr" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EnrollCertificateRequest" + } + ] + }, + "example": { + "certificateName": "Certyfikat-Auth-004", + "certificateType": "Authentication", + "csr": "MIIDJjCCAd4CAQAwgbAxIjAgBgNVBAMMGUZpcm1hIEtvd2Fsc2tpIENlcnR5ZmlrYXQxIjAgBgNVBAoMGUZpcm1hIEtvd2Fsc2tpIFNwLiB6IG8uby4xEzARBgNVBGEMCjc3NjI4MTE2OTIxCzAJBgNVBAYTAlBMMRUwEwYDVQQFEwxBQkMxMjM0NTY3ODkxLTArBgNVBC0MJGQ5ZDIyNzI0LTQ2OTYtNDYwYy05ZTVlLWI5ZTNhYWZiMGFmMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANZC1hJiB4ZBsxGy/a4yvtOUP0HQxDt7EUZrfKO78+cmI7KCO9aW96yr6O0R928/Y9vmymbgh6KvMUTzZZj24uyxar849O1laor5t8Wv63RDx/I4+9Rt7w+QPPofmpenOokJH+Fm+FDQwo2l07o8SppGfaZpvMak+cDSrh+73wfM37fvPImr9p4ckzzxA9q6f4uoqGqcGSDlSwRjfLQKzWZaEklpZBpY4jeCh54uN3+YLsMQYKdcIbW0Jart1UbwMd/wbHfzFhVmPGOAMMpwVEBw6E4A0CTWIiAX3Alqbx4+IkuqC+gEs3ETTec7eOqhxe9V9cywi7WR+Mz6JO6DJcUCAwEAAaAAMD0GCSqGSIb3DQEBCjAwoA0wCwYJYIZIAWUDBAIBoRowGAYJKoZIhvcNAQEIMAsGCWCGSAFlAwQCAaIDAgEgA4IBAQCJhtF2/2E+JmkWitE/BGbm3NU4fIxr1Z+w0UnHsP+F8n9UDwAnuncG1GH5wZFervldEMooegzEDnYaqxnEUnbZ4wxeAHqpbTZjOOfqrk7o0r66+mXUs5NnyD4M3j3ig98GcvhEdbcNH+RsIwi7FaLNXnOE4SLYL9KvW0geriywWjS+5MmA0Gcn1e4vCD6FeEls8EHzkhrWE+rUsoM5zT2a0OPNXG3fScyOqOZe+OdjT4Y7ScRGy711u3v2X9RoTqQUDfCJ3cob/KRcrzvs1TQVazGZPfcIa6an6SigUvZ7XAMHlUTyOeM4AwKqiEqQ0qfe/HhlDylgZSwulb9u0utT", + "validFrom": "2025-08-28T09:22:13.388+00:00" + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnrollCertificateResponse" + }, + "example": { + "referenceNumber": "20251010-EH-1B6C9EB000-4B15D3AEB9-89", + "timestamp": "2025-10-11T12:23:56.0154302+00:00" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25002 | Brak możliwości złożenia wniosku certyfikacyjnego dla wykorzystanego sposobu uwierzytelnienia. | |\n| 25003 | Dane w CSR nie zgadzają się z danymi w użytym wektorze uwierzytelniającym. | |\n| 25004 | Niepoprawny format CSR lub niepoprawny podpis CSR. | |\n| 25006 | Osiągnięto limit możliwych do złożenia wniosków certyfikacyjnych. | |\n| 25007 | Osiągnięto limit dopuszczalnej liczby posiadanych certyfikatów. | |\n| 25010 | Nieprawidłowy typ lub długość klucza. | |\n| 25011 | Nieprawidłowy algorytm podpisu CSR. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/certificates/enrollments/{referenceNumber}": { + "get": { + "tags": [ + "Certyfikaty" + ], + "summary": "Pobranie statusu przetwarzania wniosku certyfikacyjnego", + "description": "Zwraca informacje o statusie wniosku certyfikacyjnego.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny wniosku certyfikacyjnego", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CertificateEnrollmentStatusResponse" + }, + "example": { + "requestDate": "2025-10-11T12:23:56.0154302+00:00", + "status": { + "code": 100, + "description": "Wniosek przyjęty do realizacji" + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25005 | Wniosek certyfikacyjny o podanym numerze referencyjnym nie istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/certificates/retrieve": { + "post": { + "tags": [ + "Certyfikaty" + ], + "summary": "Pobranie certyfikatu lub listy certyfikatów", + "description": "Zwraca certyfikaty o podanych numerach seryjnych w formacie DER zakodowanym w Base64.", + "requestBody": { + "description": "", + "content": { + "application/json": { + "schema": { + "required": [ + "certificateSerialNumbers" + ], + "allOf": [ + { + "$ref": "#/components/schemas/RetrieveCertificatesRequest" + } + ] + }, + "example": { + "certificateSerialNumbers": [ + "0321C82DA41B4362", + "0321F21DA462A362" + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveCertificatesResponse" + }, + "example": { + "certificates": [ + { + "certificate": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/wABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3ODk6Ozw9Pj9AQUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX2BhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ent8fX5/gIGCg4SFhoeIiYqLjI2Oj5CRkpOUlZaXmJmam5ydnp+goaKjpKWmp6ipqqusra6vsLGys7S1tre4ubq7vL2+v8DBwsPExcbHyMnKy8zNzs/Q0dLT1NXW19jZ2tvc3d7f4OHi4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v8AAQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5Ojs8PT4/QEFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaW1xdXl9gYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+f4CBgoOEhYaHiImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6u7y9vr/AwcLDxMXGx8jJysvMzc7P0NHS09TV1tfY2drb3N3e3+Dh4uPk5ebn6Onq6+zt7u/w8fLz9PX29/j5+vv8/f7/AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w==", + "certificateName": "Cert 00023", + "certificateSerialNumber": "0321C82DA41B4362", + "certificateType": "Authentication" + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/certificates/{certificateSerialNumber}/revoke": { + "post": { + "tags": [ + "Certyfikaty" + ], + "summary": "Unieważnienie certyfikatu", + "description": "Unieważnia certyfikat o podanym numerze seryjnym.", + "parameters": [ + { + "name": "certificateSerialNumber", + "in": "path", + "description": "Numer seryjny certyfikatu (w formacie szesnastkowym).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/RevokeCertificateRequest" + } + ] + } + } + } + }, + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25008 | Certyfikat o podanym numerze seryjnym nie istnieje. | |\n| 25009 | Nie można odwołać wskazanego certyfikatu, ponieważ jest już odwołany, zablokowany lub nieważny.| |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/certificates/query": { + "post": { + "tags": [ + "Certyfikaty" + ], + "summary": "Pobranie listy metadanych certyfikatów", + "description": "Zwraca listę certyfikatów spełniających podane kryteria wyszukiwania.\nW przypadku braku podania kryteriów wyszukiwania zwrócona zostanie nieprzefiltrowana lista.\n\n**Sortowanie:**\n\n- requestDate (Desc)\n\n", + "parameters": [ + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników", + "schema": { + "maximum": 50, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + }, + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + } + ], + "requestBody": { + "description": "Kryteria filtrowania", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/QueryCertificatesRequest" + } + ] + }, + "example": { + "type": "Offline", + "status": "Active" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryCertificatesResponse" + }, + "example": { + "certificates": [ + { + "certificateSerialNumber": "018209160C631F1E", + "name": "Certyfikat 1", + "type": "Authentication", + "commonName": "Jan Kowalski", + "status": "Active", + "subjectIdentifier": { + "type": "Nip", + "value": "1234445678" + }, + "validFrom": "2025-08-24T14:15:22+00:00", + "validTo": "2027-08-24T14:15:22+00:00", + "lastUseDate": "2025-08-25T14:15:22+00:00", + "requestDate": "2025-08-24T14:15:22+00:00" + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "requestDate", + "direction": "Desc" + } + ] + } + }, + "/security/public-key-certificates": { + "get": { + "tags": [ + "Certyfikaty klucza publicznego" + ], + "summary": "Pobranie certyfikatów", + "description": "Zwraca informacje o kluczach publicznych używanych do szyfrowania danych przesyłanych do systemu KSeF.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PublicKeyCertificate" + } + }, + "example": [ + { + "certificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwocTwdNgt2+PXJ2fcB7k1kn5eFUTXBeep9pH...", + "validFrom": "2024-07-11T12:23:56.0154302+00:00", + "validTo": "2028-07-11T12:23:56.0154302+00:00", + "usage": [ + "KsefTokenEncryption", + "SymmetricKeyEncryption" + ] + } + ] + } + } + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/subject": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Utworzenie podmiotu", + "description": "Tworzenie nowego podmiotu testowego. W przypadku grupy VAT i JST istnieje możliwość stworzenia jednostek podrzędnych. W wyniku takiego działania w systemie powstanie powiązanie między tymi podmiotami.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectNip", + "subjectType", + "description" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubjectCreateRequest" + } + ] + }, + "example": { + "subjectNip": "7762811692", + "subjectType": "EnforcementAuthority", + "description": "Centrala", + "createdDate": "2025-08-25T14:15:22+00:00" + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/subject/remove": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Usunięcie podmiotu", + "description": "Usuwanie podmiotu testowego. W przypadku grupy VAT i JST usunięte zostaną również jednostki podrzędne.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectNip" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubjectRemoveRequest" + } + ] + }, + "example": { + "subjectNip": "7762811692" + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/person": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Utworzenie osoby fizycznej", + "description": "Tworzenie nowej osoby fizycznej, której system nadaje uprawnienia właścicielskie. Można również określić, czy osoba ta jest komornikiem – wówczas otrzyma odpowiednie uprawnienie egzekucyjne.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "nip", + "pesel", + "isBailiff", + "description" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonCreateRequest" + } + ] + }, + "example": { + "nip": "7762811692", + "pesel": "15062788702", + "isBailiff": true, + "description": "TestPerson_01", + "isDeceased": false, + "createdDate": "2025-08-25T14:15:22+00:00" + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/person/remove": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Usunięcie osoby fizycznej", + "description": "Usuwanie testowej osoby fizycznej. System automatycznie odbierze jej wszystkie uprawnienia.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "nip" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonRemoveRequest" + } + ] + }, + "example": { + "nip": "7762811692" + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/permissions": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Nadanie uprawnień testowemu podmiotowi/osobie fizycznej", + "description": "Nadawanie uprawnień testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "contextIdentifier", + "authorizedIdentifier", + "permissions" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TestDataPermissionsGrantRequest" + } + ] + }, + "example": { + "contextIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "authorizedIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "permissions": [ + { + "description": "Opis testowy", + "permissionType": "InvoiceRead" + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/permissions/revoke": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Odebranie uprawnień testowemu podmiotowi/osobie fizycznej", + "description": "Odbieranie uprawnień nadanych testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "contextIdentifier", + "authorizedIdentifier" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TestDataPermissionsRevokeRequest" + } + ] + }, + "example": { + "contextIdentifier": { + "type": "Nip", + "value": "5265877635" + }, + "authorizedIdentifier": { + "type": "Nip", + "value": "7762811692" + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/attachment": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Umożliwienie wysyłania faktur z załącznikiem", + "description": "Dodaje możliwość wysyłania faktur z załącznikiem przez wskazany podmiot", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "nip" + ], + "allOf": [ + { + "$ref": "#/components/schemas/AttachmentPermissionGrantRequest" + } + ] + }, + "example": { + "nip": "7762811692" + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/testdata/attachment/revoke": { + "post": { + "tags": [ + "Dane testowe" + ], + "summary": "Odebranie możliwości wysyłania faktur z załącznikiem", + "description": "Odbiera możliwość wysyłania faktur z załącznikiem przez wskazany podmiot", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "nip" + ], + "allOf": [ + { + "$ref": "#/components/schemas/AttachmentPermissionRevokeRequest" + } + ] + }, + "example": { + "nip": "7762811692" + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/limits/context": { + "get": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Pobranie limitów dla bieżącego kontekstu", + "description": "Zwraca wartości aktualnie obowiązujących limitów dla bieżącego kontekstu.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EffectiveContextLimits" + }, + "example": { + "onlineSession": { + "maxInvoiceSizeInMB": 1, + "maxInvoiceWithAttachmentSizeInMB": 3, + "maxInvoices": 10000 + }, + "batchSession": { + "maxInvoiceSizeInMB": 1, + "maxInvoiceWithAttachmentSizeInMB": 3, + "maxInvoices": 10000 + } + } + } + } + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/limits/subject": { + "get": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Pobranie limitów dla bieżącego podmiotu", + "description": "Zwraca wartości aktualnie obowiązujących limitów dla bieżącego podmiotu.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EffectiveSubjectLimits" + }, + "example": { + "enrollment": { + "maxEnrollments": 6 + }, + "certificate": { + "maxCertificates": 2 + } + } + } + } + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/rate-limits": { + "get": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Pobranie aktualnie obowiązujących limitów API", + "description": "Zwraca wartości aktualnie obowiązujących limitów ilości żądań przesyłanych do API.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EffectiveApiRateLimits" + }, + "example": { + "onlineSession": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "batchSession": { + "perSecond": 100, + "perMinute": 200, + "perHour": 600 + }, + "invoiceSend": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1800 + }, + "invoiceStatus": { + "perSecond": 300, + "perMinute": 1200, + "perHour": 12000 + }, + "sessionList": { + "perSecond": 50, + "perMinute": 100, + "perHour": 600 + }, + "sessionInvoiceList": { + "perSecond": 100, + "perMinute": 200, + "perHour": 2000 + }, + "sessionMisc": { + "perSecond": 100, + "perMinute": 1200, + "perHour": 12000 + }, + "invoiceMetadata": { + "perSecond": 80, + "perMinute": 160, + "perHour": 200 + }, + "invoiceExport": { + "perSecond": 40, + "perMinute": 80, + "perHour": 200 + }, + "invoiceExportStatus": { + "perSecond": 100, + "perMinute": 600, + "perHour": 6000 + }, + "invoiceDownload": { + "perSecond": 80, + "perMinute": 160, + "perHour": 640 + }, + "other": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + } + } + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/testdata/limits/context/session": { + "post": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Zmiana limitów sesji dla bieżącego kontekstu", + "description": "Zmienia wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu. **Tylko na środowiskach testowych.**", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "onlineSession", + "batchSession" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SetSessionLimitsRequest" + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + }, + "delete": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Przywrócenie domyślnych wartości limitów sesji dla bieżącego kontekstu", + "description": "Przywraca wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**", + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/testdata/limits/subject/certificate": { + "post": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Zmiana limitów certyfikatów dla bieżącego podmiotu", + "description": "Zmienia wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu. **Tylko na środowiskach testowych.**", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SetSubjectLimitsRequest" + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + }, + "delete": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Przywrócenie domyślnych wartości limitów certyfikatów dla bieżącego podmiotu", + "description": "Przywraca wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu do wartości domyślnych. **Tylko na środowiskach testowych.**", + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/testdata/rate-limits": { + "post": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Zmiana limitów API dla bieżącego kontekstu", + "description": "Zmienia wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu. **Tylko na środowiskach testowych.**", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "rateLimits" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SetRateLimitsRequest" + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + }, + "delete": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Przywrócenie domyślnych wartości limitów API dla bieżącego kontekstu", + "description": "Przywraca wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**", + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/testdata/rate-limits/production": { + "post": { + "tags": [ + "Limity i ograniczenia" + ], + "summary": "Zmiana limitów API dla bieżącego kontekstu na wartości produkcyjne", + "description": "Zmienia wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu na wartości takie jakie będą na środowisku produkcyjnym. **Tylko na środowiskach testowych.**", + "responses": { + "200": { + "description": "OK" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/permissions/persons/grants": { + "post": { + "tags": [ + "Nadawanie uprawnień" + ], + "summary": "Nadanie osobom fizycznym uprawnień do pracy w KSeF", + "description": "Metoda pozwala na nadanie osobie wskazanej w żądaniu uprawnień do pracy w KSeF \nw kontekście bieżącym.\n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur, \n- **InvoiceRead** – przeglądanie faktur, \n- **CredentialsManage** – zarządzanie uprawnieniami, \n- **CredentialsRead** – przeglądanie uprawnień, \n- **Introspection** – przeglądanie historii sesji i generowanie UPO, \n- **SubunitManage** – zarządzanie jednostkami podrzędnymi, \n- **EnforcementOperations** – wykonywanie operacji egzekucyjnych.\n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień. \nUprawnienie **EnforcementOperations** może być nadane wyłącznie wtedy, \ngdy podmiot kontekstu ma rolę **EnforcementAuthority** (organ egzekucyjny) \nlub **CourtBailiff** (komornik sądowy).\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadawanie-uprawnie%C5%84-osobom-fizycznym-do-pracy-w-ksef)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectIdentifier", + "permissions", + "description", + "subjectDetails" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsGrantRequest" + } + ] + }, + "example": { + "subjectIdentifier": { + "type": "Pesel", + "value": "15062788702" + }, + "permissions": [ + "InvoiceRead", + "InvoiceWrite", + "Introspection", + "CredentialsRead" + ], + "description": "Opis uprawnienia", + "subjectDetails": { + "subjectDetailsType": "PersonByIdentifier", + "personById": { + "firstName": "Adam", + "lastName": "Abacki" + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage" + ] + } + }, + "/permissions/entities/grants": { + "post": { + "tags": [ + "Nadawanie uprawnień" + ], + "summary": "Nadanie podmiotom uprawnień do obsługi faktur", + "description": "Metoda pozwala na nadanie podmiotowi wskazanemu w żądaniu uprawnień do obsługi faktur podmiotu kontekstu. \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień. \nDla każdego uprawnienia może być ustawiona flaga **canDelegate**, mówiąca o możliwości jego dalszego przekazywania poprzez nadawanie w sposób pośredni.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-podmiotom-uprawnie%C5%84-do-obs%C5%82ugi-faktur)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectIdentifier", + "permissions", + "description", + "subjectDetails" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityPermissionsGrantRequest" + } + ] + }, + "example": { + "subjectIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "permissions": [ + { + "type": "InvoiceRead", + "canDelegate": true + }, + { + "type": "InvoiceWrite", + "canDelegate": true + } + ], + "description": "Opis uprawnienia", + "subjectDetails": { + "fullName": "Firma sp. z o.o." + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage" + ] + } + }, + "/permissions/authorizations/grants": { + "post": { + "tags": [ + "Nadawanie uprawnień" + ], + "summary": "Nadanie uprawnień podmiotowych", + "description": "Metoda pozwala na nadanie jednego z uprawnień podmiotowych do obsługi podmiotu kontekstu podmiotowi wskazanemu w żądaniu.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-podmiotowych)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectIdentifier", + "permission", + "description", + "subjectDetails" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationPermissionsGrantRequest" + } + ] + }, + "example": { + "subjectIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "permission": "SelfInvoicing", + "description": "działanie w imieniu 3393244202 w kontekście 7762811692, Firma sp. z o.o.", + "subjectDetails": { + "fullName": "Firma sp. z o.o." + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage" + ] + } + }, + "/permissions/indirect/grants": { + "post": { + "tags": [ + "Nadawanie uprawnień" + ], + "summary": "Nadanie uprawnień w sposób pośredni", + "description": "Metoda pozwala na nadanie w sposób pośredni osobie wskazanej w żądaniu uprawnień do obsługi faktur innego podmiotu – klienta. \nMoże to być jedna z możliwości: \n- nadanie uprawnień generalnych – do obsługi wszystkich klientów \n- nadanie uprawnień selektywnych – do obsługi wskazanego klienta \n \nUprawnienie selektywne może być nadane wyłącznie wtedy, gdy klient nadał wcześniej podmiotowi bieżącego kontekstu dowolne uprawnienie z prawem do jego dalszego przekazywania (patrz [POST /v2/permissions/entities/grants](/docs/v2/index.html#tag/Nadawanie-uprawnien/paths/~1permissions~1entities~1grants/post)). \n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-w-spos%C3%B3b-po%C5%9Bredni)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectIdentifier", + "permissions", + "description", + "subjectDetails" + ], + "allOf": [ + { + "$ref": "#/components/schemas/IndirectPermissionsGrantRequest" + } + ] + }, + "example": { + "subjectIdentifier": { + "type": "Pesel", + "value": "22271569167" + }, + "targetIdentifier": { + "type": "Nip", + "value": "5687926712" + }, + "permissions": [ + "InvoiceWrite", + "InvoiceRead" + ], + "description": "praca dla klienta 5687926712; uprawniony PESEL: 22271569167, Adam Abacki; pośrednik 3936518395", + "subjectDetails": { + "subjectDetailsType": "PersonByIdentifier", + "personById": { + "firstName": "Adam", + "lastName": "Abacki" + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage" + ] + } + }, + "/permissions/subunits/grants": { + "post": { + "tags": [ + "Nadawanie uprawnień" + ], + "summary": "Nadanie uprawnień administratora podmiotu podrzędnego", + "description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień administratora w kontekście: \n- wskazanego NIP podmiotu podrzędnego – wyłącznie jeżeli podmiot bieżącego kontekstu logowania ma rolę podmiotu nadrzędnego:\n - **LocalGovernmentUnit** \n - **VatGroupUnit** \n- wskazanego lub utworzonego identyfikatora wewnętrznego \n \nWraz z utworzeniem administratora jednostki podrzędnej tworzony jest identyfikator wewnętrzny składający się z numeru NIP podmiotu kontekstu logowania oraz 5 cyfr unikalnie identyfikujących jednostkę wewnętrzną.\nOstatnia cyfra musi być poprawną sumą kontrolną, która jest obliczana według poniższego algorytmu.\n\nAlgorytm używa naprzemiennych wag (1×, 3×, 1×, 3×, ...), sumuje wyniki i zwraca resztę z dzielenia przez 10.\n\nPrzykład:\n- Wejście: \"6824515772-1234\" (bez cyfry kontrolnej)\n- Pozycja 0 (1. cyfra): 6 × 1 = 6\n- Pozycja 1 (2. cyfra): 8 × 3 = 24\n- Pozycja 2 (3. cyfra): 2 × 1 = 2\n- Pozycja 3 (4. cyfra): 4 × 3 = 12\n- Pozycja 4 (5. cyfra): 5 × 1 = 5\n- Pozycja 5 (6. cyfra): 1 × 3 = 3\n- Pozycja 6 (7. cyfra): 5 × 1 = 5\n- Pozycja 7 (8. cyfra): 7 × 3 = 21\n- Pozycja 8 (9. cyfra): 7 × 1 = 7\n- Pozycja 9 (10. cyfra): 2 × 3 = 6\n- Pozycja 10 (11. cyfra): 1 × 1 = 1\n- Pozycja 11 (12. cyfra): 2 × 3 = 6\n- Pozycja 12 (13. cyfra): 3 × 1 = 3\n- Pozycja 13 (14. cyfra): 4 × 3 = 12\n- Suma: 6 + 24 + 2 + 12 + 5 + 3 + 5 + 21 + 7 + 6 + 1 + 6 + 3 + 12 = 113\n- Cyfra kontrolna (15. cyfra): 113 % 10 = 3\n\nW żądaniu podaje się również nazwę tej jednostki. \n \nUprawnienia administratora jednostki podrzędnej obejmują: \n- **CredentialsManage** – zarządzanie uprawnieniami \n \nMetoda automatycznie nadaje powyższe uprawnienie, bez konieczności podawania go w żądaniu.\n \n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-podrz%C4%99dnego)\n\n**Wymagane uprawnienia**: `SubunitManage`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectIdentifier", + "contextIdentifier", + "description", + "subjectDetails" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsGrantRequest" + } + ] + }, + "example": { + "subjectIdentifier": { + "type": "Pesel", + "value": "15062788702" + }, + "contextIdentifier": { + "type": "InternalId", + "value": "7762811692-12345" + }, + "description": "Opis uprawnienia", + "subunitName": "Jednostka 014", + "subjectDetails": { + "subjectDetailsType": "PersonByIdentifier", + "personById": { + "firstName": "Adam", + "lastName": "Abacki" + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "SubunitManage" + ] + } + }, + "/permissions/eu-entities/administration/grants": { + "post": { + "tags": [ + "Nadawanie uprawnień" + ], + "summary": "Nadanie uprawnień administratora podmiotu unijnego", + "description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień administratora w kontekście złożonym z identyfikatora NIP podmiotu kontekstu bieżącego oraz numeru VAT UE podmiotu unijnego wskazanego w żądaniu. \nWraz z utworzeniem administratora podmiotu unijnego tworzony jest kontekst złożony składający się z numeru NIP podmiotu kontekstu logowania oraz wskazanego numeru identyfikacyjnego VAT UE podmiotu unijnego. \nW żądaniu podaje się również nazwę i adres podmiotu unijnego. \n \nJedynym sposobem identyfikacji uprawnianego jest odcisk palca certyfikatu kwalifikowanego: \n- certyfikat podpisu elektronicznego dla osób fizycznych \n- certyfikat pieczęci elektronicznej dla podmiotów \n \nUprawnienia administratora podmiotu unijnego obejmują: \n- **VatEuManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n- **Introspection** – przeglądanie historii sesji \n \nMetoda automatycznie nadaje wszystkie powyższe uprawnienia, bez konieczności ich wskazywania w żądaniu.\n \n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-unijnego)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectIdentifier", + "contextIdentifier", + "description", + "euEntityName", + "subjectDetails", + "euEntityDetails" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityAdministrationPermissionsGrantRequest" + } + ] + }, + "example": { + "subjectIdentifier": { + "type": "Fingerprint", + "value": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59" + }, + "contextIdentifier": { + "type": "NipVatUe", + "value": "7762811692-DE123456789012" + }, + "description": "Opis uprawnienia", + "euEntityName": "Firma G.m.b.H.", + "subjectDetails": { + "subjectDetailsType": "PersonByFingerprintWithIdentifier", + "personByFpWithId": { + "firstName": "Adam", + "lastName": "Abacki", + "identifier": { + "type": "Pesel", + "value": "15062788702" + } + } + }, + "euEntityDetails": { + "fullName": "Firma G.m.b.H.", + "address": "Warszawa ul. Świętokrzyska 4824 00-916 Warszawa" + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage" + ] + } + }, + "/permissions/eu-entities/grants": { + "post": { + "tags": [ + "Nadawanie uprawnień" + ], + "summary": "Nadanie uprawnień reprezentanta podmiotu unijnego", + "description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień do wystawiania i/lub przeglądania faktur w kontekście złożonym kontekstu bieżącego. \n \nJedynym sposobem identyfikacji uprawnianego jest odcisk palca certyfikatu kwalifikowanego: \n- certyfikat podpisu elektronicznego dla osób fizycznych \n- certyfikat pieczęci elektronicznej dla podmiotów \n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-reprezentanta-podmiotu-unijnego)\n\n**Wymagane uprawnienia**: `VatUeManage`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "subjectIdentifier", + "permissions", + "description", + "subjectDetails" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionsGrantRequest" + } + ] + }, + "example": { + "subjectIdentifier": { + "type": "Fingerprint", + "value": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59" + }, + "permissions": [ + "InvoiceRead", + "InvoiceWrite" + ], + "description": "Opis uprawnienia", + "subjectDetails": { + "subjectDetailsType": "PersonByFingerprintWithIdentifier", + "personByFpWithId": { + "firstName": "Adam", + "lastName": "Abacki", + "identifier": { + "type": "Pesel", + "value": "15062788702" + } + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "VatUeManage" + ] + } + }, + "/permissions/common/grants/{permissionId}": { + "delete": { + "tags": [ + "Odbieranie uprawnień" + ], + "summary": "Odebranie uprawnień", + "description": "Metoda pozwala na odebranie uprawnienia o wskazanym identyfikatorze. \nWymagane jest wcześniejsze odczytanie uprawnień w celu uzyskania \nidentyfikatora uprawnienia, które ma zostać odebrane.\n\n> Więcej informacji:\n> - [Odbieranie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84)\n\n**Wymagane uprawnienia**: `CredentialsManage`, `VatUeManage`, `SubunitManage`.", + "parameters": [ + { + "name": "permissionId", + "in": "path", + "description": "Id uprawnienia.", + "required": true, + "schema": { + "$ref": "#/components/schemas/PermissionId" + } + } + ], + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage", + "VatUeManage", + "SubunitManage" + ] + } + }, + "/permissions/authorizations/grants/{permissionId}": { + "delete": { + "tags": [ + "Odbieranie uprawnień" + ], + "summary": "Odebranie uprawnień podmiotowych", + "description": "Metoda pozwala na odebranie uprawnienia podmiotowego o wskazanym identyfikatorze. \nWymagane jest wcześniejsze odczytanie uprawnień w celu uzyskania \nidentyfikatora uprawnienia, które ma zostać odebrane.\n \n> Więcej informacji:\n> - [Odbieranie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84-podmiotowych)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", + "parameters": [ + { + "name": "permissionId", + "in": "path", + "description": "Id uprawnienia.", + "required": true, + "schema": { + "$ref": "#/components/schemas/PermissionId" + } + } + ], + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationResponse" + }, + "example": { + "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage" + ] + } + }, + "/permissions/operations/{referenceNumber}": { + "get": { + "tags": [ + "Operacje" + ], + "summary": "Pobranie statusu operacji", + "description": "Zwraca status operacji asynchronicznej związanej z nadaniem lub odebraniem uprawnień.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny operacji nadania lub odbierania uprawnień.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PermissionsOperationStatusResponse" + }, + "example": { + "status": { + "code": 200, + "description": "Operacja zakończona sukcesem" + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/permissions/attachments/status": { + "get": { + "tags": [ + "Operacje" + ], + "summary": "Sprawdzenie statusu zgody na wystawianie faktur z załącznikiem", + "description": "Sprawdzenie czy obecny kontekst posiada zgodę na wystawianie faktur z załącznikiem.\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CheckAttachmentPermissionStatusResponse" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "CredentialsManage", + "CredentialsRead" + ] + } + }, + "/invoices/ksef/{ksefNumber}": { + "get": { + "tags": [ + "Pobieranie faktur" + ], + "summary": "Pobranie faktury po numerze KSeF", + "description": "Zwraca fakturę o podanym numerze KSeF.\n\n**Wymagane uprawnienia**: `InvoiceRead`.", + "parameters": [ + { + "name": "ksefNumber", + "in": "path", + "description": "Numer KSeF faktury.", + "required": true, + "schema": { + "$ref": "#/components/schemas/KsefNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "headers": { + "x-ms-meta-hash": { + "description": "Skrót SHA-256 faktury, zakodowany w formacie Base64", + "schema": { + "$ref": "#/components/schemas/Sha256HashBase64" + } + } + }, + "content": { + "application/xml": { + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|\n| 21164 | Faktura o podanym identyfikatorze nie istnieje. | Faktura o numerze KSeF {ksefNumber} nie została znaleziona. |\n| 21165 | Faktura o podanym numerze KSeF nie jest jeszcze dostępna. | Faktura o numerze KSeF {ksefNumber} została przetworzona, ale nie jest jeszcze dostępna do pobrania. Spróbuj ponownie później. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 80 | 160 | 640 | invoiceDownload\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 80, + "perMinute": 160, + "perHour": 640 + }, + "x-required-permissions": [ + "InvoiceRead" + ] + } + }, + "/invoices/query/metadata": { + "post": { + "tags": [ + "Pobieranie faktur" + ], + "summary": "Pobranie listy metadanych faktur", + "description": "Zwraca metadane faktur spełniających filtry.\n\nLimit techniczny: ≤ 10 000 rekordów na zestaw filtrów, po jego osiągnięciu isTruncated = true i należy ponownie ustawić dateRange, używając ostatniej daty z wyników (tj. ustawić from/to - w zależności od kierunku sortowania, od daty ostatniego zwróconego rekordu) oraz wyzerować pageOffset.\n\n`Do scenariusza przyrostowego należy używać daty PermanentStorage oraz kolejność sortowania Asc`.\n \nScenariusz pobierania przyrostowego (skrót):\n* Gdy hasMore = false, należy zakończyć,\n* Gdy hasMore = true i isTruncated = false, należy zwiększyć pageOffset,\n* Gdy hasMore = true i isTruncated = true, należy zawęzić dateRange (ustawić from od daty ostatniego rekordu), wyzerować pageOffset i kontynuować\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc | Desc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.", + "parameters": [ + { + "name": "sortOrder", + "in": "query", + "description": "Kolejność sortowania wyników.\n| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SortOrder" + } + ], + "description": "| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n", + "default": "Asc" + } + }, + { + "name": "pageOffset", + "in": "query", + "description": "Indeks pierwszej strony wyników (0 = pierwsza strona).", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 250, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "requestBody": { + "description": "Kryteria filtrowania.", + "content": { + "application/json": { + "schema": { + "required": [ + "subjectType", + "dateRange" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQueryFilters" + } + ] + }, + "example": { + "subjectType": "Subject1", + "dateRange": { + "dateType": "PermanentStorage", + "from": "2025-08-28T09:22:13.388+00:00", + "to": "2025-09-28T09:24:13.388+00:00" + }, + "amount": { + "type": "Brutto", + "from": 100.50, + "to": 250.00 + }, + "currencyCodes": [ + "PLN", + "EUR" + ], + "invoicingMode": "Online", + "formType": "FA", + "invoiceTypes": [ + "Vat" + ], + "hasAttachment": true + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryInvoicesMetadataResponse" + }, + "example": { + "hasMore": false, + "isTruncated": false, + "permanentStorageHwmDate": "2025-08-28T09:23:55.388+00:00", + "invoices": [ + { + "ksefNumber": "5555555555-20250828-010080615740-E4", + "invoiceNumber": "FA/KUDYO1a7dddfe-610e-4843-84ba-6b887e35266e", + "issueDate": "2025-08-27", + "invoicingDate": "2025-08-28T09:22:13.388+00:00", + "acquisitionDate": "2025-08-28T09:22:56.388+00:00", + "permanentStorageDate": "2025-08-28T09:23:01.388+00:00", + "seller": { + "nip": "5555555555", + "name": "Test Company 1" + }, + "buyer": { + "identifier": { + "type": "Nip", + "value": "7352765225" + }, + "name": "Test Company 4" + }, + "netAmount": 35260.63, + "grossAmount": 43370.57, + "vatAmount": 8109.94, + "currency": "PLN", + "invoicingMode": "Offline", + "invoiceType": "Vat", + "formCode": { + "systemCode": "FA (3)", + "schemaVersion": "1-0E", + "value": "FA" + }, + "isSelfInvoicing": false, + "hasAttachment": false, + "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", + "thirdSubjects": [ ] + }, + { + "ksefNumber": "5555555555-20250828-010080615740-E4", + "invoiceNumber": "5265877635-20250925-010020A0A242-0A", + "issueDate": "2025-08-28", + "invoicingDate": "2025-08-28T10:23:13.388+00:00", + "acquisitionDate": "2025-08-28T10:23:56.388+00:00", + "permanentStorageDate": "2025-08-28T10:24:01.388+00:00", + "seller": { + "nip": "5555555555", + "name": "Test Company 1" + }, + "buyer": { + "identifier": { + "type": "Nip", + "value": "3225081610" + }, + "name": "Test Company 2" + }, + "netAmount": 35260.63, + "grossAmount": 43370.57, + "vatAmount": 8109.94, + "currency": "PLN", + "invoicingMode": "Online", + "invoiceType": "Vat", + "formCode": { + "systemCode": "FA (3)", + "schemaVersion": "1-0E", + "value": "FA" + }, + "isSelfInvoicing": false, + "hasAttachment": true, + "invoiceHash": "o+nMBU8n8TAhy6EjbcdYdHSZVbUspqmCKqOPLhy3zIQ=", + "thirdSubjects": [ + { + "identifier": { + "type": "InternalId", + "value": "5555555555-12345" + }, + "name": "Wystawca faktury", + "role": 4 + } + ] + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|\n| 21183 | Zakres filtrowania wykracza poza dostępny zakres danych. | Parametr dateRange.from jest późniejszy niż PermanentStorageHwmDate przy włączonym restrictToPermanentStorageHwmDate. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 80 | 160 | 200 | invoiceMetadata\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 80, + "perMinute": 160, + "perHour": 200 + }, + "x-sort": [ + { + "allowedFields": [ + "permanentStorageDate", + "invoicingDate", + "issueDate" + ], + "allowedDirections": [ + "Asc", + "Desc" + ] + } + ], + "x-required-permissions": [ + "InvoiceRead" + ] + } + }, + "/invoices/exports": { + "post": { + "tags": [ + "Pobieranie faktur" + ], + "summary": "Eksport paczki faktur", + "description": "Rozpoczyna asynchroniczny proces wyszukiwania faktur w systemie KSeF na podstawie przekazanych filtrów oraz przygotowania ich w formie zaszyfrowanej paczki.\nWymagane jest przekazanie informacji o szyfrowaniu w polu Encryption, które służą do zabezpieczenia przygotowanej paczki z fakturami.\nMaksymalnie można uruchomić 10 równoczesnych eksportów w zalogowanym kontekście.\n \nSystem pobiera faktury rosnąco według daty określonej w filtrze (Invoicing, Issue, PermanentStorage) i dodaje faktury(nazwa pliku: {ksefNumber}.xml) do paczki aż do osiągnięcia jednego z poniższych limitów:\n* Limit liczby faktur: 10 000 sztuk\n* Limit rozmiaru danych(skompresowanych): 1GB\n\nPaczka eksportu zawiera dodatkowy plik z metadanymi faktur w formacie JSON (`_metadata.json`). Zawartość pliku to\nobiekt z tablicą invoices, gdzie każdy element jest obiektem typu InvoiceMetadata\n(taki jak zwracany przez endpoint `POST /invoices/query/metadata`).\n\nPlik z metadanymi(_metadata.json) nie jest wliczany do limitów algorytmu budowania paczki. \n\n`Do realizacji pobierania przyrostowego należy stosować filtrowanie po dacie PermanentStorage`.\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.", + "requestBody": { + "description": "Dane wejściowe określające kryteria i format eksportu paczki faktur.", + "content": { + "application/json": { + "schema": { + "required": [ + "encryption", + "filters" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceExportRequest" + } + ] + }, + "example": { + "encryption": { + "encryptedSymmetricKey": "bdUVjqLj+y2q6aBUuLxxXYAMqeDuIBRTyr+hB96DaWKaGzuVHw9p+Nk9vhzgF/Q5cavK2k6eCh6SdsrWI0s9mFFj4A4UJtsyD8Dn3esLfUZ5A1juuG3q3SBi/XOC/+9W+0T/KdwdE393mbiUNyx1K/0bw31vKJL0COeJIDP7usAMDl42/H1TNvkjk+8iZ80V0qW7D+RZdz+tdiY1xV0f2mfgwJ46V0CpZ+sB9UAssRj+eVffavJ0TOg2b5JaBxE8MCAvrF6rO5K4KBjUmoy7PP7g1qIbm8xI2GO0KnfPOO5OWj8rsotRwBgu7x19Ine3qYUvuvCZlXRGGZ5NHIzWPM4O74+gNalaMgFCsmv8mMhETSU4SfAGmJr9edxPjQSbgD5i2X4eDRDMwvyaAa7CP1b2oICju+0L7Fywd2ZtUcr6El++eTVoi8HYsTArntET++gULT7XXjmb8e3O0nxrYiYsE9GMJ7HBGv3NOoJ1NTm3a7U6+c0ZJiBVLvn6xXw10LQX243xH+ehsKo6djQJKYtqcNPaXtCwM1c9RrsOx/wRXyWCtTffqLiaR0LbYvfMJAcEWceG+RaeAx4p37OiQqdJypd6LAv9/0ECWK8Bip8yyoA+0EYiAJb9YuDz2YlQX9Mx9E9FzFIAsgEQ2w723HZYWgPywLb+dlsum4lTZKQ=", + "initializationVector": "c29tZUluaXRWZWN0b3I=" + }, + "filters": { + "subjectType": "Subject1", + "dateRange": { + "dateType": "PermanentStorage", + "from": "2025-08-28T09:22:13.388+00:00", + "to": "2025-09-28T09:22:13.388+00:00", + "restrictToPermanentStorageHwmDate": true + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExportInvoicesResponse" + }, + "example": { + "referenceNumber": "20251010-EH-1B6C9EB000-4B15D3AEB9-89" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------|\n| 21181 | Nieprawidłowe żądanie eksportu faktur. | Nie można wyeksportować paczki faktur dla wybranego podmiotu ({subjecttype}) i zalogowanego identyfikatora kontekstu ({type}). |\n| 21182 | Osiągnięto limit trwających eksportów. | Dla uwierzytelnionego podmiotu w bieżącym kontekście osiągnięto maksymalny limit {count} równoczesnych eksportów faktur. Spróbuj ponownie później. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 40 | 80 | 200 | invoiceExport\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 40, + "perMinute": 80, + "perHour": 200 + }, + "x-sort": [ + { + "allowedFields": [ + "permanentStorageDate", + "invoicingDate", + "issueDate" + ], + "allowedDirections": "Asc" + } + ], + "x-required-permissions": [ + "InvoiceRead" + ] + } + }, + "/invoices/exports/{referenceNumber}": { + "get": { + "tags": [ + "Pobieranie faktur" + ], + "summary": "Pobranie statusu eksportu paczki faktur", + "description": "Paczka faktur jest dzielona na części o maksymalnym rozmiarze 50 MB. Każda część jest zaszyfrowana algorytmem AES-256-CBC z dopełnieniem PKCS#7, przy użyciu klucza symetrycznego przekazanego podczas inicjowania eksportu. \n\nW przypadku ucięcia wyniku eksportu z powodu przekroczenia limitów, zwracana jest flaga IsTruncated = true oraz odpowiednia data, którą należy wykorzystać do wykonania kolejnego eksportu, aż do momentu, gdy flaga IsTruncated = false.\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny eksportu faktur.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvoiceExportStatusResponse" + }, + "example": { + "status": { + "code": 200, + "description": "Eksport faktur zakończony sukcesem" + }, + "completedDate": "2025-09-16T16:09:40.901091+00:00", + "package": { + "invoiceCount": 10000, + "size": 22425060, + "parts": [ + { + "ordinalNumber": 1, + "partName": "20250925-EH-2D2C11B000-E9C9ED8340-EE-001.zip.aes", + "method": "GET", + "url": "https://ksef-api-storage/storage/00/20250626-eh-2d2c11b000-e9c9ed8340-ee/invoice-part/20250925-EH-2D2C11B000-E9C9ED8340-EE-001.zip.aes?skoid=1ad7cfe8-2cb2-406b-b96c-6eefb55794db&sktid=647754c7-3974-4442-a425-c61341b61c69&skt=2025-06-26T09%3A40%3A54Z&ske=2025-06-26T10%3A10%3A54Z&sks=b&skv=2025-01-05&sv=2025-01-05&se=2025-06-26T10%3A10%3A54Z&sr=b&sp=w&sig=8mKZEU8Reuz%2Fn7wHi4T%2FY8BzLeD5l8bR2xJsBxIgDEY%3D", + "partSize": 22425060, + "partHash": "BKH9Uy1CjBFXiQdDUM2CJYk5LxWTm4fE1lljnl83Ajw=", + "encryptedPartSize": 22425072, + "encryptedPartHash": "HlvwRLc59EJH7O5GoeHEZxTQO5TJ/WP1QH0aFi4x2Ss=", + "expirationDate": "2025-09-16T17:09:40.901091+00:00" + } + ], + "isTruncated": true, + "lastPermanentStorageDate": "2025-09-11T11:40:40.266578+00:00", + "permanentStorageHwmDate": "2025-09-11T12:00:40.266578+00:00" + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------|\n| 21175 | Wynik zapytania o podanym identyfikatorze nie istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 600 | 6000 | invoiceExportStatus\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 600, + "perHour": 6000 + }, + "x-sort": [ + { + "allowedFields": [ + "permanentStorageDate", + "invoicingDate", + "issueDate" + ], + "allowedDirections": "Asc" + } + ], + "x-required-permissions": [ + "InvoiceRead" + ] + } + }, + "/sessions": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie listy sesji", + "description": "Zwraca listę sesji spełniających podane kryteria wyszukiwania.\n\n\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n\n**Wymagane uprawnienia**:\n- `Introspection`/`EnforcementOperations` – pozwala pobrać wszystkie sesje w bieżącym kontekście uwierzytelnienia `(ContextIdentifier)`.\n- `InvoiceWrite` – pozwala pobrać wyłącznie sesje utworzone przez podmiot uwierzytelniający, czyli podmiot inicjujący uwierzytelnienie.", + "parameters": [ + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony.", + "schema": { + "maximum": 1000, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + }, + { + "name": "sessionType", + "in": "query", + "description": "Typ sesji.\n| Wartość | Opis |\n| --- | --- |\n| Online | Wysyłka interaktywna (pojedyncze faktury). |\n| Batch | Wysyłka wsadowa (paczka faktur). |\n", + "required": true, + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SessionType" + } + ] + } + }, + { + "name": "referenceNumber", + "in": "query", + "description": "Numer referencyjny sesji.", + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + }, + { + "name": "dateCreatedFrom", + "in": "query", + "description": "Data utworzenia sesji (od).", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "dateCreatedTo", + "in": "query", + "description": "Data utworzenia sesji (do).", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "dateClosedFrom", + "in": "query", + "description": "Data zamknięcia sesji (od).", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "dateClosedTo", + "in": "query", + "description": "Data zamknięcia sesji (do).", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "dateModifiedFrom", + "in": "query", + "description": "Data ostatniej aktywności (wysyłka faktury lub zmiana statusu) w ramach sesji (od).", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "dateModifiedTo", + "in": "query", + "description": "Data ostatniej aktywności (wysyłka faktury lub zmiana statusu) w ramach sesji (do).", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "statuses", + "in": "query", + "description": "Statusy sesji.\n| Wartość | Opis |\n| --- | --- |\n| InProgress | Sesja aktywna. |\n| Succeeded | Sesja przetworzona poprawnie. W trakcie przetwarzania sesji nie wystąpiły żadne błędy, ale część faktur nadal mogła zostać odrzucona. |\n| Failed | Sesja nie przetworzona z powodu błędów. Na etapie rozpoczynania lub kończenia sesji wystąpiły błędy, które nie pozwoliły na jej poprawne przetworzenie. |\n| Cancelled | Sesja anulowania. Został przekroczony czas na wysyłkę w sesji wsadowej, lub nie przesłano żadnych faktur w sesji interaktywnej. |\n", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommonSessionStatus" + } + } + }, + { + "name": "x-continuation-token", + "in": "header", + "description": "Token służący do pobrania kolejnej strony wyników.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionsQueryResponse" + }, + "example": { + "continuationToken": "W3sidG9rZW4iOiIrUklEOn4zeHd0QU1SM3dYYjRCd0FBQUFBQUNBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBZ2dBQUFBQUFDQUFBQVlBQUFBQUlBQUFBQUFBQUFBZ0FBQVVBUEVIQUVGdGdJUUFFUUJBQUJBRUFCQVVoZ1NBQXdBQUFBQWdBQUFHQUhFa0NFQWxnQVFBQUFBQUlBQUFGZ0F5Q0FVZ0VBRC9nRE9BRFlFdWdIcUF5SXBEZ0IrQUJnQUFBQUFnQUFBQ0FPNlYiLCJyYW5nZSI6eyJtaW4iOiIiLCJtYXgiOiIwNUMxREYyQjVGMzU5OCJ9fV0=", + "sessions": [ + { + "referenceNumber": "20250925-SO-2F67776000-97273B191A-65", + "status": { + "code": 200, + "description": "Sesja interaktywna przetworzona pomyślnie" + }, + "dateCreated": "2025-09-25T13:48:26.8700925+00:00", + "dateUpdated": "2025-09-26T02:16:07+00:00", + "validUntil": "2025-09-26T01:48:26.8700925+00:00", + "totalInvoiceCount": 2, + "successfulInvoiceCount": 2, + "failedInvoiceCount": 0 + }, + { + "referenceNumber": "20250928-SO-494B541000-3AD87C01BA-5D", + "status": { + "code": 200, + "description": "Sesja interaktywna przetworzona pomyślnie" + }, + "dateCreated": "2025-09-28T21:20:54.5936927+00:00", + "dateUpdated": "2025-09-29T10:19:28+00:00", + "validUntil": "2025-09-29T09:20:54.5936927+00:00", + "totalInvoiceCount": 3, + "successfulInvoiceCount": 3, + "failedInvoiceCount": 0 + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 50 | 100 | 600 | sessionList\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 50, + "perMinute": 100, + "perHour": 600 + }, + "x-sort": [ + { + "field": "dateCreated", + "direction": "Desc" + } + ], + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "EnforcementOperations" + ] + } + }, + "/sessions/{referenceNumber}": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie statusu sesji", + "description": "Sprawdza bieżący status sesji o podanym numerze referencyjnym.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionStatusResponse" + }, + "example": { + "status": { + "code": 200, + "description": "Sesja interaktywna przetworzona pomyślnie" + }, + "dateCreated": "2025-09-18T15:00:30+00:00", + "dateUpdated": "2025-09-18T15:01:20+00:00", + "upo": { + "pages": [ + { + "referenceNumber": "20250918-EU-2EBD6FA000-242EB9B66D-43", + "downloadUrl": "https://api-test.ksef.mf.gov.pl/storage/01/20250918-so-3789a40000-20373e1269-a3/session-upo/upo_00.xml?sv=2025-01-05&st=2025-09-18T14%3A55%3A50Z&se=2025-09-21T15%3A00%3A50Z&sr=b&sp=r&sig=ZlQO6Xtzu3VQQDwmEMfb0VryMxe9WcUgWtkdiB6X2Qo%3D", + "downloadUrlExpirationDate": "2025-09-21T15:00:50+00:00" + } + ] + }, + "invoiceCount": 10, + "successfulInvoiceCount": 8, + "failedInvoiceCount": 2 + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 1200, + "perHour": 12000 + }, + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/{referenceNumber}/invoices": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie faktur sesji", + "description": "Zwraca listę faktur przesłanych w sesji wraz z ich statusami, oraz informacje na temat ilości poprawnie i niepoprawnie przetworzonych faktur.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "x-continuation-token", + "in": "header", + "description": "Token służący do pobrania kolejnej strony wyników.", + "schema": { + "type": "string" + } + }, + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 1000, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionInvoicesResponse" + }, + "example": { + "continuationToken": "W34idG9rZW4iOiIrUklEOn4xUE5BQU5hcXJVOUFBQUFBQUFBQUFBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBVUFBQUFBQUFBQUFRZ0FBQUFBQUFBQT0iLCJyYW5nZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fV0=", + "invoices": [ + { + "ordinalNumber": 1, + "invoiceNumber": "FA/XPWIC-7900685789/06/2025", + "ksefNumber": "5265877635-20250626-010080DD2B5E-26", + "referenceNumber": "20250918-EE-2F15D39000-242207E5C4-1B", + "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", + "acquisitionDate": "2025-09-18T12:24:16.0154302+00:00", + "invoicingDate": "2025-09-18T12:23:56.0154302+00:00", + "permanentStorageDate": "2025-09-18T12:24:01.0154302+00:00", + "upoDownloadUrl": "https://api-test.ksef.mf.gov.pl/storage/01/20250918-SB-3789A40000-20373E1269-A3/invoice-upo/upo_5265877635-20250626-010080DD2B5E-26.xml?sv=2025-01-05&st=2025-09-18T14%3A49%3A20Z&se=2025-09-21T14%3A54%3A20Z&sr=b&sp=r&sig=%2BUWFPA10gS580VhngGKW%2FZiOOtiHPOiTyMlxhG6ZvWs%3D", + "upoDownloadUrlExpirationDate": "2025-09-21T14:54:20+00:00", + "status": { + "code": 200, + "description": "Sukces" + } + }, + { + "ordinalNumber": 2, + "referenceNumber": "20250918-EE-2F20AD2000-242386DF86-52", + "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", + "invoicingDate": "2025-09-18T12:23:56.0154302+00:00", + "status": { + "code": 440, + "description": "Duplikat faktury", + "details": [ + "Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4" + ], + "extensions": { + "originalSessionReferenceNumber": "20250626-SO-2F14610000-242991F8C9-B4", + "originalKsefNumber": "5265877635-20250626-010080DD2B5E-26" + } + } + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 2000 | sessionInvoiceList\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 200, + "perHour": 2000 + }, + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie statusu faktury z sesji", + "description": "Zwraca fakturę przesłaną w sesji wraz ze statusem.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + }, + { + "name": "invoiceReferenceNumber", + "in": "path", + "description": "Numer referencyjny faktury.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionInvoiceStatusResponse" + }, + "example": { + "ordinalNumber": 2, + "referenceNumber": "20250626-EE-2F20AD2000-242386DF86-52", + "invoicingDate": "2025-07-11T12:23:56.0154302+00:00", + "status": { + "code": 440, + "description": "Duplikat faktury", + "details": [ + "Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4" + ], + "extensions": { + "originalSessionReferenceNumber": "20250626-SO-2F14610000-242991F8C9-B4", + "originalKsefNumber": "5265877635-20250626-010080DD2B5E-26" + } + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 300 | 1200 | 12000 | invoiceStatus\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 300, + "perMinute": 1200, + "perHour": 12000 + }, + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/{referenceNumber}/invoices/failed": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie niepoprawnie przetworzonych faktur sesji", + "description": "Zwraca listę niepoprawnie przetworzonych faktur przesłanych w sesji wraz z ich statusami.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "x-continuation-token", + "in": "header", + "description": "Token służący do pobrania kolejnej strony wyników.", + "schema": { + "type": "string" + } + }, + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 1000, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionInvoicesResponse" + }, + "example": { + "continuationToken": "...", + "invoices": [ + { + "ordinalNumber": 2, + "referenceNumber": "20250626-EE-2F20AD2000-242386DF86-52", + "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", + "invoiceFileName": "invoice1.xml", + "invoicingDate": "2025-07-11T12:23:56.0154302+00:00", + "status": { + "code": 440, + "description": "Duplikat faktury", + "details": [ + "Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4" + ], + "extensions": { + "originalSessionReferenceNumber": "20250626-SO-2F14610000-242991F8C9-B4", + "originalKsefNumber": "5265877635-20250626-010080DD2B5E-26" + } + } + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 2000 | sessionInvoiceList\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 200, + "perHour": 2000 + }, + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie UPO faktury z sesji na podstawie numeru KSeF", + "description": "Zwraca UPO faktury przesłanego w sesji na podstawie jego numeru KSeF.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + }, + { + "name": "ksefNumber", + "in": "path", + "description": "Numer KSeF faktury.", + "required": true, + "schema": { + "$ref": "#/components/schemas/KsefNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "headers": { + "x-ms-meta-hash": { + "description": "Skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64", + "schema": { + "$ref": "#/components/schemas/Sha256HashBase64" + } + } + }, + "content": { + "application/xml": { + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 21178 | Nie znaleziono UPO dla podanych kryteriów. | UPO o numerze KSeF {ksefNumber} i numerze referencyjnym sesji {referenceNumber} nie zostało znalezione. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 1200, + "perHour": 12000 + }, + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie UPO faktury z sesji na podstawie numeru referencyjnego faktury", + "description": "Zwraca UPO faktury przesłanego w sesji na podstawie jego numeru KSeF.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + }, + { + "name": "invoiceReferenceNumber", + "in": "path", + "description": "Numer referencyjny faktury.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "headers": { + "x-ms-meta-hash": { + "description": "Skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64", + "schema": { + "$ref": "#/components/schemas/Sha256HashBase64" + } + } + }, + "content": { + "application/xml": { + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 1200, + "perHour": 12000 + }, + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/{referenceNumber}/upo/{upoReferenceNumber}": { + "get": { + "tags": [ + "Status wysyłki i UPO" + ], + "summary": "Pobranie UPO dla sesji", + "description": "Zwraca XML zawierający zbiorcze UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + }, + { + "name": "upoReferenceNumber", + "in": "path", + "description": "Numer referencyjny UPO.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "headers": { + "x-ms-meta-hash": { + "description": "Skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64", + "schema": { + "$ref": "#/components/schemas/Sha256HashBase64" + } + } + }, + "content": { + "application/xml": { + "schema": { + "type": "string" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21178 | Nie znaleziono UPO dla podanych kryteriów. | UPO o numerze referencyjnym {referenceNumber} dla sesji {referenceNumber} nie zostało znalezione. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 1200, + "perHour": 12000 + }, + "x-required-permissions": [ + "InvoiceWrite", + "Introspection", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/tokens": { + "post": { + "tags": [ + "Tokeny KSeF" + ], + "summary": "Wygenerowanie nowego tokena", + "description": "Zwraca token, który może być użyty do uwierzytelniania się w KSeF.\n\nToken może być generowany tylko w kontekście NIP lub identyfikatora wewnętrznego. Jest zwracany tylko raz. Zaczyna być aktywny w momencie gdy jego status zmieni się na `Active`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "permissions", + "description" + ], + "allOf": [ + { + "$ref": "#/components/schemas/GenerateTokenRequest" + } + ] + }, + "example": { + "permissions": [ + "InvoiceRead", + "InvoiceWrite" + ], + "description": "Wystawianie i przeglądanie faktur." + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GenerateTokenResponse" + }, + "example": { + "referenceNumber": "20251010-EC-1DCE3E3000-12ECB5B36E-45", + "token": "20251010-EC-1DCE3E3000-12ECB5B36E-45|internalId-5265877635-12345|919f704466624ce29cd5ac7b65ded5e7cccc112eee314f2aaa76e02cd16df7b9" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 26001 | Nie można nadać tokenowi uprawnień których nie posiadasz. | Informacja o brakujących uprawnieniach. |\n| 26002 | Nie można wygenerować tokena dla obecnego typu kontekstu. | Informacja o aktualnym i dozwolonych typach kontekstu. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + }, + "get": { + "tags": [ + "Tokeny KSeF" + ], + "summary": "Pobranie listy wygenerowanych tokenów", + "description": "\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n", + "parameters": [ + { + "name": "status", + "in": "query", + "description": "Status tokenów do zwrócenia. W przypadku braku parametru zwracane są wszystkie tokeny. Parametr można przekazać wielokrotnie.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AuthenticationTokenStatus" + } + } + }, + { + "name": "description", + "in": "query", + "description": "Umożliwia filtrowanie tokenów po opisie. Wartość parametru jest wyszukiwana w opisie tokena (operacja nie rozróżnia wielkości liter). Należy podać co najmniej 3 znaki.", + "schema": { + "minLength": 3, + "type": "string" + } + }, + { + "name": "authorIdentifier", + "in": "query", + "description": "Umożliwia filtrowanie tokenów po ich twórcy. Wartość parametru jest wyszukiwana w identyfikatorze (operacja nie rozróżnia wielkości liter). Należy podać co najmniej 3 znaki.", + "schema": { + "minLength": 3, + "type": "string" + } + }, + { + "name": "authorIdentifierType", + "in": "query", + "description": "Umożliwia filtrowanie tokenów po ich twórcy. Wartość parametru określa typ identyfikatora w którym będzie wyszukiwany ciąg znaków przekazany w parametrze `authorIdentifier`.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/TokenAuthorIdentifierType" + } + ] + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + }, + { + "name": "x-continuation-token", + "in": "header", + "description": "Token służący do pobrania kolejnej strony wyników.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryTokensResponse" + }, + "example": { + "continuationToken": "W3sidG9rZW4iOiIrUklEOn4zeHd0QUlqZUc5VkhCQUFBQUFBQUJBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBZ2dBQUFBQUFCQUFBQUFBQUFBQUVBQUFBQUFBQUFBUUFBQUVBRWVFMllFPSIsInJhbmdlIjp7Im1pbiI6IjA1QzFERjIxOUY5OTIwIiwibWF4IjoiRkYifX1d", + "tokens": [ + { + "referenceNumber": "20251001-EC-2DD3AFF000-A6B7F19A95-11", + "authorIdentifier": { + "type": "Nip", + "value": "5265877635" + }, + "contextIdentifier": { + "type": "Nip", + "value": "5265877635" + }, + "description": "Wystawianie i przeglądanie faktur.", + "requestedPermissions": [ + "InvoiceRead", + "InvoiceWrite" + ], + "dateCreated": "2025-10-01T13:20:52.9919681+00:00", + "status": "Active", + "statusDetails": [ ] + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "dateCreated", + "direction": "Desc" + } + ] + } + }, + "/tokens/{referenceNumber}": { + "get": { + "tags": [ + "Tokeny KSeF" + ], + "summary": "Pobranie statusu tokena", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny tokena KSeF.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TokenStatusResponse" + }, + "example": { + "referenceNumber": "20251001-EC-220B0CE000-E228129563-96", + "authorIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "contextIdentifier": { + "type": "Nip", + "value": "5265877635" + }, + "description": "Wystawianie i przeglądanie faktur.", + "requestedPermissions": [ + "InvoiceWrite", + "InvoiceRead" + ], + "dateCreated": "2025-07-11T12:23:56.0154302+00:00", + "lastUseDate": "2025-07-11T12:23:56.0154302+00:00", + "status": "Pending", + "statusDetails": [ ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + }, + "delete": { + "tags": [ + "Tokeny KSeF" + ], + "summary": "Unieważnienie tokena", + "description": "Unieważniony token nie pozwoli już na uwierzytelnienie się za jego pomocą. Unieważnienie nie może zostać cofnięte.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny tokena KSeF.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + } + } + }, + "/peppol/query": { + "get": { + "tags": [ + "Usługi Peppol" + ], + "summary": "Pobranie listy dostawców usług Peppol", + "description": "Zwraca listę dostawców usług Peppol zarejestrowanych w systemie.\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n- id (Asc)\n\n", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryPeppolProvidersResponse" + }, + "example": { + "peppolProviders": [ + { + "id": "P123456789", + "name": "Dostawca usług Peppol", + "dateCreated": "2025-07-11T12:23:56.0154302+00:00" + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + }, + "x-sort": [ + { + "field": "dateCreated", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ] + } + }, + "/auth/challenge": { + "post": { + "tags": [ + "Uzyskiwanie dostępu" + ], + "summary": "Inicjalizacja uwierzytelnienia", + "description": "Generuje unikalny challenge wymagany w kolejnym kroku operacji uwierzytelnienia.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationChallengeResponse" + }, + "example": { + "challenge": "20250514-CR-226FB7B000-3ACF9BE4C0-10", + "timestamp": "2025-07-11T12:23:56.0154302+00:00", + "timestampMs": 1752236636015 + } + } + } + }, + "400": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/auth/xades-signature": { + "post": { + "tags": [ + "Uzyskiwanie dostępu" + ], + "summary": "Uwierzytelnienie z wykorzystaniem podpisu XAdES", + "description": "Rozpoczyna operację uwierzytelniania za pomocą dokumentu XML podpisanego podpisem elektronicznym XAdES.\n\n> Więcej informacji:\n> - [Przygotowanie dokumentu XML](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#1-przygotowanie-dokumentu-xml-authtokenrequest)\n> - [Podpis dokumentu XML](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#2-podpisanie-dokumentu-xades)\n> - [Schemat XSD](/docs/v2/schemas/authv2.xsd)", + "parameters": [ + { + "name": "verifyCertificateChain", + "in": "query", + "description": "Wymuszenie weryfikacji zaufania łańcucha certyfikatu wraz ze sprawdzeniem statusu certyfikatu (OCSP/CRL) na środowiskach które umożliwiają wykorzystanie samodzielnie wygenerowanych certyfikatów.", + "schema": { + "type": "boolean" + } + } + ], + "requestBody": { + "content": { + "application/xml": { + "schema": { + "type": "string" + }, + "example": "\n\n 20250625-CR-20F5EE4000-DA48AE4124-46\n \n 5265877635\n \n certificateSubject\n \n \n \n" + } + }, + "required": true + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationInitResponse" + }, + "example": { + "referenceNumber": "20250514-AU-2DFC46C000-3AC6D5877F-D4", + "authenticationToken": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiT3BlcmF0aW9uVG9rZW4iLCJvcGVyYXRpb24tcmVmZXJlbmNlLW51bWJlciI6IjIwMjUwNTE0LUFVLTJERkM0NkMwMDAtM0FDNkQ1ODc3Ri1ENCIsImV4cCI6MTc0NzIzMTcxOSwiaWF0IjoxNzQ3MjI5MDE5LCJpc3MiOiJrc2VmLWFwaS10aSIsImF1ZCI6ImtzZWYtYXBpLXRpIn0.rtRcV2mR9SiuJwpQaQHsbAXvvVsdNKG4DJsdiJctIeU", + "validUntil": "2025-07-11T12:23:56.0154302+00:00" + } + } + } + } + }, + "400": { + "description": " | ExceptionCode | ExceptionDescription | Details | \n|---------------------|---------------------------------------------------------------------|-------------------------------------------------------------|\n| 21001 | Nieczytelna treść. | |\n| 21111 | Nieprawidłowe wyzwanie autoryzacyjne. | |\n| 21115 | Nieprawidłowy certyfikat. | |\n| 21117 | Nieprawidłowy identyfikator podmiotu dla wskazanego typu kontekstu. | |\n| 21217 | Nieprawidłowe kodowanie znaków. | |\n| 21401 | Dokument nie jest zgodny ze schemą (xsd). | {treść błędu walidacji} |\n| 21406 | Konflikt podpisu i typu uwierzytelnienia. | |\n| 9101 | Nieprawidłowy dokument. | |\n| 9102 | Brak podpisu. | |\n| 9103 | Przekroczona liczba dozwolonych podpisów. | |\n| 9105 | Nieprawidłowy podpis. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/auth/ksef-token": { + "post": { + "tags": [ + "Uzyskiwanie dostępu" + ], + "summary": "Uwierzytelnienie z wykorzystaniem tokena KSeF", + "description": "Rozpoczyna operację uwierzytelniania z wykorzystaniem wcześniej wygenerowanego tokena KSeF.\n\nToken KSeF wraz z timestampem ze wcześniej wygenerowanego challenge'a (w formacie ```token|timestamp```) powinien zostać zaszyfrowany dedykowanym do tego celu kluczem publicznym.\n- Timestamp powinien zostać przekazany jako **liczba milisekund od 1 stycznia 1970 roku (Unix timestamp)**.\n- Algorytm szyfrowania: **RSA-OAEP (z użyciem SHA-256 jako funkcji skrótu)**.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "challenge", + "contextIdentifier", + "encryptedToken" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InitTokenAuthenticationRequest" + } + ] + }, + "example": { + "challenge": "20250625-CR-2FDC223000-C2BFC98A9C-4E", + "contextIdentifier": { + "type": "Nip", + "value": "5265877635" + }, + "encryptedToken": "..." + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationInitResponse" + }, + "example": { + "referenceNumber": "20250514-AU-2DFC46C000-3AC6D5877F-D4", + "authenticationToken": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiT3BlcmF0aW9uVG9rZW4iLCJvcGVyYXRpb24tcmVmZXJlbmNlLW51bWJlciI6IjIwMjUwNTE0LUFVLTJERkM0NkMwMDAtM0FDNkQ1ODc3Ri1ENCIsImV4cCI6MTc0NzIzMTcxOSwiaWF0IjoxNzQ3MjI5MDE5LCJpc3MiOiJrc2VmLWFwaS10aSIsImF1ZCI6ImtzZWYtYXBpLXRpIn0.rtRcV2mR9SiuJwpQaQHsbAXvvVsdNKG4DJsdiJctIeU", + "validUntil": "2025-07-11T12:23:56.0154302+00:00" + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|------------------------------------------------|-----------------------------------------------------------------------------|\n| 21111 | Nieprawidłowe wyzwanie autoryzacyjne. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + } + }, + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/auth/{referenceNumber}": { + "get": { + "tags": [ + "Uzyskiwanie dostępu" + ], + "summary": "Pobranie statusu uwierzytelniania", + "description": "Sprawdza bieżący status operacji uwierzytelniania dla podanego tokena.\n\nSposób uwierzytelnienia: `AuthenticationToken` otrzymany przy rozpoczęciu operacji uwierzytelniania.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny tokena otrzymanego przy inicjalizacji operacji uwierzytelniania.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationOperationStatusResponse" + }, + "examples": { + "Kod 100 | Uwierzytelnianie w toku": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 100, + "description": "Uwierzytelnianie w toku" + } + } + }, + "Kod 200 | Uwierzytelnianie zakończone sukcesem": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 200, + "description": "Uwierzytelnianie zakończone sukcesem" + } + } + }, + "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Nieważny certyfikat": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 400, + "description": "Uwierzytelnianie zakończone niepowodzeniem", + "details": [ + "Nieważny certyfikat." + ] + } + } + }, + "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Błąd weryfikacji łańcucha certyfikatów": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 400, + "description": "Uwierzytelnianie zakończone niepowodzeniem", + "details": [ + "Błąd weryfikacji łańcucha certyfikatów." + ] + } + } + }, + "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Niezaufany łańcuch certyfikatów": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 400, + "description": "Uwierzytelnianie zakończone niepowodzeniem", + "details": [ + "Niezaufany łańcuch certyfikatów." + ] + } + } + }, + "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Certyfikat odwołany": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 400, + "description": "Uwierzytelnianie zakończone niepowodzeniem", + "details": [ + "Certyfikat odwołany." + ] + } + } + }, + "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Niepoprawny certyfikat": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 400, + "description": "Uwierzytelnianie zakończone niepowodzeniem", + "details": [ + "Niepoprawny certyfikat." + ] + } + } + }, + "Kod 500 | Nieznany błąd": { + "value": { + "startDate": "0001-01-01T00:00:00+00:00", + "authenticationMethod": "Token", + "status": { + "code": 500, + "description": "Nieznany błąd ({statusCode})" + } + } + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|------------------------------------------------|-----------------------------------------------------------------------------|\n| 21304 | Brak uwierzytelnienia. | Operacja uwierzytelniania o numerze referencyjnym {referenceNumber} nie została znaleziona. |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/auth/token/redeem": { + "post": { + "tags": [ + "Uzyskiwanie dostępu" + ], + "summary": "Pobranie tokenów dostępowych", + "description": "Pobiera parę tokenów (access token i refresh token) wygenerowanych w ramach pozytywnie zakończonego procesu uwierzytelniania.\n**Tokeny można pobrać tylko raz.**\n\nSposób uwierzytelnienia: `AuthenticationToken` otrzymany przy rozpoczęciu operacji uwierzytelniania.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationTokensResponse" + }, + "example": { + "accessToken": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE", + "validUntil": "2025-07-11T12:23:56.0154302+00:00" + }, + "refreshToken": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE", + "validUntil": "2025-07-11T12:23:56.0154302+00:00" + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|------------------------------------------------|-----------------------------------------------------------------------------|\n| 21301 | Brak autoryzacji. | Tokeny dla operacji uwierzytelniania {referenceNumber} zostały już pobrane. |\n| 21301 | Brak autoryzacji. | Status uwierzytelniania ({operation.Status}) nie pozwala na pobranie tokenów. |\n| 21301 | Brak autoryzacji. | Token KSeF został unieważniony. |\n| 21304 | Brak uwierzytelnienia. | Operacja uwierzytelniania o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21308 | Próba wykorzystania metod autoryzacyjnych osoby zmarłej. | |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/auth/token/refresh": { + "post": { + "tags": [ + "Uzyskiwanie dostępu" + ], + "summary": "Odświeżenie tokena dostępowego", + "description": "Generuje nowy token dostępu na podstawie ważnego refresh tokena.\n\nSposób uwierzytelnienia: `RefreshToken`.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationTokenRefreshResponse" + }, + "example": { + "accessToken": { + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE", + "validUntil": "2025-07-11T12:23:56.0154302+00:00" + } + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-----------------------------------------------------------------------------|\n| 21301 | Brak autoryzacji. | Status uwierzytelniania ({operation.Status}) nie pozwala na odświeżenie tokenu dostępowego. |\n| 21301 | Brak autoryzacji. | Token KSeF został unieważniony. |\n| 21304 | Brak uwierzytelnienia. | Operacja uwierzytelniania o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21308 | Próba wykorzystania metod autoryzacyjnych osoby zmarłej. | |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 60 + } + } + }, + "/sessions/online": { + "post": { + "tags": [ + "Wysyłka interaktywna" + ], + "summary": "Otwarcie sesji interaktywnej", + "description": "Otwiera sesję do wysyłki pojedynczych faktur. Należy przekazać schemat wysyłanych faktur oraz informacje o kluczu używanym do szyfrowania.\n\n> Więcej informacji:\n> - [Otwarcie sesji interaktywnej](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md#1-otwarcie-sesji)\n> - [Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`, `EnforcementOperations`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "formCode", + "encryption" + ], + "allOf": [ + { + "$ref": "#/components/schemas/OpenOnlineSessionRequest" + } + ] + }, + "example": { + "formCode": { + "systemCode": "FA (3)", + "schemaVersion": "1-0E", + "value": "FA" + }, + "encryption": { + "encryptedSymmetricKey": "bdUVjqLj+y2q6aBUuLxxXYAMqeDuIBRTyr+hB96DaWKaGzuVHw9p+Nk9vhzgF/Q5cavK2k6eCh6SdsrWI0s9mFFj4A4UJtsyD8Dn3esLfUZ5A1juuG3q3SBi/XOC/+9W+0T/KdwdE393mbiUNyx1K/0bw31vKJL0COeJIDP7usAMDl42/H1TNvkjk+8iZ80V0qW7D+RZdz+tdiY1xV0f2mfgwJ46V0CpZ+sB9UAssRj+eVffavJ0TOg2b5JaBxE8MCAvrF6rO5K4KBjUmoy7PP7g1qIbm8xI2GO0KnfPOO5OWj8rsotRwBgu7x19Ine3qYUvuvCZlXRGGZ5NHIzWPM4O74+gNalaMgFCsmv8mMhETSU4SfAGmJr9edxPjQSbgD5i2X4eDRDMwvyaAa7CP1b2oICju+0L7Fywd2ZtUcr6El++eTVoi8HYsTArntET++gULT7XXjmb8e3O0nxrYiYsE9GMJ7HBGv3NOoJ1NTm3a7U6+c0ZJiBVLvn6xXw10LQX243xH+ehsKo6djQJKYtqcNPaXtCwM1c9RrsOx/wRXyWCtTffqLiaR0LbYvfMJAcEWceG+RaeAx4p37OiQqdJypd6LAv9/0ECWK8Bip8yyoA+0EYiAJb9YuDz2YlQX9Mx9E9FzFIAsgEQ2w723HZYWgPywLb+dlsum4lTZKQ=", + "initializationVector": "OmtDQdl6vkOI1GLKZSjgEg==" + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpenOnlineSessionResponse" + }, + "example": { + "referenceNumber": "20250625-SO-2C3E6C8000-B675CF5D68-07", + "validUntil": "2025-07-11T12:23:56.0154302+00:00" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | onlineSession\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "InvoiceWrite", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/online/{referenceNumber}/invoices": { + "post": { + "tags": [ + "Wysyłka interaktywna" + ], + "summary": "Wysłanie faktury", + "description": "Przyjmuje zaszyfrowaną fakturę oraz jej metadane i rozpoczyna jej przetwarzanie.\n\n> Więcej informacji:\n> - [Wysłanie faktury](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md#2-wys%C5%82anie-faktury)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "requestBody": { + "description": "Dane faktury", + "content": { + "application/json": { + "schema": { + "required": [ + "invoiceHash", + "invoiceSize", + "encryptedInvoiceHash", + "encryptedInvoiceSize", + "encryptedInvoiceContent" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SendInvoiceRequest" + } + ] + }, + "example": { + "invoiceHash": "EbrK4cOSjW4hEpJaHU71YXSOZZmqP5++dK9nLgTzgV4=", + "invoiceSize": 6480, + "encryptedInvoiceHash": "miYb1z3Ljw5VucTZslv3Tlt+V/EK1V8Q8evD8HMQ0dc=", + "encryptedInvoiceSize": 6496, + "encryptedInvoiceContent": "...", + "offlineMode": false + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendInvoiceResponse" + }, + "example": { + "referenceNumber": "20250625-EE-319D7EE000-B67F415CDC-2C" + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------|\n| 21155 | Przekroczono dozwoloną liczbę faktur w sesji. | Sesja o numerze referencyjnym {referenceNumber} osiągnęła dozwolony limit liczby faktur {invoiceLimit}. |\n| 21166 | Korekta techniczna niedostępna. | Faktura posiada już przetworzoną prawidłowo korektę techniczną. |\n| 21167 | Status faktury nie pozwala na korektę techniczną. | Nie można wysłać korekty technicznej do prawidłowo przetworzonej faktury. |\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została odnaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia wysyłkę faktur. |\n| 21402 | Nieprawidłowy rozmiar pliku. | Długość treści nie zgadza się z rozmiarem pliku. |\n| 21403 | Nieprawidłowy skrót pliku. | Skrót treści nie zgadza się ze skrótem pliku. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1800 | invoiceSend\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1800 + }, + "x-required-permissions": [ + "InvoiceWrite", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/online/{referenceNumber}/close": { + "post": { + "tags": [ + "Wysyłka interaktywna" + ], + "summary": "Zamknięcie sesji interaktywnej", + "description": "Zamyka sesję interaktywną i rozpoczyna generowanie zbiorczego UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została odnaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia jej zamknięcie. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | onlineSession\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-required-permissions": [ + "InvoiceWrite", + "PefInvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/batch": { + "post": { + "tags": [ + "Wysyłka wsadowa" + ], + "summary": "Otwarcie sesji wsadowej", + "description": "Otwiera sesję do wysyłki wsadowej faktur. Należy przekazać schemat wysyłanych faktur, informacje o paczce faktur oraz informacje o kluczu używanym do szyfrowania.\n\n> Więcej informacji:\n> - [Przygotowanie paczki faktur](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-wsadowa.md)\n> - [Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `EnforcementOperations`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "formCode", + "batchFile", + "encryption" + ], + "allOf": [ + { + "$ref": "#/components/schemas/OpenBatchSessionRequest" + } + ] + }, + "example": { + "formCode": { + "systemCode": "FA (2)", + "schemaVersion": "1-0E", + "value": "FA" + }, + "batchFile": { + "fileSize": 16037, + "fileHash": "WO86CC+1Lef11wEosItld/NPwxGN8tobOMLqk9PQjgs=", + "fileParts": [ + { + "ordinalNumber": 1, + "fileSize": 16048, + "fileHash": "23ZyDAN0H/+yhC/En2xbNfF0tajAWSfejDaXD7fc2AE=" + } + ] + }, + "encryption": { + "encryptedSymmetricKey": "bYqmPAglF01AxZim4oNa+1NerhZYfFgLMnvksBprUur1aesQ0Y5jsmOIfCrozfMkF2tjdO+uOsBg4FPlDgjChwN2/tz2Hqwtxq3RkTr1SjY4x8jxJFpPedcS7EI+XO8C+i9mLj7TFx9p/bg07yM9vHtMAk5b88Ay9Qc3+T5Ch1DM2ClR3sVu2DqdlKzmbINY+rhfGtXn58Qo0XRyESGgc6M0iTZVBRPuPXLnD8a1KpOneCpNzLwxgT6Ei3ivLOpPWT53PxkRTaQ8puj6CIiCKo4FHQzHuI/NmrAhYU7TkNm2kymP/OxBgWdg3XB74tqNFfT8RZN1bZXuPhBidDOqa+xsqY3E871FSDmQwZf58HmoNl31XNvpnryiRGfnAISt+m+ELqgksAresVu6E9poUL1yiff+IOHSZABoYpNiqwnbT8qyW1uk8lKLyFVFu+kOsbzBk1OWWHqSkNFDaznDa2MKjHonOXI0uyKaKWvoBFC4dWN1PVumfpSSFAeYgNpAyVrZdcVOuiliEWepTDjGzJoOafTvwr5za2S6B5bPECDpX7JXazV7Olkq7ezG0w8y3olx+0C+NHoCk8B5/cm4gtVHTgKjiLSGpKJVOJABLXFkOyIOjbQsVe4ryX0Qy+SfL7JIQvTWvM5xkCoOMbzLdMo9tNo5qE34sguFI+lIevY=", + "initializationVector": "jWpJLNBHJ5pQEGCBglmIAw==" + }, + "offlineMode": false + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpenBatchSessionResponse" + }, + "example": { + "referenceNumber": "20250626-SB-213D593000-4DE10D80A5-E9", + "partUploadRequests": [ + { + "ordinalNumber": 1, + "method": "PUT", + "url": "https://ksef-api-storage/storage/00/20250626-sb-213d593000-4de10d80a5-e9/batch-parts/1?skoid=1ad7cfe8-2cb2-406b-b96c-6eefb55794db&sktid=647754c7-3974-4442-a425-c61341b61c69&skt=2025-06-26T09%3A40%3A54Z&ske=2025-06-26T10%3A10%3A54Z&sks=b&skv=2025-01-05&sv=2025-01-05&se=2025-06-26T10%3A10%3A54Z&sr=b&sp=w&sig=8mKZEU8Reuz%2Fn7wHi4T%2FY8BzLeD5l8bR2xJsBxIgDEY%3D", + "headers": { + "x-ms-blob-type": "BlockBlob" + } + } + ] + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------------------|\n| 21157 | Nieprawidłowy rozmiar części pakietu. | {treść błędu walidacji} | \n| 21161 | Przekroczono dozwoloną liczbę części pakietu. | {treść błędu walidacji} |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 600 | batchSession\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 200, + "perHour": 600 + }, + "x-required-permissions": [ + "InvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/sessions/batch/{referenceNumber}/close": { + "post": { + "tags": [ + "Wysyłka wsadowa" + ], + "summary": "Zamknięcie sesji wsadowej", + "description": "Zamyka sesję wsadową, rozpoczyna procesowanie paczki faktur i generowanie UPO dla prawidłowych faktur oraz zbiorczego UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `EnforcementOperations`.", + "parameters": [ + { + "name": "referenceNumber", + "in": "path", + "description": "Numer referencyjny sesji", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReferenceNumber" + } + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------|\n| 21157 | Nieprawidłowy rozmiar części pakietu. | Zadeklarowany rozmiar części '{ordinalNumber}' nie zgadza się z rzeczywistym. | \n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia jej zamknięcie. |\n| 21205 | Pakiet nie może być pusty. | Nie przesłano zadeklarowanej '{ordinalNumber}' części pliku. | \n| 21208 | Czas oczekiwania na requesty upload lub finish został przekroczony. | Sesja anulowana, przekroczony czas wysyłki. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 600 | batchSession\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 200, + "perHour": 600 + }, + "x-required-permissions": [ + "InvoiceWrite", + "EnforcementOperations" + ] + } + }, + "/permissions/query/personal/grants": { + "post": { + "tags": [ + "Wyszukiwanie nadanych uprawnień" + ], + "summary": "Pobranie listy własnych uprawnień", + "description": " Metoda pozwala na odczytanie własnych uprawnień uwierzytelnionego klienta API w bieżącym kontekście logowania. \n\n W odpowiedzi przekazywane są następujące uprawnienia: \n - nadane w sposób bezpośredni w bieżącym kontekście \n - nadane przez podmiot nadrzędny \n - nadane w sposób pośredni, jeżeli podmiot kontekstu logowania jest w uprawnieniu pośrednikiem lub podmiotem docelowym \n - nadane podmiotowi do obsługi faktur przez inny podmiot, jeśli podmiot uwierzytelniony ma w bieżącym kontekście uprawnienia właścicielskie \n\n Uprawnienia zwracane przez operację obejmują: \n - **CredentialsManage** – zarządzanie uprawnieniami \n - **CredentialsRead** – przeglądanie uprawnień \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n - **SubunitManage** – zarządzanie podmiotami podrzędnymi \n - **EnforcementOperations** – wykonywanie operacji egzekucyjnych \n - **VatEuManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **contextIdentifier** – identyfikator podmiotu, który nadał uprawnienie do obsługi faktur \n - **targetIdentifier** – identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n - **permissionState** – status uprawnienia \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-w%C5%82asnych-uprawnie%C5%84)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsQueryRequest" + } + ] + }, + "example": { + "contextIdentifier": { + "type": "Nip", + "value": "3568707925" + }, + "permissionTypes": [ + "InvoiceWrite" + ], + "permissionState": "Active" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryPersonalPermissionsResponse" + }, + "example": { + "permissions": [ + { + "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", + "contextIdentifier": { + "type": "Nip", + "value": "3568707925" + }, + "authorizedIdentifier": { + "type": "Nip", + "value": "5247677742" + }, + "permissionScope": "InvoiceWrite", + "description": "Opis uprawnienia", + "permissionState": "Active", + "startDate": "2025-06-22T10:41:11+00:00", + "canDelegate": false + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ] + } + }, + "/permissions/query/persons/grants": { + "post": { + "tags": [ + "Wyszukiwanie nadanych uprawnień" + ], + "summary": "Pobranie listy uprawnień do pracy w KSeF nadanych osobom fizycznym lub podmiotom", + "description": " Metoda pozwala na odczytanie uprawnień nadanych osobie fizycznej lub podmiotowi. \n Lista pobranych uprawnień może być dwóch rodzajów: \n - Lista wszystkich uprawnień obowiązujących w bieżącym kontekście logowania (używana, gdy administrator chce przejrzeć uprawnienia wszystkich użytkowników w bieżącym kontekście) \n - Lista wszystkich uprawnień nadanych w bieżącym kontekście przez uwierzytelnionego klienta API (używana, gdy administrator chce przejrzeć listę nadanych przez siebie uprawnień w bieżącym kontekście) \n\n Dla pierwszej listy (obowiązujących uprawnień) w odpowiedzi przekazywane są: \n - osoby i podmioty mogące pracować w bieżącym kontekście z wyjątkiem osób uprawnionych w sposób pośredni \n - osoby uprawnione w sposób pośredni przez podmiot bieżącego kontekstu \n\n Dla drugiej listy (nadanych uprawnień) w odpowiedzi przekazywane są: \n - uprawnienia nadane w sposób bezpośredni do pracy w bieżącym kontekście lub w kontekście jednostek podrzędnych \n - uprawnienia nadane w sposób pośredni do obsługi klientów podmiotu bieżącego kontekstu \n\n Uprawnienia zwracane przez operację obejmują: \n - **CredentialsManage** – zarządzanie uprawnieniami \n - **CredentialsRead** – przeglądanie uprawnień \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n - **SubunitManage** – zarządzanie podmiotami podrzędnymi \n - **EnforcementOperations** – wykonywanie operacji egzekucyjnych \n\n Odpowiedź może być filtrowana na podstawie parametrów: \n - **authorIdentifier** – identyfikator osoby, która nadała uprawnienie \n - **authorizedIdentifier** – identyfikator osoby lub podmiotu uprawnionego \n - **targetIdentifier** – identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n - **permissionState** – status uprawnienia \n - **queryType** – typ zapytania określający, która z dwóch list ma zostać zwrócona \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-do-pracy-w-ksef-nadanych-osobom-fizycznym-lub-podmiotom)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "queryType" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsQueryRequest" + } + ] + }, + "example": { + "authorIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "permissionTypes": [ + "CredentialsManage", + "CredentialsRead", + "InvoiceWrite" + ], + "permissionState": "Active", + "queryType": "PermissionsInCurrentContext" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryPersonPermissionsResponse" + }, + "example": { + "permissions": [ + { + "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", + "authorizedIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "targetIdentifier": { + "type": "Nip", + "value": "9786214922" + }, + "authorIdentifier": { + "type": "Pesel", + "value": "15062788702" + }, + "permissionScope": "InvoiceWrite", + "description": "praca dla klienta 9786214922; uprawniony NIP: 7762811692, Adam Abacki; pośrednik 3936518395", + "permissionState": "Active", + "startDate": "2025-06-22T10:41:11+00:00", + "canDelegate": false + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ], + "x-required-permissions": [ + "CredentialsManage", + "CredentialsRead", + "SubunitManage" + ] + } + }, + "/permissions/query/subunits/grants": { + "post": { + "tags": [ + "Wyszukiwanie nadanych uprawnień" + ], + "summary": "Pobranie listy uprawnień administratorów jednostek i podmiotów podrzędnych", + "description": " Metoda pozwala na odczytanie uprawnień do zarządzania uprawnieniami nadanych administratorom: \n - jednostek podrzędnych identyfikowanych identyfikatorem wewnętrznym \n - podmiotów podrzędnych (podrzędnych JST lub członków grupy VAT) identyfikowanych przez NIP \n\n Lista zwraca wyłącznie uprawnienia do zarządzania uprawnieniami nadane z kontekstu bieżącego (z podmiotu nadrzędnego). \n Nie są odczytywane uprawnienia nadane przez administratorów jednostek podrzędnych wewnątrz tych jednostek. \n\n Odpowiedź może być filtrowana na podstawie parametru: \n - **subunitIdentifier** – identyfikator jednostki lub podmiotu podrzędnego \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-administrator%C3%B3w-jednostek-i-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsQueryRequest" + } + ] + }, + "example": { + "subunitIdentifier": { + "type": "InternalId", + "value": "7762811692-12345" + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QuerySubunitPermissionsResponse" + }, + "example": { + "permissions": [ + { + "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", + "authorizedIdentifier": { + "type": "Fingerprint", + "value": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59" + }, + "subunitIdentifier": { + "type": "InternalId", + "value": "7762811692-12345" + }, + "authorIdentifier": { + "type": "Pesel", + "value": "15062788702" + }, + "permissionScope": "CredentialsManage", + "description": "Opis uprawnienia", + "startDate": "2025-06-22T10:41:11+00:00" + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ], + "x-required-permissions": [ + "CredentialsManage", + "CredentialsRead", + "SubunitManage" + ] + } + }, + "/permissions/query/entities/roles": { + "get": { + "tags": [ + "Wyszukiwanie nadanych uprawnień" + ], + "summary": "Pobranie listy ról podmiotu", + "description": " Metoda pozwala na **odczytanie listy ról podmiotu bieżącego kontekstu logowania**.\n\n#### Role podmiotów zwracane przez operację:\n- **CourtBailiff** – komornik sądowy \n- **EnforcementAuthority** – organ egzekucyjny \n- **LocalGovernmentUnit** – nadrzędna JST \n- **LocalGovernmentSubUnit** – podrzędne JST \n- **VatGroupUnit** – grupa VAT \n- **VatGroupSubUnit** – członek grupy VAT\n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy ról](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-r%C3%B3l-podmiotu)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryEntityRolesResponse" + }, + "example": { + "roles": [ + { + "role": "EnforcementAuthority", + "description": "Organ egzekucyjny", + "startDate": "2025-06-22T10:41:11+00:00" + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ], + "x-required-permissions": [ + "CredentialsManage", + "CredentialsRead" + ] + } + }, + "/permissions/query/subordinate-entities/roles": { + "post": { + "tags": [ + "Wyszukiwanie nadanych uprawnień" + ], + "summary": "Pobranie listy podmiotów podrzędnych", + "description": " Metoda pozwala na odczytanie listy podmiotów podrzędnych, \n jeżeli podmiot bieżącego kontekstu ma rolę podmiotu nadrzędnego:\n - **nadrzędna JST** – odczytywane są podrzędne JST, \n - **grupa VAT** – odczytywane są podmioty będące członkami grupy VAT.\n\n Role podmiotów zwracane przez operację obejmują: \n - **LocalGovernmentSubUnit** – podrzędne JST, \n - **VatGroupSubUnit** – członek grupy VAT.\n\n Odpowiedź może być filtrowana według parametru: \n - **subordinateEntityIdentifier** – identyfikator podmiotu podrzędnego.\n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy podmiotów podrzędnych](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SubordinateEntityRolesQueryRequest" + } + ] + }, + "example": { + "subordinateEntityIdentifier": { + "type": "Nip", + "value": "7762811692" + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QuerySubordinateEntityRolesResponse" + }, + "example": { + "roles": [ + { + "subordinateEntityIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "role": "VatGroupSubUnit", + "description": "Członek grupy VAT 8373740478", + "startDate": "2025-06-22T10:41:11+00:00" + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ], + "x-required-permissions": [ + "CredentialsManage", + "CredentialsRead", + "SubunitManage" + ] + } + }, + "/permissions/query/authorizations/grants": { + "post": { + "tags": [ + "Wyszukiwanie nadanych uprawnień" + ], + "summary": "Pobranie listy uprawnień podmiotowych do obsługi faktur", + "description": " Metoda pozwala na odczytanie uprawnień podmiotowych: \n - otrzymanych przez podmiot bieżącego kontekstu \n - nadanych przez podmiot bieżącego kontekstu \n\n Wybór listy nadanych lub otrzymanych uprawnień odbywa się przy użyciu parametru **queryType**. \n\n Uprawnienia zwracane przez operację obejmują: \n - **SelfInvoicing** – wystawianie faktur w trybie samofakturowania \n - **TaxRepresentative** – wykonywanie operacji przedstawiciela podatkowego \n - **RRInvoicing** – wystawianie faktur VAT RR \n - **PefInvoicing** – wystawianie faktur PEF \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **authorizingIdentifier** – identyfikator podmiotu uprawniającego (stosowane przy queryType = Received) \n - **authorizedIdentifier** – identyfikator podmiotu uprawnionego (stosowane przy queryType = Granted) \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-podmiotowych-do-obs%C5%82ugi-faktur)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `PefInvoiceWrite`.", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "queryType" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationPermissionsQueryRequest" + } + ] + }, + "example": { + "authorizedIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "queryType": "Granted", + "permissionTypes": [ + "SelfInvoicing", + "TaxRepresentative", + "RRInvoicing" + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryEntityAuthorizationPermissionsResponse" + }, + "example": { + "authorizationGrants": [ + { + "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", + "authorIdentifier": { + "type": "Pesel", + "value": "15062788702" + }, + "authorizedEntityIdentifier": { + "type": "Nip", + "value": "7762811692" + }, + "authorizingEntityIdentifier": { + "type": "Nip", + "value": "1134256681" + }, + "authorizationScope": "SelfInvoicing", + "description": "Uprawnienie podmiotowe do samofakturowania", + "startDate": "2025-06-22T10:41:11+00:00" + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ], + "x-required-permissions": [ + "CredentialsManage", + "CredentialsRead", + "PefInvoiceWrite" + ] + } + }, + "/permissions/query/eu-entities/grants": { + "post": { + "tags": [ + "Wyszukiwanie nadanych uprawnień" + ], + "summary": "Pobranie listy uprawnień administratorów lub reprezentantów podmiotów unijnych uprawnionych do samofakturowania", + "description": " Metoda pozwala na odczytanie uprawnień administratorów lub reprezentantów podmiotów unijnych: \n - Jeżeli kontekstem logowania jest NIP, możliwe jest odczytanie uprawnień administratorów podmiotów unijnych powiązanych z podmiotem bieżącego kontekstu, czyli takich, dla których pierwszy człon kontekstu złożonego jest równy NIP-owi kontekstu logowania. \n - Jeżeli kontekst logowania jest złożony (NIP-VAT UE), możliwe jest pobranie wszystkich uprawnień administratorów i reprezentantów podmiotu w bieżącym kontekście złożonym. \n\n Uprawnienia zwracane przez operację obejmują: \n - **VatUeManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **vatUeIdentifier** – identyfikator podmiotu unijnego \n - **authorizedFingerprintIdentifier** – odcisk palca certyfikatu uprawnionej osoby lub podmiotu \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-administrator%C3%B3w-lub-reprezentant%C3%B3w-podmiot%C3%B3w-unijnych-uprawnionych-do-samofakturowania)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `VatUeManage`.", + "parameters": [ + { + "name": "pageOffset", + "in": "query", + "description": "Numer strony wyników.", + "schema": { + "minimum": 0, + "type": "integer", + "format": "int32", + "default": 0 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Rozmiar strony wyników.", + "schema": { + "maximum": 100, + "minimum": 10, + "type": "integer", + "format": "int32", + "default": 10 + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionsQueryRequest" + } + ] + }, + "example": { + "vatUeIdentifier": "DE123456789012", + "permissionTypes": [ + "VatUeManage", + "Introspection" + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryEuEntityPermissionsResponse" + }, + "example": { + "permissions": [ + { + "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", + "authorIdentifier": { + "type": "Pesel", + "value": "15062788702" + }, + "vatUeIdentifier": "DE123456789012", + "euEntityName": "Podmiot unijny", + "authorizedFingerprintIdentifier": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59", + "permissionScope": "VatUeManage", + "description": "Opis uprawnienia", + "startDate": "2025-06-22T10:41:11+00:00" + } + ], + "hasMore": false + } + } + } + }, + "400": { + "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExceptionResponse" + } + } + }, + "x-summary": "Bad Request" + }, + "429": { + "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", + "headers": { + "Retry-After": { + "schema": { + "$ref": "#/components/schemas/RetryAfter" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsResponse" + } + } + }, + "x-summary": "Too Many Requests" + }, + "403": { + "description": "Forbidden" + }, + "401": { + "description": "Unauthorized" + } + }, + "security": [ + { + "Bearer": [ ] + } + ], + "x-rate-limits": { + "perSecond": 100, + "perMinute": 300, + "perHour": 1200 + }, + "x-sort": [ + { + "field": "startDate", + "direction": "Desc" + }, + { + "field": "id", + "direction": "Asc" + } + ], + "x-required-permissions": [ + "CredentialsManage", + "CredentialsRead", + "VatUeManage" + ] + } + } + }, + "components": { + "schemas": { + "AllowedIps": { + "type": "object", + "properties": { + "ip4Addresses": { + "type": "array", + "items": { + "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$", + "type": "string" + }, + "description": "Lista adresów IPv4 w notacji dziesiętnej kropkowanej, np. `192.168.0.10`.", + "nullable": true + }, + "ip4Ranges": { + "type": "array", + "items": { + "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}-((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$", + "type": "string" + }, + "description": "Lista adresów IPv4 podana w formie zakresu początek–koniec, oddzielonego pojedynczym myślnikiem, np. `10.0.0.1–10.0.0.254`.", + "nullable": true + }, + "ip4Masks": { + "type": "array", + "items": { + "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}\\/(0|[1-9]|1[0-9]|2[0-9]|3[0-2])$", + "type": "string" + }, + "description": "Lista adresów IPv4 w notacji CIDR, np. `172.16.0.0/16`.", + "nullable": true + } + }, + "additionalProperties": false + }, + "AmountType": { + "enum": [ + "Brutto", + "Netto", + "Vat" + ], + "type": "string" + }, + "ApiRateLimitValuesOverride": { + "required": [ + "perHour", + "perMinute", + "perSecond" + ], + "type": "object", + "properties": { + "perSecond": { + "type": "integer", + "description": "Limit na sekundę.", + "format": "int32" + }, + "perMinute": { + "type": "integer", + "description": "Limit na minutę.", + "format": "int32" + }, + "perHour": { + "type": "integer", + "description": "Limit na godzinę.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "ApiRateLimitsOverride": { + "required": [ + "batchSession", + "invoiceDownload", + "invoiceExport", + "invoiceExportStatus", + "invoiceMetadata", + "invoiceSend", + "invoiceStatus", + "onlineSession", + "other", + "sessionInvoiceList", + "sessionList", + "sessionMisc" + ], + "type": "object", + "properties": { + "onlineSession": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla otwierania/zamykania sesji interaktywnych." + }, + "batchSession": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla otwierania/zamykania sesji wsadowych." + }, + "invoiceSend": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla wysyłki faktur." + }, + "invoiceStatus": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pobierania statusu faktury z sesji." + }, + "sessionList": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pobierania listy sesji." + }, + "sessionInvoiceList": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pobierania listy faktur w sesji." + }, + "sessionMisc": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pozostałych operacji w ramach sesji." + }, + "invoiceMetadata": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pobierania metadanych faktur." + }, + "invoiceExport": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla eksportu paczki faktur." + }, + "invoiceExportStatus": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pobierania statusu eksportu paczki faktur." + }, + "invoiceDownload": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pobierania faktur po numerze KSeF." + }, + "other": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitValuesOverride" + } + ], + "description": "Limity dla pozostałych operacji API." + } + }, + "additionalProperties": false + }, + "AttachmentPermissionGrantRequest": { + "required": [ + "nip" + ], + "type": "object", + "properties": { + "nip": { + "$ref": "#/components/schemas/Nip" + } + }, + "additionalProperties": false + }, + "AttachmentPermissionRevokeRequest": { + "required": [ + "nip" + ], + "type": "object", + "properties": { + "nip": { + "$ref": "#/components/schemas/Nip" + }, + "expectedEndDate": { + "type": "string", + "description": "Data wycofania zgody na przesyłanie faktur z załącznikiem.", + "format": "date", + "nullable": true + } + }, + "additionalProperties": false + }, + "AuthenticationChallengeResponse": { + "required": [ + "challenge", + "timestamp", + "timestampMs" + ], + "type": "object", + "properties": { + "challenge": { + "$ref": "#/components/schemas/Challenge" + }, + "timestamp": { + "type": "string", + "description": "Czas wygenerowania challenge-a.", + "format": "date-time" + }, + "timestampMs": { + "type": "integer", + "description": "Czas wygenerowania challenge-a w milisekundach od 1 stycznia 1970 roku (Unix timestamp).", + "format": "int64" + } + }, + "additionalProperties": false + }, + "AuthenticationContextIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/AuthenticationContextIdentifierType" + } + ], + "description": "Typ identyfikatora" + }, + "value": { + "type": "string", + "description": "Wartość identyfikatora" + } + }, + "additionalProperties": false + }, + "AuthenticationContextIdentifierType": { + "enum": [ + "Nip", + "InternalId", + "NipVatUe", + "PeppolId" + ], + "type": "string" + }, + "AuthenticationInitResponse": { + "required": [ + "authenticationToken", + "referenceNumber" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny sesji uwierzytelnienia." + }, + "authenticationToken": { + "required": [ + "token", + "validUntil" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenInfo" + } + ], + "description": "Token operacji uwierzytelnienia." + } + }, + "additionalProperties": false + }, + "AuthenticationListItem": { + "required": [ + "authenticationMethod", + "referenceNumber", + "startDate", + "status" + ], + "type": "object", + "properties": { + "startDate": { + "type": "string", + "description": "Data rozpoczęcia operacji uwierzytelnienia.", + "format": "date-time" + }, + "authenticationMethod": { + "allOf": [ + { + "$ref": "#/components/schemas/AuthenticationMethod" + } + ], + "description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy usług Peppol. |\n" + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/StatusInfo" + } + ], + "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Uwierzytelnianie w toku | - |\n| 200 | Uwierzytelnianie zakończone sukcesem | - |\n| 415 | Uwierzytelnianie zakończone niepowodzeniem | Brak przypisanych uprawnień |\n| 425 | Uwierzytelnienie unieważnione | Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe wyzwanie autoryzacyjne |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy token |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy czas tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token unieważniony |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nieaktywny |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Nieważny certyfikat |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Błąd weryfikacji łańcucha certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niezaufany łańcuch certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Certyfikat odwołany |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niepoprawny certyfikat |\n| 470 | Uwierzytelnianie zakończone niepowodzeniem | Próba wykorzystania metod autoryzacyjnych osoby zmarłej |\n| 480 | Uwierzytelnienie zablokowane | Podejrzenie incydentu bezpieczeństwa. Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy. |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" + }, + "isTokenRedeemed": { + "type": "boolean", + "description": "Czy został już wydany refresh token powiązany z danym uwierzytelnieniem.", + "nullable": true + }, + "lastTokenRefreshDate": { + "type": "string", + "description": "Data ostatniego odświeżenia tokena.", + "format": "date-time", + "nullable": true + }, + "refreshTokenValidUntil": { + "type": "string", + "description": "Termin ważności refresh tokena (o ile nie zostanie wcześniej unieważniony).", + "format": "date-time", + "nullable": true + }, + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny sesji uwierzytelnienia." + }, + "isCurrent": { + "type": "boolean", + "description": "Czy sesja jest powiązana z aktualnie używanym tokenem.", + "readOnly": true + } + }, + "additionalProperties": false + }, + "AuthenticationListResponse": { + "required": [ + "items" + ], + "type": "object", + "properties": { + "continuationToken": { + "type": "string", + "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", + "nullable": true + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AuthenticationListItem" + }, + "description": "Lista sesji uwierzytelniania." + } + }, + "additionalProperties": false + }, + "AuthenticationMethod": { + "enum": [ + "Token", + "TrustedProfile", + "InternalCertificate", + "QualifiedSignature", + "QualifiedSeal", + "PersonalSignature", + "PeppolSignature" + ], + "type": "string", + "description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy usług Peppol. |\n" + }, + "AuthenticationOperationStatusResponse": { + "required": [ + "authenticationMethod", + "startDate", + "status" + ], + "type": "object", + "properties": { + "startDate": { + "type": "string", + "description": "Data rozpoczęcia operacji uwierzytelnienia.", + "format": "date-time" + }, + "authenticationMethod": { + "allOf": [ + { + "$ref": "#/components/schemas/AuthenticationMethod" + } + ], + "description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy usług Peppol. |\n" + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/StatusInfo" + } + ], + "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Uwierzytelnianie w toku | - |\n| 200 | Uwierzytelnianie zakończone sukcesem | - |\n| 415 | Uwierzytelnianie zakończone niepowodzeniem | Brak przypisanych uprawnień |\n| 425 | Uwierzytelnienie unieważnione | Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe wyzwanie autoryzacyjne |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy token |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy czas tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token unieważniony |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nieaktywny |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Nieważny certyfikat |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Błąd weryfikacji łańcucha certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niezaufany łańcuch certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Certyfikat odwołany |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niepoprawny certyfikat |\n| 470 | Uwierzytelnianie zakończone niepowodzeniem | Próba wykorzystania metod autoryzacyjnych osoby zmarłej |\n| 480 | Uwierzytelnienie zablokowane | Podejrzenie incydentu bezpieczeństwa. Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy. |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" + }, + "isTokenRedeemed": { + "type": "boolean", + "description": "Czy został już wydany refresh token powiązany z danym uwierzytelnieniem.", + "nullable": true + }, + "lastTokenRefreshDate": { + "type": "string", + "description": "Data ostatniego odświeżenia tokena.", + "format": "date-time", + "nullable": true + }, + "refreshTokenValidUntil": { + "type": "string", + "description": "Termin ważności refresh tokena (o ile nie zostanie wcześniej unieważniony).", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "AuthenticationTokenRefreshResponse": { + "required": [ + "accessToken" + ], + "type": "object", + "properties": { + "accessToken": { + "required": [ + "token", + "validUntil" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenInfo" + } + ], + "description": "Token dostępu, którego należy używać w wywołaniach chronionych zasobów API." + } + }, + "additionalProperties": false + }, + "AuthenticationTokenStatus": { + "enum": [ + "Pending", + "Active", + "Revoking", + "Revoked", + "Failed" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n" + }, + "AuthenticationTokensResponse": { + "required": [ + "accessToken", + "refreshToken" + ], + "type": "object", + "properties": { + "accessToken": { + "required": [ + "token", + "validUntil" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenInfo" + } + ], + "description": "Token dostępu." + }, + "refreshToken": { + "required": [ + "token", + "validUntil" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenInfo" + } + ], + "description": "Token umożliwiający odświeżenie tokenu dostępu.\n> Więcej informacji:\n> - [Odświeżanie tokena](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#5-od%C5%9Bwie%C5%BCenie-tokena-dost%C4%99powego-accesstoken)" + } + }, + "additionalProperties": false + }, + "AuthorizationPolicy": { + "type": "object", + "properties": { + "allowedIps": { + "allOf": [ + { + "$ref": "#/components/schemas/AllowedIps" + } + ], + "description": "Lista dozwolonych adresów IP.", + "nullable": true + } + }, + "additionalProperties": false + }, + "BatchFileInfo": { + "required": [ + "fileHash", + "fileParts", + "fileSize" + ], + "type": "object", + "properties": { + "fileSize": { + "maximum": 5000000000, + "minimum": 1, + "type": "integer", + "description": "Rozmiar pliku paczki w bajtach. Maksymalny rozmiar paczki to 5GB.", + "format": "int64" + }, + "fileHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 pliku paczki, zakodowany w formacie Base64." + }, + "fileParts": { + "maxItems": 50, + "minItems": 1, + "type": "array", + "items": { + "$ref": "#/components/schemas/BatchFilePartInfo" + }, + "description": "Informacje o częściach pliku paczki. Maksymalna liczba części to 50. Maksymalny dozwolony rozmiar części przed zaszyfrowaniem to 100MB." + } + }, + "additionalProperties": false + }, + "BatchFilePartInfo": { + "required": [ + "fileHash", + "fileSize", + "ordinalNumber" + ], + "type": "object", + "properties": { + "ordinalNumber": { + "minimum": 1, + "type": "integer", + "description": "Numer sekwencyjny części pliku paczki.", + "format": "int32" + }, + "fileSize": { + "minimum": 1, + "type": "integer", + "description": "Rozmiar zaszyfrowanej części pliku paczki w bajtach.", + "format": "int64" + }, + "fileHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 zaszyfrowanej części pliku paczki, zakodowany w formacie Base64." + } + }, + "additionalProperties": false + }, + "BatchSessionContextLimitsOverride": { + "required": [ + "maxInvoices", + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB" + ], + "type": "object", + "properties": { + "maxInvoiceSizeInMB": { + "maximum": 5, + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury w MB.", + "format": "int32" + }, + "maxInvoiceWithAttachmentSizeInMB": { + "maximum": 10, + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", + "format": "int32" + }, + "maxInvoices": { + "maximum": 100000, + "minimum": 0, + "type": "integer", + "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "BatchSessionEffectiveContextLimits": { + "required": [ + "maxInvoices", + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB" + ], + "type": "object", + "properties": { + "maxInvoiceSizeInMB": { + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury w MB.", + "format": "int32" + }, + "maxInvoiceWithAttachmentSizeInMB": { + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", + "format": "int32" + }, + "maxInvoices": { + "minimum": 0, + "type": "integer", + "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "BuyerIdentifierType": { + "enum": [ + "Nip", + "VatUe", + "Other", + "None" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora nabywcy |\n" + }, + "CertificateEffectiveSubjectLimits": { + "type": "object", + "properties": { + "maxCertificates": { + "type": "integer", + "format": "int32" + } + }, + "additionalProperties": false + }, + "CertificateEnrollmentDataResponse": { + "required": [ + "commonName", + "countryName" + ], + "type": "object", + "properties": { + "commonName": { + "type": "string", + "description": "Nazwa powszechna." + }, + "countryName": { + "type": "string", + "description": "Kraj, kod ISO 3166." + }, + "givenName": { + "type": "string", + "description": "Imię.", + "nullable": true + }, + "surname": { + "type": "string", + "description": "Nazwisko.", + "nullable": true + }, + "serialNumber": { + "type": "string", + "description": "Numer seryjny podmiotu.", + "nullable": true + }, + "uniqueIdentifier": { + "type": "string", + "description": "Unikalny identyfikator.", + "nullable": true + }, + "organizationName": { + "type": "string", + "description": "Nazwa organizacji.", + "nullable": true + }, + "organizationIdentifier": { + "type": "string", + "description": "Identyfikator organizacji.", + "nullable": true + } + }, + "additionalProperties": false + }, + "CertificateEnrollmentStatusResponse": { + "required": [ + "requestDate", + "status" + ], + "type": "object", + "properties": { + "requestDate": { + "type": "string", + "description": "Data złożenia wniosku certyfikacyjnego.", + "format": "date-time" + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/StatusInfo" + } + ], + "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Wniosek przyjęty do realizacji | - |\n| 200 | Wniosek obsłużony (certyfikat wygenerowany) | - |\n| 400 | Wniosek odrzucony | Klucz publiczny został już certyfikowany przez inny podmiot. |\n| 400 | Wniosek odrzucony | Osiągnięto dopuszczalny limit posiadanych certyfikatów. |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" + }, + "certificateSerialNumber": { + "type": "string", + "description": "Numer seryjny wygenerowanego certyfikatu (w formacie szesnastkowym). \nZwracany w przypadku prawidłowego przeprocesowania wniosku certyfikacyjnego.", + "nullable": true + } + }, + "additionalProperties": false + }, + "CertificateLimit": { + "required": [ + "limit", + "remaining" + ], + "type": "object", + "properties": { + "remaining": { + "type": "integer", + "description": "Pozostała wartość limitu.", + "format": "int32" + }, + "limit": { + "type": "integer", + "description": "Maksymalna liczba zasobów dozwolona w ramach limitu.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "CertificateLimitsResponse": { + "required": [ + "canRequest", + "certificate", + "enrollment" + ], + "type": "object", + "properties": { + "canRequest": { + "type": "boolean", + "description": "Flaga informująca czy uwierzytelniony podmiot może złożyć nowy wniosek o certyfikat.", + "readOnly": true + }, + "enrollment": { + "required": [ + "remaining", + "limit" + ], + "allOf": [ + { + "$ref": "#/components/schemas/CertificateLimit" + } + ], + "description": "Informacje o limitach związanych z liczbą możliwych do złożenia wniosków certyfikacyjnych." + }, + "certificate": { + "required": [ + "remaining", + "limit" + ], + "allOf": [ + { + "$ref": "#/components/schemas/CertificateLimit" + } + ], + "description": "Informacje o limitach dotyczących liczby aktywnych certyfikatów wydanych dla danego podmiotu." + } + }, + "additionalProperties": false, + "description": "Informacje o limitach wniosków oraz certyfikatów dla uwierzytelnionego podmiotu." + }, + "CertificateListItem": { + "required": [ + "certificateSerialNumber", + "commonName", + "name", + "requestDate", + "status", + "subjectIdentifier", + "type", + "validFrom", + "validTo" + ], + "type": "object", + "properties": { + "certificateSerialNumber": { + "type": "string", + "description": "Numer seryjny certyfikatu (w formacie szesnastkowym)." + }, + "name": { + "maxLength": 100, + "type": "string", + "description": "Nazwa własna certyfikatu." + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/KsefCertificateType" + } + ], + "description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" + }, + "commonName": { + "type": "string", + "description": "Nazwa powszechna (CN) podmiotu, dla którego wystawiono certyfikat." + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/CertificateListItemStatus" + } + ], + "description": "Status certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n" + }, + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/CertificateSubjectIdentifier" + } + ], + "description": "Identyfikator podmiotu, dla którego wystawiono certyfikat." + }, + "validFrom": { + "type": "string", + "description": "Data rozpoczęcia ważności certyfikatu.", + "format": "date-time" + }, + "validTo": { + "type": "string", + "description": "Data wygaśnięcia certyfikatu.", + "format": "date-time" + }, + "lastUseDate": { + "type": "string", + "description": "Data ostatniego użycia certyfikatu.", + "format": "date-time", + "nullable": true + }, + "requestDate": { + "type": "string", + "description": "Data złożenia wniosku certyfikacyjnego.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "CertificateListItemStatus": { + "enum": [ + "Active", + "Blocked", + "Revoked", + "Expired" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n" + }, + "CertificateRevocationReason": { + "enum": [ + "Unspecified", + "Superseded", + "KeyCompromise" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Unspecified | Nieokreślony. |\n| Superseded | Certyfikat został zastąpiony przez inny. |\n| KeyCompromise | Klucz prywatny powiązany z certyfikatem został skompromitowany. |\n" + }, + "CertificateSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/CertificateSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu dla którego wystawiono certyfikat.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "CertificateSubjectIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "CertificateSubjectLimitsOverride": { + "type": "object", + "properties": { + "maxCertificates": { + "minimum": 0, + "type": "integer", + "format": "int32", + "nullable": true + } + }, + "additionalProperties": false + }, + "Challenge": { + "maxLength": 36, + "minLength": 36, + "type": "string", + "description": "Unikalny challenge." + }, + "CheckAttachmentPermissionStatusResponse": { + "type": "object", + "properties": { + "isAttachmentAllowed": { + "type": "boolean", + "description": "Informacja czy Podmiot ma obecnie możliwość dodawania Załączników do Faktur" + }, + "revokedDate": { + "type": "string", + "description": "Data i czas zakończenia możliwość dodawania przez Podmiot Załączników do Faktur.\nBrak podanej daty oznacza bezterminową możliwość dodawania Załączników do Faktur", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "CommonSessionStatus": { + "enum": [ + "InProgress", + "Succeeded", + "Failed", + "Cancelled" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| InProgress | Sesja aktywna. |\n| Succeeded | Sesja przetworzona poprawnie. W trakcie przetwarzania sesji nie wystąpiły żadne błędy, ale część faktur nadal mogła zostać odrzucona. |\n| Failed | Sesja nie przetworzona z powodu błędów. Na etapie rozpoczynania lub kończenia sesji wystąpiły błędy, które nie pozwoliły na jej poprawne przetworzenie. |\n| Cancelled | Sesja anulowania. Został przekroczony czas na wysyłkę w sesji wsadowej, lub nie przesłano żadnych faktur w sesji interaktywnej. |\n" + }, + "CurrencyCode": { + "enum": [ + "AED", + "AFN", + "ALL", + "AMD", + "ANG", + "AOA", + "ARS", + "AUD", + "AWG", + "AZN", + "BAM", + "BBD", + "BDT", + "BGN", + "BHD", + "BIF", + "BMD", + "BND", + "BOB", + "BOV", + "BRL", + "BSD", + "BTN", + "BWP", + "BYN", + "BZD", + "CAD", + "CDF", + "CHE", + "CHF", + "CHW", + "CLF", + "CLP", + "CNY", + "COP", + "COU", + "CRC", + "CUC", + "CUP", + "CVE", + "CZK", + "DJF", + "DKK", + "DOP", + "DZD", + "EGP", + "ERN", + "ETB", + "EUR", + "FJD", + "FKP", + "GBP", + "GEL", + "GGP", + "GHS", + "GIP", + "GMD", + "GNF", + "GTQ", + "GYD", + "HKD", + "HNL", + "HRK", + "HTG", + "HUF", + "IDR", + "ILS", + "IMP", + "INR", + "IQD", + "IRR", + "ISK", + "JEP", + "JMD", + "JOD", + "JPY", + "KES", + "KGS", + "KHR", + "KMF", + "KPW", + "KRW", + "KWD", + "KYD", + "KZT", + "LAK", + "LBP", + "LKR", + "LRD", + "LSL", + "LYD", + "MAD", + "MDL", + "MGA", + "MKD", + "MMK", + "MNT", + "MOP", + "MRU", + "MUR", + "MVR", + "MWK", + "MXN", + "MXV", + "MYR", + "MZN", + "NAD", + "NGN", + "NIO", + "NOK", + "NPR", + "NZD", + "OMR", + "PAB", + "PEN", + "PGK", + "PHP", + "PKR", + "PLN", + "PYG", + "QAR", + "RON", + "RSD", + "RUB", + "RWF", + "SAR", + "SBD", + "SCR", + "SDG", + "SEK", + "SGD", + "SHP", + "SLL", + "SOS", + "SRD", + "SSP", + "STN", + "SVC", + "SYP", + "SZL", + "THB", + "TJS", + "TMT", + "TND", + "TOP", + "TRY", + "TTD", + "TWD", + "TZS", + "UAH", + "UGX", + "USD", + "USN", + "UYI", + "UYU", + "UYW", + "UZS", + "VES", + "VND", + "VUV", + "WST", + "XAF", + "XAG", + "XAU", + "XBA", + "XBB", + "XBC", + "XBD", + "XCD", + "XCG", + "XDR", + "XOF", + "XPD", + "XPF", + "XPT", + "XSU", + "XUA", + "XXX", + "YER", + "ZAR", + "ZMW", + "ZWL" + ], + "type": "string" + }, + "EffectiveApiRateLimitValues": { + "required": [ + "perHour", + "perMinute", + "perSecond" + ], + "type": "object", + "properties": { + "perSecond": { + "type": "integer", + "description": "Limit na sekundę.", + "format": "int32" + }, + "perMinute": { + "type": "integer", + "description": "Limit na minutę.", + "format": "int32" + }, + "perHour": { + "type": "integer", + "description": "Limit na godzinę.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "EffectiveApiRateLimits": { + "required": [ + "batchSession", + "invoiceDownload", + "invoiceExport", + "invoiceExportStatus", + "invoiceMetadata", + "invoiceSend", + "invoiceStatus", + "onlineSession", + "other", + "sessionInvoiceList", + "sessionList", + "sessionMisc" + ], + "type": "object", + "properties": { + "onlineSession": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla otwierania/zamykania sesji interaktywnych." + }, + "batchSession": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla otwierania/zamykania sesji wsadowych." + }, + "invoiceSend": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla wysyłki faktur." + }, + "invoiceStatus": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pobierania statusu faktury z sesji." + }, + "sessionList": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pobierania listy sesji." + }, + "sessionInvoiceList": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pobierania listy faktur w sesji." + }, + "sessionMisc": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pozostałych operacji w ramach sesji." + }, + "invoiceMetadata": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pobierania metadanych faktur." + }, + "invoiceExport": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla eksportu paczki faktur." + }, + "invoiceExportStatus": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pobierana statusu eksportu paczki faktur." + }, + "invoiceDownload": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pobierania faktur po numerze KSeF." + }, + "other": { + "required": [ + "perSecond", + "perMinute", + "perHour" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EffectiveApiRateLimitValues" + } + ], + "description": "Limity dla pozostałych operacji API." + } + }, + "additionalProperties": false + }, + "EffectiveContextLimits": { + "required": [ + "batchSession", + "onlineSession" + ], + "type": "object", + "properties": { + "onlineSession": { + "required": [ + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB", + "maxInvoices" + ], + "allOf": [ + { + "$ref": "#/components/schemas/OnlineSessionEffectiveContextLimits" + } + ], + "description": "Limity dla sesji interaktywnych." + }, + "batchSession": { + "required": [ + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB", + "maxInvoices" + ], + "allOf": [ + { + "$ref": "#/components/schemas/BatchSessionEffectiveContextLimits" + } + ], + "description": "Limity dla sesji wsadowych." + } + }, + "additionalProperties": false + }, + "EffectiveSubjectLimits": { + "type": "object", + "properties": { + "enrollment": { + "allOf": [ + { + "$ref": "#/components/schemas/EnrollmentEffectiveSubjectLimits" + } + ], + "nullable": true + }, + "certificate": { + "allOf": [ + { + "$ref": "#/components/schemas/CertificateEffectiveSubjectLimits" + } + ], + "nullable": true + } + }, + "additionalProperties": false + }, + "EncryptionInfo": { + "required": [ + "encryptedSymmetricKey", + "initializationVector" + ], + "type": "object", + "properties": { + "encryptedSymmetricKey": { + "type": "string", + "description": "Klucz symetryczny o długości 32 bajtów, zaszyfrowany algorytmem RSA (Padding: OAEP z SHA-256), zakodowany w formacie Base64.\n\n[Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)", + "format": "byte" + }, + "initializationVector": { + "type": "string", + "description": "Wektor inicjalizujący (IV) o długości 16 bajtów, używany do szyfrowania symetrycznego, zakodowany w formacie Base64.", + "format": "byte" + } + }, + "additionalProperties": false + }, + "EnrollCertificateRequest": { + "required": [ + "certificateName", + "certificateType", + "csr" + ], + "type": "object", + "properties": { + "certificateName": { + "maxLength": 100, + "minLength": 5, + "pattern": "^[a-zA-Z0-9_\\-\\ ąćęłńóśźżĄĆĘŁŃÓŚŹŻ]+$", + "type": "string", + "description": "Nazwa własna certyfikatu." + }, + "certificateType": { + "allOf": [ + { + "$ref": "#/components/schemas/KsefCertificateType" + } + ], + "description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" + }, + "csr": { + "type": "string", + "description": "Wniosek certyfikacyjny PKCS#10 (CSR) w formacie DER, zakodowany w formacie Base64.", + "format": "byte" + }, + "validFrom": { + "type": "string", + "description": "Data rozpoczęcia ważności certyfikatu.\nJeśli nie zostanie podana, certyfikat będzie ważny od momentu jego wystawienia.", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "EnrollCertificateResponse": { + "required": [ + "referenceNumber", + "timestamp" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny wniosku certyfikacyjnego." + }, + "timestamp": { + "type": "string", + "description": "Data złożenia wniosku certyfikacyjnego.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "EnrollmentEffectiveSubjectLimits": { + "type": "object", + "properties": { + "maxEnrollments": { + "type": "integer", + "format": "int32" + } + }, + "additionalProperties": false + }, + "EnrollmentSubjectLimitsOverride": { + "type": "object", + "properties": { + "maxEnrollments": { + "minimum": 0, + "type": "integer", + "format": "int32", + "nullable": true + } + }, + "additionalProperties": false + }, + "EntityAuthorizationGrant": { + "required": [ + "authorizationScope", + "authorizedEntityIdentifier", + "authorizingEntityIdentifier", + "description", + "id", + "startDate" + ], + "type": "object", + "properties": { + "id": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionId" + } + ], + "description": "Identyfikator uprawnienia." + }, + "authorIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorIdentifier" + } + ], + "description": "Identyfikator osoby nadającej uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |", + "nullable": true + }, + "authorizedEntityIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" + }, + "authorizingEntityIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "authorizationScope": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoicePermissionType" + } + ], + "description": "Rodzaj uprawnienia." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia." + }, + "subjectEntityDetails": { + "required": [ + "subjectDetailsType", + "fullName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectEntityByIdentifierDetails" + } + ], + "description": "Dane podmiotu uprawnionego.", + "nullable": true + }, + "startDate": { + "type": "string", + "description": "Data rozpoczęcia obowiązywania uprawnienia.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "EntityAuthorizationPermissionType": { + "enum": [ + "SelfInvoicing", + "RRInvoicing", + "TaxRepresentative", + "PefInvoicing" + ], + "type": "string" + }, + "EntityAuthorizationPermissionsGrantRequest": { + "required": [ + "description", + "permission", + "subjectDetails", + "subjectIdentifier" + ], + "type": "object", + "properties": { + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationPermissionsSubjectIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" + }, + "permission": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationPermissionType" + } + ], + "description": "Rodzaj uprawnienia." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia" + }, + "subjectDetails": { + "required": [ + "fullName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityDetails" + } + ], + "description": "Dane podmiotu, któremu nadawane są uprawnienia." + } + }, + "additionalProperties": false + }, + "EntityAuthorizationPermissionsQueryRequest": { + "required": [ + "queryType" + ], + "type": "object", + "properties": { + "authorizingIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", + "nullable": true + }, + "authorizedIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |", + "nullable": true + }, + "queryType": { + "allOf": [ + { + "$ref": "#/components/schemas/QueryType" + } + ], + "description": "Typ zapytania.\n| Type | Value |\n| --- | --- |\n| Granted | Uprawnienia nadane innym podmiotom |\n| Received | Uprawnienia otrzymane od innych podmiotów |" + }, + "permissionTypes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InvoicePermissionType" + }, + "description": "Lista rodzajów wyszukiwanych uprawnień.", + "nullable": true + } + }, + "additionalProperties": false + }, + "EntityAuthorizationPermissionsSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 10, + "minLength": 9, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" + }, + "EntityAuthorizationPermissionsSubjectIdentifierType": { + "enum": [ + "Nip", + "PeppolId" + ], + "type": "string" + }, + "EntityAuthorizationsAuthorIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator osoby nadającej uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "EntityAuthorizationsAuthorIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "EntityAuthorizationsAuthorizedEntityIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 10, + "minLength": 9, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" + }, + "EntityAuthorizationsAuthorizedEntityIdentifierType": { + "enum": [ + "Nip", + "PeppolId" + ], + "type": "string" + }, + "EntityAuthorizationsAuthorizingEntityIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 10, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "EntityAuthorizationsAuthorizingEntityIdentifierType": { + "enum": [ + "Nip" + ], + "type": "string" + }, + "EntityByFingerprintDetails": { + "required": [ + "address", + "fullName" + ], + "type": "object", + "properties": { + "fullName": { + "maxLength": 100, + "type": "string", + "description": "Pełna nazwa podmiotu." + }, + "address": { + "maxLength": 512, + "type": "string", + "description": "Adres podmiotu." + } + }, + "additionalProperties": false + }, + "EntityDetails": { + "required": [ + "fullName" + ], + "type": "object", + "properties": { + "fullName": { + "maxLength": 90, + "minLength": 5, + "type": "string", + "description": "Pełna nazwa podmiotu." + } + }, + "additionalProperties": false + }, + "EntityPermission": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityPermissionType" + } + ], + "description": "Rodzaj uprawnienia." + }, + "canDelegate": { + "type": "boolean", + "description": "Flaga pozwalająca na pośrednie przekazywanie danego uprawnienia" + } + }, + "additionalProperties": false + }, + "EntityPermissionType": { + "enum": [ + "InvoiceWrite", + "InvoiceRead" + ], + "type": "string" + }, + "EntityPermissionsGrantRequest": { + "required": [ + "description", + "permissions", + "subjectDetails", + "subjectIdentifier" + ], + "type": "object", + "properties": { + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityPermissionsSubjectIdentifier" + } + ], + "description": "Identyfikator podmiotu.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EntityPermission" + }, + "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia" + }, + "subjectDetails": { + "required": [ + "fullName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityDetails" + } + ], + "description": "Dane podmiotu, któremu nadawane są uprawnienia." + } + }, + "additionalProperties": false + }, + "EntityPermissionsSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 10, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "EntityPermissionsSubjectIdentifierType": { + "enum": [ + "Nip" + ], + "type": "string" + }, + "EntityPermissionsSubordinateEntityIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityPermissionsSubordinateEntityIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 10, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "EntityPermissionsSubordinateEntityIdentifierType": { + "enum": [ + "Nip" + ], + "type": "string" + }, + "EntityRole": { + "required": [ + "description", + "role", + "startDate" + ], + "type": "object", + "properties": { + "parentEntityIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityRolesParentEntityIdentifier" + } + ], + "description": "Identyfikator podmiotu nadrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", + "nullable": true + }, + "role": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityRoleType" + } + ], + "description": "Typ roli - powiązania z podmiotem nadrzędnym." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis roli." + }, + "startDate": { + "type": "string", + "description": "Data rozpoczęcia obowiązywania roli.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "EntityRoleType": { + "enum": [ + "CourtBailiff", + "EnforcementAuthority", + "LocalGovernmentUnit", + "LocalGovernmentSubUnit", + "VatGroupUnit", + "VatGroupSubUnit" + ], + "type": "string" + }, + "EntityRolesParentEntityIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityRolesParentEntityIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 10, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu nadrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "EntityRolesParentEntityIdentifierType": { + "enum": [ + "Nip" + ], + "type": "string" + }, + "EntitySubjectByFingerprintDetailsType": { + "enum": [ + "EntityByFingerprint" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" + }, + "EntitySubjectByIdentifierDetailsType": { + "enum": [ + "EntityByIdentifier" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n" + }, + "EntitySubjectDetailsType": { + "enum": [ + "EntityByIdentifier", + "EntityByFingerprint" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" + }, + "EuEntityAdministrationPermissionsContextIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityAdministrationPermissionsContextIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 25, + "minLength": 15, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator kontekstu złożonego.\n| Type | Value |\n| --- | --- |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}` |" + }, + "EuEntityAdministrationPermissionsContextIdentifierType": { + "enum": [ + "NipVatUe" + ], + "type": "string" + }, + "EuEntityAdministrationPermissionsGrantRequest": { + "required": [ + "contextIdentifier", + "description", + "euEntityDetails", + "euEntityName", + "subjectDetails", + "subjectIdentifier" + ], + "type": "object", + "properties": { + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityAdministrationPermissionsSubjectIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityAdministrationPermissionsContextIdentifier" + } + ], + "description": "Identyfikator kontekstu złożonego.\n| Type | Value |\n| --- | --- |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}` |" + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia" + }, + "euEntityName": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Nazwa i adres podmiotu unijnego w formacie: \n`{euSubjectName}, {euSubjectAddress}`" + }, + "subjectDetails": { + "required": [ + "subjectDetailsType" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionSubjectDetails" + } + ], + "description": "Dane podmiotu, któremu nadawane są uprawnienia." + }, + "euEntityDetails": { + "required": [ + "fullName", + "address" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityDetails" + } + ], + "description": "Dane podmiotu unijnego, w kontekście którego nadawane są uprawnienia." + } + }, + "additionalProperties": false + }, + "EuEntityAdministrationPermissionsSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityAdministrationPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 64, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "EuEntityAdministrationPermissionsSubjectIdentifierType": { + "enum": [ + "Fingerprint" + ], + "type": "string" + }, + "EuEntityDetails": { + "required": [ + "address", + "fullName" + ], + "type": "object", + "properties": { + "fullName": { + "maxLength": 100, + "type": "string", + "description": "Pełna nazwa podmiotu." + }, + "address": { + "maxLength": 512, + "type": "string", + "description": "Adres podmiotu." + } + }, + "additionalProperties": false + }, + "EuEntityPermission": { + "required": [ + "authorIdentifier", + "authorizedFingerprintIdentifier", + "description", + "euEntityName", + "id", + "permissionScope", + "startDate", + "vatUeIdentifier" + ], + "type": "object", + "properties": { + "id": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionId" + } + ], + "description": "Identyfikator uprawnienia." + }, + "authorIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionsAuthorIdentifier" + } + ], + "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "vatUeIdentifier": { + "type": "string", + "description": "Identyfikator podmiotu unijnego." + }, + "euEntityName": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Nazwa podmiotu unijnego." + }, + "authorizedFingerprintIdentifier": { + "maxLength": 64, + "minLength": 64, + "type": "string", + "description": "Uprawniony odcisk palca certyfikatu." + }, + "permissionScope": { + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionsQueryPermissionType" + } + ], + "description": "Uprawnienie." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia." + }, + "subjectPersonDetails": { + "required": [ + "subjectDetailsType", + "firstName", + "lastName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectPersonByFingerprintDetails" + } + ], + "description": "Dane osoby uprawnionej.", + "nullable": true + }, + "subjectEntityDetails": { + "required": [ + "subjectDetailsType", + "fullName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectEntityByFingerprintDetails" + } + ], + "description": "Dane podmiotu uprawnionego.", + "nullable": true + }, + "euEntityDetails": { + "required": [ + "fullName", + "address" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsEuEntityDetails" + } + ], + "description": "Dane podmiotu unijnego, w kontekście którego nadane jest uprawnienie.", + "nullable": true + }, + "startDate": { + "type": "string", + "description": "Data rozpoczęcia obowiązywania uprawnienia.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "EuEntityPermissionSubjectDetails": { + "required": [ + "subjectDetailsType" + ], + "type": "object", + "properties": { + "subjectDetailsType": { + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionSubjectDetailsType" + } + ], + "description": "Typ danych podmiotu.\n| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" + }, + "personByFpWithId": { + "required": [ + "firstName", + "lastName", + "identifier" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonByFingerprintWithIdentifierDetails" + } + ], + "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithIdentifier.*", + "nullable": true + }, + "personByFpNoId": { + "required": [ + "firstName", + "lastName", + "birthDate", + "idDocument" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonByFingerprintWithoutIdentifierDetails" + } + ], + "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithoutIdentifier.*", + "nullable": true + }, + "entityByFp": { + "required": [ + "fullName", + "address" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityByFingerprintDetails" + } + ], + "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = EntityByFingerprint.*", + "nullable": true + } + }, + "additionalProperties": false + }, + "EuEntityPermissionSubjectDetailsType": { + "enum": [ + "PersonByFingerprintWithIdentifier", + "PersonByFingerprintWithoutIdentifier", + "EntityByFingerprint" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" + }, + "EuEntityPermissionType": { + "enum": [ + "InvoiceWrite", + "InvoiceRead" + ], + "type": "string" + }, + "EuEntityPermissionsAuthorIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionsAuthorIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "EuEntityPermissionsAuthorIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "EuEntityPermissionsGrantRequest": { + "required": [ + "description", + "permissions", + "subjectDetails", + "subjectIdentifier" + ], + "type": "object", + "properties": { + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionsSubjectIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EuEntityPermissionType" + }, + "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia" + }, + "subjectDetails": { + "required": [ + "subjectDetailsType" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionSubjectDetails" + } + ], + "description": "Dane podmiotu, któremu nadawane są uprawnienia." + } + }, + "additionalProperties": false + }, + "EuEntityPermissionsQueryPermissionType": { + "enum": [ + "VatUeManage", + "InvoiceWrite", + "InvoiceRead", + "Introspection" + ], + "type": "string" + }, + "EuEntityPermissionsQueryRequest": { + "type": "object", + "properties": { + "vatUeIdentifier": { + "pattern": "^(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))$", + "type": "string", + "description": "Wartość identyfikatora (numeru identyfikacyjnego VAT) podmiotu unijnego (exact match).", + "nullable": true + }, + "authorizedFingerprintIdentifier": { + "type": "string", + "description": "Odcisk palca certyfikatu kwalifikowanego uprawnionego (contains).", + "nullable": true + }, + "permissionTypes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EuEntityPermissionsQueryPermissionType" + }, + "description": "Lista rodzajów wyszukiwanych uprawnień.", + "nullable": true + } + }, + "additionalProperties": false + }, + "EuEntityPermissionsSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/EuEntityPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 64, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "EuEntityPermissionsSubjectIdentifierType": { + "enum": [ + "Fingerprint" + ], + "type": "string" + }, + "ExceptionDetails": { + "type": "object", + "properties": { + "exceptionCode": { + "type": "integer", + "format": "int32" + }, + "exceptionDescription": { + "type": "string", + "nullable": true + }, + "details": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true + } + }, + "additionalProperties": false + }, + "ExceptionInfo": { + "type": "object", + "properties": { + "exceptionDetailList": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExceptionDetails" + }, + "nullable": true + }, + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "nullable": true + }, + "serviceCode": { + "type": "string", + "nullable": true + }, + "serviceCtx": { + "type": "string", + "nullable": true + }, + "serviceName": { + "type": "string", + "nullable": true + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "ExceptionResponse": { + "type": "object", + "properties": { + "exception": { + "allOf": [ + { + "$ref": "#/components/schemas/ExceptionInfo" + } + ], + "nullable": true + } + }, + "additionalProperties": false, + "example": { + "exception": { + "exceptionDetailList": [ + { + "exceptionCode": 12345, + "exceptionDescription": "Opis błędu.", + "details": [ + "Opcjonalne dodatkowe szczegóły błędu." + ] + } + ], + "referenceNumber": "a1b2c3d4-e5f6-4789-ab12-cd34ef567890", + "serviceCode": "00-c02cc3747020c605be02159bf3324f0e-eee7647dc67aa74a-00", + "serviceCtx": "srvABCDA", + "serviceName": "Undefined", + "timestamp": "2025-10-11T12:23:56.0154302" + } + } + }, + "ExportInvoicesResponse": { + "required": [ + "referenceNumber" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny eksportu faktur." + } + }, + "additionalProperties": false + }, + "FormCode": { + "required": [ + "schemaVersion", + "systemCode", + "value" + ], + "type": "object", + "properties": { + "systemCode": { + "type": "string", + "description": "Kod systemowy" + }, + "schemaVersion": { + "type": "string", + "description": "Wersja schematu" + }, + "value": { + "type": "string", + "description": "Wartość" + } + }, + "additionalProperties": false + }, + "GenerateTokenRequest": { + "required": [ + "description", + "permissions" + ], + "type": "object", + "properties": { + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TokenPermissionType" + }, + "description": "Uprawnienia przypisane tokenowi." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis tokena." + } + }, + "additionalProperties": false + }, + "GenerateTokenResponse": { + "required": [ + "referenceNumber", + "token" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny tokena KSeF." + }, + "token": { + "maxLength": 160, + "type": "string", + "description": "Token KSeF." + } + }, + "additionalProperties": false + }, + "IdDocument": { + "required": [ + "country", + "number", + "type" + ], + "type": "object", + "properties": { + "type": { + "maxLength": 20, + "type": "string", + "description": "Rodzaj dokumentu tożsamości." + }, + "number": { + "maxLength": 20, + "type": "string", + "description": "Seria i numer dokumentu tożsamości." + }, + "country": { + "maxLength": 2, + "minLength": 2, + "type": "string", + "description": "Kraj wydania dokumentu tożsamości. Musi być zgodny z ISO 3166-1 alpha-2 (np. PL, DE, US) oraz zawierać dokładnie 2 wielkie litery." + } + }, + "additionalProperties": false, + "description": "Dane dokumentu tożsamości osoby fizycznej." + }, + "IndirectPermissionType": { + "enum": [ + "InvoiceRead", + "InvoiceWrite" + ], + "type": "string" + }, + "IndirectPermissionsGrantRequest": { + "required": [ + "description", + "permissions", + "subjectDetails", + "subjectIdentifier" + ], + "type": "object", + "properties": { + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/IndirectPermissionsSubjectIdentifier" + } + ], + "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "targetIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/IndirectPermissionsTargetIdentifier" + } + ], + "description": "Identyfikator kontekstu klienta. Nie przekazanie identyfikatora oznacza, że uprawnienie nadane w sposób pośredni jest typu generalnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IndirectPermissionType" + }, + "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia" + }, + "subjectDetails": { + "required": [ + "subjectDetailsType" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionSubjectDetails" + } + ], + "description": "Dane podmiotu, któremu nadawane są uprawnienia." + } + }, + "additionalProperties": false + }, + "IndirectPermissionsSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/IndirectPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "IndirectPermissionsSubjectIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "IndirectPermissionsTargetIdentifier": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/IndirectPermissionsTargetIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 16, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Identyfikator kontekstu klienta. Nie przekazanie identyfikatora oznacza, że uprawnienie nadane w sposób pośredni jest typu generalnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" + }, + "IndirectPermissionsTargetIdentifierType": { + "enum": [ + "Nip", + "AllPartners", + "InternalId" + ], + "type": "string" + }, + "InitTokenAuthenticationRequest": { + "required": [ + "challenge", + "contextIdentifier", + "encryptedToken" + ], + "type": "object", + "properties": { + "challenge": { + "allOf": [ + { + "$ref": "#/components/schemas/Challenge" + } + ], + "description": "Wygenerowany wcześniej challenge." + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/AuthenticationContextIdentifier" + } + ], + "description": "Identyfikator kontekstu do którego następuje uwierzytelnienie." + }, + "encryptedToken": { + "type": "string", + "description": "Zaszyfrowany token wraz z timestampem z challenge'a, w postaci `token|timestamp`, zakodowany w formacie Base64.", + "format": "byte" + }, + "authorizationPolicy": { + "allOf": [ + { + "$ref": "#/components/schemas/AuthorizationPolicy" + } + ], + "description": "Polityka autoryzacji żądań przy każdym użyciu tokena dostępu.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InternalId": { + "maxLength": 16, + "minLength": 16, + "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}-\\d{5}$", + "type": "string", + "description": "Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr." + }, + "InvoiceExportRequest": { + "required": [ + "encryption", + "filters" + ], + "type": "object", + "properties": { + "encryption": { + "required": [ + "encryptedSymmetricKey", + "initializationVector" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EncryptionInfo" + } + ], + "description": "Informacje wymagane do zaszyfrowania wyniku zapytania." + }, + "filters": { + "required": [ + "subjectType", + "dateRange" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQueryFilters" + } + ], + "description": "Zestaw filtrów do wyszukiwania faktur." + } + }, + "additionalProperties": false + }, + "InvoiceExportStatusResponse": { + "required": [ + "status" + ], + "type": "object", + "properties": { + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/StatusInfo" + } + ], + "description": "Status eksportu.\n\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Eksport faktur w toku | - |\n| 200 | Eksport faktur zakończony sukcesem | - |\n| 210 | Eksport faktur wygasł i nie jest już dostępny do pobrania | - |\n| 415 | Błąd odszyfrowania dostarczonego klucza | - |\n| 420 | Zakres filtrowania wykracza poza dostępny zakres danych | Parametr dateRange.from jest późniejszy niż PermanentStorageHwmDate przy włączonym restrictToPermanentStorageHwmDate. |\n| 500 | Nieznany błąd ({statusCode}) | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" + }, + "completedDate": { + "type": "string", + "description": "Data zakończenia przetwarzania żądania eksportu faktur.", + "format": "date-time", + "nullable": true + }, + "packageExpirationDate": { + "type": "string", + "description": "Data wygaśnięcia paczki faktur przygotowanej do pobrania.\nPo upływie tej daty paczka nie będzie już dostępna do pobrania.", + "format": "date-time", + "nullable": true + }, + "package": { + "required": [ + "invoiceCount", + "size", + "parts", + "isTruncated" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoicePackage" + } + ], + "description": "Dane paczki faktur przygotowanej do pobrania.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceMetadata": { + "required": [ + "acquisitionDate", + "buyer", + "currency", + "formCode", + "grossAmount", + "hasAttachment", + "invoiceHash", + "invoiceNumber", + "invoiceType", + "invoicingDate", + "invoicingMode", + "isSelfInvoicing", + "issueDate", + "ksefNumber", + "netAmount", + "permanentStorageDate", + "seller", + "vatAmount" + ], + "type": "object", + "properties": { + "ksefNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/KsefNumber" + } + ], + "description": "Numer KSeF faktury." + }, + "invoiceNumber": { + "maxLength": 256, + "type": "string", + "description": "Numer faktury nadany przez wystawcę." + }, + "issueDate": { + "type": "string", + "description": "Data wystawienia faktury.", + "format": "date" + }, + "invoicingDate": { + "type": "string", + "description": "Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania).", + "format": "date-time" + }, + "acquisitionDate": { + "type": "string", + "description": "Data nadania numeru KSeF.", + "format": "date-time" + }, + "permanentStorageDate": { + "type": "string", + "description": "Data trwałego zapisu faktury w repozytorium systemu KSeF.", + "format": "date-time" + }, + "seller": { + "required": [ + "nip" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceMetadataSeller" + } + ], + "description": "Dane identyfikujące sprzedawcę." + }, + "buyer": { + "required": [ + "identifier" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceMetadataBuyer" + } + ], + "description": "Dane identyfikujące nabywcę." + }, + "netAmount": { + "type": "number", + "description": "Łączna kwota netto.", + "format": "double" + }, + "grossAmount": { + "type": "number", + "description": "Łączna kwota brutto.", + "format": "double" + }, + "vatAmount": { + "type": "number", + "description": "Łączna kwota VAT.", + "format": "double" + }, + "currency": { + "maxLength": 3, + "minLength": 3, + "type": "string", + "description": "Kod waluty." + }, + "invoicingMode": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoicingMode" + } + ], + "description": "Tryb fakturowania (online/offline)." + }, + "invoiceType": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceType" + } + ], + "description": "Rodzaj faktury.\n| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n" + }, + "formCode": { + "required": [ + "systemCode", + "schemaVersion", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/FormCode" + } + ], + "description": "Struktura dokumentu faktury.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| [FA (2)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n| [PEF (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF(3)_v2-1.xsd) | 2-1 | PEF |\n| [PEF_KOR (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF_KOR(3)_v2-1.xsd) | 2-1 | PEF |\n| FA_RR (1) | 1-0E | RR |\n" + }, + "isSelfInvoicing": { + "type": "boolean", + "description": "Czy faktura została wystawiona w trybie samofakturowania." + }, + "hasAttachment": { + "type": "boolean", + "description": "Określa, czy faktura posiada załącznik." + }, + "invoiceHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 faktury, zakodowany w formacie Base64." + }, + "hashOfCorrectedInvoice": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 korygowanej faktury, zakodowany w formacie Base64.", + "nullable": true + }, + "thirdSubjects": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InvoiceMetadataThirdSubject" + }, + "description": "Lista podmiotów trzecich.", + "nullable": true + }, + "authorizedSubject": { + "required": [ + "nip", + "role" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceMetadataAuthorizedSubject" + } + ], + "description": "Podmiot upoważniony.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceMetadataAuthorizedSubject": { + "required": [ + "nip", + "role" + ], + "type": "object", + "properties": { + "nip": { + "allOf": [ + { + "$ref": "#/components/schemas/Nip" + } + ], + "description": "Nip podmiotu upoważnionego" + }, + "name": { + "maxLength": 512, + "type": "string", + "description": "Nazwa podmiotu upoważnionego.", + "nullable": true + }, + "role": { + "type": "integer", + "description": "Rola podmiotu upoważnionego.\n| Wartość | Opis |\n| ---- | --- |\n| 1 | Organ egzekucyjny - w przypadku, o którym mowa w art. 106c pkt 1 ustawy |\n| 2 | Komornik sądowy - w przypadku, o którym mowa w art. 106c pkt 2 ustawy |\n| 3 | Przedstawiciel podatkowy - w przypadku gdy na fakturze występują dane przedstawiciela podatkowego, o którym mowa w art. 18a - 18d ustawy |", + "format": "int32" + } + }, + "additionalProperties": false + }, + "InvoiceMetadataBuyer": { + "required": [ + "identifier" + ], + "type": "object", + "properties": { + "identifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceMetadataBuyerIdentifier" + } + ], + "description": "Identyfikator nabywcy.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator|\n| None | Brak identyfikatora nabywcy |" + }, + "name": { + "maxLength": 512, + "type": "string", + "description": "Nazwa nabywcy.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceMetadataBuyerIdentifier": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/BuyerIdentifierType" + } + ], + "description": "Typ identyfikatora nabywcy.\n| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora nabywcy |\n" + }, + "value": { + "maxLength": 50, + "type": "string", + "description": "Wartość identyfikatora nabywcy.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceMetadataSeller": { + "required": [ + "nip" + ], + "type": "object", + "properties": { + "nip": { + "allOf": [ + { + "$ref": "#/components/schemas/Nip" + } + ], + "description": "Nip sprzedawcy." + }, + "name": { + "maxLength": 512, + "type": "string", + "description": "Nazwa sprzedawcy.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceMetadataThirdSubject": { + "required": [ + "identifier", + "role" + ], + "type": "object", + "properties": { + "identifier": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceMetadataThirdSubjectIdentifier" + } + ] + }, + "name": { + "maxLength": 512, + "type": "string", + "description": "Nazwa podmiotu trzeciego.", + "nullable": true + }, + "role": { + "type": "integer", + "description": "Rola podmiotu trzeciego.\n| Wartość | Opis |\n| ---- | --- |\n| 0 | Inna rola |\n| 1 | Faktor - w przypadku gdy na fakturze występują dane faktora |\n| 2 | Odbiorca - w przypadku gdy na fakturze występują dane jednostek wewnętrznych, oddziałów, wyodrębnionych w ramach nabywcy, które same nie stanowią nabywcy w rozumieniu ustawy |\n| 3 | Podmiot pierwotny - w przypadku gdy na fakturze występują dane podmiotu będącego w stosunku do podatnika podmiotem przejętym lub przekształconym, który dokonywał dostawy lub świadczył usługę. Z wyłączeniem przypadków, o których mowa w art. 106j ust.2 pkt 3 ustawy, gdy dane te wykazywane są w części Podmiot1K |\n| 4 | Dodatkowy nabywca - w przypadku gdy na fakturze występują dane kolejnych (innych niż wymieniony w części Podmiot2) nabywców |\n| 5 | Wystawca faktury - w przypadku gdy na fakturze występują dane podmiotu wystawiającego fakturę w imieniu podatnika. Nie dotyczy przypadku, gdy wystawcą faktury jest nabywca |\n| 6 | Dokonujący płatności - w przypadku gdy na fakturze występują dane podmiotu regulującego zobowiązanie w miejsce nabywcy |\n| 7 | Jednostka samorządu terytorialnego - wystawca |\n| 8 | Jednostka samorządu terytorialnego - odbiorca |\n| 9 | Członek grupy VAT - wystawca |\n| 10 | Członek grupy VAT - odbiorca |\n| 11 | Pracownik |", + "format": "int32" + } + }, + "additionalProperties": false + }, + "InvoiceMetadataThirdSubjectIdentifier": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/ThirdSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora podmiotu trzeciego.\n| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr. |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora podmiotu trzeciego |\n" + }, + "value": { + "maxLength": 50, + "type": "string", + "description": "Wartość identyfikatora podmiotu trzeciego.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoicePackage": { + "required": [ + "invoiceCount", + "isTruncated", + "parts", + "size" + ], + "type": "object", + "properties": { + "invoiceCount": { + "maximum": 10000, + "minimum": 0, + "type": "integer", + "description": "Łączna liczba faktur w paczce.", + "format": "int64" + }, + "size": { + "minimum": 0, + "type": "integer", + "description": "Rozmiar paczki w bajtach.", + "format": "int64" + }, + "parts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InvoicePackagePart" + }, + "description": "Lista dostępnych części paczki do pobrania." + }, + "isTruncated": { + "type": "boolean", + "description": "Określa, czy wynik eksportu został ucięty z powodu przekroczenia limitu liczby faktur lub wielkości paczki." + }, + "lastIssueDate": { + "type": "string", + "description": "Data wystawienia ostatniej faktury ujętej w paczce.\nPole występuje wyłącznie wtedy, gdy paczka została ucięta i eksport był filtrowany po typie daty `Issue`.", + "format": "date", + "nullable": true + }, + "lastInvoicingDate": { + "type": "string", + "description": "Data przyjęcia ostatniej faktury ujętej w paczce.\nPole występuje wyłącznie wtedy, gdy paczka została ucięta i eksport był filtrowany po typie daty `Invoicing`.", + "format": "date-time", + "nullable": true + }, + "lastPermanentStorageDate": { + "type": "string", + "description": "Data trwałego zapisu ostatniej faktury ujętej w paczce.\nPole występuje wyłącznie wtedy, gdy paczka została ucięta i eksport był filtrowany po typie daty `PermanentStorage`.", + "format": "date-time", + "nullable": true + }, + "permanentStorageHwmDate": { + "type": "string", + "description": "Dotyczy wyłącznie zapytań filtrowanych po typie daty PermanentStorage.\nJeśli zapytanie dotyczyło najnowszego okresu, wartość ta może być wartością nieznacznie skorygowaną względem górnej granicy podanej w warunkach zapytania.\nDla okresów starszych, będzie to zgodne z warunkami zapytania. \n\nSystem gwarantuje, że dane poniżej tej wartości są spójne i kompletne.\nPonowne zapytania obejmujące zakresem dane poniżej tego kroczącego znacznika czasu nie zwrócą w przyszłości innych wyników (np.dodatkowych faktur). \n\nDla dateType = Issue lub Invoicing – null.", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoicePackagePart": { + "required": [ + "encryptedPartHash", + "encryptedPartSize", + "expirationDate", + "method", + "ordinalNumber", + "partHash", + "partName", + "partSize", + "url" + ], + "type": "object", + "properties": { + "ordinalNumber": { + "minimum": 1, + "type": "integer", + "description": "Numer sekwencyjny pliku części paczki.", + "format": "int32" + }, + "partName": { + "maxLength": 100, + "type": "string", + "description": "Nazwa pliku części paczki." + }, + "method": { + "type": "string", + "description": "Metoda HTTP, której należy użyć przy pobieraniu pliku." + }, + "url": { + "type": "string", + "description": "Adres URL, pod który należy wysłać żądanie pobrania części paczki.\nLink jest generowany dynamicznie w momencie odpytania o status operacji eksportu.\nNie podlega limitom API i nie wymaga przesyłania tokenu dostępowego przy pobraniu.\n\nOdpowiedź HTTP zawiera dodatkowe nagłówki:\n- `x-ms-meta-hash` – zaszyfrowanej części paczki, zakodowany w formacie Base64.", + "format": "uri" + }, + "partSize": { + "minimum": 1, + "type": "integer", + "description": "Rozmiar części paczki w bajtach.", + "format": "int64" + }, + "partHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 pliku części paczki, zakodowany w formacie Base64." + }, + "encryptedPartSize": { + "minimum": 1, + "type": "integer", + "description": "Rozmiar zaszyfrowanej części paczki w bajtach.", + "format": "int64" + }, + "encryptedPartHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 zaszyfrowanej części paczki, zakodowany w formacie Base64." + }, + "expirationDate": { + "type": "string", + "description": "Data i godzina wygaśnięcia linku umożliwiającego pobranie części paczki.\nPo upływie tego momentu link przestaje być aktywny.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "InvoicePermissionType": { + "enum": [ + "SelfInvoicing", + "TaxRepresentative", + "RRInvoicing", + "PefInvoicing" + ], + "type": "string" + }, + "InvoiceQueryAmount": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/AmountType" + } + ] + }, + "from": { + "type": "number", + "format": "double", + "nullable": true + }, + "to": { + "type": "number", + "format": "double", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceQueryBuyerIdentifier": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/BuyerIdentifierType" + } + ], + "description": "Typ identyfikatora nabywcy.\n| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora nabywcy |\n" + }, + "value": { + "maxLength": 50, + "type": "string", + "description": "Wartość identyfikatora nabywcy (exact match).", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceQueryDateRange": { + "required": [ + "dateType", + "from" + ], + "type": "object", + "properties": { + "dateType": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQueryDateType" + } + ], + "description": "Typ daty, według której ma być zastosowany zakres.\n| Wartość | Opis |\n| --- | --- |\n| Issue | Data wystawienia faktury. |\n| Invoicing | Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania). |\n| PermanentStorage | Data trwałego zapisu faktury w repozytorium systemu KSeF. |\n" + }, + "from": { + "type": "string", + "description": "Data początkowa zakresu w formacie ISO-8601 np. 2026-01-03T13:45:00+00:00.", + "format": "date-time" + }, + "to": { + "type": "string", + "description": "Data końcowa zakresu w formacie ISO-8601. Jeśli nie zostanie podana, przyjmowana jest bieżąca data i czas w UTC.", + "format": "date-time", + "nullable": true + }, + "restrictToPermanentStorageHwmDate": { + "type": "boolean", + "description": "Określa, czy system ma ograniczyć filtrowanie (zakres dateRange.to) do wartości `PermanentStorageHwmDate`.\n\n* Dotyczy wyłącznie zapytań z `dateType = PermanentStorage`, \n* Gdy `true`, system ogranicza filtrowanie tak, aby wartość `dateRange.to` nie przekraczała wartości `PermanentStorageHwmDate`, \n* Gdy `null` lub `false`, filtrowanie może wykraczać poza `PermanentStorageHwmDate`.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceQueryDateType": { + "enum": [ + "Issue", + "Invoicing", + "PermanentStorage" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Issue | Data wystawienia faktury. |\n| Invoicing | Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania). |\n| PermanentStorage | Data trwałego zapisu faktury w repozytorium systemu KSeF. |\n" + }, + "InvoiceQueryFilters": { + "required": [ + "dateRange", + "subjectType" + ], + "type": "object", + "properties": { + "subjectType": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQuerySubjectType" + } + ], + "description": "Typ podmiotu, którego dotyczą kryteria filtrowania metadanych faktur.\nOkreśla kontekst, w jakim przeszukiwane są dane.\n| Wartość | Opis |\n| --- | --- |\n| Subject1 | Podmiot 1 - sprzedawca |\n| Subject2 | Podmiot 2 - nabywca |\n| Subject3 | Podmiot 3 |\n| SubjectAuthorized | Podmiot upoważniony |\n" + }, + "dateRange": { + "required": [ + "dateType", + "from" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQueryDateRange" + } + ], + "description": "Typ i zakres dat, według którego mają być filtrowane faktury. Dozwolony maksymalny okres wynosi 3 miesiące. Zakres uznawany jest za poprawny, jeśli mieści się w trzech miesiącach w UTC lub w czasie polskim." + }, + "ksefNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/KsefNumber" + } + ], + "description": "Numer KSeF faktury (exact match).", + "nullable": true + }, + "invoiceNumber": { + "maxLength": 256, + "type": "string", + "description": "Numer faktury nadany przez wystawcę (exact match).", + "nullable": true + }, + "amount": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQueryAmount" + } + ], + "description": "Filtr kwotowy – brutto, netto lub VAT (z wartością).", + "nullable": true + }, + "sellerNip": { + "allOf": [ + { + "$ref": "#/components/schemas/Nip" + } + ], + "description": "Nip sprzedawcy (exact match).", + "nullable": true + }, + "buyerIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQueryBuyerIdentifier" + } + ], + "description": "Identyfikator nabywcy.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego. |\n| Other | Inny identyfikator|\n| None | Brak identyfikatora nabywcy |", + "nullable": true + }, + "currencyCodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CurrencyCode" + }, + "description": "Kody walut.", + "nullable": true + }, + "invoicingMode": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoicingMode" + } + ], + "description": "Tryb wystawienia faktury: online lub offline.", + "nullable": true + }, + "isSelfInvoicing": { + "type": "boolean", + "description": "Czy faktura została wystawiona w trybie samofakturowania.", + "nullable": true + }, + "formType": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceQueryFormType" + } + ], + "description": "Typ dokumentu.\n| Wartość | Opis |\n| --- | --- |\n| FA | Faktura VAT |\n| PEF | Faktura PEF |\n| RR | Faktura RR |\n", + "nullable": true + }, + "invoiceTypes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InvoiceType" + }, + "description": "Rodzaje faktur.\n| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n", + "nullable": true + }, + "hasAttachment": { + "type": "boolean", + "description": "Czy faktura ma załącznik.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceQueryFormType": { + "enum": [ + "FA", + "PEF", + "RR" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| FA | Faktura VAT |\n| PEF | Faktura PEF |\n| RR | Faktura RR |\n" + }, + "InvoiceQuerySubjectType": { + "enum": [ + "Subject1", + "Subject2", + "Subject3", + "SubjectAuthorized" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Subject1 | Podmiot 1 - sprzedawca |\n| Subject2 | Podmiot 2 - nabywca |\n| Subject3 | Podmiot 3 |\n| SubjectAuthorized | Podmiot upoważniony |\n" + }, + "InvoiceStatusInfo": { + "required": [ + "code", + "description" + ], + "type": "object", + "properties": { + "code": { + "type": "integer", + "description": "Kod statusu faktury", + "format": "int32" + }, + "description": { + "minLength": 1, + "type": "string", + "description": "Opis statusu" + }, + "details": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Dodatkowe szczegóły statusu", + "nullable": true + }, + "extensions": { + "type": "object", + "additionalProperties": { + "type": "string", + "nullable": true + }, + "description": "Zbiór dodatkowych informacji związanych ze statusem faktury, zapisanych jako pary klucz–wartość.\nUmożliwia rozszerzenie modelu o dane specyficzne dla danego przypadku.", + "nullable": true + } + }, + "additionalProperties": false + }, + "InvoiceType": { + "enum": [ + "Vat", + "Zal", + "Kor", + "Roz", + "Upr", + "KorZal", + "KorRoz", + "VatPef", + "VatPefSp", + "KorPef", + "VatRr", + "KorVatRr" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n" + }, + "InvoicingMode": { + "enum": [ + "Online", + "Offline" + ], + "type": "string" + }, + "KsefCertificateType": { + "enum": [ + "Authentication", + "Offline" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" + }, + "KsefNumber": { + "maxLength": 36, + "minLength": 35, + "pattern": "^([1-9](\\d[1-9]|[1-9]\\d)\\d{7})-(20[2-9][0-9]|2[1-9]\\d{2}|[3-9]\\d{3})(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])-([0-9A-F]{6})-?([0-9A-F]{6})-([0-9A-F]{2})$", + "type": "string", + "description": "Numer KSeF o długości 36 znaków jest akceptowany, by zachować kompatybilność wsteczna z KSeF 1.0. W KSeF 2.0 numery są generowane wyłącznie w formacie 35-znakowym." + }, + "Nip": { + "maxLength": 10, + "minLength": 10, + "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}$", + "type": "string", + "description": "10 cyfrowy numer NIP." + }, + "NipVatUe": { + "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}-(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))$", + "type": "string", + "description": "Identyfikator złożony, czyli dwuczłonowy identyfikator składający się z nr NIP podmiotu polskiego oraz numeru VAT UE podmiotu unijnego." + }, + "OnlineSessionContextLimitsOverride": { + "required": [ + "maxInvoices", + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB" + ], + "type": "object", + "properties": { + "maxInvoiceSizeInMB": { + "maximum": 5, + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury w MB.", + "format": "int32" + }, + "maxInvoiceWithAttachmentSizeInMB": { + "maximum": 10, + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", + "format": "int32" + }, + "maxInvoices": { + "maximum": 100000, + "minimum": 0, + "type": "integer", + "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "OnlineSessionEffectiveContextLimits": { + "required": [ + "maxInvoices", + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB" + ], + "type": "object", + "properties": { + "maxInvoiceSizeInMB": { + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury w MB.", + "format": "int32" + }, + "maxInvoiceWithAttachmentSizeInMB": { + "minimum": 0, + "type": "integer", + "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", + "format": "int32" + }, + "maxInvoices": { + "minimum": 0, + "type": "integer", + "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "OpenBatchSessionRequest": { + "required": [ + "batchFile", + "encryption", + "formCode" + ], + "type": "object", + "properties": { + "formCode": { + "required": [ + "systemCode", + "schemaVersion", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/FormCode" + } + ], + "description": "Schemat faktur wysyłanych w ramach sesji.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| [FA (2)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n" + }, + "batchFile": { + "required": [ + "fileSize", + "fileHash", + "fileParts" + ], + "allOf": [ + { + "$ref": "#/components/schemas/BatchFileInfo" + } + ], + "description": "Informacje o przesyłanej paczce faktur." + }, + "encryption": { + "required": [ + "encryptedSymmetricKey", + "initializationVector" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EncryptionInfo" + } + ], + "description": "Symetryczny klucz szyfrujący plik paczki, zaszyfrowany kluczem publicznym Ministerstwa Finansów." + }, + "offlineMode": { + "type": "boolean", + "description": "Określa, czy podatnik deklaruje tryb fakturowania \"offline\" dla dokumentów przesyłanych w sesji wsadowej.", + "default": false + } + }, + "additionalProperties": false + }, + "OpenBatchSessionResponse": { + "required": [ + "partUploadRequests", + "referenceNumber" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny sesji." + }, + "partUploadRequests": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PartUploadRequest" + }, + "description": "Dane wymagane do poprawnego przesłania poszczególnych części pliku paczki faktur.\n\nKażdą część pliku paczki zadeklarowaną w fileParts należy przesłać zgodnie z odpowiadającym jej obiektem w partUploadRequests.\nŁącznikiem pomiędzy deklaracją a instrukcją wysyłki jest pole ordinalNumber.\n\nDla każdej części należy:\n* zastosować metodę HTTP wskazaną w method,\n* ustawić adres z url,\n* dołączyć nagłówki z headers,\n* dołączyć treść części pliku w korpusie żądania.\n\n`Uwaga: nie należy dodawać do nagłówków token dostępu (accessToken).`\n \nKażdą część przesyła się oddzielnym żądaniem HTTP.Zwracane kody odpowiedzi:\n * 201 – poprawne przyjęcie pliku,\n * 400 – błędne dane,\n * 401 – nieprawidłowe uwierzytelnienie,\n * 403 – brak uprawnień do zapisu (np.upłynął czas na zapis)." + } + }, + "additionalProperties": false + }, + "OpenOnlineSessionRequest": { + "required": [ + "encryption", + "formCode" + ], + "type": "object", + "properties": { + "formCode": { + "required": [ + "systemCode", + "schemaVersion", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/FormCode" + } + ], + "description": "Schemat faktur wysyłanych w ramach sesji.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| [FA (2)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n| [PEF (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF(3)_v2-1.xsd) | 2-1 | PEF |\n| [PEF_KOR (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF_KOR(3)_v2-1.xsd) | 2-1 | PEF |\n" + }, + "encryption": { + "required": [ + "encryptedSymmetricKey", + "initializationVector" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EncryptionInfo" + } + ], + "description": "Symetryczny klucz szyfrujący pliki XML, zaszyfrowany kluczem publicznym Ministerstwa Finansów." + } + }, + "additionalProperties": false + }, + "OpenOnlineSessionResponse": { + "required": [ + "referenceNumber", + "validUntil" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny sesji." + }, + "validUntil": { + "type": "string", + "description": "Termin ważności sesji. Po jego upływie sesja zostanie automatycznie zamknięta.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "PartUploadRequest": { + "required": [ + "headers", + "method", + "ordinalNumber", + "url" + ], + "type": "object", + "properties": { + "ordinalNumber": { + "minimum": 1, + "type": "integer", + "description": "Numer sekwencyjny części pliku paczki.", + "format": "int32" + }, + "method": { + "type": "string", + "description": "Metoda HTTP, której należy użyć przy wysyłce części pliku paczki." + }, + "url": { + "type": "string", + "description": "Adres pod który należy wysłać część pliku paczki.", + "format": "uri" + }, + "headers": { + "type": "object", + "additionalProperties": { + "type": "string", + "nullable": true + }, + "description": "Nagłówki, których należy użyć przy wysyłce części pliku paczki." + } + }, + "additionalProperties": false + }, + "PeppolId": { + "maxLength": 9, + "minLength": 9, + "pattern": "^P[A-Z]{2}[0-9]{6}$", + "type": "string", + "description": "Identyfikator dostawcy usług Peppol." + }, + "PeppolProvider": { + "required": [ + "dateCreated", + "id", + "name" + ], + "type": "object", + "properties": { + "id": { + "allOf": [ + { + "$ref": "#/components/schemas/PeppolId" + } + ], + "description": "Identyfikator dostawcy usług Peppol." + }, + "name": { + "maxLength": 256, + "type": "string", + "description": "Nazwa dostawcy usług Peppol." + }, + "dateCreated": { + "type": "string", + "description": "Data rejestracji dostawcy usług Peppol w systemie.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "PermissionId": { + "maxLength": 36, + "minLength": 36, + "type": "string", + "description": "Techniczny identyfikator nadanego uprawnienia – wymagany m.in. przy operacjach odbierania." + }, + "PermissionState": { + "enum": [ + "Active", + "Inactive" + ], + "type": "string" + }, + "PermissionsEuEntityDetails": { + "required": [ + "address", + "fullName" + ], + "type": "object", + "properties": { + "fullName": { + "maxLength": 100, + "type": "string", + "description": "Pełna nazwa podmiotu unijnego." + }, + "address": { + "maxLength": 512, + "type": "string", + "description": "Adres podmiotu unijnego." + } + }, + "additionalProperties": false + }, + "PermissionsOperationResponse": { + "required": [ + "referenceNumber" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny operacji nadania lub odbierania uprawnień." + } + }, + "additionalProperties": false + }, + "PermissionsOperationStatusResponse": { + "required": [ + "status" + ], + "type": "object", + "properties": { + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/StatusInfo" + } + ], + "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Operacja przyjęta do realizacji | - |\n| 200 | Operacja zakończona sukcesem | - |\n| 400 | Operacja zakończona niepowodzeniem | - |\n| 410 | Podane identyfikatory są niezgodne lub pozostają w niewłaściwej relacji | - |\n| 420 | Użyte poświadczenia nie mają uprawnień do wykonania tej operacji | - |\n| 430 | Kontekst identyfikatora nie odpowiada wymaganej roli lub uprawnieniom | - |\n| 440 | Operacja niedozwolona dla wskazanych powiązań identyfikatorów | - |\n| 450 | Operacja niedozwolona dla wskazanego identyfikatora lub jego typu | - |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie później. |" + } + }, + "additionalProperties": false + }, + "PermissionsSubjectEntityByFingerprintDetails": { + "required": [ + "fullName", + "subjectDetailsType" + ], + "type": "object", + "properties": { + "subjectDetailsType": { + "allOf": [ + { + "$ref": "#/components/schemas/EntitySubjectByFingerprintDetailsType" + } + ], + "description": "Typ danych podmiotu uprawnionego.\n| Wartość | Opis |\n| --- | --- |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" + }, + "fullName": { + "maxLength": 100, + "type": "string", + "description": "Pełna nazwa podmiotu." + }, + "address": { + "maxLength": 512, + "type": "string", + "description": "Adres podmiotu.", + "nullable": true + } + }, + "additionalProperties": false + }, + "PermissionsSubjectEntityByIdentifierDetails": { + "required": [ + "fullName", + "subjectDetailsType" + ], + "type": "object", + "properties": { + "subjectDetailsType": { + "allOf": [ + { + "$ref": "#/components/schemas/EntitySubjectByIdentifierDetailsType" + } + ], + "description": "Typ danych podmiotu uprawnionego.\n| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n" + }, + "fullName": { + "maxLength": 100, + "type": "string", + "description": "Pełna nazwa podmiotu." + } + }, + "additionalProperties": false + }, + "PermissionsSubjectEntityDetails": { + "required": [ + "fullName", + "subjectDetailsType" + ], + "type": "object", + "properties": { + "subjectDetailsType": { + "allOf": [ + { + "$ref": "#/components/schemas/EntitySubjectDetailsType" + } + ], + "description": "Typ danych podmiotu uprawnionego.\n| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" + }, + "fullName": { + "maxLength": 100, + "type": "string", + "description": "Pełna nazwa podmiotu." + }, + "address": { + "maxLength": 512, + "type": "string", + "description": "Adres podmiotu.", + "nullable": true + } + }, + "additionalProperties": false + }, + "PermissionsSubjectPersonByFingerprintDetails": { + "required": [ + "firstName", + "lastName", + "subjectDetailsType" + ], + "type": "object", + "properties": { + "subjectDetailsType": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonSubjectByFingerprintDetailsType" + } + ], + "description": "Typ danych uprawnionej osoby fizycznej.\n| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" + }, + "firstName": { + "maxLength": 30, + "minLength": 2, + "type": "string", + "description": "Imię osoby fizycznej." + }, + "lastName": { + "maxLength": 81, + "minLength": 2, + "type": "string", + "description": "Nazwisko osoby fizycznej." + }, + "personIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonIdentifier" + } + ], + "description": "Identyfikator osoby fizycznej.", + "nullable": true + }, + "birthDate": { + "type": "string", + "description": "Data urodzenia osoby fizycznej.", + "format": "date", + "nullable": true + }, + "idDocument": { + "required": [ + "type", + "number", + "country" + ], + "allOf": [ + { + "$ref": "#/components/schemas/IdDocument" + } + ], + "description": "Dane dokumentu tożsamości osoby fizycznej.", + "nullable": true + } + }, + "additionalProperties": false + }, + "PermissionsSubjectPersonDetails": { + "required": [ + "firstName", + "lastName", + "subjectDetailsType" + ], + "type": "object", + "properties": { + "subjectDetailsType": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonSubjectDetailsType" + } + ], + "description": "Typ danych uprawnionej osoby fizycznej.\n| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" + }, + "firstName": { + "maxLength": 30, + "minLength": 2, + "type": "string", + "description": "Imię osoby fizycznej." + }, + "lastName": { + "maxLength": 81, + "minLength": 2, + "type": "string", + "description": "Nazwisko osoby fizycznej." + }, + "personIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonIdentifier" + } + ], + "description": "Identyfikator osoby fizycznej.", + "nullable": true + }, + "birthDate": { + "type": "string", + "description": "Data urodzenia osoby fizycznej.", + "format": "date", + "nullable": true + }, + "idDocument": { + "required": [ + "type", + "number", + "country" + ], + "allOf": [ + { + "$ref": "#/components/schemas/IdDocument" + } + ], + "description": "Dane dokumentu tożsamości osoby fizycznej.", + "nullable": true + } + }, + "additionalProperties": false + }, + "PersonByFingerprintWithIdentifierDetails": { + "required": [ + "firstName", + "identifier", + "lastName" + ], + "type": "object", + "properties": { + "firstName": { + "maxLength": 30, + "minLength": 2, + "type": "string", + "description": "Imię osoby fizycznej." + }, + "lastName": { + "maxLength": 81, + "minLength": 2, + "type": "string", + "description": "Nazwisko osoby fizycznej." + }, + "identifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonIdentifier" + } + ], + "description": "Identyfikator osoby fizycznej." + } + }, + "additionalProperties": false + }, + "PersonByFingerprintWithoutIdentifierDetails": { + "required": [ + "birthDate", + "firstName", + "idDocument", + "lastName" + ], + "type": "object", + "properties": { + "firstName": { + "maxLength": 30, + "minLength": 2, + "type": "string", + "description": "Imię osoby fizycznej." + }, + "lastName": { + "maxLength": 81, + "minLength": 2, + "type": "string", + "description": "Nazwisko osoby fizycznej." + }, + "birthDate": { + "type": "string", + "description": "Data urodzenia osoby fizycznej.", + "format": "date" + }, + "idDocument": { + "required": [ + "type", + "number", + "country" + ], + "allOf": [ + { + "$ref": "#/components/schemas/IdDocument" + } + ], + "description": "Dane dokumentu tożsamości osoby fizycznej." + } + }, + "additionalProperties": false + }, + "PersonCreateRequest": { + "required": [ + "description", + "isBailiff", + "nip", + "pesel" + ], + "type": "object", + "properties": { + "nip": { + "$ref": "#/components/schemas/Nip" + }, + "pesel": { + "$ref": "#/components/schemas/Pesel" + }, + "isBailiff": { + "type": "boolean" + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string" + }, + "isDeceased": { + "type": "boolean" + }, + "createdDate": { + "type": "string", + "description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "PersonDetails": { + "required": [ + "firstName", + "lastName" + ], + "type": "object", + "properties": { + "firstName": { + "maxLength": 30, + "minLength": 2, + "type": "string", + "description": "Imię osoby fizycznej." + }, + "lastName": { + "maxLength": 81, + "minLength": 2, + "type": "string", + "description": "Nazwisko osoby fizycznej." + } + }, + "additionalProperties": false + }, + "PersonIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 11, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false + }, + "PersonIdentifierType": { + "enum": [ + "Pesel", + "Nip" + ], + "type": "string", + "description": "Typ identyfikatora osoby fizycznej." + }, + "PersonPermission": { + "required": [ + "authorIdentifier", + "authorizedIdentifier", + "canDelegate", + "description", + "id", + "permissionScope", + "permissionState", + "startDate" + ], + "type": "object", + "properties": { + "id": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionId" + } + ], + "description": "Identyfikator uprawnienia." + }, + "authorizedIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifier" + } + ], + "description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsContextIdentifier" + } + ], + "description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "targetIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsTargetIdentifier" + } + ], + "description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "authorIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsAuthorIdentifier" + } + ], + "description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |" + }, + "permissionScope": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionScope" + } + ], + "description": "Rodzaj uprawnienia." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia." + }, + "subjectPersonDetails": { + "required": [ + "subjectDetailsType", + "firstName", + "lastName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectPersonDetails" + } + ], + "description": "Dane osoby uprawnionej.", + "nullable": true + }, + "subjectEntityDetails": { + "required": [ + "subjectDetailsType", + "fullName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectEntityDetails" + } + ], + "description": "Dane podmiotu uprawnionego.", + "nullable": true + }, + "permissionState": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionState" + } + ], + "description": "Stan uprawnienia." + }, + "startDate": { + "type": "string", + "description": "Data rozpoczęcia obowiązywania uprawnienia.", + "format": "date-time" + }, + "canDelegate": { + "type": "boolean", + "description": "Flaga określająca, czy uprawnienie ma być możliwe do dalszego przekazywania." + } + }, + "additionalProperties": false + }, + "PersonPermissionScope": { + "enum": [ + "CredentialsManage", + "CredentialsRead", + "InvoiceWrite", + "InvoiceRead", + "Introspection", + "SubunitManage", + "EnforcementOperations" + ], + "type": "string" + }, + "PersonPermissionSubjectDetails": { + "required": [ + "subjectDetailsType" + ], + "type": "object", + "properties": { + "subjectDetailsType": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionSubjectDetailsType" + } + ], + "description": "Typ danych podmiotu.\n| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" + }, + "personById": { + "required": [ + "firstName", + "lastName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonDetails" + } + ], + "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByIdentifier.*", + "nullable": true + }, + "personByFpWithId": { + "required": [ + "firstName", + "lastName", + "identifier" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonByFingerprintWithIdentifierDetails" + } + ], + "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithIdentifier.*", + "nullable": true + }, + "personByFpNoId": { + "required": [ + "firstName", + "lastName", + "birthDate", + "idDocument" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonByFingerprintWithoutIdentifierDetails" + } + ], + "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithoutIdentifier.*", + "nullable": true + } + }, + "additionalProperties": false + }, + "PersonPermissionSubjectDetailsType": { + "enum": [ + "PersonByIdentifier", + "PersonByFingerprintWithIdentifier", + "PersonByFingerprintWithoutIdentifier" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" + }, + "PersonPermissionType": { + "enum": [ + "CredentialsManage", + "CredentialsRead", + "InvoiceWrite", + "InvoiceRead", + "Introspection", + "SubunitManage", + "EnforcementOperations" + ], + "type": "string" + }, + "PersonPermissionsAuthorIdentifier": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsAuthorIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora. W przypadku typu System należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |" + }, + "PersonPermissionsAuthorIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint", + "System" + ], + "type": "string" + }, + "PersonPermissionsAuthorizedIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "PersonPermissionsAuthorizedIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "PersonPermissionsContextIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsContextIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 16, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" + }, + "PersonPermissionsContextIdentifierType": { + "enum": [ + "Nip", + "InternalId" + ], + "type": "string" + }, + "PersonPermissionsGrantRequest": { + "required": [ + "description", + "permissions", + "subjectDetails", + "subjectIdentifier" + ], + "type": "object", + "properties": { + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsSubjectIdentifier" + } + ], + "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PersonPermissionType" + }, + "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia" + }, + "subjectDetails": { + "required": [ + "subjectDetailsType" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionSubjectDetails" + } + ], + "description": "Dane podmiotu, któremu nadawane są uprawnienia." + } + }, + "additionalProperties": false + }, + "PersonPermissionsQueryRequest": { + "required": [ + "queryType" + ], + "type": "object", + "properties": { + "authorIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsAuthorIdentifier" + } + ], + "description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |", + "nullable": true + }, + "authorizedIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifier" + } + ], + "description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |", + "nullable": true + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsContextIdentifier" + } + ], + "description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "targetIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsTargetIdentifier" + } + ], + "description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "permissionTypes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PersonPermissionType" + }, + "description": "Lista rodzajów wyszukiwanych uprawnień.", + "nullable": true + }, + "permissionState": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionState" + } + ], + "description": "Stan uprawnienia. \n| Type | Value |\n| --- | --- |\n| Active | Uprawnienia aktywne |\n| Inactive | Uprawnienia nieaktywne, nadane w sposób pośredni |", + "nullable": true + }, + "queryType": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsQueryType" + } + ], + "description": "Typ zapytania.\n| Type | Value |\n| --- | --- |\n| PermissionsInCurrentContext | Lista uprawnień obowiązujących w bieżącym kontekście |\n| PermissionsGrantedInCurrentContext | Lista uprawnień nadanych w bieżącym kontekście |" + } + }, + "additionalProperties": false + }, + "PersonPermissionsQueryType": { + "enum": [ + "PermissionsInCurrentContext", + "PermissionsGrantedInCurrentContext" + ], + "type": "string" + }, + "PersonPermissionsSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "PersonPermissionsSubjectIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "PersonPermissionsTargetIdentifier": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionsTargetIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 16, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" + }, + "PersonPermissionsTargetIdentifierType": { + "enum": [ + "Nip", + "AllPartners", + "InternalId" + ], + "type": "string" + }, + "PersonRemoveRequest": { + "required": [ + "nip" + ], + "type": "object", + "properties": { + "nip": { + "$ref": "#/components/schemas/Nip" + } + }, + "additionalProperties": false + }, + "PersonSubjectByFingerprintDetailsType": { + "enum": [ + "PersonByFingerprintWithIdentifier", + "PersonByFingerprintWithoutIdentifier" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" + }, + "PersonSubjectDetailsType": { + "enum": [ + "PersonByIdentifier", + "PersonByFingerprintWithIdentifier", + "PersonByFingerprintWithoutIdentifier" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" + }, + "PersonalPermission": { + "required": [ + "canDelegate", + "description", + "id", + "permissionScope", + "permissionState", + "startDate" + ], + "type": "object", + "properties": { + "id": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionId" + } + ], + "description": "Identyfikator uprawnienia." + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsContextIdentifier" + } + ], + "description": "Identyfikator kontekstu podmiotu, który nadał uprawnienia do obsługi faktur.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "authorizedIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsAuthorizedIdentifier" + } + ], + "description": "Identyfikator podmiotu uprawnionego, jeżeli jest inny niż identyfikator uwierzytelnionego klienta API.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", + "nullable": true + }, + "targetIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsTargetIdentifier" + } + ], + "description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "permissionScope": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionScope" + } + ], + "description": "Rodzaj uprawnienia." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia." + }, + "subjectPersonDetails": { + "required": [ + "subjectDetailsType", + "firstName", + "lastName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectPersonDetails" + } + ], + "description": "Dane osoby uprawnionej.", + "nullable": true + }, + "subjectEntityDetails": { + "required": [ + "subjectDetailsType", + "fullName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectEntityDetails" + } + ], + "description": "Dane podmiotu uprawnionego.", + "nullable": true + }, + "permissionState": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionState" + } + ], + "description": "Stan uprawnienia." + }, + "startDate": { + "type": "string", + "description": "Data rozpoczęcia obowiązywania uprawnienia.", + "format": "date-time" + }, + "canDelegate": { + "type": "boolean", + "description": "Flaga określająca, czy uprawnienie ma być możliwe do dalszego przekazywania." + } + }, + "additionalProperties": false + }, + "PersonalPermissionScope": { + "enum": [ + "CredentialsManage", + "CredentialsRead", + "InvoiceWrite", + "InvoiceRead", + "Introspection", + "SubunitManage", + "EnforcementOperations", + "VatUeManage" + ], + "type": "string" + }, + "PersonalPermissionType": { + "enum": [ + "CredentialsManage", + "CredentialsRead", + "InvoiceWrite", + "InvoiceRead", + "Introspection", + "SubunitManage", + "EnforcementOperations", + "VatUeManage" + ], + "type": "string" + }, + "PersonalPermissionsAuthorizedIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsAuthorizedIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu uprawnionego, jeżeli jest inny niż identyfikator uwierzytelnionego klienta API.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "PersonalPermissionsAuthorizedIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "PersonalPermissionsContextIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsContextIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 16, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator kontekstu podmiotu, który nadał uprawnienia do obsługi faktur.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" + }, + "PersonalPermissionsContextIdentifierType": { + "enum": [ + "Nip", + "InternalId" + ], + "type": "string" + }, + "PersonalPermissionsQueryRequest": { + "type": "object", + "properties": { + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsContextIdentifier" + } + ], + "description": "Identyfikator kontekstu podmiotu, który nadał uprawnienia do obsługi faktur.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "targetIdentifier": { + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsTargetIdentifier" + } + ], + "description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", + "nullable": true + }, + "permissionTypes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PersonalPermissionType" + }, + "description": "Lista rodzajów wyszukiwanych uprawnień.", + "nullable": true + }, + "permissionState": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionState" + } + ], + "description": "Stan uprawnienia. \n| Type | Value |\n| --- | --- |\n| Active | Uprawnienia aktywne |\n| Inactive | Uprawnienia nieaktywne |", + "nullable": true + } + }, + "additionalProperties": false + }, + "PersonalPermissionsTargetIdentifier": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/PersonalPermissionsTargetIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 16, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", + "nullable": true + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" + }, + "PersonalPermissionsTargetIdentifierType": { + "enum": [ + "Nip", + "AllPartners", + "InternalId" + ], + "type": "string" + }, + "Pesel": { + "maxLength": 11, + "minLength": 11, + "pattern": "^\\d{2}(?:0[1-9]|1[0-2]|2[1-9]|3[0-2]|4[1-9]|5[0-2]|6[1-9]|7[0-2]|8[1-9]|9[0-2])\\d{7}$", + "type": "string", + "description": "11 cyfrowy numer PESEL." + }, + "PublicKeyCertificate": { + "required": [ + "certificate", + "usage", + "validFrom", + "validTo" + ], + "type": "object", + "properties": { + "certificate": { + "type": "string", + "description": "Certyfikat klucza publicznego w formacie DER, zakodowany w formacie Base64.", + "format": "byte" + }, + "validFrom": { + "type": "string", + "description": "Data początku obowiązywania certyfikatu.", + "format": "date-time" + }, + "validTo": { + "type": "string", + "description": "Data końca obowiązywania certyfikatu.", + "format": "date-time" + }, + "usage": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PublicKeyCertificateUsage" + }, + "description": "Operacje do których może być używany certyfikat.\n| Wartość | Opis |\n| --- | --- |\n| KsefTokenEncryption | Szyfrowanie tokenów KSeF przesyłanych w trakcie procesu uwierzytelniania. |\n| SymmetricKeyEncryption | Szyfrowanie klucza symetrycznego wykorzystywanego do szyfrowania przesyłanych faktur. |\n" + } + }, + "additionalProperties": false + }, + "PublicKeyCertificateUsage": { + "enum": [ + "KsefTokenEncryption", + "SymmetricKeyEncryption" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| KsefTokenEncryption | Szyfrowanie tokenów KSeF przesyłanych w trakcie procesu uwierzytelniania. |\n| SymmetricKeyEncryption | Szyfrowanie klucza symetrycznego wykorzystywanego do szyfrowania przesyłanych faktur. |\n" + }, + "QueryCertificatesRequest": { + "type": "object", + "properties": { + "certificateSerialNumber": { + "type": "string", + "description": "Numer seryjny certyfikatu. Wyszukiwanie odbywa się na zasadzie dokładnego dopasowania (exact match).", + "nullable": true + }, + "name": { + "type": "string", + "description": "Nazwa własna certyfikatu. Wyszukiwanie jest częściowe, czyli zwracane są certyfikaty, których nazwa zawiera podany ciąg znaków (contains).", + "nullable": true + }, + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/KsefCertificateType" + } + ], + "description": "Typ certyfikatu KSeF.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n", + "nullable": true + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/CertificateListItemStatus" + } + ], + "description": "Status certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n", + "nullable": true + }, + "expiresAfter": { + "type": "string", + "description": "Filtruje certyfikaty, które wygasają po podanej dacie.", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "QueryCertificatesResponse": { + "required": [ + "certificates", + "hasMore" + ], + "type": "object", + "properties": { + "certificates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CertificateListItem" + }, + "description": "Lista certyfikatów spełniających kryteria wyszukiwania." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QueryEntityAuthorizationPermissionsResponse": { + "required": [ + "authorizationGrants", + "hasMore" + ], + "type": "object", + "properties": { + "authorizationGrants": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EntityAuthorizationGrant" + }, + "description": "Lista odczytanych uprawnień." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QueryEntityRolesResponse": { + "required": [ + "hasMore", + "roles" + ], + "type": "object", + "properties": { + "roles": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EntityRole" + }, + "description": "Lista odczytanych ról podmiotu." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QueryEuEntityPermissionsResponse": { + "required": [ + "hasMore", + "permissions" + ], + "type": "object", + "properties": { + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EuEntityPermission" + }, + "description": "Lista odczytanych uprawnień." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QueryInvoicesMetadataResponse": { + "required": [ + "hasMore", + "invoices", + "isTruncated" + ], + "type": "object", + "properties": { + "hasMore": { + "type": "boolean", + "description": "Określa, czy istnieją kolejne wyniki zapytania." + }, + "isTruncated": { + "type": "boolean", + "description": "Określa, czy osiągnięto maksymalny dopuszczalny zakres wyników zapytania (10 000)." + }, + "permanentStorageHwmDate": { + "type": "string", + "description": "Dotyczy wyłącznie zapytań filtrowanych po typie daty PermanentStorage.\nJeśli zapytanie dotyczyło najnowszego okresu, wartość ta może być wartością nieznacznie skorygowaną względem górnej granicy podanej w warunkach zapytania.\nDla okresów starszych, będzie to zgodne z warunkami zapytania. \n\nWartość jest stała dla wszystkich stron tego samego zapytania\ni nie zależy od paginacji ani sortowania.\n\nSystem gwarantuje, że dane poniżej tej wartości są spójne i kompletne.\nPonowne zapytania obejmujące zakresem dane poniżej tego kroczącego znacznika czasu nie zwrócą w przyszłości innych wyników (np.dodatkowych faktur). \n\nDla dateType = Issue lub Invoicing – null.", + "format": "date-time", + "nullable": true + }, + "invoices": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InvoiceMetadata" + }, + "description": "Lista faktur spełniających kryteria." + } + }, + "additionalProperties": false + }, + "QueryPeppolProvidersResponse": { + "required": [ + "hasMore", + "peppolProviders" + ], + "type": "object", + "properties": { + "peppolProviders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PeppolProvider" + }, + "description": "Lista dostawców usług Peppol." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QueryPersonPermissionsResponse": { + "required": [ + "hasMore", + "permissions" + ], + "type": "object", + "properties": { + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PersonPermission" + }, + "description": "Lista odczytanych uprawnień." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QueryPersonalPermissionsResponse": { + "required": [ + "hasMore", + "permissions" + ], + "type": "object", + "properties": { + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PersonalPermission" + }, + "description": "Lista odczytanych uprawnień." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QuerySubordinateEntityRolesResponse": { + "required": [ + "hasMore", + "roles" + ], + "type": "object", + "properties": { + "roles": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SubordinateEntityRole" + }, + "description": "Lista odczytanych podmiotów podrzędnych i ich ról." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QuerySubunitPermissionsResponse": { + "required": [ + "hasMore", + "permissions" + ], + "type": "object", + "properties": { + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SubunitPermission" + }, + "description": "Lista odczytanych uprawnień." + }, + "hasMore": { + "type": "boolean", + "description": "Flaga informująca o dostępności kolejnej strony wyników." + } + }, + "additionalProperties": false + }, + "QueryTokensResponse": { + "required": [ + "tokens" + ], + "type": "object", + "properties": { + "continuationToken": { + "type": "string", + "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", + "nullable": true + }, + "tokens": { + "type": "array", + "items": { + "$ref": "#/components/schemas/QueryTokensResponseItem" + }, + "description": "Lista tokenów uwierzytelniających." + } + }, + "additionalProperties": false + }, + "QueryTokensResponseItem": { + "required": [ + "authorIdentifier", + "contextIdentifier", + "dateCreated", + "description", + "referenceNumber", + "requestedPermissions", + "status" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny tokena KSeF." + }, + "authorIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenAuthorIdentifierTypeIdentifier" + } + ], + "description": "Identyfikator osoby która wygenerowała token." + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenContextIdentifierTypeIdentifier" + } + ], + "description": "Identyfikator kontekstu, w którym został wygenerowany token i do którego daje dostęp." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis tokena." + }, + "requestedPermissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TokenPermissionType" + }, + "description": "Uprawnienia przypisane tokenowi." + }, + "dateCreated": { + "type": "string", + "description": "Data i czas utworzenia tokena.", + "format": "date-time" + }, + "lastUseDate": { + "type": "string", + "description": "Data ostatniego użycia tokena.", + "format": "date-time", + "nullable": true + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/AuthenticationTokenStatus" + } + ], + "description": "Status tokena.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n" + }, + "statusDetails": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Dodatkowe informacje na temat statusu, zwracane w przypadku błędów.", + "nullable": true + } + }, + "additionalProperties": false + }, + "QueryType": { + "enum": [ + "Granted", + "Received" + ], + "type": "string" + }, + "ReferenceNumber": { + "maxLength": 36, + "minLength": 36, + "type": "string", + "description": "Numer referencyjny." + }, + "RetrieveCertificatesListItem": { + "required": [ + "certificate", + "certificateName", + "certificateSerialNumber", + "certificateType" + ], + "type": "object", + "properties": { + "certificate": { + "type": "string", + "description": "Certyfikat w formacie DER, zakodowany w formacie Base64.", + "format": "byte" + }, + "certificateName": { + "type": "string", + "description": "Nazwa własna certyfikatu." + }, + "certificateSerialNumber": { + "type": "string", + "description": "Numer seryjny certyfikatu." + }, + "certificateType": { + "allOf": [ + { + "$ref": "#/components/schemas/KsefCertificateType" + } + ], + "description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" + } + }, + "additionalProperties": false + }, + "RetrieveCertificatesRequest": { + "required": [ + "certificateSerialNumbers" + ], + "type": "object", + "properties": { + "certificateSerialNumbers": { + "maxItems": 10, + "minItems": 1, + "type": "array", + "items": { + "type": "string" + }, + "description": "Numery seryjne certyfikatów do pobrania." + } + }, + "additionalProperties": false + }, + "RetrieveCertificatesResponse": { + "required": [ + "certificates" + ], + "type": "object", + "properties": { + "certificates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RetrieveCertificatesListItem" + }, + "description": "Pobrane certyfikaty." + } + }, + "additionalProperties": false + }, + "RetryAfter": { + "type": "integer", + "description": "Liczba sekund po których można ponowić żądanie.", + "format": "int32", + "example": 30 + }, + "RevokeCertificateRequest": { + "type": "object", + "properties": { + "revocationReason": { + "allOf": [ + { + "$ref": "#/components/schemas/CertificateRevocationReason" + } + ], + "description": "Powód unieważnienia certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Unspecified | Nieokreślony. |\n| Superseded | Certyfikat został zastąpiony przez inny. |\n| KeyCompromise | Klucz prywatny powiązany z certyfikatem został skompromitowany. |\n", + "nullable": true + } + }, + "additionalProperties": false + }, + "SendInvoiceRequest": { + "required": [ + "encryptedInvoiceContent", + "encryptedInvoiceHash", + "encryptedInvoiceSize", + "invoiceHash", + "invoiceSize" + ], + "type": "object", + "properties": { + "invoiceHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 oryginalnej faktury, zakodowany w formacie Base64." + }, + "invoiceSize": { + "minimum": 1, + "type": "integer", + "description": "Rozmiar oryginalnej faktury w bajtach. Maksymalny rozmiar zależy od limitów ustawionych dla uwierzytelnionego kontekstu.", + "format": "int64" + }, + "encryptedInvoiceHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 zaszyfrowanej faktury, zakodowany w formacie Base64." + }, + "encryptedInvoiceSize": { + "minimum": 1, + "type": "integer", + "description": "Rozmiar zaszyfrowanej faktury w bajtach.", + "format": "int64" + }, + "encryptedInvoiceContent": { + "type": "string", + "description": "Faktura zaszyfrowana algorytmem AES-256-CBC z dopełnianiem PKCS#7 (kluczem przekazanym przy otwarciu sesji), zakodowana w formacie Base64.", + "format": "byte" + }, + "offlineMode": { + "type": "boolean", + "description": "Określa, czy podatnik deklaruje tryb fakturowania \"offline\" dla przesyłanego dokumentu.", + "default": false + }, + "hashOfCorrectedInvoice": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 korygowanej faktury, zakodowany w formacie Base64. Wymagany przy wysyłaniu korekty technicznej faktury.", + "nullable": true + } + }, + "additionalProperties": false + }, + "SendInvoiceResponse": { + "required": [ + "referenceNumber" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny faktury." + } + }, + "additionalProperties": false + }, + "SessionInvoiceStatusResponse": { + "required": [ + "invoiceHash", + "invoicingDate", + "ordinalNumber", + "referenceNumber", + "status" + ], + "type": "object", + "properties": { + "ordinalNumber": { + "minimum": 1, + "type": "integer", + "description": "Numer sekwencyjny faktury w ramach sesji.", + "format": "int32" + }, + "invoiceNumber": { + "maxLength": 256, + "type": "string", + "description": "Numer faktury.", + "nullable": true + }, + "ksefNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/KsefNumber" + } + ], + "description": "Numer KSeF.", + "nullable": true + }, + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny faktury." + }, + "invoiceHash": { + "allOf": [ + { + "$ref": "#/components/schemas/Sha256HashBase64" + } + ], + "description": "Skrót SHA256 faktury, zakodowany w formacie Base64." + }, + "invoiceFileName": { + "maxLength": 128, + "type": "string", + "description": "Nazwa pliku faktury (zwracana dla faktur wysyłanych wsadowo).", + "nullable": true + }, + "acquisitionDate": { + "type": "string", + "description": "Data nadania numeru KSeF.", + "format": "date-time", + "nullable": true + }, + "invoicingDate": { + "type": "string", + "description": "Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania).", + "format": "date-time" + }, + "permanentStorageDate": { + "type": "string", + "description": "Data trwałego zapisu faktury w repozytorium KSeF. Wartość uzupełniana asynchronicznie w momencie trwałego zapisu; zawsze późniejsza niż acquisitionDate. Podczas sprawdzania statusu może być jeszcze niedostępna.", + "format": "date-time", + "nullable": true + }, + "upoDownloadUrl": { + "type": "string", + "description": "Adres do pobrania UPO. Link generowany jest przy każdym odpytaniu o status. \nDostęp odbywa się metodą `HTTP GET` i nie należy wysyłać tokenu dostępowego. \nLink nie podlega limitom API i wygasa po określonym czasie w `UpoDownloadUrlExpirationDate`.\n\nOdpowiedź HTTP zawiera dodatkowe nagłówki:\n- `x-ms-meta-hash` – skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64.", + "format": "uri", + "nullable": true + }, + "upoDownloadUrlExpirationDate": { + "type": "string", + "description": "Data i godzina wygaśnięcia adresu. Po tej dacie link `UpoDownloadUrl` nie będzie już aktywny.", + "format": "date-time", + "nullable": true + }, + "invoicingMode": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoicingMode" + } + ], + "description": "Tryb fakturowania (online/offline).", + "nullable": true + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/InvoiceStatusInfo" + } + ], + "description": "Status faktury.\n\n| Code | Description | Details | Extensions |\n| --- | --- | --- | ---|\n| 100 | Faktura przyjęta do dalszego przetwarzania | - | - |\n| 150 | Trwa przetwarzanie | - | - |\n| 200 | Sukces | - | - |\n| 405 | Przetwarzanie anulowane z powodu błędu sesji | - | - |\n| 410 | Nieprawidłowy zakres uprawnień | - | - |\n| 415 | Brak możliwości wysyłania faktury z załącznikiem | - | - |\n| 430 | Błąd weryfikacji pliku faktury | - | - |\n| 435 | Błąd odszyfrowania pliku | - | - |\n| 440 | Duplikat faktury | - | 'originalSessionReferenceNumber', 'originalKsefNumber'|\n| 450 | Błąd weryfikacji semantyki dokumentu faktury | - | - |\n| 500 | Nieznany błąd ({statusCode}) | - | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |- |" + } + }, + "additionalProperties": false + }, + "SessionInvoicesResponse": { + "required": [ + "invoices" + ], + "type": "object", + "properties": { + "continuationToken": { + "type": "string", + "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", + "nullable": true + }, + "invoices": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SessionInvoiceStatusResponse" + }, + "description": "Lista pobranych faktur." + } + }, + "additionalProperties": false + }, + "SessionStatusResponse": { + "required": [ + "dateCreated", + "dateUpdated", + "status" + ], + "type": "object", + "properties": { + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/StatusInfo" + } + ], + "description": "Informacje o aktualnym statusie.\n \nSesja wsadowa:\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Sesja wsadowa rozpoczęta | - |\n| 150 | Trwa przetwarzanie | - |\n| 200 | Sesja wsadowa przetworzona pomyślnie | - |\n| 405 | Błąd weryfikacji poprawności dostarczonych elementów paczki | - |\n| 415 | Błąd odszyfrowania dostarczonego klucza | - |\n| 420 | Przekroczony limit faktur w sesji | - |\n| 430 | Błąd dekompresji pierwotnego archiwum | - |\n| 435 | Błąd odszyfrowania zaszyfrowanych części archiwum | - |\n| 440 | Sesja anulowana | Przekroczono czas wysyłki |\n| 440 | Sesja anulowana | Nie przesłano faktur |\n| 445 | Błąd weryfikacji, brak poprawnych faktur | - |\n| 500 | Nieznany błąd ({statusCode}) | - |\n\nSesja interaktywna:\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Sesja interaktywna otwarta | - |\n| 170 | Sesja interaktywna zamknięta | - |\n| 200 | Sesja interaktywna przetworzona pomyślnie | - |\n| 415 | Błąd odszyfrowania dostarczonego klucza | - |\n| 440 | Sesja anulowana | Nie przesłano faktur |\n| 445 | Błąd weryfikacji, brak poprawnych faktur | - |\n| * | description missing | - |" + }, + "dateCreated": { + "type": "string", + "description": "Data utworzenia sesji.", + "format": "date-time" + }, + "dateUpdated": { + "type": "string", + "description": "Data ostatniej aktywności w ramach sesji.", + "format": "date-time" + }, + "validUntil": { + "type": "string", + "description": "Termin ważności sesji. Po jego upływie sesja zostanie automatycznie zamknięta.", + "format": "date-time", + "nullable": true, + "readOnly": true + }, + "upo": { + "required": [ + "pages" + ], + "allOf": [ + { + "$ref": "#/components/schemas/UpoResponse" + } + ], + "description": "Informacja o UPO sesyjnym, zwracana gdy sesja została zamknięta i UPO zostało wygenerowane.", + "nullable": true + }, + "invoiceCount": { + "minimum": 0, + "type": "integer", + "description": "Liczba przyjętych faktur w ramach sesji.", + "format": "int32", + "nullable": true + }, + "successfulInvoiceCount": { + "minimum": 0, + "type": "integer", + "description": "Liczba faktur przeprocesowanych w ramach sesji z sukcesem .", + "format": "int32", + "nullable": true + }, + "failedInvoiceCount": { + "minimum": 0, + "type": "integer", + "description": "Liczba faktur przeprocesowanych w ramach sesji z błędem.", + "format": "int32", + "nullable": true + } + }, + "additionalProperties": false + }, + "SessionType": { + "enum": [ + "Online", + "Batch" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Online | Wysyłka interaktywna (pojedyncze faktury). |\n| Batch | Wysyłka wsadowa (paczka faktur). |\n" + }, + "SessionsQueryResponse": { + "required": [ + "sessions" + ], + "type": "object", + "properties": { + "continuationToken": { + "type": "string", + "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", + "nullable": true + }, + "sessions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SessionsQueryResponseItem" + }, + "description": "Lista sesji." + } + }, + "additionalProperties": false + }, + "SessionsQueryResponseItem": { + "required": [ + "dateCreated", + "dateUpdated", + "failedInvoiceCount", + "referenceNumber", + "status", + "successfulInvoiceCount", + "totalInvoiceCount" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny sesji." + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/StatusInfo" + } + ], + "description": "Status sesji." + }, + "dateCreated": { + "type": "string", + "description": "Data utworzenia sesji.", + "format": "date-time" + }, + "dateUpdated": { + "type": "string", + "description": "Data ostatniej aktywności w ramach sesji.", + "format": "date-time" + }, + "validUntil": { + "type": "string", + "description": "Termin ważności sesji. Po jego upływie sesja interaktywna zostanie automatycznie zamknięta.", + "format": "date-time", + "nullable": true + }, + "totalInvoiceCount": { + "minimum": 0, + "type": "integer", + "description": "Łączna liczba faktur (uwzględnia również te w trakcie przetwarzania).", + "format": "int32" + }, + "successfulInvoiceCount": { + "minimum": 0, + "type": "integer", + "description": "Liczba poprawnie przetworzonych faktur.", + "format": "int32" + }, + "failedInvoiceCount": { + "minimum": 0, + "type": "integer", + "description": "Liczba błędnie przetworzonych faktur.", + "format": "int32" + } + }, + "additionalProperties": false + }, + "SetRateLimitsRequest": { + "required": [ + "rateLimits" + ], + "type": "object", + "properties": { + "rateLimits": { + "required": [ + "onlineSession", + "batchSession", + "invoiceSend", + "invoiceStatus", + "sessionList", + "sessionInvoiceList", + "sessionMisc", + "invoiceMetadata", + "invoiceExport", + "invoiceExportStatus", + "invoiceDownload", + "other" + ], + "allOf": [ + { + "$ref": "#/components/schemas/ApiRateLimitsOverride" + } + ], + "description": "Limity dla ilości żądań do API." + } + }, + "additionalProperties": false + }, + "SetSessionLimitsRequest": { + "required": [ + "batchSession", + "onlineSession" + ], + "type": "object", + "properties": { + "onlineSession": { + "required": [ + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB", + "maxInvoices" + ], + "allOf": [ + { + "$ref": "#/components/schemas/OnlineSessionContextLimitsOverride" + } + ], + "description": "Limity dla sesji interaktywnych." + }, + "batchSession": { + "required": [ + "maxInvoiceSizeInMB", + "maxInvoiceWithAttachmentSizeInMB", + "maxInvoices" + ], + "allOf": [ + { + "$ref": "#/components/schemas/BatchSessionContextLimitsOverride" + } + ], + "description": "Limity dla sesji wsadowych." + } + }, + "additionalProperties": false + }, + "SetSubjectLimitsRequest": { + "type": "object", + "properties": { + "subjectIdentifierType": { + "allOf": [ + { + "$ref": "#/components/schemas/SubjectIdentifierType" + } + ] + }, + "enrollment": { + "allOf": [ + { + "$ref": "#/components/schemas/EnrollmentSubjectLimitsOverride" + } + ], + "nullable": true + }, + "certificate": { + "allOf": [ + { + "$ref": "#/components/schemas/CertificateSubjectLimitsOverride" + } + ], + "nullable": true + } + }, + "additionalProperties": false + }, + "Sha256HashBase64": { + "maxLength": 44, + "minLength": 44, + "type": "string", + "description": "SHA-256 w Base64.", + "format": "byte" + }, + "SortOrder": { + "enum": [ + "Asc", + "Desc" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n" + }, + "StatusInfo": { + "required": [ + "code", + "description" + ], + "type": "object", + "properties": { + "code": { + "type": "integer", + "description": "Kod statusu", + "format": "int32" + }, + "description": { + "minLength": 1, + "type": "string", + "description": "Opis statusu" + }, + "details": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Dodatkowe szczegóły statusu", + "nullable": true + } + }, + "additionalProperties": false + }, + "SubjectCreateRequest": { + "required": [ + "description", + "subjectNip", + "subjectType" + ], + "type": "object", + "properties": { + "subjectNip": { + "$ref": "#/components/schemas/Nip" + }, + "subjectType": { + "allOf": [ + { + "$ref": "#/components/schemas/SubjectType" + } + ] + }, + "subunits": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Subunit" + }, + "nullable": true + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string" + }, + "createdDate": { + "type": "string", + "description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.", + "format": "date-time", + "nullable": true + } + }, + "additionalProperties": false + }, + "SubjectIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "SubjectRemoveRequest": { + "required": [ + "subjectNip" + ], + "type": "object", + "properties": { + "subjectNip": { + "$ref": "#/components/schemas/Nip" + } + }, + "additionalProperties": false + }, + "SubjectType": { + "enum": [ + "EnforcementAuthority", + "VatGroup", + "JST" + ], + "type": "string" + }, + "SubordinateEntityRole": { + "required": [ + "description", + "role", + "startDate", + "subordinateEntityIdentifier" + ], + "type": "object", + "properties": { + "subordinateEntityIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubordinateRoleSubordinateEntityIdentifier" + } + ], + "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "role": { + "allOf": [ + { + "$ref": "#/components/schemas/SubordinateEntityRoleType" + } + ], + "description": "Typ roli - powiązania z podmiotem nadrzędnym." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis powiązania." + }, + "startDate": { + "type": "string", + "description": "Data rozpoczęcia obowiązywania powiązania.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "SubordinateEntityRoleType": { + "enum": [ + "LocalGovernmentSubUnit", + "VatGroupSubUnit" + ], + "type": "string" + }, + "SubordinateEntityRolesQueryRequest": { + "type": "object", + "properties": { + "subordinateEntityIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/EntityPermissionsSubordinateEntityIdentifier" + } + ], + "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", + "nullable": true + } + }, + "additionalProperties": false + }, + "SubordinateRoleSubordinateEntityIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/SubordinateRoleSubordinateEntityIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 10, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" + }, + "SubordinateRoleSubordinateEntityIdentifierType": { + "enum": [ + "Nip" + ], + "type": "string" + }, + "Subunit": { + "required": [ + "description", + "subjectNip" + ], + "type": "object", + "properties": { + "subjectNip": { + "$ref": "#/components/schemas/Nip" + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string" + } + }, + "additionalProperties": false + }, + "SubunitPermission": { + "required": [ + "authorIdentifier", + "authorizedIdentifier", + "description", + "id", + "permissionScope", + "startDate", + "subunitIdentifier" + ], + "type": "object", + "properties": { + "id": { + "allOf": [ + { + "$ref": "#/components/schemas/PermissionId" + } + ], + "description": "Identyfikator uprawnienia." + }, + "authorizedIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsAuthorizedIdentifier" + } + ], + "description": "Identyfikator uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "subunitIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifier" + } + ], + "description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |" + }, + "authorIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsAuthorIdentifier" + } + ], + "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "permissionScope": { + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionScope" + } + ], + "description": "Rodzaj uprawnienia." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia." + }, + "subjectPersonDetails": { + "required": [ + "subjectDetailsType", + "firstName", + "lastName" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PermissionsSubjectPersonDetails" + } + ], + "description": "Dane osoby uprawnionej.", + "nullable": true + }, + "subunitName": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Nazwa jednostki podrzędnej.", + "nullable": true + }, + "startDate": { + "type": "string", + "description": "Data rozpoczęcia obowiązywania uprawnienia.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "SubunitPermissionScope": { + "enum": [ + "CredentialsManage" + ], + "type": "string" + }, + "SubunitPermissionsAuthorIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsAuthorIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "SubunitPermissionsAuthorIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "SubunitPermissionsAuthorizedIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "SubunitPermissionsContextIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsContextIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 16, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" + }, + "SubunitPermissionsContextIdentifierType": { + "enum": [ + "InternalId", + "Nip" + ], + "type": "string" + }, + "SubunitPermissionsGrantRequest": { + "required": [ + "contextIdentifier", + "description", + "subjectDetails", + "subjectIdentifier" + ], + "type": "object", + "properties": { + "subjectIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifier" + } + ], + "description": "Identyfikator podmiotu lub osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsContextIdentifier" + } + ], + "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis uprawnienia" + }, + "subunitName": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Nazwa jednostki podrzędnej. W przypadku jednostki podrzędnej z identyfikatorem wewnętrznym pole jest wymagane.", + "nullable": true + }, + "subjectDetails": { + "required": [ + "subjectDetailsType" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonPermissionSubjectDetails" + } + ], + "description": "Dane podmiotu, któremu nadawane są uprawnienia." + } + }, + "additionalProperties": false + }, + "SubunitPermissionsQueryRequest": { + "type": "object", + "properties": { + "subunitIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifier" + } + ], + "description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |", + "nullable": true + } + }, + "additionalProperties": false + }, + "SubunitPermissionsSubjectIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator podmiotu lub osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" + }, + "SubunitPermissionsSubjectIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "SubunitPermissionsSubunitIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifierType" + } + ], + "description": "Typ identyfikatora." + }, + "value": { + "maxLength": 16, + "minLength": 10, + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false, + "description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |" + }, + "SubunitPermissionsSubunitIdentifierType": { + "enum": [ + "InternalId", + "Nip" + ], + "type": "string" + }, + "TestDataAuthorizedIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/TestDataAuthorizedIdentifierType" + } + ] + }, + "value": { + "maxLength": 64, + "minLength": 10, + "type": "string" + } + }, + "additionalProperties": false + }, + "TestDataAuthorizedIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string" + }, + "TestDataContextIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/TestDataContextIdentifierType" + } + ] + }, + "value": { + "maxLength": 10, + "minLength": 10, + "type": "string" + } + }, + "additionalProperties": false + }, + "TestDataContextIdentifierType": { + "enum": [ + "Nip" + ], + "type": "string" + }, + "TestDataPermission": { + "required": [ + "description", + "permissionType" + ], + "type": "object", + "properties": { + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string" + }, + "permissionType": { + "allOf": [ + { + "$ref": "#/components/schemas/TestDataPermissionType" + } + ] + } + }, + "additionalProperties": false + }, + "TestDataPermissionType": { + "enum": [ + "InvoiceRead", + "InvoiceWrite", + "Introspection", + "CredentialsRead", + "CredentialsManage", + "EnforcementOperations", + "SubunitManage" + ], + "type": "string" + }, + "TestDataPermissionsGrantRequest": { + "required": [ + "authorizedIdentifier", + "contextIdentifier", + "permissions" + ], + "type": "object", + "properties": { + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TestDataContextIdentifier" + } + ] + }, + "authorizedIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TestDataAuthorizedIdentifier" + } + ] + }, + "permissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TestDataPermission" + } + } + }, + "additionalProperties": false + }, + "TestDataPermissionsRevokeRequest": { + "required": [ + "authorizedIdentifier", + "contextIdentifier" + ], + "type": "object", + "properties": { + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TestDataContextIdentifier" + } + ] + }, + "authorizedIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TestDataAuthorizedIdentifier" + } + ] + } + }, + "additionalProperties": false + }, + "ThirdSubjectIdentifierType": { + "enum": [ + "Nip", + "InternalId", + "VatUe", + "Other", + "None" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr. |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora podmiotu trzeciego |\n" + }, + "TokenAuthorIdentifierType": { + "enum": [ + "Nip", + "Pesel", + "Fingerprint" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n" + }, + "TokenAuthorIdentifierTypeIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/TokenAuthorIdentifierType" + } + ], + "description": "Typ identyfikatora.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n" + }, + "value": { + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false + }, + "TokenContextIdentifierType": { + "enum": [ + "Nip", + "InternalId", + "NipVatUe", + "PeppolId" + ], + "type": "string", + "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| InternalId | Identyfikator wewnętrzny. |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}`. |\n| PeppolId | Identyfikator dostawcy usług Peppol. |\n" + }, + "TokenContextIdentifierTypeIdentifier": { + "required": [ + "type", + "value" + ], + "type": "object", + "properties": { + "type": { + "allOf": [ + { + "$ref": "#/components/schemas/TokenContextIdentifierType" + } + ], + "description": "Typ identyfikatora.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| InternalId | Identyfikator wewnętrzny. |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}`. |\n| PeppolId | Identyfikator dostawcy usług Peppol. |\n" + }, + "value": { + "type": "string", + "description": "Wartość identyfikatora." + } + }, + "additionalProperties": false + }, + "TokenInfo": { + "required": [ + "token", + "validUntil" + ], + "type": "object", + "properties": { + "token": { + "type": "string", + "description": "Token w formacie JWT." + }, + "validUntil": { + "type": "string", + "description": "Data ważności tokena.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "TokenPermissionType": { + "enum": [ + "InvoiceRead", + "InvoiceWrite", + "CredentialsRead", + "CredentialsManage", + "SubunitManage", + "EnforcementOperations" + ], + "type": "string" + }, + "TokenStatusResponse": { + "required": [ + "authorIdentifier", + "contextIdentifier", + "dateCreated", + "description", + "referenceNumber", + "requestedPermissions", + "status" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny tokena KSeF." + }, + "authorIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenAuthorIdentifierTypeIdentifier" + } + ], + "description": "Identyfikator osoby która wygenerowała token." + }, + "contextIdentifier": { + "required": [ + "type", + "value" + ], + "allOf": [ + { + "$ref": "#/components/schemas/TokenContextIdentifierTypeIdentifier" + } + ], + "description": "Identyfikator kontekstu, w którym został wygenerowany token i do którego daje dostęp." + }, + "description": { + "maxLength": 256, + "minLength": 5, + "type": "string", + "description": "Opis tokena." + }, + "requestedPermissions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TokenPermissionType" + }, + "description": "Uprawnienia przypisane tokenowi." + }, + "dateCreated": { + "type": "string", + "description": "Data i czas utworzenia tokena.", + "format": "date-time" + }, + "lastUseDate": { + "type": "string", + "description": "Data ostatniego użycia tokena.", + "format": "date-time", + "nullable": true + }, + "status": { + "allOf": [ + { + "$ref": "#/components/schemas/AuthenticationTokenStatus" + } + ], + "description": "Status tokena.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n" + }, + "statusDetails": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Dodatkowe informacje na temat statusu, zwracane w przypadku błędów.", + "nullable": true + } + }, + "additionalProperties": false + }, + "TooManyRequestsResponse": { + "required": [ + "status" + ], + "type": "object", + "properties": { + "status": { + "required": [ + "code", + "description", + "details" + ], + "type": "object", + "properties": { + "code": { + "type": "integer", + "description": "Kod statusu HTTP odpowiadający błędowi. Zawsze ma wartość 429." + }, + "description": { + "type": "string", + "description": "Opis błędu zgodny z nazwą statusu HTTP." + }, + "details": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Lista szczegółowych informacji opisujących przyczynę przekroczenia limitu żądań oraz wskazówki dotyczące ponowienia żądania." + } + }, + "description": "Informacje o błędzie związanym z przekroczeniem limitu żądań." + } + }, + "example": { + "status": { + "code": 429, + "description": "Too Many Requests", + "details": [ + "Przekroczono limit 20 żądań na minutę. Spróbuj ponownie po 30 sekundach." + ] + } + } + }, + "UpoPageResponse": { + "required": [ + "downloadUrl", + "downloadUrlExpirationDate", + "referenceNumber" + ], + "type": "object", + "properties": { + "referenceNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/ReferenceNumber" + } + ], + "description": "Numer referencyjny strony UPO." + }, + "downloadUrl": { + "type": "string", + "description": "Adres do pobrania strony UPO. Link generowany jest przy każdym odpytaniu o status. \nDostęp odbywa się metodą `HTTP GET` i nie należy wysyłać tokenu dostępowego. \nLink nie podlega limitom API i wygasa po określonym czasie w `DownloadUrlExpirationDate`.\n\nOdpowiedź HTTP zawiera dodatkowe nagłówki:\n- `x-ms-meta-hash` – skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64.", + "format": "uri" + }, + "downloadUrlExpirationDate": { + "type": "string", + "description": "Data i godzina wygaśnięcia adresu. Po tej dacie link `DownloadUrl` nie będzie już aktywny.", + "format": "date-time" + } + }, + "additionalProperties": false + }, + "UpoResponse": { + "required": [ + "pages" + ], + "type": "object", + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UpoPageResponse" + }, + "description": "Lista stron UPO." + } + }, + "additionalProperties": false + } + }, + "securitySchemes": { + "Bearer": { + "type": "http", + "description": "Token dostępu uzyskany w wyniku operacji uwierzytelnienia.", + "scheme": "Bearer", + "bearerFormat": "JWT" + }, + "SessionToken": { + "type": "apiKey", + "name": "SessionToken", + "in": "header" + } + } + }, + "tags": [ + { + "name": "Aktywne sesje" + }, + { + "name": "Certyfikaty", + "description": "Certyfikat KSeF to cyfrowe poświadczenie tożsamości podmiotu, wydawane przez system KSeF na wniosek uwierzytelnionego podmiotu. \nCertyfikat ten może być wykorzystywany do:\n\n- uwierzytelniania się w systemie KSeF,\n- realizacji operacji w trybie offline, w tym wystawiania faktur bezpośrednio w aplikacji użytkownika.\n\n**Uwaga**: Wnioskowanie o certyfikat KSeF jest możliwe wyłącznie po uwierzytelnieniu z wykorzystaniem podpisu (XAdES). Uwierzytelnienie przy użyciu tokenu systemowego KSeF nie pozwala na złożenie wniosku." + }, + { + "name": "Certyfikaty klucza publicznego" + }, + { + "name": "Dane testowe", + "description": "API służy do tworzenia i zarządzania danymi testowymi, takimi jak podmioty, osoby fizyczne oraz uprawnienia. Możliwe do utworzenia podmioty to: organ egzekucyjny, grupa VAT oraz jednostki samorządu terytorialnego. W przypadku osób fizycznych można określić, czy dana osoba jest komornikiem. Funkcjonalność nadawania i odbierania uprawnień ma na celu odwzorowanie działania formularza ZAW-FA w środowisku testowym.\n\nWięcej informacji:\n- [Scenariusze testowe](https://github.com/CIRFMF/ksef-docs/blob/main/dane-testowe-scenariusze.md)" + }, + { + "name": "Limity i ograniczenia" + }, + { + "name": "Nadawanie uprawnień" + }, + { + "name": "Odbieranie uprawnień" + }, + { + "name": "Operacje" + }, + { + "name": "Pobieranie faktur" + }, + { + "name": "Status wysyłki i UPO" + }, + { + "name": "Tokeny KSeF", + "description": "Token KSeF to unikalny, generowany identyfikator uwierzytelniający, który — na równi z [kwalifikowanym podpisem elektronicznym](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#21-uwierzytelnianie-kwalifikowanym-podpisem-elektronicznym) — umożliwia [uwierzytelnienie](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#22-uwierzytelnianie-tokenem-ksef) się do API KSeF.\n\nToken KSeF jest wydawany z niezmiennym zestawem uprawnień określonych przy jego tworzeniu; każda modyfikacja tych uprawnień wymaga wygenerowania nowego tokena.\n> **Uwaga!**
\n> Token KSeF pełni rolę **poufnego sekretu** uwierzytelniającego — należy przechowywać go wyłącznie w zaufanym i bezpiecznym magazynie.\n\nWięcej informacji:\n- [Token KSeF](https://github.com/CIRFMF/ksef-docs/blob/main/tokeny-ksef.md)\n" + }, + { + "name": "Usługi Peppol", + "description": "" + }, + { + "name": "Uzyskiwanie dostępu", + "description": "Uwierzytelnianie w systemie KSeF API 2.0 jest obowiązkowym etapem, który należy wykonać przed dostępem do chronionych zasobów systemu. Proces ten oparty jest na **uzyskaniu tokenu dostępu** (```accessToken```) w formacie ```JWT```, który następnie wykorzystywany jest do autoryzacji operacji API.\n\n> Więcej informacji:\n> - [Uwierzytelnianie](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md)" + }, + { + "name": "Wysyłka interaktywna" + }, + { + "name": "Wysyłka wsadowa", + "description": "" + }, + { + "name": "Wyszukiwanie nadanych uprawnień" + } + ], + "x-tagGroups": [ + { + "name": "Uwierzytelnianie", + "tags": [ + "Uzyskiwanie dostępu", + "Aktywne sesje" + ] + }, + { + "name": "Limity i ograniczenia", + "tags": [ + "Limity i ograniczenia" + ] + }, + { + "name": "Szyfrowanie danych", + "tags": [ + "Certyfikaty klucza publicznego" + ] + }, + { + "name": "Faktury", + "tags": [ + "Wysyłka interaktywna", + "Wysyłka wsadowa", + "Status wysyłki i UPO", + "Pobieranie faktur" + ] + }, + { + "name": "Uprawnienia", + "tags": [ + "Nadawanie uprawnień", + "Odbieranie uprawnień", + "Wyszukiwanie nadanych uprawnień", + "Operacje" + ] + }, + { + "name": "Certyfikaty", + "tags": [ + "Certyfikaty" + ] + }, + { + "name": "Tokeny KSeF", + "tags": [ + "Tokeny KSeF" + ] + }, + { + "name": "Usługi Peppol", + "tags": [ + "Usługi Peppol" + ] + }, + { + "name": "Dane testowe", + "tags": [ + "Dane testowe" + ] + } + ] +} \ No newline at end of file diff --git a/src/ksef_client/clients/security.py b/src/ksef_client/clients/security.py index 2cef4f9..ba72560 100644 --- a/src/ksef_client/clients/security.py +++ b/src/ksef_client/clients/security.py @@ -9,5 +9,7 @@ class SecurityClient(BaseApiClient): def get_public_key_certificates(self) -> Any: return self._request_json("GET", "/security/public-key-certificates", skip_auth=True) + +class AsyncSecurityClient(AsyncBaseApiClient): async def get_public_key_certificates(self) -> Any: return await self._request_json("GET", "/security/public-key-certificates", skip_auth=True) diff --git a/src/ksef_client/openapi_models.py b/src/ksef_client/openapi_models.py index a15b1e0..3c7426b 100644 --- a/src/ksef_client/openapi_models.py +++ b/src/ksef_client/openapi_models.py @@ -1,17 +1,17 @@ # Generated from ksef-docs/open-api.json. Do not edit manually. from __future__ import annotations -import sys -from dataclasses import dataclass, field, fields +from dataclasses import MISSING, dataclass, field, fields from enum import Enum -from typing import Any, TypeAlias, TypeVar, cast, get_args, get_origin, get_type_hints +import sys +from typing import Any, Optional, TypeAlias, TypeVar +from typing import get_args, get_origin, get_type_hints JsonValue: TypeAlias = Any T = TypeVar("T", bound="OpenApiModel") _TYPE_CACHE: dict[type, dict[str, Any]] = {} - def _get_type_map(cls: type) -> dict[str, Any]: cached = _TYPE_CACHE.get(cls) if cached is not None: @@ -21,7 +21,6 @@ def _get_type_map(cls: type) -> dict[str, Any]: _TYPE_CACHE[cls] = hints return hints - def _convert_value(type_hint: Any, value: Any) -> Any: if value is None: return None @@ -41,15 +40,11 @@ def _convert_value(type_hint: Any, value: Any) -> Any: return _convert_value(args[0], value) if isinstance(type_hint, type) and issubclass(type_hint, Enum): return type_hint(value) - if ( - isinstance(type_hint, type) - and issubclass(type_hint, OpenApiModel) - and isinstance(value, dict) - ): - return type_hint.from_dict(value) + if isinstance(type_hint, type) and issubclass(type_hint, OpenApiModel): + if isinstance(value, dict): + return type_hint.from_dict(value) return value - def _serialize_value(value: Any) -> Any: if isinstance(value, Enum): return value.value @@ -61,7 +56,6 @@ def _serialize_value(value: Any) -> Any: return {key: _serialize_value(item) for key, item in value.items()} return value - class OpenApiModel: @classmethod def from_dict(cls: type[T], data: dict[str, Any]) -> T: @@ -69,7 +63,7 @@ def from_dict(cls: type[T], data: dict[str, Any]) -> T: raise ValueError("data is None") type_map = _get_type_map(cls) kwargs: dict[str, Any] = {} - for model_field in fields(cast(Any, cls)): + for model_field in fields(cls): json_key = model_field.metadata.get("json_key", model_field.name) if json_key in data: type_hint = type_map.get(model_field.name, Any) @@ -78,7 +72,7 @@ def from_dict(cls: type[T], data: dict[str, Any]) -> T: def to_dict(self, omit_none: bool = True) -> dict[str, Any]: result: dict[str, Any] = {} - for model_field in fields(cast(Any, self)): + for model_field in fields(self): json_key = model_field.metadata.get("json_key", model_field.name) value = getattr(self, model_field.name) if omit_none and value is None: @@ -86,20 +80,17 @@ def to_dict(self, omit_none: bool = True) -> dict[str, Any]: result[json_key] = _serialize_value(value) return result - class AmountType(Enum): BRUTTO = "Brutto" NETTO = "Netto" VAT = "Vat" - class AuthenticationContextIdentifierType(Enum): NIP = "Nip" INTERNALID = "InternalId" NIPVATUE = "NipVatUe" PEPPOLID = "PeppolId" - class AuthenticationMethod(Enum): TOKEN = "Token" TRUSTEDPROFILE = "TrustedProfile" @@ -109,7 +100,6 @@ class AuthenticationMethod(Enum): PERSONALSIGNATURE = "PersonalSignature" PEPPOLSIGNATURE = "PeppolSignature" - class AuthenticationTokenStatus(Enum): PENDING = "Pending" ACTIVE = "Active" @@ -117,40 +107,34 @@ class AuthenticationTokenStatus(Enum): REVOKED = "Revoked" FAILED = "Failed" - class BuyerIdentifierType(Enum): NIP = "Nip" VATUE = "VatUe" OTHER = "Other" NONE = "None" - class CertificateListItemStatus(Enum): ACTIVE = "Active" BLOCKED = "Blocked" REVOKED = "Revoked" EXPIRED = "Expired" - class CertificateRevocationReason(Enum): UNSPECIFIED = "Unspecified" SUPERSEDED = "Superseded" KEYCOMPROMISE = "KeyCompromise" - class CertificateSubjectIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class CommonSessionStatus(Enum): INPROGRESS = "InProgress" SUCCEEDED = "Succeeded" FAILED = "Failed" CANCELLED = "Cancelled" - class CurrencyCode(Enum): AED = "AED" AFN = "AFN" @@ -335,47 +319,38 @@ class CurrencyCode(Enum): ZMW = "ZMW" ZWL = "ZWL" - class EntityAuthorizationPermissionType(Enum): SELFINVOICING = "SelfInvoicing" RRINVOICING = "RRInvoicing" TAXREPRESENTATIVE = "TaxRepresentative" PEFINVOICING = "PefInvoicing" - class EntityAuthorizationPermissionsSubjectIdentifierType(Enum): NIP = "Nip" PEPPOLID = "PeppolId" - class EntityAuthorizationsAuthorIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class EntityAuthorizationsAuthorizedEntityIdentifierType(Enum): NIP = "Nip" PEPPOLID = "PeppolId" - class EntityAuthorizationsAuthorizingEntityIdentifierType(Enum): NIP = "Nip" - class EntityPermissionType(Enum): INVOICEWRITE = "InvoiceWrite" INVOICEREAD = "InvoiceRead" - class EntityPermissionsSubjectIdentifierType(Enum): NIP = "Nip" - class EntityPermissionsSubordinateEntityIdentifierType(Enum): NIP = "Nip" - class EntityRoleType(Enum): COURTBAILIFF = "CourtBailiff" ENFORCEMENTAUTHORITY = "EnforcementAuthority" @@ -384,103 +359,84 @@ class EntityRoleType(Enum): VATGROUPUNIT = "VatGroupUnit" VATGROUPSUBUNIT = "VatGroupSubUnit" - class EntityRolesParentEntityIdentifierType(Enum): NIP = "Nip" - class EntitySubjectByFingerprintDetailsType(Enum): ENTITYBYFINGERPRINT = "EntityByFingerprint" - class EntitySubjectByIdentifierDetailsType(Enum): ENTITYBYIDENTIFIER = "EntityByIdentifier" - class EntitySubjectDetailsType(Enum): ENTITYBYIDENTIFIER = "EntityByIdentifier" ENTITYBYFINGERPRINT = "EntityByFingerprint" - class EuEntityAdministrationPermissionsContextIdentifierType(Enum): NIPVATUE = "NipVatUe" - class EuEntityAdministrationPermissionsSubjectIdentifierType(Enum): FINGERPRINT = "Fingerprint" - class EuEntityPermissionSubjectDetailsType(Enum): PERSONBYFINGERPRINTWITHIDENTIFIER = "PersonByFingerprintWithIdentifier" PERSONBYFINGERPRINTWITHOUTIDENTIFIER = "PersonByFingerprintWithoutIdentifier" ENTITYBYFINGERPRINT = "EntityByFingerprint" - class EuEntityPermissionType(Enum): INVOICEWRITE = "InvoiceWrite" INVOICEREAD = "InvoiceRead" - class EuEntityPermissionsAuthorIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class EuEntityPermissionsQueryPermissionType(Enum): VATUEMANAGE = "VatUeManage" INVOICEWRITE = "InvoiceWrite" INVOICEREAD = "InvoiceRead" INTROSPECTION = "Introspection" - class EuEntityPermissionsSubjectIdentifierType(Enum): FINGERPRINT = "Fingerprint" - class IndirectPermissionType(Enum): INVOICEREAD = "InvoiceRead" INVOICEWRITE = "InvoiceWrite" - class IndirectPermissionsSubjectIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class IndirectPermissionsTargetIdentifierType(Enum): NIP = "Nip" ALLPARTNERS = "AllPartners" INTERNALID = "InternalId" - class InvoicePermissionType(Enum): SELFINVOICING = "SelfInvoicing" TAXREPRESENTATIVE = "TaxRepresentative" RRINVOICING = "RRInvoicing" PEFINVOICING = "PefInvoicing" - class InvoiceQueryDateType(Enum): ISSUE = "Issue" INVOICING = "Invoicing" PERMANENTSTORAGE = "PermanentStorage" - class InvoiceQueryFormType(Enum): FA = "FA" PEF = "PEF" RR = "RR" - class InvoiceQuerySubjectType(Enum): SUBJECT1 = "Subject1" SUBJECT2 = "Subject2" SUBJECT3 = "Subject3" SUBJECTAUTHORIZED = "SubjectAuthorized" - class InvoiceType(Enum): VAT = "Vat" ZAL = "Zal" @@ -495,27 +451,22 @@ class InvoiceType(Enum): VATRR = "VatRr" KORVATRR = "KorVatRr" - class InvoicingMode(Enum): ONLINE = "Online" OFFLINE = "Offline" - class KsefCertificateType(Enum): AUTHENTICATION = "Authentication" OFFLINE = "Offline" - class PermissionState(Enum): ACTIVE = "Active" INACTIVE = "Inactive" - class PersonIdentifierType(Enum): PESEL = "Pesel" NIP = "Nip" - class PersonPermissionScope(Enum): CREDENTIALSMANAGE = "CredentialsManage" CREDENTIALSREAD = "CredentialsRead" @@ -525,13 +476,11 @@ class PersonPermissionScope(Enum): SUBUNITMANAGE = "SubunitManage" ENFORCEMENTOPERATIONS = "EnforcementOperations" - class PersonPermissionSubjectDetailsType(Enum): PERSONBYIDENTIFIER = "PersonByIdentifier" PERSONBYFINGERPRINTWITHIDENTIFIER = "PersonByFingerprintWithIdentifier" PERSONBYFINGERPRINTWITHOUTIDENTIFIER = "PersonByFingerprintWithoutIdentifier" - class PersonPermissionType(Enum): CREDENTIALSMANAGE = "CredentialsManage" CREDENTIALSREAD = "CredentialsRead" @@ -541,53 +490,44 @@ class PersonPermissionType(Enum): SUBUNITMANAGE = "SubunitManage" ENFORCEMENTOPERATIONS = "EnforcementOperations" - class PersonPermissionsAuthorIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" SYSTEM = "System" - class PersonPermissionsAuthorizedIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class PersonPermissionsContextIdentifierType(Enum): NIP = "Nip" INTERNALID = "InternalId" - class PersonPermissionsQueryType(Enum): PERMISSIONSINCURRENTCONTEXT = "PermissionsInCurrentContext" PERMISSIONSGRANTEDINCURRENTCONTEXT = "PermissionsGrantedInCurrentContext" - class PersonPermissionsSubjectIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class PersonPermissionsTargetIdentifierType(Enum): NIP = "Nip" ALLPARTNERS = "AllPartners" INTERNALID = "InternalId" - class PersonSubjectByFingerprintDetailsType(Enum): PERSONBYFINGERPRINTWITHIDENTIFIER = "PersonByFingerprintWithIdentifier" PERSONBYFINGERPRINTWITHOUTIDENTIFIER = "PersonByFingerprintWithoutIdentifier" - class PersonSubjectDetailsType(Enum): PERSONBYIDENTIFIER = "PersonByIdentifier" PERSONBYFINGERPRINTWITHIDENTIFIER = "PersonByFingerprintWithIdentifier" PERSONBYFINGERPRINTWITHOUTIDENTIFIER = "PersonByFingerprintWithoutIdentifier" - class PersonalPermissionScope(Enum): CREDENTIALSMANAGE = "CredentialsManage" CREDENTIALSREAD = "CredentialsRead" @@ -598,7 +538,6 @@ class PersonalPermissionScope(Enum): ENFORCEMENTOPERATIONS = "EnforcementOperations" VATUEMANAGE = "VatUeManage" - class PersonalPermissionType(Enum): CREDENTIALSMANAGE = "CredentialsManage" CREDENTIALSREAD = "CredentialsRead" @@ -609,101 +548,82 @@ class PersonalPermissionType(Enum): ENFORCEMENTOPERATIONS = "EnforcementOperations" VATUEMANAGE = "VatUeManage" - class PersonalPermissionsAuthorizedIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class PersonalPermissionsContextIdentifierType(Enum): NIP = "Nip" INTERNALID = "InternalId" - class PersonalPermissionsTargetIdentifierType(Enum): NIP = "Nip" ALLPARTNERS = "AllPartners" INTERNALID = "InternalId" - class PublicKeyCertificateUsage(Enum): KSEFTOKENENCRYPTION = "KsefTokenEncryption" SYMMETRICKEYENCRYPTION = "SymmetricKeyEncryption" - class QueryType(Enum): GRANTED = "Granted" RECEIVED = "Received" - class SessionType(Enum): ONLINE = "Online" BATCH = "Batch" - class SortOrder(Enum): ASC = "Asc" DESC = "Desc" - class SubjectIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class SubjectType(Enum): ENFORCEMENTAUTHORITY = "EnforcementAuthority" VATGROUP = "VatGroup" JST = "JST" - class SubordinateEntityRoleType(Enum): LOCALGOVERNMENTSUBUNIT = "LocalGovernmentSubUnit" VATGROUPSUBUNIT = "VatGroupSubUnit" - class SubordinateRoleSubordinateEntityIdentifierType(Enum): NIP = "Nip" - class SubunitPermissionScope(Enum): CREDENTIALSMANAGE = "CredentialsManage" - class SubunitPermissionsAuthorIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class SubunitPermissionsContextIdentifierType(Enum): INTERNALID = "InternalId" NIP = "Nip" - class SubunitPermissionsSubjectIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class SubunitPermissionsSubunitIdentifierType(Enum): INTERNALID = "InternalId" NIP = "Nip" - class TestDataAuthorizedIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class TestDataContextIdentifierType(Enum): NIP = "Nip" - class TestDataPermissionType(Enum): INVOICEREAD = "InvoiceRead" INVOICEWRITE = "InvoiceWrite" @@ -713,7 +633,6 @@ class TestDataPermissionType(Enum): ENFORCEMENTOPERATIONS = "EnforcementOperations" SUBUNITMANAGE = "SubunitManage" - class ThirdSubjectIdentifierType(Enum): NIP = "Nip" INTERNALID = "InternalId" @@ -721,20 +640,17 @@ class ThirdSubjectIdentifierType(Enum): OTHER = "Other" NONE = "None" - class TokenAuthorIdentifierType(Enum): NIP = "Nip" PESEL = "Pesel" FINGERPRINT = "Fingerprint" - class TokenContextIdentifierType(Enum): NIP = "Nip" INTERNALID = "InternalId" NIPVATUE = "NipVatUe" PEPPOLID = "PeppolId" - class TokenPermissionType(Enum): INVOICEREAD = "InvoiceRead" INVOICEWRITE = "InvoiceWrite" @@ -743,7 +659,6 @@ class TokenPermissionType(Enum): SUBUNITMANAGE = "SubunitManage" ENFORCEMENTOPERATIONS = "EnforcementOperations" - Challenge: TypeAlias = str InternalId: TypeAlias = str @@ -766,13 +681,11 @@ class TokenPermissionType(Enum): Sha256HashBase64: TypeAlias = str - @dataclass(frozen=True) class AllowedIps(OpenApiModel): - ip4Addresses: list[str] | None = None - ip4Masks: list[str] | None = None - ip4Ranges: list[str] | None = None - + ip4Addresses: Optional[list[str]] = None + ip4Masks: Optional[list[str]] = None + ip4Ranges: Optional[list[str]] = None @dataclass(frozen=True) class ApiRateLimitValuesOverride(OpenApiModel): @@ -780,7 +693,6 @@ class ApiRateLimitValuesOverride(OpenApiModel): perMinute: int perSecond: int - @dataclass(frozen=True) class ApiRateLimitsOverride(OpenApiModel): batchSession: ApiRateLimitValuesOverride @@ -796,17 +708,14 @@ class ApiRateLimitsOverride(OpenApiModel): sessionList: ApiRateLimitValuesOverride sessionMisc: ApiRateLimitValuesOverride - @dataclass(frozen=True) class AttachmentPermissionGrantRequest(OpenApiModel): nip: Nip - @dataclass(frozen=True) class AttachmentPermissionRevokeRequest(OpenApiModel): nip: Nip - expectedEndDate: str | None = None - + expectedEndDate: Optional[str] = None @dataclass(frozen=True) class AuthenticationChallengeResponse(OpenApiModel): @@ -814,62 +723,53 @@ class AuthenticationChallengeResponse(OpenApiModel): timestamp: str timestampMs: int - @dataclass(frozen=True) class AuthenticationContextIdentifier(OpenApiModel): type: AuthenticationContextIdentifierType value: str - @dataclass(frozen=True) class AuthenticationInitResponse(OpenApiModel): authenticationToken: TokenInfo referenceNumber: ReferenceNumber - @dataclass(frozen=True) class AuthenticationListItem(OpenApiModel): authenticationMethod: AuthenticationMethod referenceNumber: ReferenceNumber startDate: str status: StatusInfo - isCurrent: bool | None = None - isTokenRedeemed: bool | None = None - lastTokenRefreshDate: str | None = None - refreshTokenValidUntil: str | None = None - + isCurrent: Optional[bool] = None + isTokenRedeemed: Optional[bool] = None + lastTokenRefreshDate: Optional[str] = None + refreshTokenValidUntil: Optional[str] = None @dataclass(frozen=True) class AuthenticationListResponse(OpenApiModel): items: list[AuthenticationListItem] - continuationToken: str | None = None - + continuationToken: Optional[str] = None @dataclass(frozen=True) class AuthenticationOperationStatusResponse(OpenApiModel): authenticationMethod: AuthenticationMethod startDate: str status: StatusInfo - isTokenRedeemed: bool | None = None - lastTokenRefreshDate: str | None = None - refreshTokenValidUntil: str | None = None - + isTokenRedeemed: Optional[bool] = None + lastTokenRefreshDate: Optional[str] = None + refreshTokenValidUntil: Optional[str] = None @dataclass(frozen=True) class AuthenticationTokenRefreshResponse(OpenApiModel): accessToken: TokenInfo - @dataclass(frozen=True) class AuthenticationTokensResponse(OpenApiModel): accessToken: TokenInfo refreshToken: TokenInfo - @dataclass(frozen=True) class AuthorizationPolicy(OpenApiModel): - allowedIps: AllowedIps | None = None - + allowedIps: Optional[AllowedIps] = None @dataclass(frozen=True) class BatchFileInfo(OpenApiModel): @@ -877,65 +777,56 @@ class BatchFileInfo(OpenApiModel): fileParts: list[BatchFilePartInfo] fileSize: int - @dataclass(frozen=True) class BatchFilePartInfo(OpenApiModel): fileHash: Sha256HashBase64 fileSize: int ordinalNumber: int - @dataclass(frozen=True) class BatchSessionContextLimitsOverride(OpenApiModel): maxInvoiceSizeInMB: int maxInvoiceWithAttachmentSizeInMB: int maxInvoices: int - @dataclass(frozen=True) class BatchSessionEffectiveContextLimits(OpenApiModel): maxInvoiceSizeInMB: int maxInvoiceWithAttachmentSizeInMB: int maxInvoices: int - @dataclass(frozen=True) class CertificateEffectiveSubjectLimits(OpenApiModel): - maxCertificates: int | None = None - + maxCertificates: Optional[int] = None @dataclass(frozen=True) class CertificateEnrollmentDataResponse(OpenApiModel): commonName: str countryName: str - givenName: str | None = None - organizationIdentifier: str | None = None - organizationName: str | None = None - serialNumber: str | None = None - surname: str | None = None - uniqueIdentifier: str | None = None - + givenName: Optional[str] = None + organizationIdentifier: Optional[str] = None + organizationName: Optional[str] = None + serialNumber: Optional[str] = None + surname: Optional[str] = None + uniqueIdentifier: Optional[str] = None @dataclass(frozen=True) class CertificateEnrollmentStatusResponse(OpenApiModel): requestDate: str status: StatusInfo - certificateSerialNumber: str | None = None - + certificateSerialNumber: Optional[str] = None @dataclass(frozen=True) class CertificateLimit(OpenApiModel): limit: int remaining: int - @dataclass(frozen=True) class CertificateLimitsResponse(OpenApiModel): canRequest: bool certificate: CertificateLimit enrollment: CertificateLimit - @dataclass(frozen=True) class CertificateListItem(OpenApiModel): certificateSerialNumber: str @@ -947,25 +838,21 @@ class CertificateListItem(OpenApiModel): type: KsefCertificateType validFrom: str validTo: str - lastUseDate: str | None = None - + lastUseDate: Optional[str] = None @dataclass(frozen=True) class CertificateSubjectIdentifier(OpenApiModel): type: CertificateSubjectIdentifierType value: str - @dataclass(frozen=True) class CertificateSubjectLimitsOverride(OpenApiModel): - maxCertificates: int | None = None - + maxCertificates: Optional[int] = None @dataclass(frozen=True) class CheckAttachmentPermissionStatusResponse(OpenApiModel): - isAttachmentAllowed: bool | None = None - revokedDate: str | None = None - + isAttachmentAllowed: Optional[bool] = None + revokedDate: Optional[str] = None @dataclass(frozen=True) class EffectiveApiRateLimitValues(OpenApiModel): @@ -973,7 +860,6 @@ class EffectiveApiRateLimitValues(OpenApiModel): perMinute: int perSecond: int - @dataclass(frozen=True) class EffectiveApiRateLimits(OpenApiModel): batchSession: EffectiveApiRateLimitValues @@ -989,48 +875,40 @@ class EffectiveApiRateLimits(OpenApiModel): sessionList: EffectiveApiRateLimitValues sessionMisc: EffectiveApiRateLimitValues - @dataclass(frozen=True) class EffectiveContextLimits(OpenApiModel): batchSession: BatchSessionEffectiveContextLimits onlineSession: OnlineSessionEffectiveContextLimits - @dataclass(frozen=True) class EffectiveSubjectLimits(OpenApiModel): - certificate: CertificateEffectiveSubjectLimits | None = None - enrollment: EnrollmentEffectiveSubjectLimits | None = None - + certificate: Optional[CertificateEffectiveSubjectLimits] = None + enrollment: Optional[EnrollmentEffectiveSubjectLimits] = None @dataclass(frozen=True) class EncryptionInfo(OpenApiModel): encryptedSymmetricKey: str initializationVector: str - @dataclass(frozen=True) class EnrollCertificateRequest(OpenApiModel): certificateName: str certificateType: KsefCertificateType csr: str - validFrom: str | None = None - + validFrom: Optional[str] = None @dataclass(frozen=True) class EnrollCertificateResponse(OpenApiModel): referenceNumber: ReferenceNumber timestamp: str - @dataclass(frozen=True) class EnrollmentEffectiveSubjectLimits(OpenApiModel): - maxEnrollments: int | None = None - + maxEnrollments: Optional[int] = None @dataclass(frozen=True) class EnrollmentSubjectLimitsOverride(OpenApiModel): - maxEnrollments: int | None = None - + maxEnrollments: Optional[int] = None @dataclass(frozen=True) class EntityAuthorizationGrant(OpenApiModel): @@ -1040,9 +918,8 @@ class EntityAuthorizationGrant(OpenApiModel): description: str id: PermissionId startDate: str - authorIdentifier: EntityAuthorizationsAuthorIdentifier | None = None - subjectEntityDetails: PermissionsSubjectEntityByIdentifierDetails | None = None - + authorIdentifier: Optional[EntityAuthorizationsAuthorIdentifier] = None + subjectEntityDetails: Optional[PermissionsSubjectEntityByIdentifierDetails] = None @dataclass(frozen=True) class EntityAuthorizationPermissionsGrantRequest(OpenApiModel): @@ -1051,55 +928,46 @@ class EntityAuthorizationPermissionsGrantRequest(OpenApiModel): subjectDetails: EntityDetails subjectIdentifier: EntityAuthorizationPermissionsSubjectIdentifier - @dataclass(frozen=True) class EntityAuthorizationPermissionsQueryRequest(OpenApiModel): queryType: QueryType - authorizedIdentifier: EntityAuthorizationsAuthorizedEntityIdentifier | None = None - authorizingIdentifier: EntityAuthorizationsAuthorizingEntityIdentifier | None = None - permissionTypes: list[InvoicePermissionType] | None = None - + authorizedIdentifier: Optional[EntityAuthorizationsAuthorizedEntityIdentifier] = None + authorizingIdentifier: Optional[EntityAuthorizationsAuthorizingEntityIdentifier] = None + permissionTypes: Optional[list[InvoicePermissionType]] = None @dataclass(frozen=True) class EntityAuthorizationPermissionsSubjectIdentifier(OpenApiModel): type: EntityAuthorizationPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class EntityAuthorizationsAuthorIdentifier(OpenApiModel): type: EntityAuthorizationsAuthorIdentifierType value: str - @dataclass(frozen=True) class EntityAuthorizationsAuthorizedEntityIdentifier(OpenApiModel): type: EntityAuthorizationsAuthorizedEntityIdentifierType value: str - @dataclass(frozen=True) class EntityAuthorizationsAuthorizingEntityIdentifier(OpenApiModel): type: EntityAuthorizationsAuthorizingEntityIdentifierType value: str - @dataclass(frozen=True) class EntityByFingerprintDetails(OpenApiModel): address: str fullName: str - @dataclass(frozen=True) class EntityDetails(OpenApiModel): fullName: str - @dataclass(frozen=True) class EntityPermission(OpenApiModel): type: EntityPermissionType - canDelegate: bool | None = None - + canDelegate: Optional[bool] = None @dataclass(frozen=True) class EntityPermissionsGrantRequest(OpenApiModel): @@ -1108,39 +976,33 @@ class EntityPermissionsGrantRequest(OpenApiModel): subjectDetails: EntityDetails subjectIdentifier: EntityPermissionsSubjectIdentifier - @dataclass(frozen=True) class EntityPermissionsSubjectIdentifier(OpenApiModel): type: EntityPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class EntityPermissionsSubordinateEntityIdentifier(OpenApiModel): type: EntityPermissionsSubordinateEntityIdentifierType value: str - @dataclass(frozen=True) class EntityRole(OpenApiModel): description: str role: EntityRoleType startDate: str - parentEntityIdentifier: EntityRolesParentEntityIdentifier | None = None - + parentEntityIdentifier: Optional[EntityRolesParentEntityIdentifier] = None @dataclass(frozen=True) class EntityRolesParentEntityIdentifier(OpenApiModel): type: EntityRolesParentEntityIdentifierType value: str - @dataclass(frozen=True) class EuEntityAdministrationPermissionsContextIdentifier(OpenApiModel): type: EuEntityAdministrationPermissionsContextIdentifierType value: str - @dataclass(frozen=True) class EuEntityAdministrationPermissionsGrantRequest(OpenApiModel): contextIdentifier: EuEntityAdministrationPermissionsContextIdentifier @@ -1150,19 +1012,16 @@ class EuEntityAdministrationPermissionsGrantRequest(OpenApiModel): subjectDetails: EuEntityPermissionSubjectDetails subjectIdentifier: EuEntityAdministrationPermissionsSubjectIdentifier - @dataclass(frozen=True) class EuEntityAdministrationPermissionsSubjectIdentifier(OpenApiModel): type: EuEntityAdministrationPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class EuEntityDetails(OpenApiModel): address: str fullName: str - @dataclass(frozen=True) class EuEntityPermission(OpenApiModel): authorIdentifier: EuEntityPermissionsAuthorIdentifier @@ -1173,25 +1032,22 @@ class EuEntityPermission(OpenApiModel): permissionScope: EuEntityPermissionsQueryPermissionType startDate: str vatUeIdentifier: str - euEntityDetails: PermissionsEuEntityDetails | None = None - subjectEntityDetails: PermissionsSubjectEntityByFingerprintDetails | None = None - subjectPersonDetails: PermissionsSubjectPersonByFingerprintDetails | None = None - + euEntityDetails: Optional[PermissionsEuEntityDetails] = None + subjectEntityDetails: Optional[PermissionsSubjectEntityByFingerprintDetails] = None + subjectPersonDetails: Optional[PermissionsSubjectPersonByFingerprintDetails] = None @dataclass(frozen=True) class EuEntityPermissionSubjectDetails(OpenApiModel): subjectDetailsType: EuEntityPermissionSubjectDetailsType - entityByFp: EntityByFingerprintDetails | None = None - personByFpNoId: PersonByFingerprintWithoutIdentifierDetails | None = None - personByFpWithId: PersonByFingerprintWithIdentifierDetails | None = None - + entityByFp: Optional[EntityByFingerprintDetails] = None + personByFpNoId: Optional[PersonByFingerprintWithoutIdentifierDetails] = None + personByFpWithId: Optional[PersonByFingerprintWithIdentifierDetails] = None @dataclass(frozen=True) class EuEntityPermissionsAuthorIdentifier(OpenApiModel): type: EuEntityPermissionsAuthorIdentifierType value: str - @dataclass(frozen=True) class EuEntityPermissionsGrantRequest(OpenApiModel): description: str @@ -1199,115 +1055,98 @@ class EuEntityPermissionsGrantRequest(OpenApiModel): subjectDetails: EuEntityPermissionSubjectDetails subjectIdentifier: EuEntityPermissionsSubjectIdentifier - @dataclass(frozen=True) class EuEntityPermissionsQueryRequest(OpenApiModel): - authorizedFingerprintIdentifier: str | None = None - permissionTypes: list[EuEntityPermissionsQueryPermissionType] | None = None - vatUeIdentifier: str | None = None - + authorizedFingerprintIdentifier: Optional[str] = None + permissionTypes: Optional[list[EuEntityPermissionsQueryPermissionType]] = None + vatUeIdentifier: Optional[str] = None @dataclass(frozen=True) class EuEntityPermissionsSubjectIdentifier(OpenApiModel): type: EuEntityPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class ExceptionDetails(OpenApiModel): - details: list[str] | None = None - exceptionCode: int | None = None - exceptionDescription: str | None = None - + details: Optional[list[str]] = None + exceptionCode: Optional[int] = None + exceptionDescription: Optional[str] = None @dataclass(frozen=True) class ExceptionInfo(OpenApiModel): - exceptionDetailList: list[ExceptionDetails] | None = None - referenceNumber: ReferenceNumber | None = None - serviceCode: str | None = None - serviceCtx: str | None = None - serviceName: str | None = None - timestamp: str | None = None - + exceptionDetailList: Optional[list[ExceptionDetails]] = None + referenceNumber: Optional[ReferenceNumber] = None + serviceCode: Optional[str] = None + serviceCtx: Optional[str] = None + serviceName: Optional[str] = None + timestamp: Optional[str] = None @dataclass(frozen=True) class ExceptionResponse(OpenApiModel): - exception: ExceptionInfo | None = None - + exception: Optional[ExceptionInfo] = None @dataclass(frozen=True) class ExportInvoicesResponse(OpenApiModel): referenceNumber: ReferenceNumber - @dataclass(frozen=True) class FormCode(OpenApiModel): schemaVersion: str systemCode: str value: str - @dataclass(frozen=True) class GenerateTokenRequest(OpenApiModel): description: str permissions: list[TokenPermissionType] - @dataclass(frozen=True) class GenerateTokenResponse(OpenApiModel): referenceNumber: ReferenceNumber token: str - @dataclass(frozen=True) class IdDocument(OpenApiModel): country: str number: str type: str - @dataclass(frozen=True) class IndirectPermissionsGrantRequest(OpenApiModel): description: str permissions: list[IndirectPermissionType] subjectDetails: PersonPermissionSubjectDetails subjectIdentifier: IndirectPermissionsSubjectIdentifier - targetIdentifier: IndirectPermissionsTargetIdentifier | None = None - + targetIdentifier: Optional[IndirectPermissionsTargetIdentifier] = None @dataclass(frozen=True) class IndirectPermissionsSubjectIdentifier(OpenApiModel): type: IndirectPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class IndirectPermissionsTargetIdentifier(OpenApiModel): type: IndirectPermissionsTargetIdentifierType - value: str | None = None - + value: Optional[str] = None @dataclass(frozen=True) class InitTokenAuthenticationRequest(OpenApiModel): challenge: Challenge contextIdentifier: AuthenticationContextIdentifier encryptedToken: str - authorizationPolicy: AuthorizationPolicy | None = None - + authorizationPolicy: Optional[AuthorizationPolicy] = None @dataclass(frozen=True) class InvoiceExportRequest(OpenApiModel): encryption: EncryptionInfo filters: InvoiceQueryFilters - @dataclass(frozen=True) class InvoiceExportStatusResponse(OpenApiModel): status: StatusInfo - completedDate: str | None = None - package: InvoicePackage | None = None - packageExpirationDate: str | None = None - + completedDate: Optional[str] = None + package: Optional[InvoicePackage] = None + packageExpirationDate: Optional[str] = None @dataclass(frozen=True) class InvoiceMetadata(OpenApiModel): @@ -1329,48 +1168,41 @@ class InvoiceMetadata(OpenApiModel): permanentStorageDate: str seller: InvoiceMetadataSeller vatAmount: float - authorizedSubject: InvoiceMetadataAuthorizedSubject | None = None - hashOfCorrectedInvoice: Sha256HashBase64 | None = None - thirdSubjects: list[InvoiceMetadataThirdSubject] | None = None - + authorizedSubject: Optional[InvoiceMetadataAuthorizedSubject] = None + hashOfCorrectedInvoice: Optional[Sha256HashBase64] = None + thirdSubjects: Optional[list[InvoiceMetadataThirdSubject]] = None @dataclass(frozen=True) class InvoiceMetadataAuthorizedSubject(OpenApiModel): nip: Nip role: int - name: str | None = None - + name: Optional[str] = None @dataclass(frozen=True) class InvoiceMetadataBuyer(OpenApiModel): identifier: InvoiceMetadataBuyerIdentifier - name: str | None = None - + name: Optional[str] = None @dataclass(frozen=True) class InvoiceMetadataBuyerIdentifier(OpenApiModel): type: BuyerIdentifierType - value: str | None = None - + value: Optional[str] = None @dataclass(frozen=True) class InvoiceMetadataSeller(OpenApiModel): nip: Nip - name: str | None = None - + name: Optional[str] = None @dataclass(frozen=True) class InvoiceMetadataThirdSubject(OpenApiModel): identifier: InvoiceMetadataThirdSubjectIdentifier role: int - name: str | None = None - + name: Optional[str] = None @dataclass(frozen=True) class InvoiceMetadataThirdSubjectIdentifier(OpenApiModel): type: ThirdSubjectIdentifierType - value: str | None = None - + value: Optional[str] = None @dataclass(frozen=True) class InvoicePackage(OpenApiModel): @@ -1378,11 +1210,10 @@ class InvoicePackage(OpenApiModel): isTruncated: bool parts: list[InvoicePackagePart] size: int - lastInvoicingDate: str | None = None - lastIssueDate: str | None = None - lastPermanentStorageDate: str | None = None - permanentStorageHwmDate: str | None = None - + lastInvoicingDate: Optional[str] = None + lastIssueDate: Optional[str] = None + lastPermanentStorageDate: Optional[str] = None + permanentStorageHwmDate: Optional[str] = None @dataclass(frozen=True) class InvoicePackagePart(OpenApiModel): @@ -1396,52 +1227,46 @@ class InvoicePackagePart(OpenApiModel): partSize: int url: str - @dataclass(frozen=True) class InvoiceQueryAmount(OpenApiModel): type: AmountType - from_: float | None = field(default=None, metadata={"json_key": "from"}) - to: float | None = None - + from_: Optional[float] = field(default=None, metadata={"json_key": "from"}) + to: Optional[float] = None @dataclass(frozen=True) class InvoiceQueryBuyerIdentifier(OpenApiModel): type: BuyerIdentifierType - value: str | None = None - + value: Optional[str] = None @dataclass(frozen=True) class InvoiceQueryDateRange(OpenApiModel): dateType: InvoiceQueryDateType from_: str = field(metadata={"json_key": "from"}) - restrictToPermanentStorageHwmDate: bool | None = None - to: str | None = None - + restrictToPermanentStorageHwmDate: Optional[bool] = None + to: Optional[str] = None @dataclass(frozen=True) class InvoiceQueryFilters(OpenApiModel): dateRange: InvoiceQueryDateRange subjectType: InvoiceQuerySubjectType - amount: InvoiceQueryAmount | None = None - buyerIdentifier: InvoiceQueryBuyerIdentifier | None = None - currencyCodes: list[CurrencyCode] | None = None - formType: InvoiceQueryFormType | None = None - hasAttachment: bool | None = None - invoiceNumber: str | None = None - invoiceTypes: list[InvoiceType] | None = None - invoicingMode: InvoicingMode | None = None - isSelfInvoicing: bool | None = None - ksefNumber: KsefNumber | None = None - sellerNip: Nip | None = None - + amount: Optional[InvoiceQueryAmount] = None + buyerIdentifier: Optional[InvoiceQueryBuyerIdentifier] = None + currencyCodes: Optional[list[CurrencyCode]] = None + formType: Optional[InvoiceQueryFormType] = None + hasAttachment: Optional[bool] = None + invoiceNumber: Optional[str] = None + invoiceTypes: Optional[list[InvoiceType]] = None + invoicingMode: Optional[InvoicingMode] = None + isSelfInvoicing: Optional[bool] = None + ksefNumber: Optional[KsefNumber] = None + sellerNip: Optional[Nip] = None @dataclass(frozen=True) class InvoiceStatusInfo(OpenApiModel): code: int description: str - details: list[str] | None = None - extensions: dict[str, str | None] | None = None - + details: Optional[list[str]] = None + extensions: Optional[dict[str, Optional[str]]] = None @dataclass(frozen=True) class OnlineSessionContextLimitsOverride(OpenApiModel): @@ -1449,110 +1274,94 @@ class OnlineSessionContextLimitsOverride(OpenApiModel): maxInvoiceWithAttachmentSizeInMB: int maxInvoices: int - @dataclass(frozen=True) class OnlineSessionEffectiveContextLimits(OpenApiModel): maxInvoiceSizeInMB: int maxInvoiceWithAttachmentSizeInMB: int maxInvoices: int - @dataclass(frozen=True) class OpenBatchSessionRequest(OpenApiModel): batchFile: BatchFileInfo encryption: EncryptionInfo formCode: FormCode - offlineMode: bool | None = None - + offlineMode: Optional[bool] = None @dataclass(frozen=True) class OpenBatchSessionResponse(OpenApiModel): partUploadRequests: list[PartUploadRequest] referenceNumber: ReferenceNumber - @dataclass(frozen=True) class OpenOnlineSessionRequest(OpenApiModel): encryption: EncryptionInfo formCode: FormCode - @dataclass(frozen=True) class OpenOnlineSessionResponse(OpenApiModel): referenceNumber: ReferenceNumber validUntil: str - @dataclass(frozen=True) class PartUploadRequest(OpenApiModel): - headers: dict[str, str | None] + headers: dict[str, Optional[str]] method: str ordinalNumber: int url: str - @dataclass(frozen=True) class PeppolProvider(OpenApiModel): dateCreated: str id: PeppolId name: str - @dataclass(frozen=True) class PermissionsEuEntityDetails(OpenApiModel): address: str fullName: str - @dataclass(frozen=True) class PermissionsOperationResponse(OpenApiModel): referenceNumber: ReferenceNumber - @dataclass(frozen=True) class PermissionsOperationStatusResponse(OpenApiModel): status: StatusInfo - @dataclass(frozen=True) class PermissionsSubjectEntityByFingerprintDetails(OpenApiModel): fullName: str subjectDetailsType: EntitySubjectByFingerprintDetailsType - address: str | None = None - + address: Optional[str] = None @dataclass(frozen=True) class PermissionsSubjectEntityByIdentifierDetails(OpenApiModel): fullName: str subjectDetailsType: EntitySubjectByIdentifierDetailsType - @dataclass(frozen=True) class PermissionsSubjectEntityDetails(OpenApiModel): fullName: str subjectDetailsType: EntitySubjectDetailsType - address: str | None = None - + address: Optional[str] = None @dataclass(frozen=True) class PermissionsSubjectPersonByFingerprintDetails(OpenApiModel): firstName: str lastName: str subjectDetailsType: PersonSubjectByFingerprintDetailsType - birthDate: str | None = None - idDocument: IdDocument | None = None - personIdentifier: PersonIdentifier | None = None - + birthDate: Optional[str] = None + idDocument: Optional[IdDocument] = None + personIdentifier: Optional[PersonIdentifier] = None @dataclass(frozen=True) class PermissionsSubjectPersonDetails(OpenApiModel): firstName: str lastName: str subjectDetailsType: PersonSubjectDetailsType - birthDate: str | None = None - idDocument: IdDocument | None = None - personIdentifier: PersonIdentifier | None = None - + birthDate: Optional[str] = None + idDocument: Optional[IdDocument] = None + personIdentifier: Optional[PersonIdentifier] = None @dataclass(frozen=True) class PersonByFingerprintWithIdentifierDetails(OpenApiModel): @@ -1560,7 +1369,6 @@ class PersonByFingerprintWithIdentifierDetails(OpenApiModel): identifier: PersonIdentifier lastName: str - @dataclass(frozen=True) class PersonByFingerprintWithoutIdentifierDetails(OpenApiModel): birthDate: str @@ -1568,29 +1376,25 @@ class PersonByFingerprintWithoutIdentifierDetails(OpenApiModel): idDocument: IdDocument lastName: str - @dataclass(frozen=True) class PersonCreateRequest(OpenApiModel): description: str isBailiff: bool nip: Nip pesel: Pesel - createdDate: str | None = None - isDeceased: bool | None = None - + createdDate: Optional[str] = None + isDeceased: Optional[bool] = None @dataclass(frozen=True) class PersonDetails(OpenApiModel): firstName: str lastName: str - @dataclass(frozen=True) class PersonIdentifier(OpenApiModel): type: PersonIdentifierType value: str - @dataclass(frozen=True) class PersonPermission(OpenApiModel): authorIdentifier: PersonPermissionsAuthorIdentifier @@ -1601,38 +1405,33 @@ class PersonPermission(OpenApiModel): permissionScope: PersonPermissionScope permissionState: PermissionState startDate: str - contextIdentifier: PersonPermissionsContextIdentifier | None = None - subjectEntityDetails: PermissionsSubjectEntityDetails | None = None - subjectPersonDetails: PermissionsSubjectPersonDetails | None = None - targetIdentifier: PersonPermissionsTargetIdentifier | None = None - + contextIdentifier: Optional[PersonPermissionsContextIdentifier] = None + subjectEntityDetails: Optional[PermissionsSubjectEntityDetails] = None + subjectPersonDetails: Optional[PermissionsSubjectPersonDetails] = None + targetIdentifier: Optional[PersonPermissionsTargetIdentifier] = None @dataclass(frozen=True) class PersonPermissionSubjectDetails(OpenApiModel): subjectDetailsType: PersonPermissionSubjectDetailsType - personByFpNoId: PersonByFingerprintWithoutIdentifierDetails | None = None - personByFpWithId: PersonByFingerprintWithIdentifierDetails | None = None - personById: PersonDetails | None = None - + personByFpNoId: Optional[PersonByFingerprintWithoutIdentifierDetails] = None + personByFpWithId: Optional[PersonByFingerprintWithIdentifierDetails] = None + personById: Optional[PersonDetails] = None @dataclass(frozen=True) class PersonPermissionsAuthorIdentifier(OpenApiModel): type: PersonPermissionsAuthorIdentifierType - value: str | None = None - + value: Optional[str] = None @dataclass(frozen=True) class PersonPermissionsAuthorizedIdentifier(OpenApiModel): type: PersonPermissionsAuthorizedIdentifierType value: str - @dataclass(frozen=True) class PersonPermissionsContextIdentifier(OpenApiModel): type: PersonPermissionsContextIdentifierType value: str - @dataclass(frozen=True) class PersonPermissionsGrantRequest(OpenApiModel): description: str @@ -1640,35 +1439,30 @@ class PersonPermissionsGrantRequest(OpenApiModel): subjectDetails: PersonPermissionSubjectDetails subjectIdentifier: PersonPermissionsSubjectIdentifier - @dataclass(frozen=True) class PersonPermissionsQueryRequest(OpenApiModel): queryType: PersonPermissionsQueryType - authorIdentifier: PersonPermissionsAuthorIdentifier | None = None - authorizedIdentifier: PersonPermissionsAuthorizedIdentifier | None = None - contextIdentifier: PersonPermissionsContextIdentifier | None = None - permissionState: PermissionState | None = None - permissionTypes: list[PersonPermissionType] | None = None - targetIdentifier: PersonPermissionsTargetIdentifier | None = None - + authorIdentifier: Optional[PersonPermissionsAuthorIdentifier] = None + authorizedIdentifier: Optional[PersonPermissionsAuthorizedIdentifier] = None + contextIdentifier: Optional[PersonPermissionsContextIdentifier] = None + permissionState: Optional[PermissionState] = None + permissionTypes: Optional[list[PersonPermissionType]] = None + targetIdentifier: Optional[PersonPermissionsTargetIdentifier] = None @dataclass(frozen=True) class PersonPermissionsSubjectIdentifier(OpenApiModel): type: PersonPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class PersonPermissionsTargetIdentifier(OpenApiModel): type: PersonPermissionsTargetIdentifierType - value: str | None = None - + value: Optional[str] = None @dataclass(frozen=True) class PersonRemoveRequest(OpenApiModel): nip: Nip - @dataclass(frozen=True) class PersonalPermission(OpenApiModel): canDelegate: bool @@ -1677,38 +1471,33 @@ class PersonalPermission(OpenApiModel): permissionScope: PersonalPermissionScope permissionState: PermissionState startDate: str - authorizedIdentifier: PersonalPermissionsAuthorizedIdentifier | None = None - contextIdentifier: PersonalPermissionsContextIdentifier | None = None - subjectEntityDetails: PermissionsSubjectEntityDetails | None = None - subjectPersonDetails: PermissionsSubjectPersonDetails | None = None - targetIdentifier: PersonalPermissionsTargetIdentifier | None = None - + authorizedIdentifier: Optional[PersonalPermissionsAuthorizedIdentifier] = None + contextIdentifier: Optional[PersonalPermissionsContextIdentifier] = None + subjectEntityDetails: Optional[PermissionsSubjectEntityDetails] = None + subjectPersonDetails: Optional[PermissionsSubjectPersonDetails] = None + targetIdentifier: Optional[PersonalPermissionsTargetIdentifier] = None @dataclass(frozen=True) class PersonalPermissionsAuthorizedIdentifier(OpenApiModel): type: PersonalPermissionsAuthorizedIdentifierType value: str - @dataclass(frozen=True) class PersonalPermissionsContextIdentifier(OpenApiModel): type: PersonalPermissionsContextIdentifierType value: str - @dataclass(frozen=True) class PersonalPermissionsQueryRequest(OpenApiModel): - contextIdentifier: PersonalPermissionsContextIdentifier | None = None - permissionState: PermissionState | None = None - permissionTypes: list[PersonalPermissionType] | None = None - targetIdentifier: PersonalPermissionsTargetIdentifier | None = None - + contextIdentifier: Optional[PersonalPermissionsContextIdentifier] = None + permissionState: Optional[PermissionState] = None + permissionTypes: Optional[list[PersonalPermissionType]] = None + targetIdentifier: Optional[PersonalPermissionsTargetIdentifier] = None @dataclass(frozen=True) class PersonalPermissionsTargetIdentifier(OpenApiModel): type: PersonalPermissionsTargetIdentifierType - value: str | None = None - + value: Optional[str] = None @dataclass(frozen=True) class PublicKeyCertificate(OpenApiModel): @@ -1717,83 +1506,70 @@ class PublicKeyCertificate(OpenApiModel): validFrom: str validTo: str - @dataclass(frozen=True) class QueryCertificatesRequest(OpenApiModel): - certificateSerialNumber: str | None = None - expiresAfter: str | None = None - name: str | None = None - status: CertificateListItemStatus | None = None - type: KsefCertificateType | None = None - + certificateSerialNumber: Optional[str] = None + expiresAfter: Optional[str] = None + name: Optional[str] = None + status: Optional[CertificateListItemStatus] = None + type: Optional[KsefCertificateType] = None @dataclass(frozen=True) class QueryCertificatesResponse(OpenApiModel): certificates: list[CertificateListItem] hasMore: bool - @dataclass(frozen=True) class QueryEntityAuthorizationPermissionsResponse(OpenApiModel): authorizationGrants: list[EntityAuthorizationGrant] hasMore: bool - @dataclass(frozen=True) class QueryEntityRolesResponse(OpenApiModel): hasMore: bool roles: list[EntityRole] - @dataclass(frozen=True) class QueryEuEntityPermissionsResponse(OpenApiModel): hasMore: bool permissions: list[EuEntityPermission] - @dataclass(frozen=True) class QueryInvoicesMetadataResponse(OpenApiModel): hasMore: bool invoices: list[InvoiceMetadata] isTruncated: bool - permanentStorageHwmDate: str | None = None - + permanentStorageHwmDate: Optional[str] = None @dataclass(frozen=True) class QueryPeppolProvidersResponse(OpenApiModel): hasMore: bool peppolProviders: list[PeppolProvider] - @dataclass(frozen=True) class QueryPersonPermissionsResponse(OpenApiModel): hasMore: bool permissions: list[PersonPermission] - @dataclass(frozen=True) class QueryPersonalPermissionsResponse(OpenApiModel): hasMore: bool permissions: list[PersonalPermission] - @dataclass(frozen=True) class QuerySubordinateEntityRolesResponse(OpenApiModel): hasMore: bool roles: list[SubordinateEntityRole] - @dataclass(frozen=True) class QuerySubunitPermissionsResponse(OpenApiModel): hasMore: bool permissions: list[SubunitPermission] - @dataclass(frozen=True) class QueryTokensResponse(OpenApiModel): tokens: list[QueryTokensResponseItem] - continuationToken: str | None = None - + continuationToken: Optional[str] = None @dataclass(frozen=True) class QueryTokensResponseItem(OpenApiModel): @@ -1804,9 +1580,8 @@ class QueryTokensResponseItem(OpenApiModel): referenceNumber: ReferenceNumber requestedPermissions: list[TokenPermissionType] status: AuthenticationTokenStatus - lastUseDate: str | None = None - statusDetails: list[str] | None = None - + lastUseDate: Optional[str] = None + statusDetails: Optional[list[str]] = None @dataclass(frozen=True) class RetrieveCertificatesListItem(OpenApiModel): @@ -1815,21 +1590,17 @@ class RetrieveCertificatesListItem(OpenApiModel): certificateSerialNumber: str certificateType: KsefCertificateType - @dataclass(frozen=True) class RetrieveCertificatesRequest(OpenApiModel): certificateSerialNumbers: list[str] - @dataclass(frozen=True) class RetrieveCertificatesResponse(OpenApiModel): certificates: list[RetrieveCertificatesListItem] - @dataclass(frozen=True) class RevokeCertificateRequest(OpenApiModel): - revocationReason: CertificateRevocationReason | None = None - + revocationReason: Optional[CertificateRevocationReason] = None @dataclass(frozen=True) class SendInvoiceRequest(OpenApiModel): @@ -1838,15 +1609,13 @@ class SendInvoiceRequest(OpenApiModel): encryptedInvoiceSize: int invoiceHash: Sha256HashBase64 invoiceSize: int - hashOfCorrectedInvoice: Sha256HashBase64 | None = None - offlineMode: bool | None = None - + hashOfCorrectedInvoice: Optional[Sha256HashBase64] = None + offlineMode: Optional[bool] = None @dataclass(frozen=True) class SendInvoiceResponse(OpenApiModel): referenceNumber: ReferenceNumber - @dataclass(frozen=True) class SessionInvoiceStatusResponse(OpenApiModel): invoiceHash: Sha256HashBase64 @@ -1854,39 +1623,35 @@ class SessionInvoiceStatusResponse(OpenApiModel): ordinalNumber: int referenceNumber: ReferenceNumber status: InvoiceStatusInfo - acquisitionDate: str | None = None - invoiceFileName: str | None = None - invoiceNumber: str | None = None - invoicingMode: InvoicingMode | None = None - ksefNumber: KsefNumber | None = None - permanentStorageDate: str | None = None - upoDownloadUrl: str | None = None - upoDownloadUrlExpirationDate: str | None = None - + acquisitionDate: Optional[str] = None + invoiceFileName: Optional[str] = None + invoiceNumber: Optional[str] = None + invoicingMode: Optional[InvoicingMode] = None + ksefNumber: Optional[KsefNumber] = None + permanentStorageDate: Optional[str] = None + upoDownloadUrl: Optional[str] = None + upoDownloadUrlExpirationDate: Optional[str] = None @dataclass(frozen=True) class SessionInvoicesResponse(OpenApiModel): invoices: list[SessionInvoiceStatusResponse] - continuationToken: str | None = None - + continuationToken: Optional[str] = None @dataclass(frozen=True) class SessionStatusResponse(OpenApiModel): dateCreated: str dateUpdated: str status: StatusInfo - failedInvoiceCount: int | None = None - invoiceCount: int | None = None - successfulInvoiceCount: int | None = None - upo: UpoResponse | None = None - validUntil: str | None = None - + failedInvoiceCount: Optional[int] = None + invoiceCount: Optional[int] = None + successfulInvoiceCount: Optional[int] = None + upo: Optional[UpoResponse] = None + validUntil: Optional[str] = None @dataclass(frozen=True) class SessionsQueryResponse(OpenApiModel): sessions: list[SessionsQueryResponseItem] - continuationToken: str | None = None - + continuationToken: Optional[str] = None @dataclass(frozen=True) class SessionsQueryResponseItem(OpenApiModel): @@ -1897,48 +1662,41 @@ class SessionsQueryResponseItem(OpenApiModel): status: StatusInfo successfulInvoiceCount: int totalInvoiceCount: int - validUntil: str | None = None - + validUntil: Optional[str] = None @dataclass(frozen=True) class SetRateLimitsRequest(OpenApiModel): rateLimits: ApiRateLimitsOverride - @dataclass(frozen=True) class SetSessionLimitsRequest(OpenApiModel): batchSession: BatchSessionContextLimitsOverride onlineSession: OnlineSessionContextLimitsOverride - @dataclass(frozen=True) class SetSubjectLimitsRequest(OpenApiModel): - certificate: CertificateSubjectLimitsOverride | None = None - enrollment: EnrollmentSubjectLimitsOverride | None = None - subjectIdentifierType: SubjectIdentifierType | None = None - + certificate: Optional[CertificateSubjectLimitsOverride] = None + enrollment: Optional[EnrollmentSubjectLimitsOverride] = None + subjectIdentifierType: Optional[SubjectIdentifierType] = None @dataclass(frozen=True) class StatusInfo(OpenApiModel): code: int description: str - details: list[str] | None = None - + details: Optional[list[str]] = None @dataclass(frozen=True) class SubjectCreateRequest(OpenApiModel): description: str subjectNip: Nip subjectType: SubjectType - createdDate: str | None = None - subunits: list[Subunit] | None = None - + createdDate: Optional[str] = None + subunits: Optional[list[Subunit]] = None @dataclass(frozen=True) class SubjectRemoveRequest(OpenApiModel): subjectNip: Nip - @dataclass(frozen=True) class SubordinateEntityRole(OpenApiModel): description: str @@ -1946,24 +1704,20 @@ class SubordinateEntityRole(OpenApiModel): startDate: str subordinateEntityIdentifier: SubordinateRoleSubordinateEntityIdentifier - @dataclass(frozen=True) class SubordinateEntityRolesQueryRequest(OpenApiModel): - subordinateEntityIdentifier: EntityPermissionsSubordinateEntityIdentifier | None = None - + subordinateEntityIdentifier: Optional[EntityPermissionsSubordinateEntityIdentifier] = None @dataclass(frozen=True) class SubordinateRoleSubordinateEntityIdentifier(OpenApiModel): type: SubordinateRoleSubordinateEntityIdentifierType value: str - @dataclass(frozen=True) class Subunit(OpenApiModel): description: str subjectNip: Nip - @dataclass(frozen=True) class SubunitPermission(OpenApiModel): authorIdentifier: SubunitPermissionsAuthorIdentifier @@ -1973,103 +1727,87 @@ class SubunitPermission(OpenApiModel): permissionScope: SubunitPermissionScope startDate: str subunitIdentifier: SubunitPermissionsSubunitIdentifier - subjectPersonDetails: PermissionsSubjectPersonDetails | None = None - subunitName: str | None = None - + subjectPersonDetails: Optional[PermissionsSubjectPersonDetails] = None + subunitName: Optional[str] = None @dataclass(frozen=True) class SubunitPermissionsAuthorIdentifier(OpenApiModel): type: SubunitPermissionsAuthorIdentifierType value: str - @dataclass(frozen=True) class SubunitPermissionsAuthorizedIdentifier(OpenApiModel): type: SubunitPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class SubunitPermissionsContextIdentifier(OpenApiModel): type: SubunitPermissionsContextIdentifierType value: str - @dataclass(frozen=True) class SubunitPermissionsGrantRequest(OpenApiModel): contextIdentifier: SubunitPermissionsContextIdentifier description: str subjectDetails: PersonPermissionSubjectDetails subjectIdentifier: SubunitPermissionsSubjectIdentifier - subunitName: str | None = None - + subunitName: Optional[str] = None @dataclass(frozen=True) class SubunitPermissionsQueryRequest(OpenApiModel): - subunitIdentifier: SubunitPermissionsSubunitIdentifier | None = None - + subunitIdentifier: Optional[SubunitPermissionsSubunitIdentifier] = None @dataclass(frozen=True) class SubunitPermissionsSubjectIdentifier(OpenApiModel): type: SubunitPermissionsSubjectIdentifierType value: str - @dataclass(frozen=True) class SubunitPermissionsSubunitIdentifier(OpenApiModel): type: SubunitPermissionsSubunitIdentifierType value: str - @dataclass(frozen=True) class TestDataAuthorizedIdentifier(OpenApiModel): type: TestDataAuthorizedIdentifierType value: str - @dataclass(frozen=True) class TestDataContextIdentifier(OpenApiModel): type: TestDataContextIdentifierType value: str - @dataclass(frozen=True) class TestDataPermission(OpenApiModel): description: str permissionType: TestDataPermissionType - @dataclass(frozen=True) class TestDataPermissionsGrantRequest(OpenApiModel): authorizedIdentifier: TestDataAuthorizedIdentifier contextIdentifier: TestDataContextIdentifier permissions: list[TestDataPermission] - @dataclass(frozen=True) class TestDataPermissionsRevokeRequest(OpenApiModel): authorizedIdentifier: TestDataAuthorizedIdentifier contextIdentifier: TestDataContextIdentifier - @dataclass(frozen=True) class TokenAuthorIdentifierTypeIdentifier(OpenApiModel): type: TokenAuthorIdentifierType value: str - @dataclass(frozen=True) class TokenContextIdentifierTypeIdentifier(OpenApiModel): type: TokenContextIdentifierType value: str - @dataclass(frozen=True) class TokenInfo(OpenApiModel): token: str validUntil: str - @dataclass(frozen=True) class TokenStatusResponse(OpenApiModel): authorIdentifier: TokenAuthorIdentifierTypeIdentifier @@ -2079,22 +1817,19 @@ class TokenStatusResponse(OpenApiModel): referenceNumber: ReferenceNumber requestedPermissions: list[TokenPermissionType] status: AuthenticationTokenStatus - lastUseDate: str | None = None - statusDetails: list[str] | None = None - + lastUseDate: Optional[str] = None + statusDetails: Optional[list[str]] = None @dataclass(frozen=True) class TooManyRequestsResponse(OpenApiModel): status: dict[str, Any] - @dataclass(frozen=True) class UpoPageResponse(OpenApiModel): downloadUrl: str downloadUrlExpirationDate: str referenceNumber: ReferenceNumber - @dataclass(frozen=True) class UpoResponse(OpenApiModel): pages: list[UpoPageResponse] diff --git a/tools/generate_openapi_models.py b/tools/generate_openapi_models.py index abc6590..79c370c 100644 --- a/tools/generate_openapi_models.py +++ b/tools/generate_openapi_models.py @@ -252,7 +252,8 @@ def generate_models(input_path: Path, output_path: Path) -> None: lines.extend(_generate_object(name, schemas[name])) lines.append("") - output_path.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8") + with output_path.open("w", encoding="utf-8", newline="\n") as f: + f.write("\n".join(lines).rstrip() + "\n") def main() -> None: From 1cf8748e57bfaf204e72c71f318c95bdad4cdaa8 Mon Sep 17 00:00:00 2001 From: smkc Date: Sun, 18 Jan 2026 17:37:06 +0100 Subject: [PATCH 3/7] fix(ci): Resolve Ruff linting issues in generated files and tools - Add top-level '# ruff: noqa' to generated openapi_models.py to fully disable linting. - Clean up imports and add '# ruff: noqa: E501' to check_coverage.py. --- tools/check_coverage.py | 139 +++++++++++++++++-------------- tools/generate_openapi_models.py | 5 +- 2 files changed, 79 insertions(+), 65 deletions(-) diff --git a/tools/check_coverage.py b/tools/check_coverage.py index 62717ad..618cd89 100644 --- a/tools/check_coverage.py +++ b/tools/check_coverage.py @@ -1,11 +1,11 @@ +# ruff: noqa: E501 import argparse import ast import json import re -from pathlib import Path -from typing import Set, Tuple, Dict, List, Optional -from collections import defaultdict from dataclasses import dataclass +from pathlib import Path + def normalize_path(path: str) -> str: @@ -13,7 +13,7 @@ def normalize_path(path: str) -> str: return re.sub(r"{[^}]+}", "{}", path) -def extract_path_params(path: str) -> Set[str]: +def extract_path_params(path: str) -> set[str]: # Extract parameter names from OpenAPI path: /auth/{referenceNumber} -> {referenceNumber} return set(re.findall(r"{([^}]+)}", path)) @@ -23,8 +23,8 @@ class EndpointSpec: method: str path: str normalized_path: str - path_params: Set[str] - query_params: Set[str] + path_params: set[str] + query_params: set[str] @dataclass @@ -33,39 +33,39 @@ class ImplementedEndpoint: path_pattern: str normalized_path: str # Parameters detected in the f-string path construction - detected_path_vars: Set[str] + detected_path_vars: set[str] # Parameters passed to params={} argument - detected_query_vars: Set[str] + detected_query_vars: set[str] file_path: str line_no: int -def get_openapi_specs(openapi_path: Path) -> Dict[Tuple[str, str], EndpointSpec]: +def get_openapi_specs(openapi_path: Path) -> dict[tuple[str, str], EndpointSpec]: """Returns a map of (method, normalized_path) -> EndpointSpec from OpenAPI.""" - with open(openapi_path, "r", encoding="utf-8") as f: + with open(openapi_path, encoding="utf-8") as f: data = json.load(f) specs = {} for path, methods in data.get("paths", {}).items(): norm_path = normalize_path(path) path_params = extract_path_params(path) - + for method_name, details in methods.items(): method = method_name.upper() - + # Extract query parameters defined for this operation query_params = set() parameters = details.get("parameters", []) for param in parameters: if param.get("in") == "query": query_params.add(param["name"]) - + spec = EndpointSpec( method=method, path=path, normalized_path=norm_path, path_params=path_params, - query_params=query_params + query_params=query_params, ) specs[(method, norm_path)] = spec return specs @@ -74,11 +74,16 @@ def get_openapi_specs(openapi_path: Path) -> Dict[Tuple[str, str], EndpointSpec] class AdvancedClientVisitor(ast.NodeVisitor): def __init__(self, filename: str): self.filename = filename - self.found_endpoints: List[ImplementedEndpoint] = [] + self.found_endpoints: list[ImplementedEndpoint] = [] def visit_Call(self, node): # Look for self._request_json / self._request_bytes / self._request_raw - if isinstance(node.func, ast.Attribute) and node.func.attr in ("_request_json", "_request_bytes", "_request_no_auth", "_request_raw"): + if isinstance(node.func, ast.Attribute) and node.func.attr in ( + "_request_json", + "_request_bytes", + "_request_no_auth", + "_request_raw", + ): self._analyze_request_call(node) self.generic_visit(node) @@ -92,7 +97,7 @@ def _analyze_request_call(self, node: ast.Call): # Extract Method method = self._extract_string_value(method_arg) if not method: - return # Could not resolve method statically + return # Could not resolve method statically # Extract Path and Path Params (from f-strings) path_pattern, detected_path_vars = self._extract_path_info(path_arg) @@ -104,30 +109,32 @@ def _analyze_request_call(self, node: ast.Call): # Extract Query Params detected_query_vars = self._extract_query_params(node) - self.found_endpoints.append(ImplementedEndpoint( - method=method.upper(), - path_pattern=path_pattern, - normalized_path=normalized_path, - detected_path_vars=detected_path_vars, - detected_query_vars=detected_query_vars, - file_path=self.filename, - line_no=node.lineno - )) - - def _extract_string_value(self, node) -> Optional[str]: + self.found_endpoints.append( + ImplementedEndpoint( + method=method.upper(), + path_pattern=path_pattern, + normalized_path=normalized_path, + detected_path_vars=detected_path_vars, + detected_query_vars=detected_query_vars, + file_path=self.filename, + line_no=node.lineno, + ) + ) + + def _extract_string_value(self, node) -> str | None: if isinstance(node, ast.Constant) and isinstance(node.value, str): return node.value return None - def _extract_path_info(self, node) -> Tuple[Optional[str], Set[str]]: + def _extract_path_info(self, node) -> tuple[str | None, set[str]]: if isinstance(node, ast.Constant) and isinstance(node.value, str): return node.value, set() - + if isinstance(node, ast.JoinedStr): # Convert f-string f"/auth/{ref}" to pattern "/auth/{}" and extract vars pattern_parts = [] vars_found = set() - + for part in node.values: if isinstance(part, ast.Constant) and isinstance(part.value, str): pattern_parts.append(part.value) @@ -136,34 +143,34 @@ def _extract_path_info(self, node) -> Tuple[Optional[str], Set[str]]: # Try to get the variable name used in f-string if isinstance(part.value, ast.Name): vars_found.add(part.value.id) - + return "".join(pattern_parts), vars_found - + return None, set() - def _extract_query_params(self, node: ast.Call) -> Set[str]: + def _extract_query_params(self, node: ast.Call) -> set[str]: # Look for 'params' keyword argument params_keywords = [kw for kw in node.keywords if kw.arg == "params"] if not params_keywords: return set() - + params_value = params_keywords[0].value - + # We handle: params={'page': page, 'limit': 10} # or params=params (if params is a dict built earlier, hard to track statically perfectly) - + found_keys = set() if isinstance(params_value, ast.Dict): for key in params_value.keys: if isinstance(key, ast.Constant) and isinstance(key.value, str): found_keys.add(key.value) - + # If params passed as variable (e.g. params=page_params), we assume best effort or specific variable name tracking # For now, we only statically analyze inline dict definitions or assume manual review if dynamic return found_keys -def get_implemented_endpoints_deep(source_dir: Path) -> List[ImplementedEndpoint]: +def get_implemented_endpoints_deep(source_dir: Path) -> list[ImplementedEndpoint]: endpoints = [] for py_file in source_dir.rglob("*.py"): try: @@ -178,38 +185,37 @@ def get_implemented_endpoints_deep(source_dir: Path) -> List[ImplementedEndpoint def to_camel_case(snake_str: str) -> str: # reference_number -> referenceNumber - components = snake_str.split('_') - return components[0] + ''.join(x.title() for x in components[1:]) + components = snake_str.split("_") + return components[0] + "".join(x.title() for x in components[1:]) def main(): - import sys - from dataclasses import dataclass - - # Re-declare dataclasses here for standalone script execution context if needed + # Re-declare dataclasses here for standalone script execution context if needed # (though already defined above, ensuring valid scope) parser = argparse.ArgumentParser(description="Deep API coverage check.") parser.add_argument("--openapi", required=True, type=Path, help="Path to open-api.json") - parser.add_argument("--src", required=True, type=Path, help="Path to source directory containing clients") + parser.add_argument( + "--src", required=True, type=Path, help="Path to source directory containing clients" + ) args = parser.parse_args() # 1. Load OpenAPI Specs openapi_specs = get_openapi_specs(args.openapi) - + # 2. Analyze Code implemented_eps = get_implemented_endpoints_deep(args.src) - + # 3. Compare openapi_keys = set(openapi_specs.keys()) implemented_keys = set((ep.method, ep.normalized_path) for ep in implemented_eps) - + missing = openapi_keys - implemented_keys extra = implemented_keys - openapi_keys - + print(f"OpenAPI Endpoints: {len(openapi_keys)}") print(f"Implemented Endpoints: {len(implemented_keys)}") - + issues_found = False if missing: @@ -222,39 +228,45 @@ def main(): print("\n[EXTRA] The following endpoints found in code but NOT in OpenAPI:") for method, path in sorted(extra): # Try to find file info - matches = [x for x in implemented_eps if x.method == method and x.normalized_path == path] + matches = [ + x for x in implemented_eps if x.method == method and x.normalized_path == path + ] for m in matches: print(f" - [{method}] {m.path_pattern} (at {m.file_path}:{m.line_no})") # Extra endpoints might be issues if they are typos if extra: - print(" (Note: This might be due to typos in URL or unofficial endpoints)") - issues_found = True + print(" (Note: This might be due to typos in URL or unofficial endpoints)") + issues_found = True # Deep Analysis: Params print("\n[DEEP ANALYSIS] Checking Path & Query Parameters...") - + # Map implementation to spec for verification for impl in implemented_eps: spec = openapi_specs.get((impl.method, impl.normalized_path)) if not spec: - continue # Extra endpoint implemented? or ignored - + continue # Extra endpoint implemented? or ignored + # Check Path Params # OpenAPI: {referenceNumber} -> Python: reference_number (snake case conversion usually) # We try to match count. if len(impl.detected_path_vars) != len(spec.path_params): - # Heuristic check - print(f" [WARN] Path param mismatch for {impl.method} {spec.path}") - print(f" Expected: {spec.path_params}") - print(f" Found in f-string: {impl.detected_path_vars} at {impl.file_path}:{impl.line_no}") - + # Heuristic check + print(f" [WARN] Path param mismatch for {impl.method} {spec.path}") + print(f" Expected: {spec.path_params}") + print( + f" Found in f-string: {impl.detected_path_vars} at {impl.file_path}:{impl.line_no}" + ) + # Check Query Params # We only check if the KEY names used in params={} dictionary exist in OpenAPI definition # OpenAPI params are usually camelCase (pageSize). Python code should use pageSize key in dict. for query_key in impl.detected_query_vars: if query_key not in spec.query_params: # Common false positive: 'page' vs 'Page', or continuationToken - print(f" [WARN] Unknown query param '{query_key}' used in code for {impl.method} {spec.path}") + print( + f" [WARN] Unknown query param '{query_key}' used in code for {impl.method} {spec.path}" + ) print(f" Allowed: {spec.query_params} at {impl.file_path}:{impl.line_no}") if issues_found: @@ -267,4 +279,5 @@ def main(): if __name__ == "__main__": from dataclasses import dataclass + main() diff --git a/tools/generate_openapi_models.py b/tools/generate_openapi_models.py index 79c370c..206edc0 100644 --- a/tools/generate_openapi_models.py +++ b/tools/generate_openapi_models.py @@ -156,6 +156,7 @@ def generate_models(input_path: Path, output_path: Path) -> None: alias_names.append(name) lines: list[str] = [ + "# ruff: noqa", "# Generated from ksef-docs/open-api.json. Do not edit manually.", "from __future__ import annotations", "", @@ -221,7 +222,7 @@ def generate_models(input_path: Path, output_path: Path) -> None: ' raise ValueError("data is None")', " type_map = _get_type_map(cls)", " kwargs: dict[str, Any] = {}", - " for model_field in fields(cls):", + " for model_field in fields(cls): # type: ignore", ' json_key = model_field.metadata.get("json_key", model_field.name)', " if json_key in data:", " type_hint = type_map.get(model_field.name, Any)", @@ -230,7 +231,7 @@ def generate_models(input_path: Path, output_path: Path) -> None: "", " def to_dict(self, omit_none: bool = True) -> dict[str, Any]:", " result: dict[str, Any] = {}", - " for model_field in fields(self):", + " for model_field in fields(self): # type: ignore", ' json_key = model_field.metadata.get("json_key", model_field.name)', " value = getattr(self, model_field.name)", " if omit_none and value is None:", From aa5d02b7da6a46b9f1dccf0fcfea5792775346a6 Mon Sep 17 00:00:00 2001 From: smkc Date: Sun, 18 Jan 2026 17:38:49 +0100 Subject: [PATCH 4/7] refactor: Replace raw OpenAPI specification with generated Python models. --- open-api.json | 15003 ---------------------------- src/ksef_client/openapi_models.py | 5 +- 2 files changed, 3 insertions(+), 15005 deletions(-) delete mode 100644 open-api.json diff --git a/open-api.json b/open-api.json deleted file mode 100644 index 3127eda..0000000 --- a/open-api.json +++ /dev/null @@ -1,15003 +0,0 @@ -{ - "openapi": "3.0.4", - "info": { - "title": "KSeF API TE", - "description": "**Wersja API:** 2.0.0 (build 2.0.1-te)
\n**Klucze publiczne** Ministerstwa Finansów (dla danego środowiska): [Pobierz klucze](#tag/Certyfikaty-klucza-publicznego)
\n**Historia zmian:** [Changelog](https://github.com/CIRFMF/ksef-docs/blob/main/api-changelog.md)
\n**Rozszerzona dokumentacja API:** [ksef-docs](https://github.com/CIRFMF/ksef-docs/tree/main)\n\n**Adres serwera API:**\n- Środowisko TEST: `https://api-test.ksef.mf.gov.pl/v2`\n- [deprecated] Środowisko TEST: `https://ksef-test.mf.gov.pl/api/v2`\n", - "version": "v2" - }, - "servers": [ - { - "url": "https://api-test.ksef.mf.gov.pl/v2", - "description": "Środowisko TEST" - }, - { - "url": "https://ksef-test.mf.gov.pl/api/v2", - "description": "[deprecated] Środowisko TEST" - } - ], - "paths": { - "/auth/sessions": { - "get": { - "tags": [ - "Aktywne sesje" - ], - "summary": "Pobranie listy aktywnych sesji", - "description": "Zwraca listę aktywnych sesji uwierzytelnienia.\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n", - "parameters": [ - { - "name": "x-continuation-token", - "in": "header", - "description": "Token służący do pobrania kolejnej strony wyników.", - "schema": { - "type": "string" - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationListResponse" - }, - "example": { - "continuationToken": "W3siY29tcG9zaXRlVG9rZW4iOnsidG9rZW4iOm51bGwsInJhbmdlIjp7Im1pbiI6IjA1QzFFMCIsIm1heCI6IkZGIn19LCJyZXN1bWVWYWx1ZXMiOlsiMjAyNS0xMC0wM1QxMjoxODo0OS4zNDY2ODQ3WiJdLCJyaWQiOiIzeHd0QVBJWDVRRlVoZ0FBQUFBQUJBPT0iLCJza2lwQ291bnQiOjF9XQ==", - "items": [ - { - "referenceNumber": "20251010-AU-19F5E39000-39B5B182BA-B8", - "isCurrent": false, - "startDate": "2025-10-11T12:23:56.0154302+00:00", - "authenticationMethod": "QualifiedSeal", - "status": { - "code": 200, - "description": "Uwierzytelnianie zakończone sukcesem" - }, - "isTokenRedeemed": true, - "refreshTokenValidUntil": "2025-11-28T09:22:13.388+00:00" - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - } - ] - } - }, - "/auth/sessions/current": { - "delete": { - "tags": [ - "Aktywne sesje" - ], - "summary": "Unieważnienie aktualnej sesji uwierzytelnienia", - "description": "Unieważnia sesję powiązaną z tokenem użytym do wywołania tej operacji.\n\nUnieważnienie sesji sprawia, że powiązany z nią refresh token przestaje działać i nie można już za jego pomocą uzyskać kolejnych access tokenów.\n**Aktywne access tokeny działają do czasu minięcia ich termin ważności.**\n\nSposób uwierzytelnienia: `RefreshToken` lub `AccessToken`.", - "responses": { - "204": { - "description": "No Content" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/auth/sessions/{referenceNumber}": { - "delete": { - "tags": [ - "Aktywne sesje" - ], - "summary": "Unieważnienie sesji uwierzytelnienia", - "description": "Unieważnia sesję o podanym numerze referencyjnym.\n\nUnieważnienie sesji sprawia, że powiązany z nią refresh token przestaje działać i nie można już za jego pomocą uzyskać kolejnych access tokenów.\n**Aktywne access tokeny działają do czasu minięcia ich termin ważności.**", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji uwierzytelnienia.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "204": { - "description": "No Content" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/certificates/limits": { - "get": { - "tags": [ - "Certyfikaty" - ], - "summary": "Pobranie danych o limitach certyfikatów", - "description": "Zwraca informacje o limitach certyfikatów oraz informacje czy użytkownik może zawnioskować o certyfikat KSeF.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CertificateLimitsResponse" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/certificates/enrollments/data": { - "get": { - "tags": [ - "Certyfikaty" - ], - "summary": "Pobranie danych do wniosku certyfikacyjnego", - "description": "Zwraca dane wymagane do przygotowania wniosku certyfikacyjnego PKCS#10.\n\nDane te są zwracane na podstawie certyfikatu użytego w procesie uwierzytelnienia i identyfikują podmiot, który składa wniosek o certyfikat.\n\n\n> Więcej informacji:\n> - [Pobranie danych do wniosku certyfikacyjnego](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#2-pobranie-danych-do-wniosku-certyfikacyjnego)\n> - [Przygotowanie wniosku](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#3-przygotowanie-csr-certificate-signing-request)", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CertificateEnrollmentDataResponse" - }, - "example": { - "commonName": "Firma Kowalski Certyfikat", - "countryName": "PL", - "serialNumber": "ABC123456789", - "uniqueIdentifier": "d9d22724-4696-460c-9e5e-b9e3aafb0af3", - "organizationName": "Firma Kowalski Sp. z o.o.", - "organizationIdentifier": "7762811692" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|-------------------------------------------------------------------------------------------|---------|\n| 25001 | Brak możliwości pobrania danych do CSR dla wykorzystanego sposobu uwierzytelnienia. | |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/certificates/enrollments": { - "post": { - "tags": [ - "Certyfikaty" - ], - "summary": "Wysyłka wniosku certyfikacyjnego", - "description": "Przyjmuje wniosek certyfikacyjny i rozpoczyna jego przetwarzanie.\n\nDozwolone typy kluczy prywatnych:\n- RSA (OID: 1.2.840.113549.1.1.1), długość klucza równa 2048 bitów,\n- EC (klucze oparte na krzywych eliptycznych, OID: 1.2.840.10045.2.1), krzywa NIST P-256 (secp256r1)\n\nZalecane jest stosowanie kluczy EC.\n\nDozwolone algorytmy podpisu:\n- RSA PKCS#1 v1.5,\n- RSA PSS,\n- ECDSA (format podpisu zgodny z RFC 3279)\n\nDozwolone funkcje skrótu użyte do podpisu CSR:\n- SHA1,\n- SHA256,\n- SHA384,\n- SHA512\n\n> Więcej informacji:\n> - [Wysłanie wniosku certyfikacyjnego](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#4-wys%C5%82anie-wniosku-certyfikacyjnego)", - "requestBody": { - "description": "", - "content": { - "application/json": { - "schema": { - "required": [ - "certificateName", - "certificateType", - "csr" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EnrollCertificateRequest" - } - ] - }, - "example": { - "certificateName": "Certyfikat-Auth-004", - "certificateType": "Authentication", - "csr": "MIIDJjCCAd4CAQAwgbAxIjAgBgNVBAMMGUZpcm1hIEtvd2Fsc2tpIENlcnR5ZmlrYXQxIjAgBgNVBAoMGUZpcm1hIEtvd2Fsc2tpIFNwLiB6IG8uby4xEzARBgNVBGEMCjc3NjI4MTE2OTIxCzAJBgNVBAYTAlBMMRUwEwYDVQQFEwxBQkMxMjM0NTY3ODkxLTArBgNVBC0MJGQ5ZDIyNzI0LTQ2OTYtNDYwYy05ZTVlLWI5ZTNhYWZiMGFmMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANZC1hJiB4ZBsxGy/a4yvtOUP0HQxDt7EUZrfKO78+cmI7KCO9aW96yr6O0R928/Y9vmymbgh6KvMUTzZZj24uyxar849O1laor5t8Wv63RDx/I4+9Rt7w+QPPofmpenOokJH+Fm+FDQwo2l07o8SppGfaZpvMak+cDSrh+73wfM37fvPImr9p4ckzzxA9q6f4uoqGqcGSDlSwRjfLQKzWZaEklpZBpY4jeCh54uN3+YLsMQYKdcIbW0Jart1UbwMd/wbHfzFhVmPGOAMMpwVEBw6E4A0CTWIiAX3Alqbx4+IkuqC+gEs3ETTec7eOqhxe9V9cywi7WR+Mz6JO6DJcUCAwEAAaAAMD0GCSqGSIb3DQEBCjAwoA0wCwYJYIZIAWUDBAIBoRowGAYJKoZIhvcNAQEIMAsGCWCGSAFlAwQCAaIDAgEgA4IBAQCJhtF2/2E+JmkWitE/BGbm3NU4fIxr1Z+w0UnHsP+F8n9UDwAnuncG1GH5wZFervldEMooegzEDnYaqxnEUnbZ4wxeAHqpbTZjOOfqrk7o0r66+mXUs5NnyD4M3j3ig98GcvhEdbcNH+RsIwi7FaLNXnOE4SLYL9KvW0geriywWjS+5MmA0Gcn1e4vCD6FeEls8EHzkhrWE+rUsoM5zT2a0OPNXG3fScyOqOZe+OdjT4Y7ScRGy711u3v2X9RoTqQUDfCJ3cob/KRcrzvs1TQVazGZPfcIa6an6SigUvZ7XAMHlUTyOeM4AwKqiEqQ0qfe/HhlDylgZSwulb9u0utT", - "validFrom": "2025-08-28T09:22:13.388+00:00" - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnrollCertificateResponse" - }, - "example": { - "referenceNumber": "20251010-EH-1B6C9EB000-4B15D3AEB9-89", - "timestamp": "2025-10-11T12:23:56.0154302+00:00" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25002 | Brak możliwości złożenia wniosku certyfikacyjnego dla wykorzystanego sposobu uwierzytelnienia. | |\n| 25003 | Dane w CSR nie zgadzają się z danymi w użytym wektorze uwierzytelniającym. | |\n| 25004 | Niepoprawny format CSR lub niepoprawny podpis CSR. | |\n| 25006 | Osiągnięto limit możliwych do złożenia wniosków certyfikacyjnych. | |\n| 25007 | Osiągnięto limit dopuszczalnej liczby posiadanych certyfikatów. | |\n| 25010 | Nieprawidłowy typ lub długość klucza. | |\n| 25011 | Nieprawidłowy algorytm podpisu CSR. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/certificates/enrollments/{referenceNumber}": { - "get": { - "tags": [ - "Certyfikaty" - ], - "summary": "Pobranie statusu przetwarzania wniosku certyfikacyjnego", - "description": "Zwraca informacje o statusie wniosku certyfikacyjnego.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny wniosku certyfikacyjnego", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CertificateEnrollmentStatusResponse" - }, - "example": { - "requestDate": "2025-10-11T12:23:56.0154302+00:00", - "status": { - "code": 100, - "description": "Wniosek przyjęty do realizacji" - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25005 | Wniosek certyfikacyjny o podanym numerze referencyjnym nie istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/certificates/retrieve": { - "post": { - "tags": [ - "Certyfikaty" - ], - "summary": "Pobranie certyfikatu lub listy certyfikatów", - "description": "Zwraca certyfikaty o podanych numerach seryjnych w formacie DER zakodowanym w Base64.", - "requestBody": { - "description": "", - "content": { - "application/json": { - "schema": { - "required": [ - "certificateSerialNumbers" - ], - "allOf": [ - { - "$ref": "#/components/schemas/RetrieveCertificatesRequest" - } - ] - }, - "example": { - "certificateSerialNumbers": [ - "0321C82DA41B4362", - "0321F21DA462A362" - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RetrieveCertificatesResponse" - }, - "example": { - "certificates": [ - { - "certificate": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/wABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3ODk6Ozw9Pj9AQUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX2BhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ent8fX5/gIGCg4SFhoeIiYqLjI2Oj5CRkpOUlZaXmJmam5ydnp+goaKjpKWmp6ipqqusra6vsLGys7S1tre4ubq7vL2+v8DBwsPExcbHyMnKy8zNzs/Q0dLT1NXW19jZ2tvc3d7f4OHi4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v8AAQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5Ojs8PT4/QEFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaW1xdXl9gYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+f4CBgoOEhYaHiImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6u7y9vr/AwcLDxMXGx8jJysvMzc7P0NHS09TV1tfY2drb3N3e3+Dh4uPk5ebn6Onq6+zt7u/w8fLz9PX29/j5+vv8/f7/AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w==", - "certificateName": "Cert 00023", - "certificateSerialNumber": "0321C82DA41B4362", - "certificateType": "Authentication" - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/certificates/{certificateSerialNumber}/revoke": { - "post": { - "tags": [ - "Certyfikaty" - ], - "summary": "Unieważnienie certyfikatu", - "description": "Unieważnia certyfikat o podanym numerze seryjnym.", - "parameters": [ - { - "name": "certificateSerialNumber", - "in": "path", - "description": "Numer seryjny certyfikatu (w formacie szesnastkowym).", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "description": "", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/RevokeCertificateRequest" - } - ] - } - } - } - }, - "responses": { - "204": { - "description": "No Content" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25008 | Certyfikat o podanym numerze seryjnym nie istnieje. | |\n| 25009 | Nie można odwołać wskazanego certyfikatu, ponieważ jest już odwołany, zablokowany lub nieważny.| |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/certificates/query": { - "post": { - "tags": [ - "Certyfikaty" - ], - "summary": "Pobranie listy metadanych certyfikatów", - "description": "Zwraca listę certyfikatów spełniających podane kryteria wyszukiwania.\nW przypadku braku podania kryteriów wyszukiwania zwrócona zostanie nieprzefiltrowana lista.\n\n**Sortowanie:**\n\n- requestDate (Desc)\n\n", - "parameters": [ - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników", - "schema": { - "maximum": 50, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - }, - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - } - ], - "requestBody": { - "description": "Kryteria filtrowania", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/QueryCertificatesRequest" - } - ] - }, - "example": { - "type": "Offline", - "status": "Active" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryCertificatesResponse" - }, - "example": { - "certificates": [ - { - "certificateSerialNumber": "018209160C631F1E", - "name": "Certyfikat 1", - "type": "Authentication", - "commonName": "Jan Kowalski", - "status": "Active", - "subjectIdentifier": { - "type": "Nip", - "value": "1234445678" - }, - "validFrom": "2025-08-24T14:15:22+00:00", - "validTo": "2027-08-24T14:15:22+00:00", - "lastUseDate": "2025-08-25T14:15:22+00:00", - "requestDate": "2025-08-24T14:15:22+00:00" - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "requestDate", - "direction": "Desc" - } - ] - } - }, - "/security/public-key-certificates": { - "get": { - "tags": [ - "Certyfikaty klucza publicznego" - ], - "summary": "Pobranie certyfikatów", - "description": "Zwraca informacje o kluczach publicznych używanych do szyfrowania danych przesyłanych do systemu KSeF.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PublicKeyCertificate" - } - }, - "example": [ - { - "certificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwocTwdNgt2+PXJ2fcB7k1kn5eFUTXBeep9pH...", - "validFrom": "2024-07-11T12:23:56.0154302+00:00", - "validTo": "2028-07-11T12:23:56.0154302+00:00", - "usage": [ - "KsefTokenEncryption", - "SymmetricKeyEncryption" - ] - } - ] - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/subject": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Utworzenie podmiotu", - "description": "Tworzenie nowego podmiotu testowego. W przypadku grupy VAT i JST istnieje możliwość stworzenia jednostek podrzędnych. W wyniku takiego działania w systemie powstanie powiązanie między tymi podmiotami.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectNip", - "subjectType", - "description" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubjectCreateRequest" - } - ] - }, - "example": { - "subjectNip": "7762811692", - "subjectType": "EnforcementAuthority", - "description": "Centrala", - "createdDate": "2025-08-25T14:15:22+00:00" - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/subject/remove": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Usunięcie podmiotu", - "description": "Usuwanie podmiotu testowego. W przypadku grupy VAT i JST usunięte zostaną również jednostki podrzędne.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectNip" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubjectRemoveRequest" - } - ] - }, - "example": { - "subjectNip": "7762811692" - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/person": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Utworzenie osoby fizycznej", - "description": "Tworzenie nowej osoby fizycznej, której system nadaje uprawnienia właścicielskie. Można również określić, czy osoba ta jest komornikiem – wówczas otrzyma odpowiednie uprawnienie egzekucyjne.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "nip", - "pesel", - "isBailiff", - "description" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonCreateRequest" - } - ] - }, - "example": { - "nip": "7762811692", - "pesel": "15062788702", - "isBailiff": true, - "description": "TestPerson_01", - "isDeceased": false, - "createdDate": "2025-08-25T14:15:22+00:00" - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/person/remove": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Usunięcie osoby fizycznej", - "description": "Usuwanie testowej osoby fizycznej. System automatycznie odbierze jej wszystkie uprawnienia.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "nip" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonRemoveRequest" - } - ] - }, - "example": { - "nip": "7762811692" - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/permissions": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Nadanie uprawnień testowemu podmiotowi/osobie fizycznej", - "description": "Nadawanie uprawnień testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "contextIdentifier", - "authorizedIdentifier", - "permissions" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TestDataPermissionsGrantRequest" - } - ] - }, - "example": { - "contextIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "authorizedIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "permissions": [ - { - "description": "Opis testowy", - "permissionType": "InvoiceRead" - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/permissions/revoke": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Odebranie uprawnień testowemu podmiotowi/osobie fizycznej", - "description": "Odbieranie uprawnień nadanych testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "contextIdentifier", - "authorizedIdentifier" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TestDataPermissionsRevokeRequest" - } - ] - }, - "example": { - "contextIdentifier": { - "type": "Nip", - "value": "5265877635" - }, - "authorizedIdentifier": { - "type": "Nip", - "value": "7762811692" - } - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/attachment": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Umożliwienie wysyłania faktur z załącznikiem", - "description": "Dodaje możliwość wysyłania faktur z załącznikiem przez wskazany podmiot", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "nip" - ], - "allOf": [ - { - "$ref": "#/components/schemas/AttachmentPermissionGrantRequest" - } - ] - }, - "example": { - "nip": "7762811692" - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/testdata/attachment/revoke": { - "post": { - "tags": [ - "Dane testowe" - ], - "summary": "Odebranie możliwości wysyłania faktur z załącznikiem", - "description": "Odbiera możliwość wysyłania faktur z załącznikiem przez wskazany podmiot", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "nip" - ], - "allOf": [ - { - "$ref": "#/components/schemas/AttachmentPermissionRevokeRequest" - } - ] - }, - "example": { - "nip": "7762811692" - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/limits/context": { - "get": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Pobranie limitów dla bieżącego kontekstu", - "description": "Zwraca wartości aktualnie obowiązujących limitów dla bieżącego kontekstu.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EffectiveContextLimits" - }, - "example": { - "onlineSession": { - "maxInvoiceSizeInMB": 1, - "maxInvoiceWithAttachmentSizeInMB": 3, - "maxInvoices": 10000 - }, - "batchSession": { - "maxInvoiceSizeInMB": 1, - "maxInvoiceWithAttachmentSizeInMB": 3, - "maxInvoices": 10000 - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/limits/subject": { - "get": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Pobranie limitów dla bieżącego podmiotu", - "description": "Zwraca wartości aktualnie obowiązujących limitów dla bieżącego podmiotu.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EffectiveSubjectLimits" - }, - "example": { - "enrollment": { - "maxEnrollments": 6 - }, - "certificate": { - "maxCertificates": 2 - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/rate-limits": { - "get": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Pobranie aktualnie obowiązujących limitów API", - "description": "Zwraca wartości aktualnie obowiązujących limitów ilości żądań przesyłanych do API.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EffectiveApiRateLimits" - }, - "example": { - "onlineSession": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "batchSession": { - "perSecond": 100, - "perMinute": 200, - "perHour": 600 - }, - "invoiceSend": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1800 - }, - "invoiceStatus": { - "perSecond": 300, - "perMinute": 1200, - "perHour": 12000 - }, - "sessionList": { - "perSecond": 50, - "perMinute": 100, - "perHour": 600 - }, - "sessionInvoiceList": { - "perSecond": 100, - "perMinute": 200, - "perHour": 2000 - }, - "sessionMisc": { - "perSecond": 100, - "perMinute": 1200, - "perHour": 12000 - }, - "invoiceMetadata": { - "perSecond": 80, - "perMinute": 160, - "perHour": 200 - }, - "invoiceExport": { - "perSecond": 40, - "perMinute": 80, - "perHour": 200 - }, - "invoiceExportStatus": { - "perSecond": 100, - "perMinute": 600, - "perHour": 6000 - }, - "invoiceDownload": { - "perSecond": 80, - "perMinute": 160, - "perHour": 640 - }, - "other": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/testdata/limits/context/session": { - "post": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Zmiana limitów sesji dla bieżącego kontekstu", - "description": "Zmienia wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu. **Tylko na środowiskach testowych.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "onlineSession", - "batchSession" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SetSessionLimitsRequest" - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - }, - "delete": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Przywrócenie domyślnych wartości limitów sesji dla bieżącego kontekstu", - "description": "Przywraca wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**", - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/testdata/limits/subject/certificate": { - "post": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Zmiana limitów certyfikatów dla bieżącego podmiotu", - "description": "Zmienia wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu. **Tylko na środowiskach testowych.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SetSubjectLimitsRequest" - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - }, - "delete": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Przywrócenie domyślnych wartości limitów certyfikatów dla bieżącego podmiotu", - "description": "Przywraca wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu do wartości domyślnych. **Tylko na środowiskach testowych.**", - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/testdata/rate-limits": { - "post": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Zmiana limitów API dla bieżącego kontekstu", - "description": "Zmienia wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu. **Tylko na środowiskach testowych.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "rateLimits" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SetRateLimitsRequest" - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - }, - "delete": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Przywrócenie domyślnych wartości limitów API dla bieżącego kontekstu", - "description": "Przywraca wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**", - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/testdata/rate-limits/production": { - "post": { - "tags": [ - "Limity i ograniczenia" - ], - "summary": "Zmiana limitów API dla bieżącego kontekstu na wartości produkcyjne", - "description": "Zmienia wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu na wartości takie jakie będą na środowisku produkcyjnym. **Tylko na środowiskach testowych.**", - "responses": { - "200": { - "description": "OK" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/permissions/persons/grants": { - "post": { - "tags": [ - "Nadawanie uprawnień" - ], - "summary": "Nadanie osobom fizycznym uprawnień do pracy w KSeF", - "description": "Metoda pozwala na nadanie osobie wskazanej w żądaniu uprawnień do pracy w KSeF \nw kontekście bieżącym.\n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur, \n- **InvoiceRead** – przeglądanie faktur, \n- **CredentialsManage** – zarządzanie uprawnieniami, \n- **CredentialsRead** – przeglądanie uprawnień, \n- **Introspection** – przeglądanie historii sesji i generowanie UPO, \n- **SubunitManage** – zarządzanie jednostkami podrzędnymi, \n- **EnforcementOperations** – wykonywanie operacji egzekucyjnych.\n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień. \nUprawnienie **EnforcementOperations** może być nadane wyłącznie wtedy, \ngdy podmiot kontekstu ma rolę **EnforcementAuthority** (organ egzekucyjny) \nlub **CourtBailiff** (komornik sądowy).\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadawanie-uprawnie%C5%84-osobom-fizycznym-do-pracy-w-ksef)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectIdentifier", - "permissions", - "description", - "subjectDetails" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsGrantRequest" - } - ] - }, - "example": { - "subjectIdentifier": { - "type": "Pesel", - "value": "15062788702" - }, - "permissions": [ - "InvoiceRead", - "InvoiceWrite", - "Introspection", - "CredentialsRead" - ], - "description": "Opis uprawnienia", - "subjectDetails": { - "subjectDetailsType": "PersonByIdentifier", - "personById": { - "firstName": "Adam", - "lastName": "Abacki" - } - } - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage" - ] - } - }, - "/permissions/entities/grants": { - "post": { - "tags": [ - "Nadawanie uprawnień" - ], - "summary": "Nadanie podmiotom uprawnień do obsługi faktur", - "description": "Metoda pozwala na nadanie podmiotowi wskazanemu w żądaniu uprawnień do obsługi faktur podmiotu kontekstu. \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień. \nDla każdego uprawnienia może być ustawiona flaga **canDelegate**, mówiąca o możliwości jego dalszego przekazywania poprzez nadawanie w sposób pośredni.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-podmiotom-uprawnie%C5%84-do-obs%C5%82ugi-faktur)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectIdentifier", - "permissions", - "description", - "subjectDetails" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityPermissionsGrantRequest" - } - ] - }, - "example": { - "subjectIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "permissions": [ - { - "type": "InvoiceRead", - "canDelegate": true - }, - { - "type": "InvoiceWrite", - "canDelegate": true - } - ], - "description": "Opis uprawnienia", - "subjectDetails": { - "fullName": "Firma sp. z o.o." - } - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage" - ] - } - }, - "/permissions/authorizations/grants": { - "post": { - "tags": [ - "Nadawanie uprawnień" - ], - "summary": "Nadanie uprawnień podmiotowych", - "description": "Metoda pozwala na nadanie jednego z uprawnień podmiotowych do obsługi podmiotu kontekstu podmiotowi wskazanemu w żądaniu.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-podmiotowych)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectIdentifier", - "permission", - "description", - "subjectDetails" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationPermissionsGrantRequest" - } - ] - }, - "example": { - "subjectIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "permission": "SelfInvoicing", - "description": "działanie w imieniu 3393244202 w kontekście 7762811692, Firma sp. z o.o.", - "subjectDetails": { - "fullName": "Firma sp. z o.o." - } - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage" - ] - } - }, - "/permissions/indirect/grants": { - "post": { - "tags": [ - "Nadawanie uprawnień" - ], - "summary": "Nadanie uprawnień w sposób pośredni", - "description": "Metoda pozwala na nadanie w sposób pośredni osobie wskazanej w żądaniu uprawnień do obsługi faktur innego podmiotu – klienta. \nMoże to być jedna z możliwości: \n- nadanie uprawnień generalnych – do obsługi wszystkich klientów \n- nadanie uprawnień selektywnych – do obsługi wskazanego klienta \n \nUprawnienie selektywne może być nadane wyłącznie wtedy, gdy klient nadał wcześniej podmiotowi bieżącego kontekstu dowolne uprawnienie z prawem do jego dalszego przekazywania (patrz [POST /v2/permissions/entities/grants](/docs/v2/index.html#tag/Nadawanie-uprawnien/paths/~1permissions~1entities~1grants/post)). \n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-w-spos%C3%B3b-po%C5%9Bredni)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectIdentifier", - "permissions", - "description", - "subjectDetails" - ], - "allOf": [ - { - "$ref": "#/components/schemas/IndirectPermissionsGrantRequest" - } - ] - }, - "example": { - "subjectIdentifier": { - "type": "Pesel", - "value": "22271569167" - }, - "targetIdentifier": { - "type": "Nip", - "value": "5687926712" - }, - "permissions": [ - "InvoiceWrite", - "InvoiceRead" - ], - "description": "praca dla klienta 5687926712; uprawniony PESEL: 22271569167, Adam Abacki; pośrednik 3936518395", - "subjectDetails": { - "subjectDetailsType": "PersonByIdentifier", - "personById": { - "firstName": "Adam", - "lastName": "Abacki" - } - } - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage" - ] - } - }, - "/permissions/subunits/grants": { - "post": { - "tags": [ - "Nadawanie uprawnień" - ], - "summary": "Nadanie uprawnień administratora podmiotu podrzędnego", - "description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień administratora w kontekście: \n- wskazanego NIP podmiotu podrzędnego – wyłącznie jeżeli podmiot bieżącego kontekstu logowania ma rolę podmiotu nadrzędnego:\n - **LocalGovernmentUnit** \n - **VatGroupUnit** \n- wskazanego lub utworzonego identyfikatora wewnętrznego \n \nWraz z utworzeniem administratora jednostki podrzędnej tworzony jest identyfikator wewnętrzny składający się z numeru NIP podmiotu kontekstu logowania oraz 5 cyfr unikalnie identyfikujących jednostkę wewnętrzną.\nOstatnia cyfra musi być poprawną sumą kontrolną, która jest obliczana według poniższego algorytmu.\n\nAlgorytm używa naprzemiennych wag (1×, 3×, 1×, 3×, ...), sumuje wyniki i zwraca resztę z dzielenia przez 10.\n\nPrzykład:\n- Wejście: \"6824515772-1234\" (bez cyfry kontrolnej)\n- Pozycja 0 (1. cyfra): 6 × 1 = 6\n- Pozycja 1 (2. cyfra): 8 × 3 = 24\n- Pozycja 2 (3. cyfra): 2 × 1 = 2\n- Pozycja 3 (4. cyfra): 4 × 3 = 12\n- Pozycja 4 (5. cyfra): 5 × 1 = 5\n- Pozycja 5 (6. cyfra): 1 × 3 = 3\n- Pozycja 6 (7. cyfra): 5 × 1 = 5\n- Pozycja 7 (8. cyfra): 7 × 3 = 21\n- Pozycja 8 (9. cyfra): 7 × 1 = 7\n- Pozycja 9 (10. cyfra): 2 × 3 = 6\n- Pozycja 10 (11. cyfra): 1 × 1 = 1\n- Pozycja 11 (12. cyfra): 2 × 3 = 6\n- Pozycja 12 (13. cyfra): 3 × 1 = 3\n- Pozycja 13 (14. cyfra): 4 × 3 = 12\n- Suma: 6 + 24 + 2 + 12 + 5 + 3 + 5 + 21 + 7 + 6 + 1 + 6 + 3 + 12 = 113\n- Cyfra kontrolna (15. cyfra): 113 % 10 = 3\n\nW żądaniu podaje się również nazwę tej jednostki. \n \nUprawnienia administratora jednostki podrzędnej obejmują: \n- **CredentialsManage** – zarządzanie uprawnieniami \n \nMetoda automatycznie nadaje powyższe uprawnienie, bez konieczności podawania go w żądaniu.\n \n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-podrz%C4%99dnego)\n\n**Wymagane uprawnienia**: `SubunitManage`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectIdentifier", - "contextIdentifier", - "description", - "subjectDetails" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsGrantRequest" - } - ] - }, - "example": { - "subjectIdentifier": { - "type": "Pesel", - "value": "15062788702" - }, - "contextIdentifier": { - "type": "InternalId", - "value": "7762811692-12345" - }, - "description": "Opis uprawnienia", - "subunitName": "Jednostka 014", - "subjectDetails": { - "subjectDetailsType": "PersonByIdentifier", - "personById": { - "firstName": "Adam", - "lastName": "Abacki" - } - } - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "SubunitManage" - ] - } - }, - "/permissions/eu-entities/administration/grants": { - "post": { - "tags": [ - "Nadawanie uprawnień" - ], - "summary": "Nadanie uprawnień administratora podmiotu unijnego", - "description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień administratora w kontekście złożonym z identyfikatora NIP podmiotu kontekstu bieżącego oraz numeru VAT UE podmiotu unijnego wskazanego w żądaniu. \nWraz z utworzeniem administratora podmiotu unijnego tworzony jest kontekst złożony składający się z numeru NIP podmiotu kontekstu logowania oraz wskazanego numeru identyfikacyjnego VAT UE podmiotu unijnego. \nW żądaniu podaje się również nazwę i adres podmiotu unijnego. \n \nJedynym sposobem identyfikacji uprawnianego jest odcisk palca certyfikatu kwalifikowanego: \n- certyfikat podpisu elektronicznego dla osób fizycznych \n- certyfikat pieczęci elektronicznej dla podmiotów \n \nUprawnienia administratora podmiotu unijnego obejmują: \n- **VatEuManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n- **Introspection** – przeglądanie historii sesji \n \nMetoda automatycznie nadaje wszystkie powyższe uprawnienia, bez konieczności ich wskazywania w żądaniu.\n \n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-unijnego)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectIdentifier", - "contextIdentifier", - "description", - "euEntityName", - "subjectDetails", - "euEntityDetails" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityAdministrationPermissionsGrantRequest" - } - ] - }, - "example": { - "subjectIdentifier": { - "type": "Fingerprint", - "value": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59" - }, - "contextIdentifier": { - "type": "NipVatUe", - "value": "7762811692-DE123456789012" - }, - "description": "Opis uprawnienia", - "euEntityName": "Firma G.m.b.H.", - "subjectDetails": { - "subjectDetailsType": "PersonByFingerprintWithIdentifier", - "personByFpWithId": { - "firstName": "Adam", - "lastName": "Abacki", - "identifier": { - "type": "Pesel", - "value": "15062788702" - } - } - }, - "euEntityDetails": { - "fullName": "Firma G.m.b.H.", - "address": "Warszawa ul. Świętokrzyska 4824 00-916 Warszawa" - } - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage" - ] - } - }, - "/permissions/eu-entities/grants": { - "post": { - "tags": [ - "Nadawanie uprawnień" - ], - "summary": "Nadanie uprawnień reprezentanta podmiotu unijnego", - "description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień do wystawiania i/lub przeglądania faktur w kontekście złożonym kontekstu bieżącego. \n \nJedynym sposobem identyfikacji uprawnianego jest odcisk palca certyfikatu kwalifikowanego: \n- certyfikat podpisu elektronicznego dla osób fizycznych \n- certyfikat pieczęci elektronicznej dla podmiotów \n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-reprezentanta-podmiotu-unijnego)\n\n**Wymagane uprawnienia**: `VatUeManage`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "subjectIdentifier", - "permissions", - "description", - "subjectDetails" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionsGrantRequest" - } - ] - }, - "example": { - "subjectIdentifier": { - "type": "Fingerprint", - "value": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59" - }, - "permissions": [ - "InvoiceRead", - "InvoiceWrite" - ], - "description": "Opis uprawnienia", - "subjectDetails": { - "subjectDetailsType": "PersonByFingerprintWithIdentifier", - "personByFpWithId": { - "firstName": "Adam", - "lastName": "Abacki", - "identifier": { - "type": "Pesel", - "value": "15062788702" - } - } - } - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "VatUeManage" - ] - } - }, - "/permissions/common/grants/{permissionId}": { - "delete": { - "tags": [ - "Odbieranie uprawnień" - ], - "summary": "Odebranie uprawnień", - "description": "Metoda pozwala na odebranie uprawnienia o wskazanym identyfikatorze. \nWymagane jest wcześniejsze odczytanie uprawnień w celu uzyskania \nidentyfikatora uprawnienia, które ma zostać odebrane.\n\n> Więcej informacji:\n> - [Odbieranie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84)\n\n**Wymagane uprawnienia**: `CredentialsManage`, `VatUeManage`, `SubunitManage`.", - "parameters": [ - { - "name": "permissionId", - "in": "path", - "description": "Id uprawnienia.", - "required": true, - "schema": { - "$ref": "#/components/schemas/PermissionId" - } - } - ], - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage", - "VatUeManage", - "SubunitManage" - ] - } - }, - "/permissions/authorizations/grants/{permissionId}": { - "delete": { - "tags": [ - "Odbieranie uprawnień" - ], - "summary": "Odebranie uprawnień podmiotowych", - "description": "Metoda pozwala na odebranie uprawnienia podmiotowego o wskazanym identyfikatorze. \nWymagane jest wcześniejsze odczytanie uprawnień w celu uzyskania \nidentyfikatora uprawnienia, które ma zostać odebrane.\n \n> Więcej informacji:\n> - [Odbieranie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84-podmiotowych)\n\n**Wymagane uprawnienia**: `CredentialsManage`.", - "parameters": [ - { - "name": "permissionId", - "in": "path", - "description": "Id uprawnienia.", - "required": true, - "schema": { - "$ref": "#/components/schemas/PermissionId" - } - } - ], - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationResponse" - }, - "example": { - "referenceNumber": "20250626-EG-333C814000-C529F710D8-D2" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage" - ] - } - }, - "/permissions/operations/{referenceNumber}": { - "get": { - "tags": [ - "Operacje" - ], - "summary": "Pobranie statusu operacji", - "description": "Zwraca status operacji asynchronicznej związanej z nadaniem lub odebraniem uprawnień.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny operacji nadania lub odbierania uprawnień.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PermissionsOperationStatusResponse" - }, - "example": { - "status": { - "code": 200, - "description": "Operacja zakończona sukcesem" - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/permissions/attachments/status": { - "get": { - "tags": [ - "Operacje" - ], - "summary": "Sprawdzenie statusu zgody na wystawianie faktur z załącznikiem", - "description": "Sprawdzenie czy obecny kontekst posiada zgodę na wystawianie faktur z załącznikiem.\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CheckAttachmentPermissionStatusResponse" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "CredentialsManage", - "CredentialsRead" - ] - } - }, - "/invoices/ksef/{ksefNumber}": { - "get": { - "tags": [ - "Pobieranie faktur" - ], - "summary": "Pobranie faktury po numerze KSeF", - "description": "Zwraca fakturę o podanym numerze KSeF.\n\n**Wymagane uprawnienia**: `InvoiceRead`.", - "parameters": [ - { - "name": "ksefNumber", - "in": "path", - "description": "Numer KSeF faktury.", - "required": true, - "schema": { - "$ref": "#/components/schemas/KsefNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "x-ms-meta-hash": { - "description": "Skrót SHA-256 faktury, zakodowany w formacie Base64", - "schema": { - "$ref": "#/components/schemas/Sha256HashBase64" - } - } - }, - "content": { - "application/xml": { - "schema": { - "type": "string" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|\n| 21164 | Faktura o podanym identyfikatorze nie istnieje. | Faktura o numerze KSeF {ksefNumber} nie została znaleziona. |\n| 21165 | Faktura o podanym numerze KSeF nie jest jeszcze dostępna. | Faktura o numerze KSeF {ksefNumber} została przetworzona, ale nie jest jeszcze dostępna do pobrania. Spróbuj ponownie później. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 80 | 160 | 640 | invoiceDownload\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 80, - "perMinute": 160, - "perHour": 640 - }, - "x-required-permissions": [ - "InvoiceRead" - ] - } - }, - "/invoices/query/metadata": { - "post": { - "tags": [ - "Pobieranie faktur" - ], - "summary": "Pobranie listy metadanych faktur", - "description": "Zwraca metadane faktur spełniających filtry.\n\nLimit techniczny: ≤ 10 000 rekordów na zestaw filtrów, po jego osiągnięciu isTruncated = true i należy ponownie ustawić dateRange, używając ostatniej daty z wyników (tj. ustawić from/to - w zależności od kierunku sortowania, od daty ostatniego zwróconego rekordu) oraz wyzerować pageOffset.\n\n`Do scenariusza przyrostowego należy używać daty PermanentStorage oraz kolejność sortowania Asc`.\n \nScenariusz pobierania przyrostowego (skrót):\n* Gdy hasMore = false, należy zakończyć,\n* Gdy hasMore = true i isTruncated = false, należy zwiększyć pageOffset,\n* Gdy hasMore = true i isTruncated = true, należy zawęzić dateRange (ustawić from od daty ostatniego rekordu), wyzerować pageOffset i kontynuować\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc | Desc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.", - "parameters": [ - { - "name": "sortOrder", - "in": "query", - "description": "Kolejność sortowania wyników.\n| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n", - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SortOrder" - } - ], - "description": "| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n", - "default": "Asc" - } - }, - { - "name": "pageOffset", - "in": "query", - "description": "Indeks pierwszej strony wyników (0 = pierwsza strona).", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 250, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "requestBody": { - "description": "Kryteria filtrowania.", - "content": { - "application/json": { - "schema": { - "required": [ - "subjectType", - "dateRange" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQueryFilters" - } - ] - }, - "example": { - "subjectType": "Subject1", - "dateRange": { - "dateType": "PermanentStorage", - "from": "2025-08-28T09:22:13.388+00:00", - "to": "2025-09-28T09:24:13.388+00:00" - }, - "amount": { - "type": "Brutto", - "from": 100.50, - "to": 250.00 - }, - "currencyCodes": [ - "PLN", - "EUR" - ], - "invoicingMode": "Online", - "formType": "FA", - "invoiceTypes": [ - "Vat" - ], - "hasAttachment": true - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryInvoicesMetadataResponse" - }, - "example": { - "hasMore": false, - "isTruncated": false, - "permanentStorageHwmDate": "2025-08-28T09:23:55.388+00:00", - "invoices": [ - { - "ksefNumber": "5555555555-20250828-010080615740-E4", - "invoiceNumber": "FA/KUDYO1a7dddfe-610e-4843-84ba-6b887e35266e", - "issueDate": "2025-08-27", - "invoicingDate": "2025-08-28T09:22:13.388+00:00", - "acquisitionDate": "2025-08-28T09:22:56.388+00:00", - "permanentStorageDate": "2025-08-28T09:23:01.388+00:00", - "seller": { - "nip": "5555555555", - "name": "Test Company 1" - }, - "buyer": { - "identifier": { - "type": "Nip", - "value": "7352765225" - }, - "name": "Test Company 4" - }, - "netAmount": 35260.63, - "grossAmount": 43370.57, - "vatAmount": 8109.94, - "currency": "PLN", - "invoicingMode": "Offline", - "invoiceType": "Vat", - "formCode": { - "systemCode": "FA (3)", - "schemaVersion": "1-0E", - "value": "FA" - }, - "isSelfInvoicing": false, - "hasAttachment": false, - "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", - "thirdSubjects": [ ] - }, - { - "ksefNumber": "5555555555-20250828-010080615740-E4", - "invoiceNumber": "5265877635-20250925-010020A0A242-0A", - "issueDate": "2025-08-28", - "invoicingDate": "2025-08-28T10:23:13.388+00:00", - "acquisitionDate": "2025-08-28T10:23:56.388+00:00", - "permanentStorageDate": "2025-08-28T10:24:01.388+00:00", - "seller": { - "nip": "5555555555", - "name": "Test Company 1" - }, - "buyer": { - "identifier": { - "type": "Nip", - "value": "3225081610" - }, - "name": "Test Company 2" - }, - "netAmount": 35260.63, - "grossAmount": 43370.57, - "vatAmount": 8109.94, - "currency": "PLN", - "invoicingMode": "Online", - "invoiceType": "Vat", - "formCode": { - "systemCode": "FA (3)", - "schemaVersion": "1-0E", - "value": "FA" - }, - "isSelfInvoicing": false, - "hasAttachment": true, - "invoiceHash": "o+nMBU8n8TAhy6EjbcdYdHSZVbUspqmCKqOPLhy3zIQ=", - "thirdSubjects": [ - { - "identifier": { - "type": "InternalId", - "value": "5555555555-12345" - }, - "name": "Wystawca faktury", - "role": 4 - } - ] - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|\n| 21183 | Zakres filtrowania wykracza poza dostępny zakres danych. | Parametr dateRange.from jest późniejszy niż PermanentStorageHwmDate przy włączonym restrictToPermanentStorageHwmDate. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 80 | 160 | 200 | invoiceMetadata\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 80, - "perMinute": 160, - "perHour": 200 - }, - "x-sort": [ - { - "allowedFields": [ - "permanentStorageDate", - "invoicingDate", - "issueDate" - ], - "allowedDirections": [ - "Asc", - "Desc" - ] - } - ], - "x-required-permissions": [ - "InvoiceRead" - ] - } - }, - "/invoices/exports": { - "post": { - "tags": [ - "Pobieranie faktur" - ], - "summary": "Eksport paczki faktur", - "description": "Rozpoczyna asynchroniczny proces wyszukiwania faktur w systemie KSeF na podstawie przekazanych filtrów oraz przygotowania ich w formie zaszyfrowanej paczki.\nWymagane jest przekazanie informacji o szyfrowaniu w polu Encryption, które służą do zabezpieczenia przygotowanej paczki z fakturami.\nMaksymalnie można uruchomić 10 równoczesnych eksportów w zalogowanym kontekście.\n \nSystem pobiera faktury rosnąco według daty określonej w filtrze (Invoicing, Issue, PermanentStorage) i dodaje faktury(nazwa pliku: {ksefNumber}.xml) do paczki aż do osiągnięcia jednego z poniższych limitów:\n* Limit liczby faktur: 10 000 sztuk\n* Limit rozmiaru danych(skompresowanych): 1GB\n\nPaczka eksportu zawiera dodatkowy plik z metadanymi faktur w formacie JSON (`_metadata.json`). Zawartość pliku to\nobiekt z tablicą invoices, gdzie każdy element jest obiektem typu InvoiceMetadata\n(taki jak zwracany przez endpoint `POST /invoices/query/metadata`).\n\nPlik z metadanymi(_metadata.json) nie jest wliczany do limitów algorytmu budowania paczki. \n\n`Do realizacji pobierania przyrostowego należy stosować filtrowanie po dacie PermanentStorage`.\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.", - "requestBody": { - "description": "Dane wejściowe określające kryteria i format eksportu paczki faktur.", - "content": { - "application/json": { - "schema": { - "required": [ - "encryption", - "filters" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceExportRequest" - } - ] - }, - "example": { - "encryption": { - "encryptedSymmetricKey": "bdUVjqLj+y2q6aBUuLxxXYAMqeDuIBRTyr+hB96DaWKaGzuVHw9p+Nk9vhzgF/Q5cavK2k6eCh6SdsrWI0s9mFFj4A4UJtsyD8Dn3esLfUZ5A1juuG3q3SBi/XOC/+9W+0T/KdwdE393mbiUNyx1K/0bw31vKJL0COeJIDP7usAMDl42/H1TNvkjk+8iZ80V0qW7D+RZdz+tdiY1xV0f2mfgwJ46V0CpZ+sB9UAssRj+eVffavJ0TOg2b5JaBxE8MCAvrF6rO5K4KBjUmoy7PP7g1qIbm8xI2GO0KnfPOO5OWj8rsotRwBgu7x19Ine3qYUvuvCZlXRGGZ5NHIzWPM4O74+gNalaMgFCsmv8mMhETSU4SfAGmJr9edxPjQSbgD5i2X4eDRDMwvyaAa7CP1b2oICju+0L7Fywd2ZtUcr6El++eTVoi8HYsTArntET++gULT7XXjmb8e3O0nxrYiYsE9GMJ7HBGv3NOoJ1NTm3a7U6+c0ZJiBVLvn6xXw10LQX243xH+ehsKo6djQJKYtqcNPaXtCwM1c9RrsOx/wRXyWCtTffqLiaR0LbYvfMJAcEWceG+RaeAx4p37OiQqdJypd6LAv9/0ECWK8Bip8yyoA+0EYiAJb9YuDz2YlQX9Mx9E9FzFIAsgEQ2w723HZYWgPywLb+dlsum4lTZKQ=", - "initializationVector": "c29tZUluaXRWZWN0b3I=" - }, - "filters": { - "subjectType": "Subject1", - "dateRange": { - "dateType": "PermanentStorage", - "from": "2025-08-28T09:22:13.388+00:00", - "to": "2025-09-28T09:22:13.388+00:00", - "restrictToPermanentStorageHwmDate": true - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExportInvoicesResponse" - }, - "example": { - "referenceNumber": "20251010-EH-1B6C9EB000-4B15D3AEB9-89" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------|\n| 21181 | Nieprawidłowe żądanie eksportu faktur. | Nie można wyeksportować paczki faktur dla wybranego podmiotu ({subjecttype}) i zalogowanego identyfikatora kontekstu ({type}). |\n| 21182 | Osiągnięto limit trwających eksportów. | Dla uwierzytelnionego podmiotu w bieżącym kontekście osiągnięto maksymalny limit {count} równoczesnych eksportów faktur. Spróbuj ponownie później. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 40 | 80 | 200 | invoiceExport\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 40, - "perMinute": 80, - "perHour": 200 - }, - "x-sort": [ - { - "allowedFields": [ - "permanentStorageDate", - "invoicingDate", - "issueDate" - ], - "allowedDirections": "Asc" - } - ], - "x-required-permissions": [ - "InvoiceRead" - ] - } - }, - "/invoices/exports/{referenceNumber}": { - "get": { - "tags": [ - "Pobieranie faktur" - ], - "summary": "Pobranie statusu eksportu paczki faktur", - "description": "Paczka faktur jest dzielona na części o maksymalnym rozmiarze 50 MB. Każda część jest zaszyfrowana algorytmem AES-256-CBC z dopełnieniem PKCS#7, przy użyciu klucza symetrycznego przekazanego podczas inicjowania eksportu. \n\nW przypadku ucięcia wyniku eksportu z powodu przekroczenia limitów, zwracana jest flaga IsTruncated = true oraz odpowiednia data, którą należy wykorzystać do wykonania kolejnego eksportu, aż do momentu, gdy flaga IsTruncated = false.\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny eksportu faktur.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InvoiceExportStatusResponse" - }, - "example": { - "status": { - "code": 200, - "description": "Eksport faktur zakończony sukcesem" - }, - "completedDate": "2025-09-16T16:09:40.901091+00:00", - "package": { - "invoiceCount": 10000, - "size": 22425060, - "parts": [ - { - "ordinalNumber": 1, - "partName": "20250925-EH-2D2C11B000-E9C9ED8340-EE-001.zip.aes", - "method": "GET", - "url": "https://ksef-api-storage/storage/00/20250626-eh-2d2c11b000-e9c9ed8340-ee/invoice-part/20250925-EH-2D2C11B000-E9C9ED8340-EE-001.zip.aes?skoid=1ad7cfe8-2cb2-406b-b96c-6eefb55794db&sktid=647754c7-3974-4442-a425-c61341b61c69&skt=2025-06-26T09%3A40%3A54Z&ske=2025-06-26T10%3A10%3A54Z&sks=b&skv=2025-01-05&sv=2025-01-05&se=2025-06-26T10%3A10%3A54Z&sr=b&sp=w&sig=8mKZEU8Reuz%2Fn7wHi4T%2FY8BzLeD5l8bR2xJsBxIgDEY%3D", - "partSize": 22425060, - "partHash": "BKH9Uy1CjBFXiQdDUM2CJYk5LxWTm4fE1lljnl83Ajw=", - "encryptedPartSize": 22425072, - "encryptedPartHash": "HlvwRLc59EJH7O5GoeHEZxTQO5TJ/WP1QH0aFi4x2Ss=", - "expirationDate": "2025-09-16T17:09:40.901091+00:00" - } - ], - "isTruncated": true, - "lastPermanentStorageDate": "2025-09-11T11:40:40.266578+00:00", - "permanentStorageHwmDate": "2025-09-11T12:00:40.266578+00:00" - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------|\n| 21175 | Wynik zapytania o podanym identyfikatorze nie istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 600 | 6000 | invoiceExportStatus\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 600, - "perHour": 6000 - }, - "x-sort": [ - { - "allowedFields": [ - "permanentStorageDate", - "invoicingDate", - "issueDate" - ], - "allowedDirections": "Asc" - } - ], - "x-required-permissions": [ - "InvoiceRead" - ] - } - }, - "/sessions": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie listy sesji", - "description": "Zwraca listę sesji spełniających podane kryteria wyszukiwania.\n\n\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n\n**Wymagane uprawnienia**:\n- `Introspection`/`EnforcementOperations` – pozwala pobrać wszystkie sesje w bieżącym kontekście uwierzytelnienia `(ContextIdentifier)`.\n- `InvoiceWrite` – pozwala pobrać wyłącznie sesje utworzone przez podmiot uwierzytelniający, czyli podmiot inicjujący uwierzytelnienie.", - "parameters": [ - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony.", - "schema": { - "maximum": 1000, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - }, - { - "name": "sessionType", - "in": "query", - "description": "Typ sesji.\n| Wartość | Opis |\n| --- | --- |\n| Online | Wysyłka interaktywna (pojedyncze faktury). |\n| Batch | Wysyłka wsadowa (paczka faktur). |\n", - "required": true, - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SessionType" - } - ] - } - }, - { - "name": "referenceNumber", - "in": "query", - "description": "Numer referencyjny sesji.", - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - }, - { - "name": "dateCreatedFrom", - "in": "query", - "description": "Data utworzenia sesji (od).", - "schema": { - "type": "string", - "format": "date-time" - } - }, - { - "name": "dateCreatedTo", - "in": "query", - "description": "Data utworzenia sesji (do).", - "schema": { - "type": "string", - "format": "date-time" - } - }, - { - "name": "dateClosedFrom", - "in": "query", - "description": "Data zamknięcia sesji (od).", - "schema": { - "type": "string", - "format": "date-time" - } - }, - { - "name": "dateClosedTo", - "in": "query", - "description": "Data zamknięcia sesji (do).", - "schema": { - "type": "string", - "format": "date-time" - } - }, - { - "name": "dateModifiedFrom", - "in": "query", - "description": "Data ostatniej aktywności (wysyłka faktury lub zmiana statusu) w ramach sesji (od).", - "schema": { - "type": "string", - "format": "date-time" - } - }, - { - "name": "dateModifiedTo", - "in": "query", - "description": "Data ostatniej aktywności (wysyłka faktury lub zmiana statusu) w ramach sesji (do).", - "schema": { - "type": "string", - "format": "date-time" - } - }, - { - "name": "statuses", - "in": "query", - "description": "Statusy sesji.\n| Wartość | Opis |\n| --- | --- |\n| InProgress | Sesja aktywna. |\n| Succeeded | Sesja przetworzona poprawnie. W trakcie przetwarzania sesji nie wystąpiły żadne błędy, ale część faktur nadal mogła zostać odrzucona. |\n| Failed | Sesja nie przetworzona z powodu błędów. Na etapie rozpoczynania lub kończenia sesji wystąpiły błędy, które nie pozwoliły na jej poprawne przetworzenie. |\n| Cancelled | Sesja anulowania. Został przekroczony czas na wysyłkę w sesji wsadowej, lub nie przesłano żadnych faktur w sesji interaktywnej. |\n", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CommonSessionStatus" - } - } - }, - { - "name": "x-continuation-token", - "in": "header", - "description": "Token służący do pobrania kolejnej strony wyników.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionsQueryResponse" - }, - "example": { - "continuationToken": "W3sidG9rZW4iOiIrUklEOn4zeHd0QU1SM3dYYjRCd0FBQUFBQUNBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBZ2dBQUFBQUFDQUFBQVlBQUFBQUlBQUFBQUFBQUFBZ0FBQVVBUEVIQUVGdGdJUUFFUUJBQUJBRUFCQVVoZ1NBQXdBQUFBQWdBQUFHQUhFa0NFQWxnQVFBQUFBQUlBQUFGZ0F5Q0FVZ0VBRC9nRE9BRFlFdWdIcUF5SXBEZ0IrQUJnQUFBQUFnQUFBQ0FPNlYiLCJyYW5nZSI6eyJtaW4iOiIiLCJtYXgiOiIwNUMxREYyQjVGMzU5OCJ9fV0=", - "sessions": [ - { - "referenceNumber": "20250925-SO-2F67776000-97273B191A-65", - "status": { - "code": 200, - "description": "Sesja interaktywna przetworzona pomyślnie" - }, - "dateCreated": "2025-09-25T13:48:26.8700925+00:00", - "dateUpdated": "2025-09-26T02:16:07+00:00", - "validUntil": "2025-09-26T01:48:26.8700925+00:00", - "totalInvoiceCount": 2, - "successfulInvoiceCount": 2, - "failedInvoiceCount": 0 - }, - { - "referenceNumber": "20250928-SO-494B541000-3AD87C01BA-5D", - "status": { - "code": 200, - "description": "Sesja interaktywna przetworzona pomyślnie" - }, - "dateCreated": "2025-09-28T21:20:54.5936927+00:00", - "dateUpdated": "2025-09-29T10:19:28+00:00", - "validUntil": "2025-09-29T09:20:54.5936927+00:00", - "totalInvoiceCount": 3, - "successfulInvoiceCount": 3, - "failedInvoiceCount": 0 - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 50 | 100 | 600 | sessionList\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 50, - "perMinute": 100, - "perHour": 600 - }, - "x-sort": [ - { - "field": "dateCreated", - "direction": "Desc" - } - ], - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "EnforcementOperations" - ] - } - }, - "/sessions/{referenceNumber}": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie statusu sesji", - "description": "Sprawdza bieżący status sesji o podanym numerze referencyjnym.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionStatusResponse" - }, - "example": { - "status": { - "code": 200, - "description": "Sesja interaktywna przetworzona pomyślnie" - }, - "dateCreated": "2025-09-18T15:00:30+00:00", - "dateUpdated": "2025-09-18T15:01:20+00:00", - "upo": { - "pages": [ - { - "referenceNumber": "20250918-EU-2EBD6FA000-242EB9B66D-43", - "downloadUrl": "https://api-test.ksef.mf.gov.pl/storage/01/20250918-so-3789a40000-20373e1269-a3/session-upo/upo_00.xml?sv=2025-01-05&st=2025-09-18T14%3A55%3A50Z&se=2025-09-21T15%3A00%3A50Z&sr=b&sp=r&sig=ZlQO6Xtzu3VQQDwmEMfb0VryMxe9WcUgWtkdiB6X2Qo%3D", - "downloadUrlExpirationDate": "2025-09-21T15:00:50+00:00" - } - ] - }, - "invoiceCount": 10, - "successfulInvoiceCount": 8, - "failedInvoiceCount": 2 - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 1200, - "perHour": 12000 - }, - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/{referenceNumber}/invoices": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie faktur sesji", - "description": "Zwraca listę faktur przesłanych w sesji wraz z ich statusami, oraz informacje na temat ilości poprawnie i niepoprawnie przetworzonych faktur.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "x-continuation-token", - "in": "header", - "description": "Token służący do pobrania kolejnej strony wyników.", - "schema": { - "type": "string" - } - }, - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 1000, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionInvoicesResponse" - }, - "example": { - "continuationToken": "W34idG9rZW4iOiIrUklEOn4xUE5BQU5hcXJVOUFBQUFBQUFBQUFBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBVUFBQUFBQUFBQUFRZ0FBQUFBQUFBQT0iLCJyYW5nZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fV0=", - "invoices": [ - { - "ordinalNumber": 1, - "invoiceNumber": "FA/XPWIC-7900685789/06/2025", - "ksefNumber": "5265877635-20250626-010080DD2B5E-26", - "referenceNumber": "20250918-EE-2F15D39000-242207E5C4-1B", - "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", - "acquisitionDate": "2025-09-18T12:24:16.0154302+00:00", - "invoicingDate": "2025-09-18T12:23:56.0154302+00:00", - "permanentStorageDate": "2025-09-18T12:24:01.0154302+00:00", - "upoDownloadUrl": "https://api-test.ksef.mf.gov.pl/storage/01/20250918-SB-3789A40000-20373E1269-A3/invoice-upo/upo_5265877635-20250626-010080DD2B5E-26.xml?sv=2025-01-05&st=2025-09-18T14%3A49%3A20Z&se=2025-09-21T14%3A54%3A20Z&sr=b&sp=r&sig=%2BUWFPA10gS580VhngGKW%2FZiOOtiHPOiTyMlxhG6ZvWs%3D", - "upoDownloadUrlExpirationDate": "2025-09-21T14:54:20+00:00", - "status": { - "code": 200, - "description": "Sukces" - } - }, - { - "ordinalNumber": 2, - "referenceNumber": "20250918-EE-2F20AD2000-242386DF86-52", - "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", - "invoicingDate": "2025-09-18T12:23:56.0154302+00:00", - "status": { - "code": 440, - "description": "Duplikat faktury", - "details": [ - "Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4" - ], - "extensions": { - "originalSessionReferenceNumber": "20250626-SO-2F14610000-242991F8C9-B4", - "originalKsefNumber": "5265877635-20250626-010080DD2B5E-26" - } - } - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 2000 | sessionInvoiceList\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 200, - "perHour": 2000 - }, - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie statusu faktury z sesji", - "description": "Zwraca fakturę przesłaną w sesji wraz ze statusem.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - }, - { - "name": "invoiceReferenceNumber", - "in": "path", - "description": "Numer referencyjny faktury.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionInvoiceStatusResponse" - }, - "example": { - "ordinalNumber": 2, - "referenceNumber": "20250626-EE-2F20AD2000-242386DF86-52", - "invoicingDate": "2025-07-11T12:23:56.0154302+00:00", - "status": { - "code": 440, - "description": "Duplikat faktury", - "details": [ - "Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4" - ], - "extensions": { - "originalSessionReferenceNumber": "20250626-SO-2F14610000-242991F8C9-B4", - "originalKsefNumber": "5265877635-20250626-010080DD2B5E-26" - } - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 300 | 1200 | 12000 | invoiceStatus\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 300, - "perMinute": 1200, - "perHour": 12000 - }, - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/{referenceNumber}/invoices/failed": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie niepoprawnie przetworzonych faktur sesji", - "description": "Zwraca listę niepoprawnie przetworzonych faktur przesłanych w sesji wraz z ich statusami.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "x-continuation-token", - "in": "header", - "description": "Token służący do pobrania kolejnej strony wyników.", - "schema": { - "type": "string" - } - }, - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 1000, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionInvoicesResponse" - }, - "example": { - "continuationToken": "...", - "invoices": [ - { - "ordinalNumber": 2, - "referenceNumber": "20250626-EE-2F20AD2000-242386DF86-52", - "invoiceHash": "mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=", - "invoiceFileName": "invoice1.xml", - "invoicingDate": "2025-07-11T12:23:56.0154302+00:00", - "status": { - "code": 440, - "description": "Duplikat faktury", - "details": [ - "Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4" - ], - "extensions": { - "originalSessionReferenceNumber": "20250626-SO-2F14610000-242991F8C9-B4", - "originalKsefNumber": "5265877635-20250626-010080DD2B5E-26" - } - } - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 2000 | sessionInvoiceList\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 200, - "perHour": 2000 - }, - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie UPO faktury z sesji na podstawie numeru KSeF", - "description": "Zwraca UPO faktury przesłanego w sesji na podstawie jego numeru KSeF.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - }, - { - "name": "ksefNumber", - "in": "path", - "description": "Numer KSeF faktury.", - "required": true, - "schema": { - "$ref": "#/components/schemas/KsefNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "x-ms-meta-hash": { - "description": "Skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64", - "schema": { - "$ref": "#/components/schemas/Sha256HashBase64" - } - } - }, - "content": { - "application/xml": { - "schema": { - "type": "string" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 21178 | Nie znaleziono UPO dla podanych kryteriów. | UPO o numerze KSeF {ksefNumber} i numerze referencyjnym sesji {referenceNumber} nie zostało znalezione. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 1200, - "perHour": 12000 - }, - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie UPO faktury z sesji na podstawie numeru referencyjnego faktury", - "description": "Zwraca UPO faktury przesłanego w sesji na podstawie jego numeru KSeF.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - }, - { - "name": "invoiceReferenceNumber", - "in": "path", - "description": "Numer referencyjny faktury.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "x-ms-meta-hash": { - "description": "Skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64", - "schema": { - "$ref": "#/components/schemas/Sha256HashBase64" - } - } - }, - "content": { - "application/xml": { - "schema": { - "type": "string" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 1200, - "perHour": 12000 - }, - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/{referenceNumber}/upo/{upoReferenceNumber}": { - "get": { - "tags": [ - "Status wysyłki i UPO" - ], - "summary": "Pobranie UPO dla sesji", - "description": "Zwraca XML zawierający zbiorcze UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - }, - { - "name": "upoReferenceNumber", - "in": "path", - "description": "Numer referencyjny UPO.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "headers": { - "x-ms-meta-hash": { - "description": "Skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64", - "schema": { - "$ref": "#/components/schemas/Sha256HashBase64" - } - } - }, - "content": { - "application/xml": { - "schema": { - "type": "string" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21178 | Nie znaleziono UPO dla podanych kryteriów. | UPO o numerze referencyjnym {referenceNumber} dla sesji {referenceNumber} nie zostało znalezione. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 1200 | 12000 | sessionMisc\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 1200, - "perHour": 12000 - }, - "x-required-permissions": [ - "InvoiceWrite", - "Introspection", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/tokens": { - "post": { - "tags": [ - "Tokeny KSeF" - ], - "summary": "Wygenerowanie nowego tokena", - "description": "Zwraca token, który może być użyty do uwierzytelniania się w KSeF.\n\nToken może być generowany tylko w kontekście NIP lub identyfikatora wewnętrznego. Jest zwracany tylko raz. Zaczyna być aktywny w momencie gdy jego status zmieni się na `Active`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "permissions", - "description" - ], - "allOf": [ - { - "$ref": "#/components/schemas/GenerateTokenRequest" - } - ] - }, - "example": { - "permissions": [ - "InvoiceRead", - "InvoiceWrite" - ], - "description": "Wystawianie i przeglądanie faktur." - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/GenerateTokenResponse" - }, - "example": { - "referenceNumber": "20251010-EC-1DCE3E3000-12ECB5B36E-45", - "token": "20251010-EC-1DCE3E3000-12ECB5B36E-45|internalId-5265877635-12345|919f704466624ce29cd5ac7b65ded5e7cccc112eee314f2aaa76e02cd16df7b9" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 26001 | Nie można nadać tokenowi uprawnień których nie posiadasz. | Informacja o brakujących uprawnieniach. |\n| 26002 | Nie można wygenerować tokena dla obecnego typu kontekstu. | Informacja o aktualnym i dozwolonych typach kontekstu. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - }, - "get": { - "tags": [ - "Tokeny KSeF" - ], - "summary": "Pobranie listy wygenerowanych tokenów", - "description": "\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n", - "parameters": [ - { - "name": "status", - "in": "query", - "description": "Status tokenów do zwrócenia. W przypadku braku parametru zwracane są wszystkie tokeny. Parametr można przekazać wielokrotnie.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AuthenticationTokenStatus" - } - } - }, - { - "name": "description", - "in": "query", - "description": "Umożliwia filtrowanie tokenów po opisie. Wartość parametru jest wyszukiwana w opisie tokena (operacja nie rozróżnia wielkości liter). Należy podać co najmniej 3 znaki.", - "schema": { - "minLength": 3, - "type": "string" - } - }, - { - "name": "authorIdentifier", - "in": "query", - "description": "Umożliwia filtrowanie tokenów po ich twórcy. Wartość parametru jest wyszukiwana w identyfikatorze (operacja nie rozróżnia wielkości liter). Należy podać co najmniej 3 znaki.", - "schema": { - "minLength": 3, - "type": "string" - } - }, - { - "name": "authorIdentifierType", - "in": "query", - "description": "Umożliwia filtrowanie tokenów po ich twórcy. Wartość parametru określa typ identyfikatora w którym będzie wyszukiwany ciąg znaków przekazany w parametrze `authorIdentifier`.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n", - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/TokenAuthorIdentifierType" - } - ] - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - }, - { - "name": "x-continuation-token", - "in": "header", - "description": "Token służący do pobrania kolejnej strony wyników.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryTokensResponse" - }, - "example": { - "continuationToken": "W3sidG9rZW4iOiIrUklEOn4zeHd0QUlqZUc5VkhCQUFBQUFBQUJBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBZ2dBQUFBQUFCQUFBQUFBQUFBQUVBQUFBQUFBQUFBUUFBQUVBRWVFMllFPSIsInJhbmdlIjp7Im1pbiI6IjA1QzFERjIxOUY5OTIwIiwibWF4IjoiRkYifX1d", - "tokens": [ - { - "referenceNumber": "20251001-EC-2DD3AFF000-A6B7F19A95-11", - "authorIdentifier": { - "type": "Nip", - "value": "5265877635" - }, - "contextIdentifier": { - "type": "Nip", - "value": "5265877635" - }, - "description": "Wystawianie i przeglądanie faktur.", - "requestedPermissions": [ - "InvoiceRead", - "InvoiceWrite" - ], - "dateCreated": "2025-10-01T13:20:52.9919681+00:00", - "status": "Active", - "statusDetails": [ ] - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "dateCreated", - "direction": "Desc" - } - ] - } - }, - "/tokens/{referenceNumber}": { - "get": { - "tags": [ - "Tokeny KSeF" - ], - "summary": "Pobranie statusu tokena", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny tokena KSeF.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TokenStatusResponse" - }, - "example": { - "referenceNumber": "20251001-EC-220B0CE000-E228129563-96", - "authorIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "contextIdentifier": { - "type": "Nip", - "value": "5265877635" - }, - "description": "Wystawianie i przeglądanie faktur.", - "requestedPermissions": [ - "InvoiceWrite", - "InvoiceRead" - ], - "dateCreated": "2025-07-11T12:23:56.0154302+00:00", - "lastUseDate": "2025-07-11T12:23:56.0154302+00:00", - "status": "Pending", - "statusDetails": [ ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - }, - "delete": { - "tags": [ - "Tokeny KSeF" - ], - "summary": "Unieważnienie tokena", - "description": "Unieważniony token nie pozwoli już na uwierzytelnienie się za jego pomocą. Unieważnienie nie może zostać cofnięte.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny tokena KSeF.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "204": { - "description": "No Content" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - } - } - }, - "/peppol/query": { - "get": { - "tags": [ - "Usługi Peppol" - ], - "summary": "Pobranie listy dostawców usług Peppol", - "description": "Zwraca listę dostawców usług Peppol zarejestrowanych w systemie.\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n- id (Asc)\n\n", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryPeppolProvidersResponse" - }, - "example": { - "peppolProviders": [ - { - "id": "P123456789", - "name": "Dostawca usług Peppol", - "dateCreated": "2025-07-11T12:23:56.0154302+00:00" - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - }, - "x-sort": [ - { - "field": "dateCreated", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ] - } - }, - "/auth/challenge": { - "post": { - "tags": [ - "Uzyskiwanie dostępu" - ], - "summary": "Inicjalizacja uwierzytelnienia", - "description": "Generuje unikalny challenge wymagany w kolejnym kroku operacji uwierzytelnienia.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationChallengeResponse" - }, - "example": { - "challenge": "20250514-CR-226FB7B000-3ACF9BE4C0-10", - "timestamp": "2025-07-11T12:23:56.0154302+00:00", - "timestampMs": 1752236636015 - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/auth/xades-signature": { - "post": { - "tags": [ - "Uzyskiwanie dostępu" - ], - "summary": "Uwierzytelnienie z wykorzystaniem podpisu XAdES", - "description": "Rozpoczyna operację uwierzytelniania za pomocą dokumentu XML podpisanego podpisem elektronicznym XAdES.\n\n> Więcej informacji:\n> - [Przygotowanie dokumentu XML](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#1-przygotowanie-dokumentu-xml-authtokenrequest)\n> - [Podpis dokumentu XML](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#2-podpisanie-dokumentu-xades)\n> - [Schemat XSD](/docs/v2/schemas/authv2.xsd)", - "parameters": [ - { - "name": "verifyCertificateChain", - "in": "query", - "description": "Wymuszenie weryfikacji zaufania łańcucha certyfikatu wraz ze sprawdzeniem statusu certyfikatu (OCSP/CRL) na środowiskach które umożliwiają wykorzystanie samodzielnie wygenerowanych certyfikatów.", - "schema": { - "type": "boolean" - } - } - ], - "requestBody": { - "content": { - "application/xml": { - "schema": { - "type": "string" - }, - "example": "\n\n 20250625-CR-20F5EE4000-DA48AE4124-46\n \n 5265877635\n \n certificateSubject\n \n \n \n" - } - }, - "required": true - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationInitResponse" - }, - "example": { - "referenceNumber": "20250514-AU-2DFC46C000-3AC6D5877F-D4", - "authenticationToken": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiT3BlcmF0aW9uVG9rZW4iLCJvcGVyYXRpb24tcmVmZXJlbmNlLW51bWJlciI6IjIwMjUwNTE0LUFVLTJERkM0NkMwMDAtM0FDNkQ1ODc3Ri1ENCIsImV4cCI6MTc0NzIzMTcxOSwiaWF0IjoxNzQ3MjI5MDE5LCJpc3MiOiJrc2VmLWFwaS10aSIsImF1ZCI6ImtzZWYtYXBpLXRpIn0.rtRcV2mR9SiuJwpQaQHsbAXvvVsdNKG4DJsdiJctIeU", - "validUntil": "2025-07-11T12:23:56.0154302+00:00" - } - } - } - } - }, - "400": { - "description": " | ExceptionCode | ExceptionDescription | Details | \n|---------------------|---------------------------------------------------------------------|-------------------------------------------------------------|\n| 21001 | Nieczytelna treść. | |\n| 21111 | Nieprawidłowe wyzwanie autoryzacyjne. | |\n| 21115 | Nieprawidłowy certyfikat. | |\n| 21117 | Nieprawidłowy identyfikator podmiotu dla wskazanego typu kontekstu. | |\n| 21217 | Nieprawidłowe kodowanie znaków. | |\n| 21401 | Dokument nie jest zgodny ze schemą (xsd). | {treść błędu walidacji} |\n| 21406 | Konflikt podpisu i typu uwierzytelnienia. | |\n| 9101 | Nieprawidłowy dokument. | |\n| 9102 | Brak podpisu. | |\n| 9103 | Przekroczona liczba dozwolonych podpisów. | |\n| 9105 | Nieprawidłowy podpis. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/auth/ksef-token": { - "post": { - "tags": [ - "Uzyskiwanie dostępu" - ], - "summary": "Uwierzytelnienie z wykorzystaniem tokena KSeF", - "description": "Rozpoczyna operację uwierzytelniania z wykorzystaniem wcześniej wygenerowanego tokena KSeF.\n\nToken KSeF wraz z timestampem ze wcześniej wygenerowanego challenge'a (w formacie ```token|timestamp```) powinien zostać zaszyfrowany dedykowanym do tego celu kluczem publicznym.\n- Timestamp powinien zostać przekazany jako **liczba milisekund od 1 stycznia 1970 roku (Unix timestamp)**.\n- Algorytm szyfrowania: **RSA-OAEP (z użyciem SHA-256 jako funkcji skrótu)**.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "challenge", - "contextIdentifier", - "encryptedToken" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InitTokenAuthenticationRequest" - } - ] - }, - "example": { - "challenge": "20250625-CR-2FDC223000-C2BFC98A9C-4E", - "contextIdentifier": { - "type": "Nip", - "value": "5265877635" - }, - "encryptedToken": "..." - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationInitResponse" - }, - "example": { - "referenceNumber": "20250514-AU-2DFC46C000-3AC6D5877F-D4", - "authenticationToken": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiT3BlcmF0aW9uVG9rZW4iLCJvcGVyYXRpb24tcmVmZXJlbmNlLW51bWJlciI6IjIwMjUwNTE0LUFVLTJERkM0NkMwMDAtM0FDNkQ1ODc3Ri1ENCIsImV4cCI6MTc0NzIzMTcxOSwiaWF0IjoxNzQ3MjI5MDE5LCJpc3MiOiJrc2VmLWFwaS10aSIsImF1ZCI6ImtzZWYtYXBpLXRpIn0.rtRcV2mR9SiuJwpQaQHsbAXvvVsdNKG4DJsdiJctIeU", - "validUntil": "2025-07-11T12:23:56.0154302+00:00" - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|------------------------------------------------|-----------------------------------------------------------------------------|\n| 21111 | Nieprawidłowe wyzwanie autoryzacyjne. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - } - }, - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/auth/{referenceNumber}": { - "get": { - "tags": [ - "Uzyskiwanie dostępu" - ], - "summary": "Pobranie statusu uwierzytelniania", - "description": "Sprawdza bieżący status operacji uwierzytelniania dla podanego tokena.\n\nSposób uwierzytelnienia: `AuthenticationToken` otrzymany przy rozpoczęciu operacji uwierzytelniania.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny tokena otrzymanego przy inicjalizacji operacji uwierzytelniania.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationOperationStatusResponse" - }, - "examples": { - "Kod 100 | Uwierzytelnianie w toku": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 100, - "description": "Uwierzytelnianie w toku" - } - } - }, - "Kod 200 | Uwierzytelnianie zakończone sukcesem": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 200, - "description": "Uwierzytelnianie zakończone sukcesem" - } - } - }, - "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Nieważny certyfikat": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 400, - "description": "Uwierzytelnianie zakończone niepowodzeniem", - "details": [ - "Nieważny certyfikat." - ] - } - } - }, - "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Błąd weryfikacji łańcucha certyfikatów": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 400, - "description": "Uwierzytelnianie zakończone niepowodzeniem", - "details": [ - "Błąd weryfikacji łańcucha certyfikatów." - ] - } - } - }, - "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Niezaufany łańcuch certyfikatów": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 400, - "description": "Uwierzytelnianie zakończone niepowodzeniem", - "details": [ - "Niezaufany łańcuch certyfikatów." - ] - } - } - }, - "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Certyfikat odwołany": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 400, - "description": "Uwierzytelnianie zakończone niepowodzeniem", - "details": [ - "Certyfikat odwołany." - ] - } - } - }, - "Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Niepoprawny certyfikat": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 400, - "description": "Uwierzytelnianie zakończone niepowodzeniem", - "details": [ - "Niepoprawny certyfikat." - ] - } - } - }, - "Kod 500 | Nieznany błąd": { - "value": { - "startDate": "0001-01-01T00:00:00+00:00", - "authenticationMethod": "Token", - "status": { - "code": 500, - "description": "Nieznany błąd ({statusCode})" - } - } - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|------------------------------------------------|-----------------------------------------------------------------------------|\n| 21304 | Brak uwierzytelnienia. | Operacja uwierzytelniania o numerze referencyjnym {referenceNumber} nie została znaleziona. |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/auth/token/redeem": { - "post": { - "tags": [ - "Uzyskiwanie dostępu" - ], - "summary": "Pobranie tokenów dostępowych", - "description": "Pobiera parę tokenów (access token i refresh token) wygenerowanych w ramach pozytywnie zakończonego procesu uwierzytelniania.\n**Tokeny można pobrać tylko raz.**\n\nSposób uwierzytelnienia: `AuthenticationToken` otrzymany przy rozpoczęciu operacji uwierzytelniania.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationTokensResponse" - }, - "example": { - "accessToken": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE", - "validUntil": "2025-07-11T12:23:56.0154302+00:00" - }, - "refreshToken": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE", - "validUntil": "2025-07-11T12:23:56.0154302+00:00" - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|------------------------------------------------|-----------------------------------------------------------------------------|\n| 21301 | Brak autoryzacji. | Tokeny dla operacji uwierzytelniania {referenceNumber} zostały już pobrane. |\n| 21301 | Brak autoryzacji. | Status uwierzytelniania ({operation.Status}) nie pozwala na pobranie tokenów. |\n| 21301 | Brak autoryzacji. | Token KSeF został unieważniony. |\n| 21304 | Brak uwierzytelnienia. | Operacja uwierzytelniania o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21308 | Próba wykorzystania metod autoryzacyjnych osoby zmarłej. | |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/auth/token/refresh": { - "post": { - "tags": [ - "Uzyskiwanie dostępu" - ], - "summary": "Odświeżenie tokena dostępowego", - "description": "Generuje nowy token dostępu na podstawie ważnego refresh tokena.\n\nSposób uwierzytelnienia: `RefreshToken`.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthenticationTokenRefreshResponse" - }, - "example": { - "accessToken": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE", - "validUntil": "2025-07-11T12:23:56.0154302+00:00" - } - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-----------------------------------------------------------------------------|\n| 21301 | Brak autoryzacji. | Status uwierzytelniania ({operation.Status}) nie pozwala na odświeżenie tokenu dostępowego. |\n| 21301 | Brak autoryzacji. | Token KSeF został unieważniony. |\n| 21304 | Brak uwierzytelnienia. | Operacja uwierzytelniania o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21308 | Próba wykorzystania metod autoryzacyjnych osoby zmarłej. | |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 60 | - | - | -\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 60 - } - } - }, - "/sessions/online": { - "post": { - "tags": [ - "Wysyłka interaktywna" - ], - "summary": "Otwarcie sesji interaktywnej", - "description": "Otwiera sesję do wysyłki pojedynczych faktur. Należy przekazać schemat wysyłanych faktur oraz informacje o kluczu używanym do szyfrowania.\n\n> Więcej informacji:\n> - [Otwarcie sesji interaktywnej](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md#1-otwarcie-sesji)\n> - [Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`, `EnforcementOperations`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "formCode", - "encryption" - ], - "allOf": [ - { - "$ref": "#/components/schemas/OpenOnlineSessionRequest" - } - ] - }, - "example": { - "formCode": { - "systemCode": "FA (3)", - "schemaVersion": "1-0E", - "value": "FA" - }, - "encryption": { - "encryptedSymmetricKey": "bdUVjqLj+y2q6aBUuLxxXYAMqeDuIBRTyr+hB96DaWKaGzuVHw9p+Nk9vhzgF/Q5cavK2k6eCh6SdsrWI0s9mFFj4A4UJtsyD8Dn3esLfUZ5A1juuG3q3SBi/XOC/+9W+0T/KdwdE393mbiUNyx1K/0bw31vKJL0COeJIDP7usAMDl42/H1TNvkjk+8iZ80V0qW7D+RZdz+tdiY1xV0f2mfgwJ46V0CpZ+sB9UAssRj+eVffavJ0TOg2b5JaBxE8MCAvrF6rO5K4KBjUmoy7PP7g1qIbm8xI2GO0KnfPOO5OWj8rsotRwBgu7x19Ine3qYUvuvCZlXRGGZ5NHIzWPM4O74+gNalaMgFCsmv8mMhETSU4SfAGmJr9edxPjQSbgD5i2X4eDRDMwvyaAa7CP1b2oICju+0L7Fywd2ZtUcr6El++eTVoi8HYsTArntET++gULT7XXjmb8e3O0nxrYiYsE9GMJ7HBGv3NOoJ1NTm3a7U6+c0ZJiBVLvn6xXw10LQX243xH+ehsKo6djQJKYtqcNPaXtCwM1c9RrsOx/wRXyWCtTffqLiaR0LbYvfMJAcEWceG+RaeAx4p37OiQqdJypd6LAv9/0ECWK8Bip8yyoA+0EYiAJb9YuDz2YlQX9Mx9E9FzFIAsgEQ2w723HZYWgPywLb+dlsum4lTZKQ=", - "initializationVector": "OmtDQdl6vkOI1GLKZSjgEg==" - } - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OpenOnlineSessionResponse" - }, - "example": { - "referenceNumber": "20250625-SO-2C3E6C8000-B675CF5D68-07", - "validUntil": "2025-07-11T12:23:56.0154302+00:00" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | onlineSession\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "InvoiceWrite", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/online/{referenceNumber}/invoices": { - "post": { - "tags": [ - "Wysyłka interaktywna" - ], - "summary": "Wysłanie faktury", - "description": "Przyjmuje zaszyfrowaną fakturę oraz jej metadane i rozpoczyna jej przetwarzanie.\n\n> Więcej informacji:\n> - [Wysłanie faktury](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md#2-wys%C5%82anie-faktury)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "requestBody": { - "description": "Dane faktury", - "content": { - "application/json": { - "schema": { - "required": [ - "invoiceHash", - "invoiceSize", - "encryptedInvoiceHash", - "encryptedInvoiceSize", - "encryptedInvoiceContent" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SendInvoiceRequest" - } - ] - }, - "example": { - "invoiceHash": "EbrK4cOSjW4hEpJaHU71YXSOZZmqP5++dK9nLgTzgV4=", - "invoiceSize": 6480, - "encryptedInvoiceHash": "miYb1z3Ljw5VucTZslv3Tlt+V/EK1V8Q8evD8HMQ0dc=", - "encryptedInvoiceSize": 6496, - "encryptedInvoiceContent": "...", - "offlineMode": false - } - } - } - }, - "responses": { - "202": { - "description": "Accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SendInvoiceResponse" - }, - "example": { - "referenceNumber": "20250625-EE-319D7EE000-B67F415CDC-2C" - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------|\n| 21155 | Przekroczono dozwoloną liczbę faktur w sesji. | Sesja o numerze referencyjnym {referenceNumber} osiągnęła dozwolony limit liczby faktur {invoiceLimit}. |\n| 21166 | Korekta techniczna niedostępna. | Faktura posiada już przetworzoną prawidłowo korektę techniczną. |\n| 21167 | Status faktury nie pozwala na korektę techniczną. | Nie można wysłać korekty technicznej do prawidłowo przetworzonej faktury. |\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została odnaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia wysyłkę faktur. |\n| 21402 | Nieprawidłowy rozmiar pliku. | Długość treści nie zgadza się z rozmiarem pliku. |\n| 21403 | Nieprawidłowy skrót pliku. | Skrót treści nie zgadza się ze skrótem pliku. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1800 | invoiceSend\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1800 - }, - "x-required-permissions": [ - "InvoiceWrite", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/online/{referenceNumber}/close": { - "post": { - "tags": [ - "Wysyłka interaktywna" - ], - "summary": "Zamknięcie sesji interaktywnej", - "description": "Zamyka sesję interaktywną i rozpoczyna generowanie zbiorczego UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "204": { - "description": "No Content" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została odnaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia jej zamknięcie. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | onlineSession\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-required-permissions": [ - "InvoiceWrite", - "PefInvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/batch": { - "post": { - "tags": [ - "Wysyłka wsadowa" - ], - "summary": "Otwarcie sesji wsadowej", - "description": "Otwiera sesję do wysyłki wsadowej faktur. Należy przekazać schemat wysyłanych faktur, informacje o paczce faktur oraz informacje o kluczu używanym do szyfrowania.\n\n> Więcej informacji:\n> - [Przygotowanie paczki faktur](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-wsadowa.md)\n> - [Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `EnforcementOperations`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "formCode", - "batchFile", - "encryption" - ], - "allOf": [ - { - "$ref": "#/components/schemas/OpenBatchSessionRequest" - } - ] - }, - "example": { - "formCode": { - "systemCode": "FA (2)", - "schemaVersion": "1-0E", - "value": "FA" - }, - "batchFile": { - "fileSize": 16037, - "fileHash": "WO86CC+1Lef11wEosItld/NPwxGN8tobOMLqk9PQjgs=", - "fileParts": [ - { - "ordinalNumber": 1, - "fileSize": 16048, - "fileHash": "23ZyDAN0H/+yhC/En2xbNfF0tajAWSfejDaXD7fc2AE=" - } - ] - }, - "encryption": { - "encryptedSymmetricKey": "bYqmPAglF01AxZim4oNa+1NerhZYfFgLMnvksBprUur1aesQ0Y5jsmOIfCrozfMkF2tjdO+uOsBg4FPlDgjChwN2/tz2Hqwtxq3RkTr1SjY4x8jxJFpPedcS7EI+XO8C+i9mLj7TFx9p/bg07yM9vHtMAk5b88Ay9Qc3+T5Ch1DM2ClR3sVu2DqdlKzmbINY+rhfGtXn58Qo0XRyESGgc6M0iTZVBRPuPXLnD8a1KpOneCpNzLwxgT6Ei3ivLOpPWT53PxkRTaQ8puj6CIiCKo4FHQzHuI/NmrAhYU7TkNm2kymP/OxBgWdg3XB74tqNFfT8RZN1bZXuPhBidDOqa+xsqY3E871FSDmQwZf58HmoNl31XNvpnryiRGfnAISt+m+ELqgksAresVu6E9poUL1yiff+IOHSZABoYpNiqwnbT8qyW1uk8lKLyFVFu+kOsbzBk1OWWHqSkNFDaznDa2MKjHonOXI0uyKaKWvoBFC4dWN1PVumfpSSFAeYgNpAyVrZdcVOuiliEWepTDjGzJoOafTvwr5za2S6B5bPECDpX7JXazV7Olkq7ezG0w8y3olx+0C+NHoCk8B5/cm4gtVHTgKjiLSGpKJVOJABLXFkOyIOjbQsVe4ryX0Qy+SfL7JIQvTWvM5xkCoOMbzLdMo9tNo5qE34sguFI+lIevY=", - "initializationVector": "jWpJLNBHJ5pQEGCBglmIAw==" - }, - "offlineMode": false - } - } - } - }, - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OpenBatchSessionResponse" - }, - "example": { - "referenceNumber": "20250626-SB-213D593000-4DE10D80A5-E9", - "partUploadRequests": [ - { - "ordinalNumber": 1, - "method": "PUT", - "url": "https://ksef-api-storage/storage/00/20250626-sb-213d593000-4de10d80a5-e9/batch-parts/1?skoid=1ad7cfe8-2cb2-406b-b96c-6eefb55794db&sktid=647754c7-3974-4442-a425-c61341b61c69&skt=2025-06-26T09%3A40%3A54Z&ske=2025-06-26T10%3A10%3A54Z&sks=b&skv=2025-01-05&sv=2025-01-05&se=2025-06-26T10%3A10%3A54Z&sr=b&sp=w&sig=8mKZEU8Reuz%2Fn7wHi4T%2FY8BzLeD5l8bR2xJsBxIgDEY%3D", - "headers": { - "x-ms-blob-type": "BlockBlob" - } - } - ] - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------------------|\n| 21157 | Nieprawidłowy rozmiar części pakietu. | {treść błędu walidacji} | \n| 21161 | Przekroczono dozwoloną liczbę części pakietu. | {treść błędu walidacji} |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 600 | batchSession\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 200, - "perHour": 600 - }, - "x-required-permissions": [ - "InvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/sessions/batch/{referenceNumber}/close": { - "post": { - "tags": [ - "Wysyłka wsadowa" - ], - "summary": "Zamknięcie sesji wsadowej", - "description": "Zamyka sesję wsadową, rozpoczyna procesowanie paczki faktur i generowanie UPO dla prawidłowych faktur oraz zbiorczego UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `EnforcementOperations`.", - "parameters": [ - { - "name": "referenceNumber", - "in": "path", - "description": "Numer referencyjny sesji", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReferenceNumber" - } - } - ], - "responses": { - "204": { - "description": "No Content" - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------|\n| 21157 | Nieprawidłowy rozmiar części pakietu. | Zadeklarowany rozmiar części '{ordinalNumber}' nie zgadza się z rzeczywistym. | \n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia jej zamknięcie. |\n| 21205 | Pakiet nie może być pusty. | Nie przesłano zadeklarowanej '{ordinalNumber}' części pliku. | \n| 21208 | Czas oczekiwania na requesty upload lub finish został przekroczony. | Sesja anulowana, przekroczony czas wysyłki. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 200 | 600 | batchSession\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 200, - "perHour": 600 - }, - "x-required-permissions": [ - "InvoiceWrite", - "EnforcementOperations" - ] - } - }, - "/permissions/query/personal/grants": { - "post": { - "tags": [ - "Wyszukiwanie nadanych uprawnień" - ], - "summary": "Pobranie listy własnych uprawnień", - "description": " Metoda pozwala na odczytanie własnych uprawnień uwierzytelnionego klienta API w bieżącym kontekście logowania. \n\n W odpowiedzi przekazywane są następujące uprawnienia: \n - nadane w sposób bezpośredni w bieżącym kontekście \n - nadane przez podmiot nadrzędny \n - nadane w sposób pośredni, jeżeli podmiot kontekstu logowania jest w uprawnieniu pośrednikiem lub podmiotem docelowym \n - nadane podmiotowi do obsługi faktur przez inny podmiot, jeśli podmiot uwierzytelniony ma w bieżącym kontekście uprawnienia właścicielskie \n\n Uprawnienia zwracane przez operację obejmują: \n - **CredentialsManage** – zarządzanie uprawnieniami \n - **CredentialsRead** – przeglądanie uprawnień \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n - **SubunitManage** – zarządzanie podmiotami podrzędnymi \n - **EnforcementOperations** – wykonywanie operacji egzekucyjnych \n - **VatEuManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **contextIdentifier** – identyfikator podmiotu, który nadał uprawnienie do obsługi faktur \n - **targetIdentifier** – identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n - **permissionState** – status uprawnienia \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-w%C5%82asnych-uprawnie%C5%84)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsQueryRequest" - } - ] - }, - "example": { - "contextIdentifier": { - "type": "Nip", - "value": "3568707925" - }, - "permissionTypes": [ - "InvoiceWrite" - ], - "permissionState": "Active" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryPersonalPermissionsResponse" - }, - "example": { - "permissions": [ - { - "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", - "contextIdentifier": { - "type": "Nip", - "value": "3568707925" - }, - "authorizedIdentifier": { - "type": "Nip", - "value": "5247677742" - }, - "permissionScope": "InvoiceWrite", - "description": "Opis uprawnienia", - "permissionState": "Active", - "startDate": "2025-06-22T10:41:11+00:00", - "canDelegate": false - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ] - } - }, - "/permissions/query/persons/grants": { - "post": { - "tags": [ - "Wyszukiwanie nadanych uprawnień" - ], - "summary": "Pobranie listy uprawnień do pracy w KSeF nadanych osobom fizycznym lub podmiotom", - "description": " Metoda pozwala na odczytanie uprawnień nadanych osobie fizycznej lub podmiotowi. \n Lista pobranych uprawnień może być dwóch rodzajów: \n - Lista wszystkich uprawnień obowiązujących w bieżącym kontekście logowania (używana, gdy administrator chce przejrzeć uprawnienia wszystkich użytkowników w bieżącym kontekście) \n - Lista wszystkich uprawnień nadanych w bieżącym kontekście przez uwierzytelnionego klienta API (używana, gdy administrator chce przejrzeć listę nadanych przez siebie uprawnień w bieżącym kontekście) \n\n Dla pierwszej listy (obowiązujących uprawnień) w odpowiedzi przekazywane są: \n - osoby i podmioty mogące pracować w bieżącym kontekście z wyjątkiem osób uprawnionych w sposób pośredni \n - osoby uprawnione w sposób pośredni przez podmiot bieżącego kontekstu \n\n Dla drugiej listy (nadanych uprawnień) w odpowiedzi przekazywane są: \n - uprawnienia nadane w sposób bezpośredni do pracy w bieżącym kontekście lub w kontekście jednostek podrzędnych \n - uprawnienia nadane w sposób pośredni do obsługi klientów podmiotu bieżącego kontekstu \n\n Uprawnienia zwracane przez operację obejmują: \n - **CredentialsManage** – zarządzanie uprawnieniami \n - **CredentialsRead** – przeglądanie uprawnień \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n - **SubunitManage** – zarządzanie podmiotami podrzędnymi \n - **EnforcementOperations** – wykonywanie operacji egzekucyjnych \n\n Odpowiedź może być filtrowana na podstawie parametrów: \n - **authorIdentifier** – identyfikator osoby, która nadała uprawnienie \n - **authorizedIdentifier** – identyfikator osoby lub podmiotu uprawnionego \n - **targetIdentifier** – identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n - **permissionState** – status uprawnienia \n - **queryType** – typ zapytania określający, która z dwóch list ma zostać zwrócona \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-do-pracy-w-ksef-nadanych-osobom-fizycznym-lub-podmiotom)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "queryType" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsQueryRequest" - } - ] - }, - "example": { - "authorIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "permissionTypes": [ - "CredentialsManage", - "CredentialsRead", - "InvoiceWrite" - ], - "permissionState": "Active", - "queryType": "PermissionsInCurrentContext" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryPersonPermissionsResponse" - }, - "example": { - "permissions": [ - { - "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", - "authorizedIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "targetIdentifier": { - "type": "Nip", - "value": "9786214922" - }, - "authorIdentifier": { - "type": "Pesel", - "value": "15062788702" - }, - "permissionScope": "InvoiceWrite", - "description": "praca dla klienta 9786214922; uprawniony NIP: 7762811692, Adam Abacki; pośrednik 3936518395", - "permissionState": "Active", - "startDate": "2025-06-22T10:41:11+00:00", - "canDelegate": false - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ], - "x-required-permissions": [ - "CredentialsManage", - "CredentialsRead", - "SubunitManage" - ] - } - }, - "/permissions/query/subunits/grants": { - "post": { - "tags": [ - "Wyszukiwanie nadanych uprawnień" - ], - "summary": "Pobranie listy uprawnień administratorów jednostek i podmiotów podrzędnych", - "description": " Metoda pozwala na odczytanie uprawnień do zarządzania uprawnieniami nadanych administratorom: \n - jednostek podrzędnych identyfikowanych identyfikatorem wewnętrznym \n - podmiotów podrzędnych (podrzędnych JST lub członków grupy VAT) identyfikowanych przez NIP \n\n Lista zwraca wyłącznie uprawnienia do zarządzania uprawnieniami nadane z kontekstu bieżącego (z podmiotu nadrzędnego). \n Nie są odczytywane uprawnienia nadane przez administratorów jednostek podrzędnych wewnątrz tych jednostek. \n\n Odpowiedź może być filtrowana na podstawie parametru: \n - **subunitIdentifier** – identyfikator jednostki lub podmiotu podrzędnego \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-administrator%C3%B3w-jednostek-i-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsQueryRequest" - } - ] - }, - "example": { - "subunitIdentifier": { - "type": "InternalId", - "value": "7762811692-12345" - } - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QuerySubunitPermissionsResponse" - }, - "example": { - "permissions": [ - { - "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", - "authorizedIdentifier": { - "type": "Fingerprint", - "value": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59" - }, - "subunitIdentifier": { - "type": "InternalId", - "value": "7762811692-12345" - }, - "authorIdentifier": { - "type": "Pesel", - "value": "15062788702" - }, - "permissionScope": "CredentialsManage", - "description": "Opis uprawnienia", - "startDate": "2025-06-22T10:41:11+00:00" - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ], - "x-required-permissions": [ - "CredentialsManage", - "CredentialsRead", - "SubunitManage" - ] - } - }, - "/permissions/query/entities/roles": { - "get": { - "tags": [ - "Wyszukiwanie nadanych uprawnień" - ], - "summary": "Pobranie listy ról podmiotu", - "description": " Metoda pozwala na **odczytanie listy ról podmiotu bieżącego kontekstu logowania**.\n\n#### Role podmiotów zwracane przez operację:\n- **CourtBailiff** – komornik sądowy \n- **EnforcementAuthority** – organ egzekucyjny \n- **LocalGovernmentUnit** – nadrzędna JST \n- **LocalGovernmentSubUnit** – podrzędne JST \n- **VatGroupUnit** – grupa VAT \n- **VatGroupSubUnit** – członek grupy VAT\n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy ról](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-r%C3%B3l-podmiotu)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryEntityRolesResponse" - }, - "example": { - "roles": [ - { - "role": "EnforcementAuthority", - "description": "Organ egzekucyjny", - "startDate": "2025-06-22T10:41:11+00:00" - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ], - "x-required-permissions": [ - "CredentialsManage", - "CredentialsRead" - ] - } - }, - "/permissions/query/subordinate-entities/roles": { - "post": { - "tags": [ - "Wyszukiwanie nadanych uprawnień" - ], - "summary": "Pobranie listy podmiotów podrzędnych", - "description": " Metoda pozwala na odczytanie listy podmiotów podrzędnych, \n jeżeli podmiot bieżącego kontekstu ma rolę podmiotu nadrzędnego:\n - **nadrzędna JST** – odczytywane są podrzędne JST, \n - **grupa VAT** – odczytywane są podmioty będące członkami grupy VAT.\n\n Role podmiotów zwracane przez operację obejmują: \n - **LocalGovernmentSubUnit** – podrzędne JST, \n - **VatGroupSubUnit** – członek grupy VAT.\n\n Odpowiedź może być filtrowana według parametru: \n - **subordinateEntityIdentifier** – identyfikator podmiotu podrzędnego.\n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy podmiotów podrzędnych](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/SubordinateEntityRolesQueryRequest" - } - ] - }, - "example": { - "subordinateEntityIdentifier": { - "type": "Nip", - "value": "7762811692" - } - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QuerySubordinateEntityRolesResponse" - }, - "example": { - "roles": [ - { - "subordinateEntityIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "role": "VatGroupSubUnit", - "description": "Członek grupy VAT 8373740478", - "startDate": "2025-06-22T10:41:11+00:00" - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ], - "x-required-permissions": [ - "CredentialsManage", - "CredentialsRead", - "SubunitManage" - ] - } - }, - "/permissions/query/authorizations/grants": { - "post": { - "tags": [ - "Wyszukiwanie nadanych uprawnień" - ], - "summary": "Pobranie listy uprawnień podmiotowych do obsługi faktur", - "description": " Metoda pozwala na odczytanie uprawnień podmiotowych: \n - otrzymanych przez podmiot bieżącego kontekstu \n - nadanych przez podmiot bieżącego kontekstu \n\n Wybór listy nadanych lub otrzymanych uprawnień odbywa się przy użyciu parametru **queryType**. \n\n Uprawnienia zwracane przez operację obejmują: \n - **SelfInvoicing** – wystawianie faktur w trybie samofakturowania \n - **TaxRepresentative** – wykonywanie operacji przedstawiciela podatkowego \n - **RRInvoicing** – wystawianie faktur VAT RR \n - **PefInvoicing** – wystawianie faktur PEF \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **authorizingIdentifier** – identyfikator podmiotu uprawniającego (stosowane przy queryType = Received) \n - **authorizedIdentifier** – identyfikator podmiotu uprawnionego (stosowane przy queryType = Granted) \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-podmiotowych-do-obs%C5%82ugi-faktur)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `PefInvoiceWrite`.", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "required": [ - "queryType" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationPermissionsQueryRequest" - } - ] - }, - "example": { - "authorizedIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "queryType": "Granted", - "permissionTypes": [ - "SelfInvoicing", - "TaxRepresentative", - "RRInvoicing" - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryEntityAuthorizationPermissionsResponse" - }, - "example": { - "authorizationGrants": [ - { - "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", - "authorIdentifier": { - "type": "Pesel", - "value": "15062788702" - }, - "authorizedEntityIdentifier": { - "type": "Nip", - "value": "7762811692" - }, - "authorizingEntityIdentifier": { - "type": "Nip", - "value": "1134256681" - }, - "authorizationScope": "SelfInvoicing", - "description": "Uprawnienie podmiotowe do samofakturowania", - "startDate": "2025-06-22T10:41:11+00:00" - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ], - "x-required-permissions": [ - "CredentialsManage", - "CredentialsRead", - "PefInvoiceWrite" - ] - } - }, - "/permissions/query/eu-entities/grants": { - "post": { - "tags": [ - "Wyszukiwanie nadanych uprawnień" - ], - "summary": "Pobranie listy uprawnień administratorów lub reprezentantów podmiotów unijnych uprawnionych do samofakturowania", - "description": " Metoda pozwala na odczytanie uprawnień administratorów lub reprezentantów podmiotów unijnych: \n - Jeżeli kontekstem logowania jest NIP, możliwe jest odczytanie uprawnień administratorów podmiotów unijnych powiązanych z podmiotem bieżącego kontekstu, czyli takich, dla których pierwszy człon kontekstu złożonego jest równy NIP-owi kontekstu logowania. \n - Jeżeli kontekst logowania jest złożony (NIP-VAT UE), możliwe jest pobranie wszystkich uprawnień administratorów i reprezentantów podmiotu w bieżącym kontekście złożonym. \n\n Uprawnienia zwracane przez operację obejmują: \n - **VatUeManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **vatUeIdentifier** – identyfikator podmiotu unijnego \n - **authorizedFingerprintIdentifier** – odcisk palca certyfikatu uprawnionej osoby lub podmiotu \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-administrator%C3%B3w-lub-reprezentant%C3%B3w-podmiot%C3%B3w-unijnych-uprawnionych-do-samofakturowania)\n\n**Sortowanie:**\n\n- startDate (Desc)\n- id (Asc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `VatUeManage`.", - "parameters": [ - { - "name": "pageOffset", - "in": "query", - "description": "Numer strony wyników.", - "schema": { - "minimum": 0, - "type": "integer", - "format": "int32", - "default": 0 - } - }, - { - "name": "pageSize", - "in": "query", - "description": "Rozmiar strony wyników.", - "schema": { - "maximum": 100, - "minimum": 10, - "type": "integer", - "format": "int32", - "default": 10 - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionsQueryRequest" - } - ] - }, - "example": { - "vatUeIdentifier": "DE123456789012", - "permissionTypes": [ - "VatUeManage", - "Introspection" - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryEuEntityPermissionsResponse" - }, - "example": { - "permissions": [ - { - "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", - "authorIdentifier": { - "type": "Pesel", - "value": "15062788702" - }, - "vatUeIdentifier": "DE123456789012", - "euEntityName": "Podmiot unijny", - "authorizedFingerprintIdentifier": "CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59", - "permissionScope": "VatUeManage", - "description": "Opis uprawnienia", - "startDate": "2025-06-22T10:41:11+00:00" - } - ], - "hasMore": false - } - } - } - }, - "400": { - "description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExceptionResponse" - } - } - }, - "x-summary": "Bad Request" - }, - "429": { - "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 100 | 300 | 1200 | other\n", - "headers": { - "Retry-After": { - "schema": { - "$ref": "#/components/schemas/RetryAfter" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TooManyRequestsResponse" - } - } - }, - "x-summary": "Too Many Requests" - }, - "403": { - "description": "Forbidden" - }, - "401": { - "description": "Unauthorized" - } - }, - "security": [ - { - "Bearer": [ ] - } - ], - "x-rate-limits": { - "perSecond": 100, - "perMinute": 300, - "perHour": 1200 - }, - "x-sort": [ - { - "field": "startDate", - "direction": "Desc" - }, - { - "field": "id", - "direction": "Asc" - } - ], - "x-required-permissions": [ - "CredentialsManage", - "CredentialsRead", - "VatUeManage" - ] - } - } - }, - "components": { - "schemas": { - "AllowedIps": { - "type": "object", - "properties": { - "ip4Addresses": { - "type": "array", - "items": { - "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$", - "type": "string" - }, - "description": "Lista adresów IPv4 w notacji dziesiętnej kropkowanej, np. `192.168.0.10`.", - "nullable": true - }, - "ip4Ranges": { - "type": "array", - "items": { - "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}-((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$", - "type": "string" - }, - "description": "Lista adresów IPv4 podana w formie zakresu początek–koniec, oddzielonego pojedynczym myślnikiem, np. `10.0.0.1–10.0.0.254`.", - "nullable": true - }, - "ip4Masks": { - "type": "array", - "items": { - "pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}\\/(0|[1-9]|1[0-9]|2[0-9]|3[0-2])$", - "type": "string" - }, - "description": "Lista adresów IPv4 w notacji CIDR, np. `172.16.0.0/16`.", - "nullable": true - } - }, - "additionalProperties": false - }, - "AmountType": { - "enum": [ - "Brutto", - "Netto", - "Vat" - ], - "type": "string" - }, - "ApiRateLimitValuesOverride": { - "required": [ - "perHour", - "perMinute", - "perSecond" - ], - "type": "object", - "properties": { - "perSecond": { - "type": "integer", - "description": "Limit na sekundę.", - "format": "int32" - }, - "perMinute": { - "type": "integer", - "description": "Limit na minutę.", - "format": "int32" - }, - "perHour": { - "type": "integer", - "description": "Limit na godzinę.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "ApiRateLimitsOverride": { - "required": [ - "batchSession", - "invoiceDownload", - "invoiceExport", - "invoiceExportStatus", - "invoiceMetadata", - "invoiceSend", - "invoiceStatus", - "onlineSession", - "other", - "sessionInvoiceList", - "sessionList", - "sessionMisc" - ], - "type": "object", - "properties": { - "onlineSession": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla otwierania/zamykania sesji interaktywnych." - }, - "batchSession": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla otwierania/zamykania sesji wsadowych." - }, - "invoiceSend": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla wysyłki faktur." - }, - "invoiceStatus": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pobierania statusu faktury z sesji." - }, - "sessionList": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pobierania listy sesji." - }, - "sessionInvoiceList": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pobierania listy faktur w sesji." - }, - "sessionMisc": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pozostałych operacji w ramach sesji." - }, - "invoiceMetadata": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pobierania metadanych faktur." - }, - "invoiceExport": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla eksportu paczki faktur." - }, - "invoiceExportStatus": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pobierania statusu eksportu paczki faktur." - }, - "invoiceDownload": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pobierania faktur po numerze KSeF." - }, - "other": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitValuesOverride" - } - ], - "description": "Limity dla pozostałych operacji API." - } - }, - "additionalProperties": false - }, - "AttachmentPermissionGrantRequest": { - "required": [ - "nip" - ], - "type": "object", - "properties": { - "nip": { - "$ref": "#/components/schemas/Nip" - } - }, - "additionalProperties": false - }, - "AttachmentPermissionRevokeRequest": { - "required": [ - "nip" - ], - "type": "object", - "properties": { - "nip": { - "$ref": "#/components/schemas/Nip" - }, - "expectedEndDate": { - "type": "string", - "description": "Data wycofania zgody na przesyłanie faktur z załącznikiem.", - "format": "date", - "nullable": true - } - }, - "additionalProperties": false - }, - "AuthenticationChallengeResponse": { - "required": [ - "challenge", - "timestamp", - "timestampMs" - ], - "type": "object", - "properties": { - "challenge": { - "$ref": "#/components/schemas/Challenge" - }, - "timestamp": { - "type": "string", - "description": "Czas wygenerowania challenge-a.", - "format": "date-time" - }, - "timestampMs": { - "type": "integer", - "description": "Czas wygenerowania challenge-a w milisekundach od 1 stycznia 1970 roku (Unix timestamp).", - "format": "int64" - } - }, - "additionalProperties": false - }, - "AuthenticationContextIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/AuthenticationContextIdentifierType" - } - ], - "description": "Typ identyfikatora" - }, - "value": { - "type": "string", - "description": "Wartość identyfikatora" - } - }, - "additionalProperties": false - }, - "AuthenticationContextIdentifierType": { - "enum": [ - "Nip", - "InternalId", - "NipVatUe", - "PeppolId" - ], - "type": "string" - }, - "AuthenticationInitResponse": { - "required": [ - "authenticationToken", - "referenceNumber" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny sesji uwierzytelnienia." - }, - "authenticationToken": { - "required": [ - "token", - "validUntil" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenInfo" - } - ], - "description": "Token operacji uwierzytelnienia." - } - }, - "additionalProperties": false - }, - "AuthenticationListItem": { - "required": [ - "authenticationMethod", - "referenceNumber", - "startDate", - "status" - ], - "type": "object", - "properties": { - "startDate": { - "type": "string", - "description": "Data rozpoczęcia operacji uwierzytelnienia.", - "format": "date-time" - }, - "authenticationMethod": { - "allOf": [ - { - "$ref": "#/components/schemas/AuthenticationMethod" - } - ], - "description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy usług Peppol. |\n" - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/StatusInfo" - } - ], - "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Uwierzytelnianie w toku | - |\n| 200 | Uwierzytelnianie zakończone sukcesem | - |\n| 415 | Uwierzytelnianie zakończone niepowodzeniem | Brak przypisanych uprawnień |\n| 425 | Uwierzytelnienie unieważnione | Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe wyzwanie autoryzacyjne |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy token |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy czas tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token unieważniony |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nieaktywny |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Nieważny certyfikat |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Błąd weryfikacji łańcucha certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niezaufany łańcuch certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Certyfikat odwołany |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niepoprawny certyfikat |\n| 470 | Uwierzytelnianie zakończone niepowodzeniem | Próba wykorzystania metod autoryzacyjnych osoby zmarłej |\n| 480 | Uwierzytelnienie zablokowane | Podejrzenie incydentu bezpieczeństwa. Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy. |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" - }, - "isTokenRedeemed": { - "type": "boolean", - "description": "Czy został już wydany refresh token powiązany z danym uwierzytelnieniem.", - "nullable": true - }, - "lastTokenRefreshDate": { - "type": "string", - "description": "Data ostatniego odświeżenia tokena.", - "format": "date-time", - "nullable": true - }, - "refreshTokenValidUntil": { - "type": "string", - "description": "Termin ważności refresh tokena (o ile nie zostanie wcześniej unieważniony).", - "format": "date-time", - "nullable": true - }, - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny sesji uwierzytelnienia." - }, - "isCurrent": { - "type": "boolean", - "description": "Czy sesja jest powiązana z aktualnie używanym tokenem.", - "readOnly": true - } - }, - "additionalProperties": false - }, - "AuthenticationListResponse": { - "required": [ - "items" - ], - "type": "object", - "properties": { - "continuationToken": { - "type": "string", - "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", - "nullable": true - }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AuthenticationListItem" - }, - "description": "Lista sesji uwierzytelniania." - } - }, - "additionalProperties": false - }, - "AuthenticationMethod": { - "enum": [ - "Token", - "TrustedProfile", - "InternalCertificate", - "QualifiedSignature", - "QualifiedSeal", - "PersonalSignature", - "PeppolSignature" - ], - "type": "string", - "description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy usług Peppol. |\n" - }, - "AuthenticationOperationStatusResponse": { - "required": [ - "authenticationMethod", - "startDate", - "status" - ], - "type": "object", - "properties": { - "startDate": { - "type": "string", - "description": "Data rozpoczęcia operacji uwierzytelnienia.", - "format": "date-time" - }, - "authenticationMethod": { - "allOf": [ - { - "$ref": "#/components/schemas/AuthenticationMethod" - } - ], - "description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy usług Peppol. |\n" - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/StatusInfo" - } - ], - "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Uwierzytelnianie w toku | - |\n| 200 | Uwierzytelnianie zakończone sukcesem | - |\n| 415 | Uwierzytelnianie zakończone niepowodzeniem | Brak przypisanych uprawnień |\n| 425 | Uwierzytelnienie unieważnione | Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe wyzwanie autoryzacyjne |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy token |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy czas tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token unieważniony |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nieaktywny |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Nieważny certyfikat |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Błąd weryfikacji łańcucha certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niezaufany łańcuch certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Certyfikat odwołany |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niepoprawny certyfikat |\n| 470 | Uwierzytelnianie zakończone niepowodzeniem | Próba wykorzystania metod autoryzacyjnych osoby zmarłej |\n| 480 | Uwierzytelnienie zablokowane | Podejrzenie incydentu bezpieczeństwa. Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy. |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" - }, - "isTokenRedeemed": { - "type": "boolean", - "description": "Czy został już wydany refresh token powiązany z danym uwierzytelnieniem.", - "nullable": true - }, - "lastTokenRefreshDate": { - "type": "string", - "description": "Data ostatniego odświeżenia tokena.", - "format": "date-time", - "nullable": true - }, - "refreshTokenValidUntil": { - "type": "string", - "description": "Termin ważności refresh tokena (o ile nie zostanie wcześniej unieważniony).", - "format": "date-time", - "nullable": true - } - }, - "additionalProperties": false - }, - "AuthenticationTokenRefreshResponse": { - "required": [ - "accessToken" - ], - "type": "object", - "properties": { - "accessToken": { - "required": [ - "token", - "validUntil" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenInfo" - } - ], - "description": "Token dostępu, którego należy używać w wywołaniach chronionych zasobów API." - } - }, - "additionalProperties": false - }, - "AuthenticationTokenStatus": { - "enum": [ - "Pending", - "Active", - "Revoking", - "Revoked", - "Failed" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n" - }, - "AuthenticationTokensResponse": { - "required": [ - "accessToken", - "refreshToken" - ], - "type": "object", - "properties": { - "accessToken": { - "required": [ - "token", - "validUntil" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenInfo" - } - ], - "description": "Token dostępu." - }, - "refreshToken": { - "required": [ - "token", - "validUntil" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenInfo" - } - ], - "description": "Token umożliwiający odświeżenie tokenu dostępu.\n> Więcej informacji:\n> - [Odświeżanie tokena](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#5-od%C5%9Bwie%C5%BCenie-tokena-dost%C4%99powego-accesstoken)" - } - }, - "additionalProperties": false - }, - "AuthorizationPolicy": { - "type": "object", - "properties": { - "allowedIps": { - "allOf": [ - { - "$ref": "#/components/schemas/AllowedIps" - } - ], - "description": "Lista dozwolonych adresów IP.", - "nullable": true - } - }, - "additionalProperties": false - }, - "BatchFileInfo": { - "required": [ - "fileHash", - "fileParts", - "fileSize" - ], - "type": "object", - "properties": { - "fileSize": { - "maximum": 5000000000, - "minimum": 1, - "type": "integer", - "description": "Rozmiar pliku paczki w bajtach. Maksymalny rozmiar paczki to 5GB.", - "format": "int64" - }, - "fileHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 pliku paczki, zakodowany w formacie Base64." - }, - "fileParts": { - "maxItems": 50, - "minItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/BatchFilePartInfo" - }, - "description": "Informacje o częściach pliku paczki. Maksymalna liczba części to 50. Maksymalny dozwolony rozmiar części przed zaszyfrowaniem to 100MB." - } - }, - "additionalProperties": false - }, - "BatchFilePartInfo": { - "required": [ - "fileHash", - "fileSize", - "ordinalNumber" - ], - "type": "object", - "properties": { - "ordinalNumber": { - "minimum": 1, - "type": "integer", - "description": "Numer sekwencyjny części pliku paczki.", - "format": "int32" - }, - "fileSize": { - "minimum": 1, - "type": "integer", - "description": "Rozmiar zaszyfrowanej części pliku paczki w bajtach.", - "format": "int64" - }, - "fileHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 zaszyfrowanej części pliku paczki, zakodowany w formacie Base64." - } - }, - "additionalProperties": false - }, - "BatchSessionContextLimitsOverride": { - "required": [ - "maxInvoices", - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB" - ], - "type": "object", - "properties": { - "maxInvoiceSizeInMB": { - "maximum": 5, - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury w MB.", - "format": "int32" - }, - "maxInvoiceWithAttachmentSizeInMB": { - "maximum": 10, - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", - "format": "int32" - }, - "maxInvoices": { - "maximum": 100000, - "minimum": 0, - "type": "integer", - "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "BatchSessionEffectiveContextLimits": { - "required": [ - "maxInvoices", - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB" - ], - "type": "object", - "properties": { - "maxInvoiceSizeInMB": { - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury w MB.", - "format": "int32" - }, - "maxInvoiceWithAttachmentSizeInMB": { - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", - "format": "int32" - }, - "maxInvoices": { - "minimum": 0, - "type": "integer", - "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "BuyerIdentifierType": { - "enum": [ - "Nip", - "VatUe", - "Other", - "None" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora nabywcy |\n" - }, - "CertificateEffectiveSubjectLimits": { - "type": "object", - "properties": { - "maxCertificates": { - "type": "integer", - "format": "int32" - } - }, - "additionalProperties": false - }, - "CertificateEnrollmentDataResponse": { - "required": [ - "commonName", - "countryName" - ], - "type": "object", - "properties": { - "commonName": { - "type": "string", - "description": "Nazwa powszechna." - }, - "countryName": { - "type": "string", - "description": "Kraj, kod ISO 3166." - }, - "givenName": { - "type": "string", - "description": "Imię.", - "nullable": true - }, - "surname": { - "type": "string", - "description": "Nazwisko.", - "nullable": true - }, - "serialNumber": { - "type": "string", - "description": "Numer seryjny podmiotu.", - "nullable": true - }, - "uniqueIdentifier": { - "type": "string", - "description": "Unikalny identyfikator.", - "nullable": true - }, - "organizationName": { - "type": "string", - "description": "Nazwa organizacji.", - "nullable": true - }, - "organizationIdentifier": { - "type": "string", - "description": "Identyfikator organizacji.", - "nullable": true - } - }, - "additionalProperties": false - }, - "CertificateEnrollmentStatusResponse": { - "required": [ - "requestDate", - "status" - ], - "type": "object", - "properties": { - "requestDate": { - "type": "string", - "description": "Data złożenia wniosku certyfikacyjnego.", - "format": "date-time" - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/StatusInfo" - } - ], - "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Wniosek przyjęty do realizacji | - |\n| 200 | Wniosek obsłużony (certyfikat wygenerowany) | - |\n| 400 | Wniosek odrzucony | Klucz publiczny został już certyfikowany przez inny podmiot. |\n| 400 | Wniosek odrzucony | Osiągnięto dopuszczalny limit posiadanych certyfikatów. |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" - }, - "certificateSerialNumber": { - "type": "string", - "description": "Numer seryjny wygenerowanego certyfikatu (w formacie szesnastkowym). \nZwracany w przypadku prawidłowego przeprocesowania wniosku certyfikacyjnego.", - "nullable": true - } - }, - "additionalProperties": false - }, - "CertificateLimit": { - "required": [ - "limit", - "remaining" - ], - "type": "object", - "properties": { - "remaining": { - "type": "integer", - "description": "Pozostała wartość limitu.", - "format": "int32" - }, - "limit": { - "type": "integer", - "description": "Maksymalna liczba zasobów dozwolona w ramach limitu.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "CertificateLimitsResponse": { - "required": [ - "canRequest", - "certificate", - "enrollment" - ], - "type": "object", - "properties": { - "canRequest": { - "type": "boolean", - "description": "Flaga informująca czy uwierzytelniony podmiot może złożyć nowy wniosek o certyfikat.", - "readOnly": true - }, - "enrollment": { - "required": [ - "remaining", - "limit" - ], - "allOf": [ - { - "$ref": "#/components/schemas/CertificateLimit" - } - ], - "description": "Informacje o limitach związanych z liczbą możliwych do złożenia wniosków certyfikacyjnych." - }, - "certificate": { - "required": [ - "remaining", - "limit" - ], - "allOf": [ - { - "$ref": "#/components/schemas/CertificateLimit" - } - ], - "description": "Informacje o limitach dotyczących liczby aktywnych certyfikatów wydanych dla danego podmiotu." - } - }, - "additionalProperties": false, - "description": "Informacje o limitach wniosków oraz certyfikatów dla uwierzytelnionego podmiotu." - }, - "CertificateListItem": { - "required": [ - "certificateSerialNumber", - "commonName", - "name", - "requestDate", - "status", - "subjectIdentifier", - "type", - "validFrom", - "validTo" - ], - "type": "object", - "properties": { - "certificateSerialNumber": { - "type": "string", - "description": "Numer seryjny certyfikatu (w formacie szesnastkowym)." - }, - "name": { - "maxLength": 100, - "type": "string", - "description": "Nazwa własna certyfikatu." - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/KsefCertificateType" - } - ], - "description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" - }, - "commonName": { - "type": "string", - "description": "Nazwa powszechna (CN) podmiotu, dla którego wystawiono certyfikat." - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/CertificateListItemStatus" - } - ], - "description": "Status certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n" - }, - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/CertificateSubjectIdentifier" - } - ], - "description": "Identyfikator podmiotu, dla którego wystawiono certyfikat." - }, - "validFrom": { - "type": "string", - "description": "Data rozpoczęcia ważności certyfikatu.", - "format": "date-time" - }, - "validTo": { - "type": "string", - "description": "Data wygaśnięcia certyfikatu.", - "format": "date-time" - }, - "lastUseDate": { - "type": "string", - "description": "Data ostatniego użycia certyfikatu.", - "format": "date-time", - "nullable": true - }, - "requestDate": { - "type": "string", - "description": "Data złożenia wniosku certyfikacyjnego.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "CertificateListItemStatus": { - "enum": [ - "Active", - "Blocked", - "Revoked", - "Expired" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n" - }, - "CertificateRevocationReason": { - "enum": [ - "Unspecified", - "Superseded", - "KeyCompromise" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Unspecified | Nieokreślony. |\n| Superseded | Certyfikat został zastąpiony przez inny. |\n| KeyCompromise | Klucz prywatny powiązany z certyfikatem został skompromitowany. |\n" - }, - "CertificateSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/CertificateSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu dla którego wystawiono certyfikat.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "CertificateSubjectIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "CertificateSubjectLimitsOverride": { - "type": "object", - "properties": { - "maxCertificates": { - "minimum": 0, - "type": "integer", - "format": "int32", - "nullable": true - } - }, - "additionalProperties": false - }, - "Challenge": { - "maxLength": 36, - "minLength": 36, - "type": "string", - "description": "Unikalny challenge." - }, - "CheckAttachmentPermissionStatusResponse": { - "type": "object", - "properties": { - "isAttachmentAllowed": { - "type": "boolean", - "description": "Informacja czy Podmiot ma obecnie możliwość dodawania Załączników do Faktur" - }, - "revokedDate": { - "type": "string", - "description": "Data i czas zakończenia możliwość dodawania przez Podmiot Załączników do Faktur.\nBrak podanej daty oznacza bezterminową możliwość dodawania Załączników do Faktur", - "format": "date-time", - "nullable": true - } - }, - "additionalProperties": false - }, - "CommonSessionStatus": { - "enum": [ - "InProgress", - "Succeeded", - "Failed", - "Cancelled" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| InProgress | Sesja aktywna. |\n| Succeeded | Sesja przetworzona poprawnie. W trakcie przetwarzania sesji nie wystąpiły żadne błędy, ale część faktur nadal mogła zostać odrzucona. |\n| Failed | Sesja nie przetworzona z powodu błędów. Na etapie rozpoczynania lub kończenia sesji wystąpiły błędy, które nie pozwoliły na jej poprawne przetworzenie. |\n| Cancelled | Sesja anulowania. Został przekroczony czas na wysyłkę w sesji wsadowej, lub nie przesłano żadnych faktur w sesji interaktywnej. |\n" - }, - "CurrencyCode": { - "enum": [ - "AED", - "AFN", - "ALL", - "AMD", - "ANG", - "AOA", - "ARS", - "AUD", - "AWG", - "AZN", - "BAM", - "BBD", - "BDT", - "BGN", - "BHD", - "BIF", - "BMD", - "BND", - "BOB", - "BOV", - "BRL", - "BSD", - "BTN", - "BWP", - "BYN", - "BZD", - "CAD", - "CDF", - "CHE", - "CHF", - "CHW", - "CLF", - "CLP", - "CNY", - "COP", - "COU", - "CRC", - "CUC", - "CUP", - "CVE", - "CZK", - "DJF", - "DKK", - "DOP", - "DZD", - "EGP", - "ERN", - "ETB", - "EUR", - "FJD", - "FKP", - "GBP", - "GEL", - "GGP", - "GHS", - "GIP", - "GMD", - "GNF", - "GTQ", - "GYD", - "HKD", - "HNL", - "HRK", - "HTG", - "HUF", - "IDR", - "ILS", - "IMP", - "INR", - "IQD", - "IRR", - "ISK", - "JEP", - "JMD", - "JOD", - "JPY", - "KES", - "KGS", - "KHR", - "KMF", - "KPW", - "KRW", - "KWD", - "KYD", - "KZT", - "LAK", - "LBP", - "LKR", - "LRD", - "LSL", - "LYD", - "MAD", - "MDL", - "MGA", - "MKD", - "MMK", - "MNT", - "MOP", - "MRU", - "MUR", - "MVR", - "MWK", - "MXN", - "MXV", - "MYR", - "MZN", - "NAD", - "NGN", - "NIO", - "NOK", - "NPR", - "NZD", - "OMR", - "PAB", - "PEN", - "PGK", - "PHP", - "PKR", - "PLN", - "PYG", - "QAR", - "RON", - "RSD", - "RUB", - "RWF", - "SAR", - "SBD", - "SCR", - "SDG", - "SEK", - "SGD", - "SHP", - "SLL", - "SOS", - "SRD", - "SSP", - "STN", - "SVC", - "SYP", - "SZL", - "THB", - "TJS", - "TMT", - "TND", - "TOP", - "TRY", - "TTD", - "TWD", - "TZS", - "UAH", - "UGX", - "USD", - "USN", - "UYI", - "UYU", - "UYW", - "UZS", - "VES", - "VND", - "VUV", - "WST", - "XAF", - "XAG", - "XAU", - "XBA", - "XBB", - "XBC", - "XBD", - "XCD", - "XCG", - "XDR", - "XOF", - "XPD", - "XPF", - "XPT", - "XSU", - "XUA", - "XXX", - "YER", - "ZAR", - "ZMW", - "ZWL" - ], - "type": "string" - }, - "EffectiveApiRateLimitValues": { - "required": [ - "perHour", - "perMinute", - "perSecond" - ], - "type": "object", - "properties": { - "perSecond": { - "type": "integer", - "description": "Limit na sekundę.", - "format": "int32" - }, - "perMinute": { - "type": "integer", - "description": "Limit na minutę.", - "format": "int32" - }, - "perHour": { - "type": "integer", - "description": "Limit na godzinę.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "EffectiveApiRateLimits": { - "required": [ - "batchSession", - "invoiceDownload", - "invoiceExport", - "invoiceExportStatus", - "invoiceMetadata", - "invoiceSend", - "invoiceStatus", - "onlineSession", - "other", - "sessionInvoiceList", - "sessionList", - "sessionMisc" - ], - "type": "object", - "properties": { - "onlineSession": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla otwierania/zamykania sesji interaktywnych." - }, - "batchSession": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla otwierania/zamykania sesji wsadowych." - }, - "invoiceSend": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla wysyłki faktur." - }, - "invoiceStatus": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pobierania statusu faktury z sesji." - }, - "sessionList": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pobierania listy sesji." - }, - "sessionInvoiceList": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pobierania listy faktur w sesji." - }, - "sessionMisc": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pozostałych operacji w ramach sesji." - }, - "invoiceMetadata": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pobierania metadanych faktur." - }, - "invoiceExport": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla eksportu paczki faktur." - }, - "invoiceExportStatus": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pobierana statusu eksportu paczki faktur." - }, - "invoiceDownload": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pobierania faktur po numerze KSeF." - }, - "other": { - "required": [ - "perSecond", - "perMinute", - "perHour" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EffectiveApiRateLimitValues" - } - ], - "description": "Limity dla pozostałych operacji API." - } - }, - "additionalProperties": false - }, - "EffectiveContextLimits": { - "required": [ - "batchSession", - "onlineSession" - ], - "type": "object", - "properties": { - "onlineSession": { - "required": [ - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB", - "maxInvoices" - ], - "allOf": [ - { - "$ref": "#/components/schemas/OnlineSessionEffectiveContextLimits" - } - ], - "description": "Limity dla sesji interaktywnych." - }, - "batchSession": { - "required": [ - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB", - "maxInvoices" - ], - "allOf": [ - { - "$ref": "#/components/schemas/BatchSessionEffectiveContextLimits" - } - ], - "description": "Limity dla sesji wsadowych." - } - }, - "additionalProperties": false - }, - "EffectiveSubjectLimits": { - "type": "object", - "properties": { - "enrollment": { - "allOf": [ - { - "$ref": "#/components/schemas/EnrollmentEffectiveSubjectLimits" - } - ], - "nullable": true - }, - "certificate": { - "allOf": [ - { - "$ref": "#/components/schemas/CertificateEffectiveSubjectLimits" - } - ], - "nullable": true - } - }, - "additionalProperties": false - }, - "EncryptionInfo": { - "required": [ - "encryptedSymmetricKey", - "initializationVector" - ], - "type": "object", - "properties": { - "encryptedSymmetricKey": { - "type": "string", - "description": "Klucz symetryczny o długości 32 bajtów, zaszyfrowany algorytmem RSA (Padding: OAEP z SHA-256), zakodowany w formacie Base64.\n\n[Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)", - "format": "byte" - }, - "initializationVector": { - "type": "string", - "description": "Wektor inicjalizujący (IV) o długości 16 bajtów, używany do szyfrowania symetrycznego, zakodowany w formacie Base64.", - "format": "byte" - } - }, - "additionalProperties": false - }, - "EnrollCertificateRequest": { - "required": [ - "certificateName", - "certificateType", - "csr" - ], - "type": "object", - "properties": { - "certificateName": { - "maxLength": 100, - "minLength": 5, - "pattern": "^[a-zA-Z0-9_\\-\\ ąćęłńóśźżĄĆĘŁŃÓŚŹŻ]+$", - "type": "string", - "description": "Nazwa własna certyfikatu." - }, - "certificateType": { - "allOf": [ - { - "$ref": "#/components/schemas/KsefCertificateType" - } - ], - "description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" - }, - "csr": { - "type": "string", - "description": "Wniosek certyfikacyjny PKCS#10 (CSR) w formacie DER, zakodowany w formacie Base64.", - "format": "byte" - }, - "validFrom": { - "type": "string", - "description": "Data rozpoczęcia ważności certyfikatu.\nJeśli nie zostanie podana, certyfikat będzie ważny od momentu jego wystawienia.", - "format": "date-time", - "nullable": true - } - }, - "additionalProperties": false - }, - "EnrollCertificateResponse": { - "required": [ - "referenceNumber", - "timestamp" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny wniosku certyfikacyjnego." - }, - "timestamp": { - "type": "string", - "description": "Data złożenia wniosku certyfikacyjnego.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "EnrollmentEffectiveSubjectLimits": { - "type": "object", - "properties": { - "maxEnrollments": { - "type": "integer", - "format": "int32" - } - }, - "additionalProperties": false - }, - "EnrollmentSubjectLimitsOverride": { - "type": "object", - "properties": { - "maxEnrollments": { - "minimum": 0, - "type": "integer", - "format": "int32", - "nullable": true - } - }, - "additionalProperties": false - }, - "EntityAuthorizationGrant": { - "required": [ - "authorizationScope", - "authorizedEntityIdentifier", - "authorizingEntityIdentifier", - "description", - "id", - "startDate" - ], - "type": "object", - "properties": { - "id": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionId" - } - ], - "description": "Identyfikator uprawnienia." - }, - "authorIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorIdentifier" - } - ], - "description": "Identyfikator osoby nadającej uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |", - "nullable": true - }, - "authorizedEntityIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" - }, - "authorizingEntityIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "authorizationScope": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoicePermissionType" - } - ], - "description": "Rodzaj uprawnienia." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia." - }, - "subjectEntityDetails": { - "required": [ - "subjectDetailsType", - "fullName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectEntityByIdentifierDetails" - } - ], - "description": "Dane podmiotu uprawnionego.", - "nullable": true - }, - "startDate": { - "type": "string", - "description": "Data rozpoczęcia obowiązywania uprawnienia.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "EntityAuthorizationPermissionType": { - "enum": [ - "SelfInvoicing", - "RRInvoicing", - "TaxRepresentative", - "PefInvoicing" - ], - "type": "string" - }, - "EntityAuthorizationPermissionsGrantRequest": { - "required": [ - "description", - "permission", - "subjectDetails", - "subjectIdentifier" - ], - "type": "object", - "properties": { - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationPermissionsSubjectIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" - }, - "permission": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationPermissionType" - } - ], - "description": "Rodzaj uprawnienia." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia" - }, - "subjectDetails": { - "required": [ - "fullName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityDetails" - } - ], - "description": "Dane podmiotu, któremu nadawane są uprawnienia." - } - }, - "additionalProperties": false - }, - "EntityAuthorizationPermissionsQueryRequest": { - "required": [ - "queryType" - ], - "type": "object", - "properties": { - "authorizingIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", - "nullable": true - }, - "authorizedIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |", - "nullable": true - }, - "queryType": { - "allOf": [ - { - "$ref": "#/components/schemas/QueryType" - } - ], - "description": "Typ zapytania.\n| Type | Value |\n| --- | --- |\n| Granted | Uprawnienia nadane innym podmiotom |\n| Received | Uprawnienia otrzymane od innych podmiotów |" - }, - "permissionTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InvoicePermissionType" - }, - "description": "Lista rodzajów wyszukiwanych uprawnień.", - "nullable": true - } - }, - "additionalProperties": false - }, - "EntityAuthorizationPermissionsSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 10, - "minLength": 9, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" - }, - "EntityAuthorizationPermissionsSubjectIdentifierType": { - "enum": [ - "Nip", - "PeppolId" - ], - "type": "string" - }, - "EntityAuthorizationsAuthorIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator osoby nadającej uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "EntityAuthorizationsAuthorIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "EntityAuthorizationsAuthorizedEntityIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 10, - "minLength": 9, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |" - }, - "EntityAuthorizationsAuthorizedEntityIdentifierType": { - "enum": [ - "Nip", - "PeppolId" - ], - "type": "string" - }, - "EntityAuthorizationsAuthorizingEntityIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 10, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "EntityAuthorizationsAuthorizingEntityIdentifierType": { - "enum": [ - "Nip" - ], - "type": "string" - }, - "EntityByFingerprintDetails": { - "required": [ - "address", - "fullName" - ], - "type": "object", - "properties": { - "fullName": { - "maxLength": 100, - "type": "string", - "description": "Pełna nazwa podmiotu." - }, - "address": { - "maxLength": 512, - "type": "string", - "description": "Adres podmiotu." - } - }, - "additionalProperties": false - }, - "EntityDetails": { - "required": [ - "fullName" - ], - "type": "object", - "properties": { - "fullName": { - "maxLength": 90, - "minLength": 5, - "type": "string", - "description": "Pełna nazwa podmiotu." - } - }, - "additionalProperties": false - }, - "EntityPermission": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityPermissionType" - } - ], - "description": "Rodzaj uprawnienia." - }, - "canDelegate": { - "type": "boolean", - "description": "Flaga pozwalająca na pośrednie przekazywanie danego uprawnienia" - } - }, - "additionalProperties": false - }, - "EntityPermissionType": { - "enum": [ - "InvoiceWrite", - "InvoiceRead" - ], - "type": "string" - }, - "EntityPermissionsGrantRequest": { - "required": [ - "description", - "permissions", - "subjectDetails", - "subjectIdentifier" - ], - "type": "object", - "properties": { - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityPermissionsSubjectIdentifier" - } - ], - "description": "Identyfikator podmiotu.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EntityPermission" - }, - "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia" - }, - "subjectDetails": { - "required": [ - "fullName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityDetails" - } - ], - "description": "Dane podmiotu, któremu nadawane są uprawnienia." - } - }, - "additionalProperties": false - }, - "EntityPermissionsSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 10, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "EntityPermissionsSubjectIdentifierType": { - "enum": [ - "Nip" - ], - "type": "string" - }, - "EntityPermissionsSubordinateEntityIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityPermissionsSubordinateEntityIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 10, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "EntityPermissionsSubordinateEntityIdentifierType": { - "enum": [ - "Nip" - ], - "type": "string" - }, - "EntityRole": { - "required": [ - "description", - "role", - "startDate" - ], - "type": "object", - "properties": { - "parentEntityIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityRolesParentEntityIdentifier" - } - ], - "description": "Identyfikator podmiotu nadrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", - "nullable": true - }, - "role": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityRoleType" - } - ], - "description": "Typ roli - powiązania z podmiotem nadrzędnym." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis roli." - }, - "startDate": { - "type": "string", - "description": "Data rozpoczęcia obowiązywania roli.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "EntityRoleType": { - "enum": [ - "CourtBailiff", - "EnforcementAuthority", - "LocalGovernmentUnit", - "LocalGovernmentSubUnit", - "VatGroupUnit", - "VatGroupSubUnit" - ], - "type": "string" - }, - "EntityRolesParentEntityIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EntityRolesParentEntityIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 10, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu nadrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "EntityRolesParentEntityIdentifierType": { - "enum": [ - "Nip" - ], - "type": "string" - }, - "EntitySubjectByFingerprintDetailsType": { - "enum": [ - "EntityByFingerprint" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" - }, - "EntitySubjectByIdentifierDetailsType": { - "enum": [ - "EntityByIdentifier" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n" - }, - "EntitySubjectDetailsType": { - "enum": [ - "EntityByIdentifier", - "EntityByFingerprint" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" - }, - "EuEntityAdministrationPermissionsContextIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityAdministrationPermissionsContextIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 25, - "minLength": 15, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator kontekstu złożonego.\n| Type | Value |\n| --- | --- |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}` |" - }, - "EuEntityAdministrationPermissionsContextIdentifierType": { - "enum": [ - "NipVatUe" - ], - "type": "string" - }, - "EuEntityAdministrationPermissionsGrantRequest": { - "required": [ - "contextIdentifier", - "description", - "euEntityDetails", - "euEntityName", - "subjectDetails", - "subjectIdentifier" - ], - "type": "object", - "properties": { - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityAdministrationPermissionsSubjectIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityAdministrationPermissionsContextIdentifier" - } - ], - "description": "Identyfikator kontekstu złożonego.\n| Type | Value |\n| --- | --- |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}` |" - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia" - }, - "euEntityName": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Nazwa i adres podmiotu unijnego w formacie: \n`{euSubjectName}, {euSubjectAddress}`" - }, - "subjectDetails": { - "required": [ - "subjectDetailsType" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionSubjectDetails" - } - ], - "description": "Dane podmiotu, któremu nadawane są uprawnienia." - }, - "euEntityDetails": { - "required": [ - "fullName", - "address" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityDetails" - } - ], - "description": "Dane podmiotu unijnego, w kontekście którego nadawane są uprawnienia." - } - }, - "additionalProperties": false - }, - "EuEntityAdministrationPermissionsSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityAdministrationPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 64, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "EuEntityAdministrationPermissionsSubjectIdentifierType": { - "enum": [ - "Fingerprint" - ], - "type": "string" - }, - "EuEntityDetails": { - "required": [ - "address", - "fullName" - ], - "type": "object", - "properties": { - "fullName": { - "maxLength": 100, - "type": "string", - "description": "Pełna nazwa podmiotu." - }, - "address": { - "maxLength": 512, - "type": "string", - "description": "Adres podmiotu." - } - }, - "additionalProperties": false - }, - "EuEntityPermission": { - "required": [ - "authorIdentifier", - "authorizedFingerprintIdentifier", - "description", - "euEntityName", - "id", - "permissionScope", - "startDate", - "vatUeIdentifier" - ], - "type": "object", - "properties": { - "id": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionId" - } - ], - "description": "Identyfikator uprawnienia." - }, - "authorIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionsAuthorIdentifier" - } - ], - "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "vatUeIdentifier": { - "type": "string", - "description": "Identyfikator podmiotu unijnego." - }, - "euEntityName": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Nazwa podmiotu unijnego." - }, - "authorizedFingerprintIdentifier": { - "maxLength": 64, - "minLength": 64, - "type": "string", - "description": "Uprawniony odcisk palca certyfikatu." - }, - "permissionScope": { - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionsQueryPermissionType" - } - ], - "description": "Uprawnienie." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia." - }, - "subjectPersonDetails": { - "required": [ - "subjectDetailsType", - "firstName", - "lastName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectPersonByFingerprintDetails" - } - ], - "description": "Dane osoby uprawnionej.", - "nullable": true - }, - "subjectEntityDetails": { - "required": [ - "subjectDetailsType", - "fullName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectEntityByFingerprintDetails" - } - ], - "description": "Dane podmiotu uprawnionego.", - "nullable": true - }, - "euEntityDetails": { - "required": [ - "fullName", - "address" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsEuEntityDetails" - } - ], - "description": "Dane podmiotu unijnego, w kontekście którego nadane jest uprawnienie.", - "nullable": true - }, - "startDate": { - "type": "string", - "description": "Data rozpoczęcia obowiązywania uprawnienia.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "EuEntityPermissionSubjectDetails": { - "required": [ - "subjectDetailsType" - ], - "type": "object", - "properties": { - "subjectDetailsType": { - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionSubjectDetailsType" - } - ], - "description": "Typ danych podmiotu.\n| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" - }, - "personByFpWithId": { - "required": [ - "firstName", - "lastName", - "identifier" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonByFingerprintWithIdentifierDetails" - } - ], - "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithIdentifier.*", - "nullable": true - }, - "personByFpNoId": { - "required": [ - "firstName", - "lastName", - "birthDate", - "idDocument" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonByFingerprintWithoutIdentifierDetails" - } - ], - "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithoutIdentifier.*", - "nullable": true - }, - "entityByFp": { - "required": [ - "fullName", - "address" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityByFingerprintDetails" - } - ], - "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = EntityByFingerprint.*", - "nullable": true - } - }, - "additionalProperties": false - }, - "EuEntityPermissionSubjectDetailsType": { - "enum": [ - "PersonByFingerprintWithIdentifier", - "PersonByFingerprintWithoutIdentifier", - "EntityByFingerprint" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" - }, - "EuEntityPermissionType": { - "enum": [ - "InvoiceWrite", - "InvoiceRead" - ], - "type": "string" - }, - "EuEntityPermissionsAuthorIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionsAuthorIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "EuEntityPermissionsAuthorIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "EuEntityPermissionsGrantRequest": { - "required": [ - "description", - "permissions", - "subjectDetails", - "subjectIdentifier" - ], - "type": "object", - "properties": { - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionsSubjectIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EuEntityPermissionType" - }, - "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia" - }, - "subjectDetails": { - "required": [ - "subjectDetailsType" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionSubjectDetails" - } - ], - "description": "Dane podmiotu, któremu nadawane są uprawnienia." - } - }, - "additionalProperties": false - }, - "EuEntityPermissionsQueryPermissionType": { - "enum": [ - "VatUeManage", - "InvoiceWrite", - "InvoiceRead", - "Introspection" - ], - "type": "string" - }, - "EuEntityPermissionsQueryRequest": { - "type": "object", - "properties": { - "vatUeIdentifier": { - "pattern": "^(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))$", - "type": "string", - "description": "Wartość identyfikatora (numeru identyfikacyjnego VAT) podmiotu unijnego (exact match).", - "nullable": true - }, - "authorizedFingerprintIdentifier": { - "type": "string", - "description": "Odcisk palca certyfikatu kwalifikowanego uprawnionego (contains).", - "nullable": true - }, - "permissionTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EuEntityPermissionsQueryPermissionType" - }, - "description": "Lista rodzajów wyszukiwanych uprawnień.", - "nullable": true - } - }, - "additionalProperties": false - }, - "EuEntityPermissionsSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/EuEntityPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 64, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "EuEntityPermissionsSubjectIdentifierType": { - "enum": [ - "Fingerprint" - ], - "type": "string" - }, - "ExceptionDetails": { - "type": "object", - "properties": { - "exceptionCode": { - "type": "integer", - "format": "int32" - }, - "exceptionDescription": { - "type": "string", - "nullable": true - }, - "details": { - "type": "array", - "items": { - "type": "string" - }, - "nullable": true - } - }, - "additionalProperties": false - }, - "ExceptionInfo": { - "type": "object", - "properties": { - "exceptionDetailList": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExceptionDetails" - }, - "nullable": true - }, - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "nullable": true - }, - "serviceCode": { - "type": "string", - "nullable": true - }, - "serviceCtx": { - "type": "string", - "nullable": true - }, - "serviceName": { - "type": "string", - "nullable": true - }, - "timestamp": { - "type": "string", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "ExceptionResponse": { - "type": "object", - "properties": { - "exception": { - "allOf": [ - { - "$ref": "#/components/schemas/ExceptionInfo" - } - ], - "nullable": true - } - }, - "additionalProperties": false, - "example": { - "exception": { - "exceptionDetailList": [ - { - "exceptionCode": 12345, - "exceptionDescription": "Opis błędu.", - "details": [ - "Opcjonalne dodatkowe szczegóły błędu." - ] - } - ], - "referenceNumber": "a1b2c3d4-e5f6-4789-ab12-cd34ef567890", - "serviceCode": "00-c02cc3747020c605be02159bf3324f0e-eee7647dc67aa74a-00", - "serviceCtx": "srvABCDA", - "serviceName": "Undefined", - "timestamp": "2025-10-11T12:23:56.0154302" - } - } - }, - "ExportInvoicesResponse": { - "required": [ - "referenceNumber" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny eksportu faktur." - } - }, - "additionalProperties": false - }, - "FormCode": { - "required": [ - "schemaVersion", - "systemCode", - "value" - ], - "type": "object", - "properties": { - "systemCode": { - "type": "string", - "description": "Kod systemowy" - }, - "schemaVersion": { - "type": "string", - "description": "Wersja schematu" - }, - "value": { - "type": "string", - "description": "Wartość" - } - }, - "additionalProperties": false - }, - "GenerateTokenRequest": { - "required": [ - "description", - "permissions" - ], - "type": "object", - "properties": { - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TokenPermissionType" - }, - "description": "Uprawnienia przypisane tokenowi." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis tokena." - } - }, - "additionalProperties": false - }, - "GenerateTokenResponse": { - "required": [ - "referenceNumber", - "token" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny tokena KSeF." - }, - "token": { - "maxLength": 160, - "type": "string", - "description": "Token KSeF." - } - }, - "additionalProperties": false - }, - "IdDocument": { - "required": [ - "country", - "number", - "type" - ], - "type": "object", - "properties": { - "type": { - "maxLength": 20, - "type": "string", - "description": "Rodzaj dokumentu tożsamości." - }, - "number": { - "maxLength": 20, - "type": "string", - "description": "Seria i numer dokumentu tożsamości." - }, - "country": { - "maxLength": 2, - "minLength": 2, - "type": "string", - "description": "Kraj wydania dokumentu tożsamości. Musi być zgodny z ISO 3166-1 alpha-2 (np. PL, DE, US) oraz zawierać dokładnie 2 wielkie litery." - } - }, - "additionalProperties": false, - "description": "Dane dokumentu tożsamości osoby fizycznej." - }, - "IndirectPermissionType": { - "enum": [ - "InvoiceRead", - "InvoiceWrite" - ], - "type": "string" - }, - "IndirectPermissionsGrantRequest": { - "required": [ - "description", - "permissions", - "subjectDetails", - "subjectIdentifier" - ], - "type": "object", - "properties": { - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/IndirectPermissionsSubjectIdentifier" - } - ], - "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "targetIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/IndirectPermissionsTargetIdentifier" - } - ], - "description": "Identyfikator kontekstu klienta. Nie przekazanie identyfikatora oznacza, że uprawnienie nadane w sposób pośredni jest typu generalnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IndirectPermissionType" - }, - "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia" - }, - "subjectDetails": { - "required": [ - "subjectDetailsType" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionSubjectDetails" - } - ], - "description": "Dane podmiotu, któremu nadawane są uprawnienia." - } - }, - "additionalProperties": false - }, - "IndirectPermissionsSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/IndirectPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "IndirectPermissionsSubjectIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "IndirectPermissionsTargetIdentifier": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/IndirectPermissionsTargetIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 16, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", - "nullable": true - } - }, - "additionalProperties": false, - "description": "Identyfikator kontekstu klienta. Nie przekazanie identyfikatora oznacza, że uprawnienie nadane w sposób pośredni jest typu generalnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" - }, - "IndirectPermissionsTargetIdentifierType": { - "enum": [ - "Nip", - "AllPartners", - "InternalId" - ], - "type": "string" - }, - "InitTokenAuthenticationRequest": { - "required": [ - "challenge", - "contextIdentifier", - "encryptedToken" - ], - "type": "object", - "properties": { - "challenge": { - "allOf": [ - { - "$ref": "#/components/schemas/Challenge" - } - ], - "description": "Wygenerowany wcześniej challenge." - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/AuthenticationContextIdentifier" - } - ], - "description": "Identyfikator kontekstu do którego następuje uwierzytelnienie." - }, - "encryptedToken": { - "type": "string", - "description": "Zaszyfrowany token wraz z timestampem z challenge'a, w postaci `token|timestamp`, zakodowany w formacie Base64.", - "format": "byte" - }, - "authorizationPolicy": { - "allOf": [ - { - "$ref": "#/components/schemas/AuthorizationPolicy" - } - ], - "description": "Polityka autoryzacji żądań przy każdym użyciu tokena dostępu.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InternalId": { - "maxLength": 16, - "minLength": 16, - "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}-\\d{5}$", - "type": "string", - "description": "Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr." - }, - "InvoiceExportRequest": { - "required": [ - "encryption", - "filters" - ], - "type": "object", - "properties": { - "encryption": { - "required": [ - "encryptedSymmetricKey", - "initializationVector" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EncryptionInfo" - } - ], - "description": "Informacje wymagane do zaszyfrowania wyniku zapytania." - }, - "filters": { - "required": [ - "subjectType", - "dateRange" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQueryFilters" - } - ], - "description": "Zestaw filtrów do wyszukiwania faktur." - } - }, - "additionalProperties": false - }, - "InvoiceExportStatusResponse": { - "required": [ - "status" - ], - "type": "object", - "properties": { - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/StatusInfo" - } - ], - "description": "Status eksportu.\n\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Eksport faktur w toku | - |\n| 200 | Eksport faktur zakończony sukcesem | - |\n| 210 | Eksport faktur wygasł i nie jest już dostępny do pobrania | - |\n| 415 | Błąd odszyfrowania dostarczonego klucza | - |\n| 420 | Zakres filtrowania wykracza poza dostępny zakres danych | Parametr dateRange.from jest późniejszy niż PermanentStorageHwmDate przy włączonym restrictToPermanentStorageHwmDate. |\n| 500 | Nieznany błąd ({statusCode}) | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |" - }, - "completedDate": { - "type": "string", - "description": "Data zakończenia przetwarzania żądania eksportu faktur.", - "format": "date-time", - "nullable": true - }, - "packageExpirationDate": { - "type": "string", - "description": "Data wygaśnięcia paczki faktur przygotowanej do pobrania.\nPo upływie tej daty paczka nie będzie już dostępna do pobrania.", - "format": "date-time", - "nullable": true - }, - "package": { - "required": [ - "invoiceCount", - "size", - "parts", - "isTruncated" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoicePackage" - } - ], - "description": "Dane paczki faktur przygotowanej do pobrania.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceMetadata": { - "required": [ - "acquisitionDate", - "buyer", - "currency", - "formCode", - "grossAmount", - "hasAttachment", - "invoiceHash", - "invoiceNumber", - "invoiceType", - "invoicingDate", - "invoicingMode", - "isSelfInvoicing", - "issueDate", - "ksefNumber", - "netAmount", - "permanentStorageDate", - "seller", - "vatAmount" - ], - "type": "object", - "properties": { - "ksefNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/KsefNumber" - } - ], - "description": "Numer KSeF faktury." - }, - "invoiceNumber": { - "maxLength": 256, - "type": "string", - "description": "Numer faktury nadany przez wystawcę." - }, - "issueDate": { - "type": "string", - "description": "Data wystawienia faktury.", - "format": "date" - }, - "invoicingDate": { - "type": "string", - "description": "Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania).", - "format": "date-time" - }, - "acquisitionDate": { - "type": "string", - "description": "Data nadania numeru KSeF.", - "format": "date-time" - }, - "permanentStorageDate": { - "type": "string", - "description": "Data trwałego zapisu faktury w repozytorium systemu KSeF.", - "format": "date-time" - }, - "seller": { - "required": [ - "nip" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceMetadataSeller" - } - ], - "description": "Dane identyfikujące sprzedawcę." - }, - "buyer": { - "required": [ - "identifier" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceMetadataBuyer" - } - ], - "description": "Dane identyfikujące nabywcę." - }, - "netAmount": { - "type": "number", - "description": "Łączna kwota netto.", - "format": "double" - }, - "grossAmount": { - "type": "number", - "description": "Łączna kwota brutto.", - "format": "double" - }, - "vatAmount": { - "type": "number", - "description": "Łączna kwota VAT.", - "format": "double" - }, - "currency": { - "maxLength": 3, - "minLength": 3, - "type": "string", - "description": "Kod waluty." - }, - "invoicingMode": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoicingMode" - } - ], - "description": "Tryb fakturowania (online/offline)." - }, - "invoiceType": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceType" - } - ], - "description": "Rodzaj faktury.\n| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n" - }, - "formCode": { - "required": [ - "systemCode", - "schemaVersion", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/FormCode" - } - ], - "description": "Struktura dokumentu faktury.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| [FA (2)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n| [PEF (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF(3)_v2-1.xsd) | 2-1 | PEF |\n| [PEF_KOR (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF_KOR(3)_v2-1.xsd) | 2-1 | PEF |\n| FA_RR (1) | 1-0E | RR |\n" - }, - "isSelfInvoicing": { - "type": "boolean", - "description": "Czy faktura została wystawiona w trybie samofakturowania." - }, - "hasAttachment": { - "type": "boolean", - "description": "Określa, czy faktura posiada załącznik." - }, - "invoiceHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 faktury, zakodowany w formacie Base64." - }, - "hashOfCorrectedInvoice": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 korygowanej faktury, zakodowany w formacie Base64.", - "nullable": true - }, - "thirdSubjects": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InvoiceMetadataThirdSubject" - }, - "description": "Lista podmiotów trzecich.", - "nullable": true - }, - "authorizedSubject": { - "required": [ - "nip", - "role" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceMetadataAuthorizedSubject" - } - ], - "description": "Podmiot upoważniony.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceMetadataAuthorizedSubject": { - "required": [ - "nip", - "role" - ], - "type": "object", - "properties": { - "nip": { - "allOf": [ - { - "$ref": "#/components/schemas/Nip" - } - ], - "description": "Nip podmiotu upoważnionego" - }, - "name": { - "maxLength": 512, - "type": "string", - "description": "Nazwa podmiotu upoważnionego.", - "nullable": true - }, - "role": { - "type": "integer", - "description": "Rola podmiotu upoważnionego.\n| Wartość | Opis |\n| ---- | --- |\n| 1 | Organ egzekucyjny - w przypadku, o którym mowa w art. 106c pkt 1 ustawy |\n| 2 | Komornik sądowy - w przypadku, o którym mowa w art. 106c pkt 2 ustawy |\n| 3 | Przedstawiciel podatkowy - w przypadku gdy na fakturze występują dane przedstawiciela podatkowego, o którym mowa w art. 18a - 18d ustawy |", - "format": "int32" - } - }, - "additionalProperties": false - }, - "InvoiceMetadataBuyer": { - "required": [ - "identifier" - ], - "type": "object", - "properties": { - "identifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceMetadataBuyerIdentifier" - } - ], - "description": "Identyfikator nabywcy.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator|\n| None | Brak identyfikatora nabywcy |" - }, - "name": { - "maxLength": 512, - "type": "string", - "description": "Nazwa nabywcy.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceMetadataBuyerIdentifier": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/BuyerIdentifierType" - } - ], - "description": "Typ identyfikatora nabywcy.\n| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora nabywcy |\n" - }, - "value": { - "maxLength": 50, - "type": "string", - "description": "Wartość identyfikatora nabywcy.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceMetadataSeller": { - "required": [ - "nip" - ], - "type": "object", - "properties": { - "nip": { - "allOf": [ - { - "$ref": "#/components/schemas/Nip" - } - ], - "description": "Nip sprzedawcy." - }, - "name": { - "maxLength": 512, - "type": "string", - "description": "Nazwa sprzedawcy.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceMetadataThirdSubject": { - "required": [ - "identifier", - "role" - ], - "type": "object", - "properties": { - "identifier": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceMetadataThirdSubjectIdentifier" - } - ] - }, - "name": { - "maxLength": 512, - "type": "string", - "description": "Nazwa podmiotu trzeciego.", - "nullable": true - }, - "role": { - "type": "integer", - "description": "Rola podmiotu trzeciego.\n| Wartość | Opis |\n| ---- | --- |\n| 0 | Inna rola |\n| 1 | Faktor - w przypadku gdy na fakturze występują dane faktora |\n| 2 | Odbiorca - w przypadku gdy na fakturze występują dane jednostek wewnętrznych, oddziałów, wyodrębnionych w ramach nabywcy, które same nie stanowią nabywcy w rozumieniu ustawy |\n| 3 | Podmiot pierwotny - w przypadku gdy na fakturze występują dane podmiotu będącego w stosunku do podatnika podmiotem przejętym lub przekształconym, który dokonywał dostawy lub świadczył usługę. Z wyłączeniem przypadków, o których mowa w art. 106j ust.2 pkt 3 ustawy, gdy dane te wykazywane są w części Podmiot1K |\n| 4 | Dodatkowy nabywca - w przypadku gdy na fakturze występują dane kolejnych (innych niż wymieniony w części Podmiot2) nabywców |\n| 5 | Wystawca faktury - w przypadku gdy na fakturze występują dane podmiotu wystawiającego fakturę w imieniu podatnika. Nie dotyczy przypadku, gdy wystawcą faktury jest nabywca |\n| 6 | Dokonujący płatności - w przypadku gdy na fakturze występują dane podmiotu regulującego zobowiązanie w miejsce nabywcy |\n| 7 | Jednostka samorządu terytorialnego - wystawca |\n| 8 | Jednostka samorządu terytorialnego - odbiorca |\n| 9 | Członek grupy VAT - wystawca |\n| 10 | Członek grupy VAT - odbiorca |\n| 11 | Pracownik |", - "format": "int32" - } - }, - "additionalProperties": false - }, - "InvoiceMetadataThirdSubjectIdentifier": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/ThirdSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora podmiotu trzeciego.\n| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr. |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora podmiotu trzeciego |\n" - }, - "value": { - "maxLength": 50, - "type": "string", - "description": "Wartość identyfikatora podmiotu trzeciego.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoicePackage": { - "required": [ - "invoiceCount", - "isTruncated", - "parts", - "size" - ], - "type": "object", - "properties": { - "invoiceCount": { - "maximum": 10000, - "minimum": 0, - "type": "integer", - "description": "Łączna liczba faktur w paczce.", - "format": "int64" - }, - "size": { - "minimum": 0, - "type": "integer", - "description": "Rozmiar paczki w bajtach.", - "format": "int64" - }, - "parts": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InvoicePackagePart" - }, - "description": "Lista dostępnych części paczki do pobrania." - }, - "isTruncated": { - "type": "boolean", - "description": "Określa, czy wynik eksportu został ucięty z powodu przekroczenia limitu liczby faktur lub wielkości paczki." - }, - "lastIssueDate": { - "type": "string", - "description": "Data wystawienia ostatniej faktury ujętej w paczce.\nPole występuje wyłącznie wtedy, gdy paczka została ucięta i eksport był filtrowany po typie daty `Issue`.", - "format": "date", - "nullable": true - }, - "lastInvoicingDate": { - "type": "string", - "description": "Data przyjęcia ostatniej faktury ujętej w paczce.\nPole występuje wyłącznie wtedy, gdy paczka została ucięta i eksport był filtrowany po typie daty `Invoicing`.", - "format": "date-time", - "nullable": true - }, - "lastPermanentStorageDate": { - "type": "string", - "description": "Data trwałego zapisu ostatniej faktury ujętej w paczce.\nPole występuje wyłącznie wtedy, gdy paczka została ucięta i eksport był filtrowany po typie daty `PermanentStorage`.", - "format": "date-time", - "nullable": true - }, - "permanentStorageHwmDate": { - "type": "string", - "description": "Dotyczy wyłącznie zapytań filtrowanych po typie daty PermanentStorage.\nJeśli zapytanie dotyczyło najnowszego okresu, wartość ta może być wartością nieznacznie skorygowaną względem górnej granicy podanej w warunkach zapytania.\nDla okresów starszych, będzie to zgodne z warunkami zapytania. \n\nSystem gwarantuje, że dane poniżej tej wartości są spójne i kompletne.\nPonowne zapytania obejmujące zakresem dane poniżej tego kroczącego znacznika czasu nie zwrócą w przyszłości innych wyników (np.dodatkowych faktur). \n\nDla dateType = Issue lub Invoicing – null.", - "format": "date-time", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoicePackagePart": { - "required": [ - "encryptedPartHash", - "encryptedPartSize", - "expirationDate", - "method", - "ordinalNumber", - "partHash", - "partName", - "partSize", - "url" - ], - "type": "object", - "properties": { - "ordinalNumber": { - "minimum": 1, - "type": "integer", - "description": "Numer sekwencyjny pliku części paczki.", - "format": "int32" - }, - "partName": { - "maxLength": 100, - "type": "string", - "description": "Nazwa pliku części paczki." - }, - "method": { - "type": "string", - "description": "Metoda HTTP, której należy użyć przy pobieraniu pliku." - }, - "url": { - "type": "string", - "description": "Adres URL, pod który należy wysłać żądanie pobrania części paczki.\nLink jest generowany dynamicznie w momencie odpytania o status operacji eksportu.\nNie podlega limitom API i nie wymaga przesyłania tokenu dostępowego przy pobraniu.\n\nOdpowiedź HTTP zawiera dodatkowe nagłówki:\n- `x-ms-meta-hash` – zaszyfrowanej części paczki, zakodowany w formacie Base64.", - "format": "uri" - }, - "partSize": { - "minimum": 1, - "type": "integer", - "description": "Rozmiar części paczki w bajtach.", - "format": "int64" - }, - "partHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 pliku części paczki, zakodowany w formacie Base64." - }, - "encryptedPartSize": { - "minimum": 1, - "type": "integer", - "description": "Rozmiar zaszyfrowanej części paczki w bajtach.", - "format": "int64" - }, - "encryptedPartHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 zaszyfrowanej części paczki, zakodowany w formacie Base64." - }, - "expirationDate": { - "type": "string", - "description": "Data i godzina wygaśnięcia linku umożliwiającego pobranie części paczki.\nPo upływie tego momentu link przestaje być aktywny.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "InvoicePermissionType": { - "enum": [ - "SelfInvoicing", - "TaxRepresentative", - "RRInvoicing", - "PefInvoicing" - ], - "type": "string" - }, - "InvoiceQueryAmount": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/AmountType" - } - ] - }, - "from": { - "type": "number", - "format": "double", - "nullable": true - }, - "to": { - "type": "number", - "format": "double", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceQueryBuyerIdentifier": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/BuyerIdentifierType" - } - ], - "description": "Typ identyfikatora nabywcy.\n| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora nabywcy |\n" - }, - "value": { - "maxLength": 50, - "type": "string", - "description": "Wartość identyfikatora nabywcy (exact match).", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceQueryDateRange": { - "required": [ - "dateType", - "from" - ], - "type": "object", - "properties": { - "dateType": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQueryDateType" - } - ], - "description": "Typ daty, według której ma być zastosowany zakres.\n| Wartość | Opis |\n| --- | --- |\n| Issue | Data wystawienia faktury. |\n| Invoicing | Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania). |\n| PermanentStorage | Data trwałego zapisu faktury w repozytorium systemu KSeF. |\n" - }, - "from": { - "type": "string", - "description": "Data początkowa zakresu w formacie ISO-8601 np. 2026-01-03T13:45:00+00:00.", - "format": "date-time" - }, - "to": { - "type": "string", - "description": "Data końcowa zakresu w formacie ISO-8601. Jeśli nie zostanie podana, przyjmowana jest bieżąca data i czas w UTC.", - "format": "date-time", - "nullable": true - }, - "restrictToPermanentStorageHwmDate": { - "type": "boolean", - "description": "Określa, czy system ma ograniczyć filtrowanie (zakres dateRange.to) do wartości `PermanentStorageHwmDate`.\n\n* Dotyczy wyłącznie zapytań z `dateType = PermanentStorage`, \n* Gdy `true`, system ogranicza filtrowanie tak, aby wartość `dateRange.to` nie przekraczała wartości `PermanentStorageHwmDate`, \n* Gdy `null` lub `false`, filtrowanie może wykraczać poza `PermanentStorageHwmDate`.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceQueryDateType": { - "enum": [ - "Issue", - "Invoicing", - "PermanentStorage" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Issue | Data wystawienia faktury. |\n| Invoicing | Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania). |\n| PermanentStorage | Data trwałego zapisu faktury w repozytorium systemu KSeF. |\n" - }, - "InvoiceQueryFilters": { - "required": [ - "dateRange", - "subjectType" - ], - "type": "object", - "properties": { - "subjectType": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQuerySubjectType" - } - ], - "description": "Typ podmiotu, którego dotyczą kryteria filtrowania metadanych faktur.\nOkreśla kontekst, w jakim przeszukiwane są dane.\n| Wartość | Opis |\n| --- | --- |\n| Subject1 | Podmiot 1 - sprzedawca |\n| Subject2 | Podmiot 2 - nabywca |\n| Subject3 | Podmiot 3 |\n| SubjectAuthorized | Podmiot upoważniony |\n" - }, - "dateRange": { - "required": [ - "dateType", - "from" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQueryDateRange" - } - ], - "description": "Typ i zakres dat, według którego mają być filtrowane faktury. Dozwolony maksymalny okres wynosi 3 miesiące. Zakres uznawany jest za poprawny, jeśli mieści się w trzech miesiącach w UTC lub w czasie polskim." - }, - "ksefNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/KsefNumber" - } - ], - "description": "Numer KSeF faktury (exact match).", - "nullable": true - }, - "invoiceNumber": { - "maxLength": 256, - "type": "string", - "description": "Numer faktury nadany przez wystawcę (exact match).", - "nullable": true - }, - "amount": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQueryAmount" - } - ], - "description": "Filtr kwotowy – brutto, netto lub VAT (z wartością).", - "nullable": true - }, - "sellerNip": { - "allOf": [ - { - "$ref": "#/components/schemas/Nip" - } - ], - "description": "Nip sprzedawcy (exact match).", - "nullable": true - }, - "buyerIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQueryBuyerIdentifier" - } - ], - "description": "Identyfikator nabywcy.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego. |\n| Other | Inny identyfikator|\n| None | Brak identyfikatora nabywcy |", - "nullable": true - }, - "currencyCodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CurrencyCode" - }, - "description": "Kody walut.", - "nullable": true - }, - "invoicingMode": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoicingMode" - } - ], - "description": "Tryb wystawienia faktury: online lub offline.", - "nullable": true - }, - "isSelfInvoicing": { - "type": "boolean", - "description": "Czy faktura została wystawiona w trybie samofakturowania.", - "nullable": true - }, - "formType": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceQueryFormType" - } - ], - "description": "Typ dokumentu.\n| Wartość | Opis |\n| --- | --- |\n| FA | Faktura VAT |\n| PEF | Faktura PEF |\n| RR | Faktura RR |\n", - "nullable": true - }, - "invoiceTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InvoiceType" - }, - "description": "Rodzaje faktur.\n| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n", - "nullable": true - }, - "hasAttachment": { - "type": "boolean", - "description": "Czy faktura ma załącznik.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceQueryFormType": { - "enum": [ - "FA", - "PEF", - "RR" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| FA | Faktura VAT |\n| PEF | Faktura PEF |\n| RR | Faktura RR |\n" - }, - "InvoiceQuerySubjectType": { - "enum": [ - "Subject1", - "Subject2", - "Subject3", - "SubjectAuthorized" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Subject1 | Podmiot 1 - sprzedawca |\n| Subject2 | Podmiot 2 - nabywca |\n| Subject3 | Podmiot 3 |\n| SubjectAuthorized | Podmiot upoważniony |\n" - }, - "InvoiceStatusInfo": { - "required": [ - "code", - "description" - ], - "type": "object", - "properties": { - "code": { - "type": "integer", - "description": "Kod statusu faktury", - "format": "int32" - }, - "description": { - "minLength": 1, - "type": "string", - "description": "Opis statusu" - }, - "details": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Dodatkowe szczegóły statusu", - "nullable": true - }, - "extensions": { - "type": "object", - "additionalProperties": { - "type": "string", - "nullable": true - }, - "description": "Zbiór dodatkowych informacji związanych ze statusem faktury, zapisanych jako pary klucz–wartość.\nUmożliwia rozszerzenie modelu o dane specyficzne dla danego przypadku.", - "nullable": true - } - }, - "additionalProperties": false - }, - "InvoiceType": { - "enum": [ - "Vat", - "Zal", - "Kor", - "Roz", - "Upr", - "KorZal", - "KorRoz", - "VatPef", - "VatPefSp", - "KorPef", - "VatRr", - "KorVatRr" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n" - }, - "InvoicingMode": { - "enum": [ - "Online", - "Offline" - ], - "type": "string" - }, - "KsefCertificateType": { - "enum": [ - "Authentication", - "Offline" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" - }, - "KsefNumber": { - "maxLength": 36, - "minLength": 35, - "pattern": "^([1-9](\\d[1-9]|[1-9]\\d)\\d{7})-(20[2-9][0-9]|2[1-9]\\d{2}|[3-9]\\d{3})(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])-([0-9A-F]{6})-?([0-9A-F]{6})-([0-9A-F]{2})$", - "type": "string", - "description": "Numer KSeF o długości 36 znaków jest akceptowany, by zachować kompatybilność wsteczna z KSeF 1.0. W KSeF 2.0 numery są generowane wyłącznie w formacie 35-znakowym." - }, - "Nip": { - "maxLength": 10, - "minLength": 10, - "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}$", - "type": "string", - "description": "10 cyfrowy numer NIP." - }, - "NipVatUe": { - "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}-(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))$", - "type": "string", - "description": "Identyfikator złożony, czyli dwuczłonowy identyfikator składający się z nr NIP podmiotu polskiego oraz numeru VAT UE podmiotu unijnego." - }, - "OnlineSessionContextLimitsOverride": { - "required": [ - "maxInvoices", - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB" - ], - "type": "object", - "properties": { - "maxInvoiceSizeInMB": { - "maximum": 5, - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury w MB.", - "format": "int32" - }, - "maxInvoiceWithAttachmentSizeInMB": { - "maximum": 10, - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", - "format": "int32" - }, - "maxInvoices": { - "maximum": 100000, - "minimum": 0, - "type": "integer", - "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "OnlineSessionEffectiveContextLimits": { - "required": [ - "maxInvoices", - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB" - ], - "type": "object", - "properties": { - "maxInvoiceSizeInMB": { - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury w MB.", - "format": "int32" - }, - "maxInvoiceWithAttachmentSizeInMB": { - "minimum": 0, - "type": "integer", - "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", - "format": "int32" - }, - "maxInvoices": { - "minimum": 0, - "type": "integer", - "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "OpenBatchSessionRequest": { - "required": [ - "batchFile", - "encryption", - "formCode" - ], - "type": "object", - "properties": { - "formCode": { - "required": [ - "systemCode", - "schemaVersion", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/FormCode" - } - ], - "description": "Schemat faktur wysyłanych w ramach sesji.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| [FA (2)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n" - }, - "batchFile": { - "required": [ - "fileSize", - "fileHash", - "fileParts" - ], - "allOf": [ - { - "$ref": "#/components/schemas/BatchFileInfo" - } - ], - "description": "Informacje o przesyłanej paczce faktur." - }, - "encryption": { - "required": [ - "encryptedSymmetricKey", - "initializationVector" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EncryptionInfo" - } - ], - "description": "Symetryczny klucz szyfrujący plik paczki, zaszyfrowany kluczem publicznym Ministerstwa Finansów." - }, - "offlineMode": { - "type": "boolean", - "description": "Określa, czy podatnik deklaruje tryb fakturowania \"offline\" dla dokumentów przesyłanych w sesji wsadowej.", - "default": false - } - }, - "additionalProperties": false - }, - "OpenBatchSessionResponse": { - "required": [ - "partUploadRequests", - "referenceNumber" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny sesji." - }, - "partUploadRequests": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PartUploadRequest" - }, - "description": "Dane wymagane do poprawnego przesłania poszczególnych części pliku paczki faktur.\n\nKażdą część pliku paczki zadeklarowaną w fileParts należy przesłać zgodnie z odpowiadającym jej obiektem w partUploadRequests.\nŁącznikiem pomiędzy deklaracją a instrukcją wysyłki jest pole ordinalNumber.\n\nDla każdej części należy:\n* zastosować metodę HTTP wskazaną w method,\n* ustawić adres z url,\n* dołączyć nagłówki z headers,\n* dołączyć treść części pliku w korpusie żądania.\n\n`Uwaga: nie należy dodawać do nagłówków token dostępu (accessToken).`\n \nKażdą część przesyła się oddzielnym żądaniem HTTP.Zwracane kody odpowiedzi:\n * 201 – poprawne przyjęcie pliku,\n * 400 – błędne dane,\n * 401 – nieprawidłowe uwierzytelnienie,\n * 403 – brak uprawnień do zapisu (np.upłynął czas na zapis)." - } - }, - "additionalProperties": false - }, - "OpenOnlineSessionRequest": { - "required": [ - "encryption", - "formCode" - ], - "type": "object", - "properties": { - "formCode": { - "required": [ - "systemCode", - "schemaVersion", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/FormCode" - } - ], - "description": "Schemat faktur wysyłanych w ramach sesji.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| [FA (2)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n| [PEF (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF(3)_v2-1.xsd) | 2-1 | PEF |\n| [PEF_KOR (3)](https://github.com/CIRFMF/ksef-docs/blob/main/faktury/schemy/PEF/Schemat_PEF_KOR(3)_v2-1.xsd) | 2-1 | PEF |\n" - }, - "encryption": { - "required": [ - "encryptedSymmetricKey", - "initializationVector" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EncryptionInfo" - } - ], - "description": "Symetryczny klucz szyfrujący pliki XML, zaszyfrowany kluczem publicznym Ministerstwa Finansów." - } - }, - "additionalProperties": false - }, - "OpenOnlineSessionResponse": { - "required": [ - "referenceNumber", - "validUntil" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny sesji." - }, - "validUntil": { - "type": "string", - "description": "Termin ważności sesji. Po jego upływie sesja zostanie automatycznie zamknięta.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "PartUploadRequest": { - "required": [ - "headers", - "method", - "ordinalNumber", - "url" - ], - "type": "object", - "properties": { - "ordinalNumber": { - "minimum": 1, - "type": "integer", - "description": "Numer sekwencyjny części pliku paczki.", - "format": "int32" - }, - "method": { - "type": "string", - "description": "Metoda HTTP, której należy użyć przy wysyłce części pliku paczki." - }, - "url": { - "type": "string", - "description": "Adres pod który należy wysłać część pliku paczki.", - "format": "uri" - }, - "headers": { - "type": "object", - "additionalProperties": { - "type": "string", - "nullable": true - }, - "description": "Nagłówki, których należy użyć przy wysyłce części pliku paczki." - } - }, - "additionalProperties": false - }, - "PeppolId": { - "maxLength": 9, - "minLength": 9, - "pattern": "^P[A-Z]{2}[0-9]{6}$", - "type": "string", - "description": "Identyfikator dostawcy usług Peppol." - }, - "PeppolProvider": { - "required": [ - "dateCreated", - "id", - "name" - ], - "type": "object", - "properties": { - "id": { - "allOf": [ - { - "$ref": "#/components/schemas/PeppolId" - } - ], - "description": "Identyfikator dostawcy usług Peppol." - }, - "name": { - "maxLength": 256, - "type": "string", - "description": "Nazwa dostawcy usług Peppol." - }, - "dateCreated": { - "type": "string", - "description": "Data rejestracji dostawcy usług Peppol w systemie.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "PermissionId": { - "maxLength": 36, - "minLength": 36, - "type": "string", - "description": "Techniczny identyfikator nadanego uprawnienia – wymagany m.in. przy operacjach odbierania." - }, - "PermissionState": { - "enum": [ - "Active", - "Inactive" - ], - "type": "string" - }, - "PermissionsEuEntityDetails": { - "required": [ - "address", - "fullName" - ], - "type": "object", - "properties": { - "fullName": { - "maxLength": 100, - "type": "string", - "description": "Pełna nazwa podmiotu unijnego." - }, - "address": { - "maxLength": 512, - "type": "string", - "description": "Adres podmiotu unijnego." - } - }, - "additionalProperties": false - }, - "PermissionsOperationResponse": { - "required": [ - "referenceNumber" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny operacji nadania lub odbierania uprawnień." - } - }, - "additionalProperties": false - }, - "PermissionsOperationStatusResponse": { - "required": [ - "status" - ], - "type": "object", - "properties": { - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/StatusInfo" - } - ], - "description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Operacja przyjęta do realizacji | - |\n| 200 | Operacja zakończona sukcesem | - |\n| 400 | Operacja zakończona niepowodzeniem | - |\n| 410 | Podane identyfikatory są niezgodne lub pozostają w niewłaściwej relacji | - |\n| 420 | Użyte poświadczenia nie mają uprawnień do wykonania tej operacji | - |\n| 430 | Kontekst identyfikatora nie odpowiada wymaganej roli lub uprawnieniom | - |\n| 440 | Operacja niedozwolona dla wskazanych powiązań identyfikatorów | - |\n| 450 | Operacja niedozwolona dla wskazanego identyfikatora lub jego typu | - |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie później. |" - } - }, - "additionalProperties": false - }, - "PermissionsSubjectEntityByFingerprintDetails": { - "required": [ - "fullName", - "subjectDetailsType" - ], - "type": "object", - "properties": { - "subjectDetailsType": { - "allOf": [ - { - "$ref": "#/components/schemas/EntitySubjectByFingerprintDetailsType" - } - ], - "description": "Typ danych podmiotu uprawnionego.\n| Wartość | Opis |\n| --- | --- |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" - }, - "fullName": { - "maxLength": 100, - "type": "string", - "description": "Pełna nazwa podmiotu." - }, - "address": { - "maxLength": 512, - "type": "string", - "description": "Adres podmiotu.", - "nullable": true - } - }, - "additionalProperties": false - }, - "PermissionsSubjectEntityByIdentifierDetails": { - "required": [ - "fullName", - "subjectDetailsType" - ], - "type": "object", - "properties": { - "subjectDetailsType": { - "allOf": [ - { - "$ref": "#/components/schemas/EntitySubjectByIdentifierDetailsType" - } - ], - "description": "Typ danych podmiotu uprawnionego.\n| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n" - }, - "fullName": { - "maxLength": 100, - "type": "string", - "description": "Pełna nazwa podmiotu." - } - }, - "additionalProperties": false - }, - "PermissionsSubjectEntityDetails": { - "required": [ - "fullName", - "subjectDetailsType" - ], - "type": "object", - "properties": { - "subjectDetailsType": { - "allOf": [ - { - "$ref": "#/components/schemas/EntitySubjectDetailsType" - } - ], - "description": "Typ danych podmiotu uprawnionego.\n| Wartość | Opis |\n| --- | --- |\n| EntityByIdentifier | Podmiot identyfikowany numerem NIP. |\n| EntityByFingerprint | Podmiot identyfikowany odciskiem palca pieczęci kwalifikowanej. |\n" - }, - "fullName": { - "maxLength": 100, - "type": "string", - "description": "Pełna nazwa podmiotu." - }, - "address": { - "maxLength": 512, - "type": "string", - "description": "Adres podmiotu.", - "nullable": true - } - }, - "additionalProperties": false - }, - "PermissionsSubjectPersonByFingerprintDetails": { - "required": [ - "firstName", - "lastName", - "subjectDetailsType" - ], - "type": "object", - "properties": { - "subjectDetailsType": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonSubjectByFingerprintDetailsType" - } - ], - "description": "Typ danych uprawnionej osoby fizycznej.\n| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" - }, - "firstName": { - "maxLength": 30, - "minLength": 2, - "type": "string", - "description": "Imię osoby fizycznej." - }, - "lastName": { - "maxLength": 81, - "minLength": 2, - "type": "string", - "description": "Nazwisko osoby fizycznej." - }, - "personIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonIdentifier" - } - ], - "description": "Identyfikator osoby fizycznej.", - "nullable": true - }, - "birthDate": { - "type": "string", - "description": "Data urodzenia osoby fizycznej.", - "format": "date", - "nullable": true - }, - "idDocument": { - "required": [ - "type", - "number", - "country" - ], - "allOf": [ - { - "$ref": "#/components/schemas/IdDocument" - } - ], - "description": "Dane dokumentu tożsamości osoby fizycznej.", - "nullable": true - } - }, - "additionalProperties": false - }, - "PermissionsSubjectPersonDetails": { - "required": [ - "firstName", - "lastName", - "subjectDetailsType" - ], - "type": "object", - "properties": { - "subjectDetailsType": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonSubjectDetailsType" - } - ], - "description": "Typ danych uprawnionej osoby fizycznej.\n| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" - }, - "firstName": { - "maxLength": 30, - "minLength": 2, - "type": "string", - "description": "Imię osoby fizycznej." - }, - "lastName": { - "maxLength": 81, - "minLength": 2, - "type": "string", - "description": "Nazwisko osoby fizycznej." - }, - "personIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonIdentifier" - } - ], - "description": "Identyfikator osoby fizycznej.", - "nullable": true - }, - "birthDate": { - "type": "string", - "description": "Data urodzenia osoby fizycznej.", - "format": "date", - "nullable": true - }, - "idDocument": { - "required": [ - "type", - "number", - "country" - ], - "allOf": [ - { - "$ref": "#/components/schemas/IdDocument" - } - ], - "description": "Dane dokumentu tożsamości osoby fizycznej.", - "nullable": true - } - }, - "additionalProperties": false - }, - "PersonByFingerprintWithIdentifierDetails": { - "required": [ - "firstName", - "identifier", - "lastName" - ], - "type": "object", - "properties": { - "firstName": { - "maxLength": 30, - "minLength": 2, - "type": "string", - "description": "Imię osoby fizycznej." - }, - "lastName": { - "maxLength": 81, - "minLength": 2, - "type": "string", - "description": "Nazwisko osoby fizycznej." - }, - "identifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonIdentifier" - } - ], - "description": "Identyfikator osoby fizycznej." - } - }, - "additionalProperties": false - }, - "PersonByFingerprintWithoutIdentifierDetails": { - "required": [ - "birthDate", - "firstName", - "idDocument", - "lastName" - ], - "type": "object", - "properties": { - "firstName": { - "maxLength": 30, - "minLength": 2, - "type": "string", - "description": "Imię osoby fizycznej." - }, - "lastName": { - "maxLength": 81, - "minLength": 2, - "type": "string", - "description": "Nazwisko osoby fizycznej." - }, - "birthDate": { - "type": "string", - "description": "Data urodzenia osoby fizycznej.", - "format": "date" - }, - "idDocument": { - "required": [ - "type", - "number", - "country" - ], - "allOf": [ - { - "$ref": "#/components/schemas/IdDocument" - } - ], - "description": "Dane dokumentu tożsamości osoby fizycznej." - } - }, - "additionalProperties": false - }, - "PersonCreateRequest": { - "required": [ - "description", - "isBailiff", - "nip", - "pesel" - ], - "type": "object", - "properties": { - "nip": { - "$ref": "#/components/schemas/Nip" - }, - "pesel": { - "$ref": "#/components/schemas/Pesel" - }, - "isBailiff": { - "type": "boolean" - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string" - }, - "isDeceased": { - "type": "boolean" - }, - "createdDate": { - "type": "string", - "description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.", - "format": "date-time", - "nullable": true - } - }, - "additionalProperties": false - }, - "PersonDetails": { - "required": [ - "firstName", - "lastName" - ], - "type": "object", - "properties": { - "firstName": { - "maxLength": 30, - "minLength": 2, - "type": "string", - "description": "Imię osoby fizycznej." - }, - "lastName": { - "maxLength": 81, - "minLength": 2, - "type": "string", - "description": "Nazwisko osoby fizycznej." - } - }, - "additionalProperties": false - }, - "PersonIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 11, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false - }, - "PersonIdentifierType": { - "enum": [ - "Pesel", - "Nip" - ], - "type": "string", - "description": "Typ identyfikatora osoby fizycznej." - }, - "PersonPermission": { - "required": [ - "authorIdentifier", - "authorizedIdentifier", - "canDelegate", - "description", - "id", - "permissionScope", - "permissionState", - "startDate" - ], - "type": "object", - "properties": { - "id": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionId" - } - ], - "description": "Identyfikator uprawnienia." - }, - "authorizedIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifier" - } - ], - "description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsContextIdentifier" - } - ], - "description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "targetIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsTargetIdentifier" - } - ], - "description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "authorIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsAuthorIdentifier" - } - ], - "description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |" - }, - "permissionScope": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionScope" - } - ], - "description": "Rodzaj uprawnienia." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia." - }, - "subjectPersonDetails": { - "required": [ - "subjectDetailsType", - "firstName", - "lastName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectPersonDetails" - } - ], - "description": "Dane osoby uprawnionej.", - "nullable": true - }, - "subjectEntityDetails": { - "required": [ - "subjectDetailsType", - "fullName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectEntityDetails" - } - ], - "description": "Dane podmiotu uprawnionego.", - "nullable": true - }, - "permissionState": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionState" - } - ], - "description": "Stan uprawnienia." - }, - "startDate": { - "type": "string", - "description": "Data rozpoczęcia obowiązywania uprawnienia.", - "format": "date-time" - }, - "canDelegate": { - "type": "boolean", - "description": "Flaga określająca, czy uprawnienie ma być możliwe do dalszego przekazywania." - } - }, - "additionalProperties": false - }, - "PersonPermissionScope": { - "enum": [ - "CredentialsManage", - "CredentialsRead", - "InvoiceWrite", - "InvoiceRead", - "Introspection", - "SubunitManage", - "EnforcementOperations" - ], - "type": "string" - }, - "PersonPermissionSubjectDetails": { - "required": [ - "subjectDetailsType" - ], - "type": "object", - "properties": { - "subjectDetailsType": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionSubjectDetailsType" - } - ], - "description": "Typ danych podmiotu.\n| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" - }, - "personById": { - "required": [ - "firstName", - "lastName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonDetails" - } - ], - "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByIdentifier.*", - "nullable": true - }, - "personByFpWithId": { - "required": [ - "firstName", - "lastName", - "identifier" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonByFingerprintWithIdentifierDetails" - } - ], - "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithIdentifier.*", - "nullable": true - }, - "personByFpNoId": { - "required": [ - "firstName", - "lastName", - "birthDate", - "idDocument" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonByFingerprintWithoutIdentifierDetails" - } - ], - "description": "Dane podmiotu.\n*Wymagane, gdy subjectDetailsType = PersonByFingerprintWithoutIdentifier.*", - "nullable": true - } - }, - "additionalProperties": false - }, - "PersonPermissionSubjectDetailsType": { - "enum": [ - "PersonByIdentifier", - "PersonByFingerprintWithIdentifier", - "PersonByFingerprintWithoutIdentifier" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" - }, - "PersonPermissionType": { - "enum": [ - "CredentialsManage", - "CredentialsRead", - "InvoiceWrite", - "InvoiceRead", - "Introspection", - "SubunitManage", - "EnforcementOperations" - ], - "type": "string" - }, - "PersonPermissionsAuthorIdentifier": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsAuthorIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora. W przypadku typu System należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", - "nullable": true - } - }, - "additionalProperties": false, - "description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |" - }, - "PersonPermissionsAuthorIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint", - "System" - ], - "type": "string" - }, - "PersonPermissionsAuthorizedIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "PersonPermissionsAuthorizedIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "PersonPermissionsContextIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsContextIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 16, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" - }, - "PersonPermissionsContextIdentifierType": { - "enum": [ - "Nip", - "InternalId" - ], - "type": "string" - }, - "PersonPermissionsGrantRequest": { - "required": [ - "description", - "permissions", - "subjectDetails", - "subjectIdentifier" - ], - "type": "object", - "properties": { - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsSubjectIdentifier" - } - ], - "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PersonPermissionType" - }, - "description": "Lista nadawanych uprawnień. Każda wartość może wystąpić tylko raz." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia" - }, - "subjectDetails": { - "required": [ - "subjectDetailsType" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionSubjectDetails" - } - ], - "description": "Dane podmiotu, któremu nadawane są uprawnienia." - } - }, - "additionalProperties": false - }, - "PersonPermissionsQueryRequest": { - "required": [ - "queryType" - ], - "type": "object", - "properties": { - "authorIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsAuthorIdentifier" - } - ], - "description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |", - "nullable": true - }, - "authorizedIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifier" - } - ], - "description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |", - "nullable": true - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsContextIdentifier" - } - ], - "description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "targetIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsTargetIdentifier" - } - ], - "description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "permissionTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PersonPermissionType" - }, - "description": "Lista rodzajów wyszukiwanych uprawnień.", - "nullable": true - }, - "permissionState": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionState" - } - ], - "description": "Stan uprawnienia. \n| Type | Value |\n| --- | --- |\n| Active | Uprawnienia aktywne |\n| Inactive | Uprawnienia nieaktywne, nadane w sposób pośredni |", - "nullable": true - }, - "queryType": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsQueryType" - } - ], - "description": "Typ zapytania.\n| Type | Value |\n| --- | --- |\n| PermissionsInCurrentContext | Lista uprawnień obowiązujących w bieżącym kontekście |\n| PermissionsGrantedInCurrentContext | Lista uprawnień nadanych w bieżącym kontekście |" - } - }, - "additionalProperties": false - }, - "PersonPermissionsQueryType": { - "enum": [ - "PermissionsInCurrentContext", - "PermissionsGrantedInCurrentContext" - ], - "type": "string" - }, - "PersonPermissionsSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "PersonPermissionsSubjectIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "PersonPermissionsTargetIdentifier": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionsTargetIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 16, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", - "nullable": true - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" - }, - "PersonPermissionsTargetIdentifierType": { - "enum": [ - "Nip", - "AllPartners", - "InternalId" - ], - "type": "string" - }, - "PersonRemoveRequest": { - "required": [ - "nip" - ], - "type": "object", - "properties": { - "nip": { - "$ref": "#/components/schemas/Nip" - } - }, - "additionalProperties": false - }, - "PersonSubjectByFingerprintDetailsType": { - "enum": [ - "PersonByFingerprintWithIdentifier", - "PersonByFingerprintWithoutIdentifier" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" - }, - "PersonSubjectDetailsType": { - "enum": [ - "PersonByIdentifier", - "PersonByFingerprintWithIdentifier", - "PersonByFingerprintWithoutIdentifier" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| PersonByIdentifier | Osoba fizyczna posługująca się Profilem Zaufanym lub certyfikatem zawierającym identyfikator NIP lub PESEL. |\n| PersonByFingerprintWithIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL, ale mająca NIP lub PESEL. |\n| PersonByFingerprintWithoutIdentifier | Osoba fizyczna posługująca się certyfikatem niezawierającym identyfikatora NIP ani PESEL i niemająca NIP ani PESEL. |\n" - }, - "PersonalPermission": { - "required": [ - "canDelegate", - "description", - "id", - "permissionScope", - "permissionState", - "startDate" - ], - "type": "object", - "properties": { - "id": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionId" - } - ], - "description": "Identyfikator uprawnienia." - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsContextIdentifier" - } - ], - "description": "Identyfikator kontekstu podmiotu, który nadał uprawnienia do obsługi faktur.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "authorizedIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsAuthorizedIdentifier" - } - ], - "description": "Identyfikator podmiotu uprawnionego, jeżeli jest inny niż identyfikator uwierzytelnionego klienta API.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", - "nullable": true - }, - "targetIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsTargetIdentifier" - } - ], - "description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "permissionScope": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionScope" - } - ], - "description": "Rodzaj uprawnienia." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia." - }, - "subjectPersonDetails": { - "required": [ - "subjectDetailsType", - "firstName", - "lastName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectPersonDetails" - } - ], - "description": "Dane osoby uprawnionej.", - "nullable": true - }, - "subjectEntityDetails": { - "required": [ - "subjectDetailsType", - "fullName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectEntityDetails" - } - ], - "description": "Dane podmiotu uprawnionego.", - "nullable": true - }, - "permissionState": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionState" - } - ], - "description": "Stan uprawnienia." - }, - "startDate": { - "type": "string", - "description": "Data rozpoczęcia obowiązywania uprawnienia.", - "format": "date-time" - }, - "canDelegate": { - "type": "boolean", - "description": "Flaga określająca, czy uprawnienie ma być możliwe do dalszego przekazywania." - } - }, - "additionalProperties": false - }, - "PersonalPermissionScope": { - "enum": [ - "CredentialsManage", - "CredentialsRead", - "InvoiceWrite", - "InvoiceRead", - "Introspection", - "SubunitManage", - "EnforcementOperations", - "VatUeManage" - ], - "type": "string" - }, - "PersonalPermissionType": { - "enum": [ - "CredentialsManage", - "CredentialsRead", - "InvoiceWrite", - "InvoiceRead", - "Introspection", - "SubunitManage", - "EnforcementOperations", - "VatUeManage" - ], - "type": "string" - }, - "PersonalPermissionsAuthorizedIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsAuthorizedIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu uprawnionego, jeżeli jest inny niż identyfikator uwierzytelnionego klienta API.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "PersonalPermissionsAuthorizedIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "PersonalPermissionsContextIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsContextIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 16, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator kontekstu podmiotu, który nadał uprawnienia do obsługi faktur.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" - }, - "PersonalPermissionsContextIdentifierType": { - "enum": [ - "Nip", - "InternalId" - ], - "type": "string" - }, - "PersonalPermissionsQueryRequest": { - "type": "object", - "properties": { - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsContextIdentifier" - } - ], - "description": "Identyfikator kontekstu podmiotu, który nadał uprawnienia do obsługi faktur.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "targetIdentifier": { - "required": [ - "type" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsTargetIdentifier" - } - ], - "description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |", - "nullable": true - }, - "permissionTypes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PersonalPermissionType" - }, - "description": "Lista rodzajów wyszukiwanych uprawnień.", - "nullable": true - }, - "permissionState": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionState" - } - ], - "description": "Stan uprawnienia. \n| Type | Value |\n| --- | --- |\n| Active | Uprawnienia aktywne |\n| Inactive | Uprawnienia nieaktywne |", - "nullable": true - } - }, - "additionalProperties": false - }, - "PersonalPermissionsTargetIdentifier": { - "required": [ - "type" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/PersonalPermissionsTargetIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 16, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.", - "nullable": true - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" - }, - "PersonalPermissionsTargetIdentifierType": { - "enum": [ - "Nip", - "AllPartners", - "InternalId" - ], - "type": "string" - }, - "Pesel": { - "maxLength": 11, - "minLength": 11, - "pattern": "^\\d{2}(?:0[1-9]|1[0-2]|2[1-9]|3[0-2]|4[1-9]|5[0-2]|6[1-9]|7[0-2]|8[1-9]|9[0-2])\\d{7}$", - "type": "string", - "description": "11 cyfrowy numer PESEL." - }, - "PublicKeyCertificate": { - "required": [ - "certificate", - "usage", - "validFrom", - "validTo" - ], - "type": "object", - "properties": { - "certificate": { - "type": "string", - "description": "Certyfikat klucza publicznego w formacie DER, zakodowany w formacie Base64.", - "format": "byte" - }, - "validFrom": { - "type": "string", - "description": "Data początku obowiązywania certyfikatu.", - "format": "date-time" - }, - "validTo": { - "type": "string", - "description": "Data końca obowiązywania certyfikatu.", - "format": "date-time" - }, - "usage": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PublicKeyCertificateUsage" - }, - "description": "Operacje do których może być używany certyfikat.\n| Wartość | Opis |\n| --- | --- |\n| KsefTokenEncryption | Szyfrowanie tokenów KSeF przesyłanych w trakcie procesu uwierzytelniania. |\n| SymmetricKeyEncryption | Szyfrowanie klucza symetrycznego wykorzystywanego do szyfrowania przesyłanych faktur. |\n" - } - }, - "additionalProperties": false - }, - "PublicKeyCertificateUsage": { - "enum": [ - "KsefTokenEncryption", - "SymmetricKeyEncryption" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| KsefTokenEncryption | Szyfrowanie tokenów KSeF przesyłanych w trakcie procesu uwierzytelniania. |\n| SymmetricKeyEncryption | Szyfrowanie klucza symetrycznego wykorzystywanego do szyfrowania przesyłanych faktur. |\n" - }, - "QueryCertificatesRequest": { - "type": "object", - "properties": { - "certificateSerialNumber": { - "type": "string", - "description": "Numer seryjny certyfikatu. Wyszukiwanie odbywa się na zasadzie dokładnego dopasowania (exact match).", - "nullable": true - }, - "name": { - "type": "string", - "description": "Nazwa własna certyfikatu. Wyszukiwanie jest częściowe, czyli zwracane są certyfikaty, których nazwa zawiera podany ciąg znaków (contains).", - "nullable": true - }, - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/KsefCertificateType" - } - ], - "description": "Typ certyfikatu KSeF.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n", - "nullable": true - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/CertificateListItemStatus" - } - ], - "description": "Status certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n", - "nullable": true - }, - "expiresAfter": { - "type": "string", - "description": "Filtruje certyfikaty, które wygasają po podanej dacie.", - "format": "date-time", - "nullable": true - } - }, - "additionalProperties": false - }, - "QueryCertificatesResponse": { - "required": [ - "certificates", - "hasMore" - ], - "type": "object", - "properties": { - "certificates": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CertificateListItem" - }, - "description": "Lista certyfikatów spełniających kryteria wyszukiwania." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QueryEntityAuthorizationPermissionsResponse": { - "required": [ - "authorizationGrants", - "hasMore" - ], - "type": "object", - "properties": { - "authorizationGrants": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EntityAuthorizationGrant" - }, - "description": "Lista odczytanych uprawnień." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QueryEntityRolesResponse": { - "required": [ - "hasMore", - "roles" - ], - "type": "object", - "properties": { - "roles": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EntityRole" - }, - "description": "Lista odczytanych ról podmiotu." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QueryEuEntityPermissionsResponse": { - "required": [ - "hasMore", - "permissions" - ], - "type": "object", - "properties": { - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EuEntityPermission" - }, - "description": "Lista odczytanych uprawnień." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QueryInvoicesMetadataResponse": { - "required": [ - "hasMore", - "invoices", - "isTruncated" - ], - "type": "object", - "properties": { - "hasMore": { - "type": "boolean", - "description": "Określa, czy istnieją kolejne wyniki zapytania." - }, - "isTruncated": { - "type": "boolean", - "description": "Określa, czy osiągnięto maksymalny dopuszczalny zakres wyników zapytania (10 000)." - }, - "permanentStorageHwmDate": { - "type": "string", - "description": "Dotyczy wyłącznie zapytań filtrowanych po typie daty PermanentStorage.\nJeśli zapytanie dotyczyło najnowszego okresu, wartość ta może być wartością nieznacznie skorygowaną względem górnej granicy podanej w warunkach zapytania.\nDla okresów starszych, będzie to zgodne z warunkami zapytania. \n\nWartość jest stała dla wszystkich stron tego samego zapytania\ni nie zależy od paginacji ani sortowania.\n\nSystem gwarantuje, że dane poniżej tej wartości są spójne i kompletne.\nPonowne zapytania obejmujące zakresem dane poniżej tego kroczącego znacznika czasu nie zwrócą w przyszłości innych wyników (np.dodatkowych faktur). \n\nDla dateType = Issue lub Invoicing – null.", - "format": "date-time", - "nullable": true - }, - "invoices": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InvoiceMetadata" - }, - "description": "Lista faktur spełniających kryteria." - } - }, - "additionalProperties": false - }, - "QueryPeppolProvidersResponse": { - "required": [ - "hasMore", - "peppolProviders" - ], - "type": "object", - "properties": { - "peppolProviders": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PeppolProvider" - }, - "description": "Lista dostawców usług Peppol." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QueryPersonPermissionsResponse": { - "required": [ - "hasMore", - "permissions" - ], - "type": "object", - "properties": { - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PersonPermission" - }, - "description": "Lista odczytanych uprawnień." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QueryPersonalPermissionsResponse": { - "required": [ - "hasMore", - "permissions" - ], - "type": "object", - "properties": { - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PersonalPermission" - }, - "description": "Lista odczytanych uprawnień." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QuerySubordinateEntityRolesResponse": { - "required": [ - "hasMore", - "roles" - ], - "type": "object", - "properties": { - "roles": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SubordinateEntityRole" - }, - "description": "Lista odczytanych podmiotów podrzędnych i ich ról." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QuerySubunitPermissionsResponse": { - "required": [ - "hasMore", - "permissions" - ], - "type": "object", - "properties": { - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SubunitPermission" - }, - "description": "Lista odczytanych uprawnień." - }, - "hasMore": { - "type": "boolean", - "description": "Flaga informująca o dostępności kolejnej strony wyników." - } - }, - "additionalProperties": false - }, - "QueryTokensResponse": { - "required": [ - "tokens" - ], - "type": "object", - "properties": { - "continuationToken": { - "type": "string", - "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", - "nullable": true - }, - "tokens": { - "type": "array", - "items": { - "$ref": "#/components/schemas/QueryTokensResponseItem" - }, - "description": "Lista tokenów uwierzytelniających." - } - }, - "additionalProperties": false - }, - "QueryTokensResponseItem": { - "required": [ - "authorIdentifier", - "contextIdentifier", - "dateCreated", - "description", - "referenceNumber", - "requestedPermissions", - "status" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny tokena KSeF." - }, - "authorIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenAuthorIdentifierTypeIdentifier" - } - ], - "description": "Identyfikator osoby która wygenerowała token." - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenContextIdentifierTypeIdentifier" - } - ], - "description": "Identyfikator kontekstu, w którym został wygenerowany token i do którego daje dostęp." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis tokena." - }, - "requestedPermissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TokenPermissionType" - }, - "description": "Uprawnienia przypisane tokenowi." - }, - "dateCreated": { - "type": "string", - "description": "Data i czas utworzenia tokena.", - "format": "date-time" - }, - "lastUseDate": { - "type": "string", - "description": "Data ostatniego użycia tokena.", - "format": "date-time", - "nullable": true - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/AuthenticationTokenStatus" - } - ], - "description": "Status tokena.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n" - }, - "statusDetails": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Dodatkowe informacje na temat statusu, zwracane w przypadku błędów.", - "nullable": true - } - }, - "additionalProperties": false - }, - "QueryType": { - "enum": [ - "Granted", - "Received" - ], - "type": "string" - }, - "ReferenceNumber": { - "maxLength": 36, - "minLength": 36, - "type": "string", - "description": "Numer referencyjny." - }, - "RetrieveCertificatesListItem": { - "required": [ - "certificate", - "certificateName", - "certificateSerialNumber", - "certificateType" - ], - "type": "object", - "properties": { - "certificate": { - "type": "string", - "description": "Certyfikat w formacie DER, zakodowany w formacie Base64.", - "format": "byte" - }, - "certificateName": { - "type": "string", - "description": "Nazwa własna certyfikatu." - }, - "certificateSerialNumber": { - "type": "string", - "description": "Numer seryjny certyfikatu." - }, - "certificateType": { - "allOf": [ - { - "$ref": "#/components/schemas/KsefCertificateType" - } - ], - "description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n" - } - }, - "additionalProperties": false - }, - "RetrieveCertificatesRequest": { - "required": [ - "certificateSerialNumbers" - ], - "type": "object", - "properties": { - "certificateSerialNumbers": { - "maxItems": 10, - "minItems": 1, - "type": "array", - "items": { - "type": "string" - }, - "description": "Numery seryjne certyfikatów do pobrania." - } - }, - "additionalProperties": false - }, - "RetrieveCertificatesResponse": { - "required": [ - "certificates" - ], - "type": "object", - "properties": { - "certificates": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RetrieveCertificatesListItem" - }, - "description": "Pobrane certyfikaty." - } - }, - "additionalProperties": false - }, - "RetryAfter": { - "type": "integer", - "description": "Liczba sekund po których można ponowić żądanie.", - "format": "int32", - "example": 30 - }, - "RevokeCertificateRequest": { - "type": "object", - "properties": { - "revocationReason": { - "allOf": [ - { - "$ref": "#/components/schemas/CertificateRevocationReason" - } - ], - "description": "Powód unieważnienia certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Unspecified | Nieokreślony. |\n| Superseded | Certyfikat został zastąpiony przez inny. |\n| KeyCompromise | Klucz prywatny powiązany z certyfikatem został skompromitowany. |\n", - "nullable": true - } - }, - "additionalProperties": false - }, - "SendInvoiceRequest": { - "required": [ - "encryptedInvoiceContent", - "encryptedInvoiceHash", - "encryptedInvoiceSize", - "invoiceHash", - "invoiceSize" - ], - "type": "object", - "properties": { - "invoiceHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 oryginalnej faktury, zakodowany w formacie Base64." - }, - "invoiceSize": { - "minimum": 1, - "type": "integer", - "description": "Rozmiar oryginalnej faktury w bajtach. Maksymalny rozmiar zależy od limitów ustawionych dla uwierzytelnionego kontekstu.", - "format": "int64" - }, - "encryptedInvoiceHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 zaszyfrowanej faktury, zakodowany w formacie Base64." - }, - "encryptedInvoiceSize": { - "minimum": 1, - "type": "integer", - "description": "Rozmiar zaszyfrowanej faktury w bajtach.", - "format": "int64" - }, - "encryptedInvoiceContent": { - "type": "string", - "description": "Faktura zaszyfrowana algorytmem AES-256-CBC z dopełnianiem PKCS#7 (kluczem przekazanym przy otwarciu sesji), zakodowana w formacie Base64.", - "format": "byte" - }, - "offlineMode": { - "type": "boolean", - "description": "Określa, czy podatnik deklaruje tryb fakturowania \"offline\" dla przesyłanego dokumentu.", - "default": false - }, - "hashOfCorrectedInvoice": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 korygowanej faktury, zakodowany w formacie Base64. Wymagany przy wysyłaniu korekty technicznej faktury.", - "nullable": true - } - }, - "additionalProperties": false - }, - "SendInvoiceResponse": { - "required": [ - "referenceNumber" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny faktury." - } - }, - "additionalProperties": false - }, - "SessionInvoiceStatusResponse": { - "required": [ - "invoiceHash", - "invoicingDate", - "ordinalNumber", - "referenceNumber", - "status" - ], - "type": "object", - "properties": { - "ordinalNumber": { - "minimum": 1, - "type": "integer", - "description": "Numer sekwencyjny faktury w ramach sesji.", - "format": "int32" - }, - "invoiceNumber": { - "maxLength": 256, - "type": "string", - "description": "Numer faktury.", - "nullable": true - }, - "ksefNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/KsefNumber" - } - ], - "description": "Numer KSeF.", - "nullable": true - }, - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny faktury." - }, - "invoiceHash": { - "allOf": [ - { - "$ref": "#/components/schemas/Sha256HashBase64" - } - ], - "description": "Skrót SHA256 faktury, zakodowany w formacie Base64." - }, - "invoiceFileName": { - "maxLength": 128, - "type": "string", - "description": "Nazwa pliku faktury (zwracana dla faktur wysyłanych wsadowo).", - "nullable": true - }, - "acquisitionDate": { - "type": "string", - "description": "Data nadania numeru KSeF.", - "format": "date-time", - "nullable": true - }, - "invoicingDate": { - "type": "string", - "description": "Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania).", - "format": "date-time" - }, - "permanentStorageDate": { - "type": "string", - "description": "Data trwałego zapisu faktury w repozytorium KSeF. Wartość uzupełniana asynchronicznie w momencie trwałego zapisu; zawsze późniejsza niż acquisitionDate. Podczas sprawdzania statusu może być jeszcze niedostępna.", - "format": "date-time", - "nullable": true - }, - "upoDownloadUrl": { - "type": "string", - "description": "Adres do pobrania UPO. Link generowany jest przy każdym odpytaniu o status. \nDostęp odbywa się metodą `HTTP GET` i nie należy wysyłać tokenu dostępowego. \nLink nie podlega limitom API i wygasa po określonym czasie w `UpoDownloadUrlExpirationDate`.\n\nOdpowiedź HTTP zawiera dodatkowe nagłówki:\n- `x-ms-meta-hash` – skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64.", - "format": "uri", - "nullable": true - }, - "upoDownloadUrlExpirationDate": { - "type": "string", - "description": "Data i godzina wygaśnięcia adresu. Po tej dacie link `UpoDownloadUrl` nie będzie już aktywny.", - "format": "date-time", - "nullable": true - }, - "invoicingMode": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoicingMode" - } - ], - "description": "Tryb fakturowania (online/offline).", - "nullable": true - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/InvoiceStatusInfo" - } - ], - "description": "Status faktury.\n\n| Code | Description | Details | Extensions |\n| --- | --- | --- | ---|\n| 100 | Faktura przyjęta do dalszego przetwarzania | - | - |\n| 150 | Trwa przetwarzanie | - | - |\n| 200 | Sukces | - | - |\n| 405 | Przetwarzanie anulowane z powodu błędu sesji | - | - |\n| 410 | Nieprawidłowy zakres uprawnień | - | - |\n| 415 | Brak możliwości wysyłania faktury z załącznikiem | - | - |\n| 430 | Błąd weryfikacji pliku faktury | - | - |\n| 435 | Błąd odszyfrowania pliku | - | - |\n| 440 | Duplikat faktury | - | 'originalSessionReferenceNumber', 'originalKsefNumber'|\n| 450 | Błąd weryfikacji semantyki dokumentu faktury | - | - |\n| 500 | Nieznany błąd ({statusCode}) | - | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |- |" - } - }, - "additionalProperties": false - }, - "SessionInvoicesResponse": { - "required": [ - "invoices" - ], - "type": "object", - "properties": { - "continuationToken": { - "type": "string", - "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", - "nullable": true - }, - "invoices": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SessionInvoiceStatusResponse" - }, - "description": "Lista pobranych faktur." - } - }, - "additionalProperties": false - }, - "SessionStatusResponse": { - "required": [ - "dateCreated", - "dateUpdated", - "status" - ], - "type": "object", - "properties": { - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/StatusInfo" - } - ], - "description": "Informacje o aktualnym statusie.\n \nSesja wsadowa:\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Sesja wsadowa rozpoczęta | - |\n| 150 | Trwa przetwarzanie | - |\n| 200 | Sesja wsadowa przetworzona pomyślnie | - |\n| 405 | Błąd weryfikacji poprawności dostarczonych elementów paczki | - |\n| 415 | Błąd odszyfrowania dostarczonego klucza | - |\n| 420 | Przekroczony limit faktur w sesji | - |\n| 430 | Błąd dekompresji pierwotnego archiwum | - |\n| 435 | Błąd odszyfrowania zaszyfrowanych części archiwum | - |\n| 440 | Sesja anulowana | Przekroczono czas wysyłki |\n| 440 | Sesja anulowana | Nie przesłano faktur |\n| 445 | Błąd weryfikacji, brak poprawnych faktur | - |\n| 500 | Nieznany błąd ({statusCode}) | - |\n\nSesja interaktywna:\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Sesja interaktywna otwarta | - |\n| 170 | Sesja interaktywna zamknięta | - |\n| 200 | Sesja interaktywna przetworzona pomyślnie | - |\n| 415 | Błąd odszyfrowania dostarczonego klucza | - |\n| 440 | Sesja anulowana | Nie przesłano faktur |\n| 445 | Błąd weryfikacji, brak poprawnych faktur | - |\n| * | description missing | - |" - }, - "dateCreated": { - "type": "string", - "description": "Data utworzenia sesji.", - "format": "date-time" - }, - "dateUpdated": { - "type": "string", - "description": "Data ostatniej aktywności w ramach sesji.", - "format": "date-time" - }, - "validUntil": { - "type": "string", - "description": "Termin ważności sesji. Po jego upływie sesja zostanie automatycznie zamknięta.", - "format": "date-time", - "nullable": true, - "readOnly": true - }, - "upo": { - "required": [ - "pages" - ], - "allOf": [ - { - "$ref": "#/components/schemas/UpoResponse" - } - ], - "description": "Informacja o UPO sesyjnym, zwracana gdy sesja została zamknięta i UPO zostało wygenerowane.", - "nullable": true - }, - "invoiceCount": { - "minimum": 0, - "type": "integer", - "description": "Liczba przyjętych faktur w ramach sesji.", - "format": "int32", - "nullable": true - }, - "successfulInvoiceCount": { - "minimum": 0, - "type": "integer", - "description": "Liczba faktur przeprocesowanych w ramach sesji z sukcesem .", - "format": "int32", - "nullable": true - }, - "failedInvoiceCount": { - "minimum": 0, - "type": "integer", - "description": "Liczba faktur przeprocesowanych w ramach sesji z błędem.", - "format": "int32", - "nullable": true - } - }, - "additionalProperties": false - }, - "SessionType": { - "enum": [ - "Online", - "Batch" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Online | Wysyłka interaktywna (pojedyncze faktury). |\n| Batch | Wysyłka wsadowa (paczka faktur). |\n" - }, - "SessionsQueryResponse": { - "required": [ - "sessions" - ], - "type": "object", - "properties": { - "continuationToken": { - "type": "string", - "description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.", - "nullable": true - }, - "sessions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SessionsQueryResponseItem" - }, - "description": "Lista sesji." - } - }, - "additionalProperties": false - }, - "SessionsQueryResponseItem": { - "required": [ - "dateCreated", - "dateUpdated", - "failedInvoiceCount", - "referenceNumber", - "status", - "successfulInvoiceCount", - "totalInvoiceCount" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny sesji." - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/StatusInfo" - } - ], - "description": "Status sesji." - }, - "dateCreated": { - "type": "string", - "description": "Data utworzenia sesji.", - "format": "date-time" - }, - "dateUpdated": { - "type": "string", - "description": "Data ostatniej aktywności w ramach sesji.", - "format": "date-time" - }, - "validUntil": { - "type": "string", - "description": "Termin ważności sesji. Po jego upływie sesja interaktywna zostanie automatycznie zamknięta.", - "format": "date-time", - "nullable": true - }, - "totalInvoiceCount": { - "minimum": 0, - "type": "integer", - "description": "Łączna liczba faktur (uwzględnia również te w trakcie przetwarzania).", - "format": "int32" - }, - "successfulInvoiceCount": { - "minimum": 0, - "type": "integer", - "description": "Liczba poprawnie przetworzonych faktur.", - "format": "int32" - }, - "failedInvoiceCount": { - "minimum": 0, - "type": "integer", - "description": "Liczba błędnie przetworzonych faktur.", - "format": "int32" - } - }, - "additionalProperties": false - }, - "SetRateLimitsRequest": { - "required": [ - "rateLimits" - ], - "type": "object", - "properties": { - "rateLimits": { - "required": [ - "onlineSession", - "batchSession", - "invoiceSend", - "invoiceStatus", - "sessionList", - "sessionInvoiceList", - "sessionMisc", - "invoiceMetadata", - "invoiceExport", - "invoiceExportStatus", - "invoiceDownload", - "other" - ], - "allOf": [ - { - "$ref": "#/components/schemas/ApiRateLimitsOverride" - } - ], - "description": "Limity dla ilości żądań do API." - } - }, - "additionalProperties": false - }, - "SetSessionLimitsRequest": { - "required": [ - "batchSession", - "onlineSession" - ], - "type": "object", - "properties": { - "onlineSession": { - "required": [ - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB", - "maxInvoices" - ], - "allOf": [ - { - "$ref": "#/components/schemas/OnlineSessionContextLimitsOverride" - } - ], - "description": "Limity dla sesji interaktywnych." - }, - "batchSession": { - "required": [ - "maxInvoiceSizeInMB", - "maxInvoiceWithAttachmentSizeInMB", - "maxInvoices" - ], - "allOf": [ - { - "$ref": "#/components/schemas/BatchSessionContextLimitsOverride" - } - ], - "description": "Limity dla sesji wsadowych." - } - }, - "additionalProperties": false - }, - "SetSubjectLimitsRequest": { - "type": "object", - "properties": { - "subjectIdentifierType": { - "allOf": [ - { - "$ref": "#/components/schemas/SubjectIdentifierType" - } - ] - }, - "enrollment": { - "allOf": [ - { - "$ref": "#/components/schemas/EnrollmentSubjectLimitsOverride" - } - ], - "nullable": true - }, - "certificate": { - "allOf": [ - { - "$ref": "#/components/schemas/CertificateSubjectLimitsOverride" - } - ], - "nullable": true - } - }, - "additionalProperties": false - }, - "Sha256HashBase64": { - "maxLength": 44, - "minLength": 44, - "type": "string", - "description": "SHA-256 w Base64.", - "format": "byte" - }, - "SortOrder": { - "enum": [ - "Asc", - "Desc" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n" - }, - "StatusInfo": { - "required": [ - "code", - "description" - ], - "type": "object", - "properties": { - "code": { - "type": "integer", - "description": "Kod statusu", - "format": "int32" - }, - "description": { - "minLength": 1, - "type": "string", - "description": "Opis statusu" - }, - "details": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Dodatkowe szczegóły statusu", - "nullable": true - } - }, - "additionalProperties": false - }, - "SubjectCreateRequest": { - "required": [ - "description", - "subjectNip", - "subjectType" - ], - "type": "object", - "properties": { - "subjectNip": { - "$ref": "#/components/schemas/Nip" - }, - "subjectType": { - "allOf": [ - { - "$ref": "#/components/schemas/SubjectType" - } - ] - }, - "subunits": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Subunit" - }, - "nullable": true - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string" - }, - "createdDate": { - "type": "string", - "description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.", - "format": "date-time", - "nullable": true - } - }, - "additionalProperties": false - }, - "SubjectIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "SubjectRemoveRequest": { - "required": [ - "subjectNip" - ], - "type": "object", - "properties": { - "subjectNip": { - "$ref": "#/components/schemas/Nip" - } - }, - "additionalProperties": false - }, - "SubjectType": { - "enum": [ - "EnforcementAuthority", - "VatGroup", - "JST" - ], - "type": "string" - }, - "SubordinateEntityRole": { - "required": [ - "description", - "role", - "startDate", - "subordinateEntityIdentifier" - ], - "type": "object", - "properties": { - "subordinateEntityIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubordinateRoleSubordinateEntityIdentifier" - } - ], - "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "role": { - "allOf": [ - { - "$ref": "#/components/schemas/SubordinateEntityRoleType" - } - ], - "description": "Typ roli - powiązania z podmiotem nadrzędnym." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis powiązania." - }, - "startDate": { - "type": "string", - "description": "Data rozpoczęcia obowiązywania powiązania.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "SubordinateEntityRoleType": { - "enum": [ - "LocalGovernmentSubUnit", - "VatGroupSubUnit" - ], - "type": "string" - }, - "SubordinateEntityRolesQueryRequest": { - "type": "object", - "properties": { - "subordinateEntityIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/EntityPermissionsSubordinateEntityIdentifier" - } - ], - "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |", - "nullable": true - } - }, - "additionalProperties": false - }, - "SubordinateRoleSubordinateEntityIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/SubordinateRoleSubordinateEntityIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 10, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" - }, - "SubordinateRoleSubordinateEntityIdentifierType": { - "enum": [ - "Nip" - ], - "type": "string" - }, - "Subunit": { - "required": [ - "description", - "subjectNip" - ], - "type": "object", - "properties": { - "subjectNip": { - "$ref": "#/components/schemas/Nip" - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string" - } - }, - "additionalProperties": false - }, - "SubunitPermission": { - "required": [ - "authorIdentifier", - "authorizedIdentifier", - "description", - "id", - "permissionScope", - "startDate", - "subunitIdentifier" - ], - "type": "object", - "properties": { - "id": { - "allOf": [ - { - "$ref": "#/components/schemas/PermissionId" - } - ], - "description": "Identyfikator uprawnienia." - }, - "authorizedIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsAuthorizedIdentifier" - } - ], - "description": "Identyfikator uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "subunitIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifier" - } - ], - "description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |" - }, - "authorIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsAuthorIdentifier" - } - ], - "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "permissionScope": { - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionScope" - } - ], - "description": "Rodzaj uprawnienia." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia." - }, - "subjectPersonDetails": { - "required": [ - "subjectDetailsType", - "firstName", - "lastName" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PermissionsSubjectPersonDetails" - } - ], - "description": "Dane osoby uprawnionej.", - "nullable": true - }, - "subunitName": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Nazwa jednostki podrzędnej.", - "nullable": true - }, - "startDate": { - "type": "string", - "description": "Data rozpoczęcia obowiązywania uprawnienia.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "SubunitPermissionScope": { - "enum": [ - "CredentialsManage" - ], - "type": "string" - }, - "SubunitPermissionsAuthorIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsAuthorIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "SubunitPermissionsAuthorIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "SubunitPermissionsAuthorizedIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "SubunitPermissionsContextIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsContextIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 16, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" - }, - "SubunitPermissionsContextIdentifierType": { - "enum": [ - "InternalId", - "Nip" - ], - "type": "string" - }, - "SubunitPermissionsGrantRequest": { - "required": [ - "contextIdentifier", - "description", - "subjectDetails", - "subjectIdentifier" - ], - "type": "object", - "properties": { - "subjectIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifier" - } - ], - "description": "Identyfikator podmiotu lub osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsContextIdentifier" - } - ], - "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |" - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis uprawnienia" - }, - "subunitName": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Nazwa jednostki podrzędnej. W przypadku jednostki podrzędnej z identyfikatorem wewnętrznym pole jest wymagane.", - "nullable": true - }, - "subjectDetails": { - "required": [ - "subjectDetailsType" - ], - "allOf": [ - { - "$ref": "#/components/schemas/PersonPermissionSubjectDetails" - } - ], - "description": "Dane podmiotu, któremu nadawane są uprawnienia." - } - }, - "additionalProperties": false - }, - "SubunitPermissionsQueryRequest": { - "type": "object", - "properties": { - "subunitIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifier" - } - ], - "description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |", - "nullable": true - } - }, - "additionalProperties": false - }, - "SubunitPermissionsSubjectIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator podmiotu lub osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |" - }, - "SubunitPermissionsSubjectIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "SubunitPermissionsSubunitIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifierType" - } - ], - "description": "Typ identyfikatora." - }, - "value": { - "maxLength": 16, - "minLength": 10, - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false, - "description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |" - }, - "SubunitPermissionsSubunitIdentifierType": { - "enum": [ - "InternalId", - "Nip" - ], - "type": "string" - }, - "TestDataAuthorizedIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/TestDataAuthorizedIdentifierType" - } - ] - }, - "value": { - "maxLength": 64, - "minLength": 10, - "type": "string" - } - }, - "additionalProperties": false - }, - "TestDataAuthorizedIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string" - }, - "TestDataContextIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/TestDataContextIdentifierType" - } - ] - }, - "value": { - "maxLength": 10, - "minLength": 10, - "type": "string" - } - }, - "additionalProperties": false - }, - "TestDataContextIdentifierType": { - "enum": [ - "Nip" - ], - "type": "string" - }, - "TestDataPermission": { - "required": [ - "description", - "permissionType" - ], - "type": "object", - "properties": { - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string" - }, - "permissionType": { - "allOf": [ - { - "$ref": "#/components/schemas/TestDataPermissionType" - } - ] - } - }, - "additionalProperties": false - }, - "TestDataPermissionType": { - "enum": [ - "InvoiceRead", - "InvoiceWrite", - "Introspection", - "CredentialsRead", - "CredentialsManage", - "EnforcementOperations", - "SubunitManage" - ], - "type": "string" - }, - "TestDataPermissionsGrantRequest": { - "required": [ - "authorizedIdentifier", - "contextIdentifier", - "permissions" - ], - "type": "object", - "properties": { - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TestDataContextIdentifier" - } - ] - }, - "authorizedIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TestDataAuthorizedIdentifier" - } - ] - }, - "permissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TestDataPermission" - } - } - }, - "additionalProperties": false - }, - "TestDataPermissionsRevokeRequest": { - "required": [ - "authorizedIdentifier", - "contextIdentifier" - ], - "type": "object", - "properties": { - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TestDataContextIdentifier" - } - ] - }, - "authorizedIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TestDataAuthorizedIdentifier" - } - ] - } - }, - "additionalProperties": false - }, - "ThirdSubjectIdentifierType": { - "enum": [ - "Nip", - "InternalId", - "VatUe", - "Other", - "None" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr. |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora podmiotu trzeciego |\n" - }, - "TokenAuthorIdentifierType": { - "enum": [ - "Nip", - "Pesel", - "Fingerprint" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n" - }, - "TokenAuthorIdentifierTypeIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/TokenAuthorIdentifierType" - } - ], - "description": "Typ identyfikatora.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n" - }, - "value": { - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false - }, - "TokenContextIdentifierType": { - "enum": [ - "Nip", - "InternalId", - "NipVatUe", - "PeppolId" - ], - "type": "string", - "description": "| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| InternalId | Identyfikator wewnętrzny. |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}`. |\n| PeppolId | Identyfikator dostawcy usług Peppol. |\n" - }, - "TokenContextIdentifierTypeIdentifier": { - "required": [ - "type", - "value" - ], - "type": "object", - "properties": { - "type": { - "allOf": [ - { - "$ref": "#/components/schemas/TokenContextIdentifierType" - } - ], - "description": "Typ identyfikatora.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| InternalId | Identyfikator wewnętrzny. |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}`. |\n| PeppolId | Identyfikator dostawcy usług Peppol. |\n" - }, - "value": { - "type": "string", - "description": "Wartość identyfikatora." - } - }, - "additionalProperties": false - }, - "TokenInfo": { - "required": [ - "token", - "validUntil" - ], - "type": "object", - "properties": { - "token": { - "type": "string", - "description": "Token w formacie JWT." - }, - "validUntil": { - "type": "string", - "description": "Data ważności tokena.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "TokenPermissionType": { - "enum": [ - "InvoiceRead", - "InvoiceWrite", - "CredentialsRead", - "CredentialsManage", - "SubunitManage", - "EnforcementOperations" - ], - "type": "string" - }, - "TokenStatusResponse": { - "required": [ - "authorIdentifier", - "contextIdentifier", - "dateCreated", - "description", - "referenceNumber", - "requestedPermissions", - "status" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny tokena KSeF." - }, - "authorIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenAuthorIdentifierTypeIdentifier" - } - ], - "description": "Identyfikator osoby która wygenerowała token." - }, - "contextIdentifier": { - "required": [ - "type", - "value" - ], - "allOf": [ - { - "$ref": "#/components/schemas/TokenContextIdentifierTypeIdentifier" - } - ], - "description": "Identyfikator kontekstu, w którym został wygenerowany token i do którego daje dostęp." - }, - "description": { - "maxLength": 256, - "minLength": 5, - "type": "string", - "description": "Opis tokena." - }, - "requestedPermissions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TokenPermissionType" - }, - "description": "Uprawnienia przypisane tokenowi." - }, - "dateCreated": { - "type": "string", - "description": "Data i czas utworzenia tokena.", - "format": "date-time" - }, - "lastUseDate": { - "type": "string", - "description": "Data ostatniego użycia tokena.", - "format": "date-time", - "nullable": true - }, - "status": { - "allOf": [ - { - "$ref": "#/components/schemas/AuthenticationTokenStatus" - } - ], - "description": "Status tokena.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n" - }, - "statusDetails": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Dodatkowe informacje na temat statusu, zwracane w przypadku błędów.", - "nullable": true - } - }, - "additionalProperties": false - }, - "TooManyRequestsResponse": { - "required": [ - "status" - ], - "type": "object", - "properties": { - "status": { - "required": [ - "code", - "description", - "details" - ], - "type": "object", - "properties": { - "code": { - "type": "integer", - "description": "Kod statusu HTTP odpowiadający błędowi. Zawsze ma wartość 429." - }, - "description": { - "type": "string", - "description": "Opis błędu zgodny z nazwą statusu HTTP." - }, - "details": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Lista szczegółowych informacji opisujących przyczynę przekroczenia limitu żądań oraz wskazówki dotyczące ponowienia żądania." - } - }, - "description": "Informacje o błędzie związanym z przekroczeniem limitu żądań." - } - }, - "example": { - "status": { - "code": 429, - "description": "Too Many Requests", - "details": [ - "Przekroczono limit 20 żądań na minutę. Spróbuj ponownie po 30 sekundach." - ] - } - } - }, - "UpoPageResponse": { - "required": [ - "downloadUrl", - "downloadUrlExpirationDate", - "referenceNumber" - ], - "type": "object", - "properties": { - "referenceNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/ReferenceNumber" - } - ], - "description": "Numer referencyjny strony UPO." - }, - "downloadUrl": { - "type": "string", - "description": "Adres do pobrania strony UPO. Link generowany jest przy każdym odpytaniu o status. \nDostęp odbywa się metodą `HTTP GET` i nie należy wysyłać tokenu dostępowego. \nLink nie podlega limitom API i wygasa po określonym czasie w `DownloadUrlExpirationDate`.\n\nOdpowiedź HTTP zawiera dodatkowe nagłówki:\n- `x-ms-meta-hash` – skrót SHA-256 dokumentu UPO, zakodowany w formacie Base64.", - "format": "uri" - }, - "downloadUrlExpirationDate": { - "type": "string", - "description": "Data i godzina wygaśnięcia adresu. Po tej dacie link `DownloadUrl` nie będzie już aktywny.", - "format": "date-time" - } - }, - "additionalProperties": false - }, - "UpoResponse": { - "required": [ - "pages" - ], - "type": "object", - "properties": { - "pages": { - "type": "array", - "items": { - "$ref": "#/components/schemas/UpoPageResponse" - }, - "description": "Lista stron UPO." - } - }, - "additionalProperties": false - } - }, - "securitySchemes": { - "Bearer": { - "type": "http", - "description": "Token dostępu uzyskany w wyniku operacji uwierzytelnienia.", - "scheme": "Bearer", - "bearerFormat": "JWT" - }, - "SessionToken": { - "type": "apiKey", - "name": "SessionToken", - "in": "header" - } - } - }, - "tags": [ - { - "name": "Aktywne sesje" - }, - { - "name": "Certyfikaty", - "description": "Certyfikat KSeF to cyfrowe poświadczenie tożsamości podmiotu, wydawane przez system KSeF na wniosek uwierzytelnionego podmiotu. \nCertyfikat ten może być wykorzystywany do:\n\n- uwierzytelniania się w systemie KSeF,\n- realizacji operacji w trybie offline, w tym wystawiania faktur bezpośrednio w aplikacji użytkownika.\n\n**Uwaga**: Wnioskowanie o certyfikat KSeF jest możliwe wyłącznie po uwierzytelnieniu z wykorzystaniem podpisu (XAdES). Uwierzytelnienie przy użyciu tokenu systemowego KSeF nie pozwala na złożenie wniosku." - }, - { - "name": "Certyfikaty klucza publicznego" - }, - { - "name": "Dane testowe", - "description": "API służy do tworzenia i zarządzania danymi testowymi, takimi jak podmioty, osoby fizyczne oraz uprawnienia. Możliwe do utworzenia podmioty to: organ egzekucyjny, grupa VAT oraz jednostki samorządu terytorialnego. W przypadku osób fizycznych można określić, czy dana osoba jest komornikiem. Funkcjonalność nadawania i odbierania uprawnień ma na celu odwzorowanie działania formularza ZAW-FA w środowisku testowym.\n\nWięcej informacji:\n- [Scenariusze testowe](https://github.com/CIRFMF/ksef-docs/blob/main/dane-testowe-scenariusze.md)" - }, - { - "name": "Limity i ograniczenia" - }, - { - "name": "Nadawanie uprawnień" - }, - { - "name": "Odbieranie uprawnień" - }, - { - "name": "Operacje" - }, - { - "name": "Pobieranie faktur" - }, - { - "name": "Status wysyłki i UPO" - }, - { - "name": "Tokeny KSeF", - "description": "Token KSeF to unikalny, generowany identyfikator uwierzytelniający, który — na równi z [kwalifikowanym podpisem elektronicznym](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#21-uwierzytelnianie-kwalifikowanym-podpisem-elektronicznym) — umożliwia [uwierzytelnienie](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#22-uwierzytelnianie-tokenem-ksef) się do API KSeF.\n\nToken KSeF jest wydawany z niezmiennym zestawem uprawnień określonych przy jego tworzeniu; każda modyfikacja tych uprawnień wymaga wygenerowania nowego tokena.\n> **Uwaga!**
\n> Token KSeF pełni rolę **poufnego sekretu** uwierzytelniającego — należy przechowywać go wyłącznie w zaufanym i bezpiecznym magazynie.\n\nWięcej informacji:\n- [Token KSeF](https://github.com/CIRFMF/ksef-docs/blob/main/tokeny-ksef.md)\n" - }, - { - "name": "Usługi Peppol", - "description": "" - }, - { - "name": "Uzyskiwanie dostępu", - "description": "Uwierzytelnianie w systemie KSeF API 2.0 jest obowiązkowym etapem, który należy wykonać przed dostępem do chronionych zasobów systemu. Proces ten oparty jest na **uzyskaniu tokenu dostępu** (```accessToken```) w formacie ```JWT```, który następnie wykorzystywany jest do autoryzacji operacji API.\n\n> Więcej informacji:\n> - [Uwierzytelnianie](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md)" - }, - { - "name": "Wysyłka interaktywna" - }, - { - "name": "Wysyłka wsadowa", - "description": "" - }, - { - "name": "Wyszukiwanie nadanych uprawnień" - } - ], - "x-tagGroups": [ - { - "name": "Uwierzytelnianie", - "tags": [ - "Uzyskiwanie dostępu", - "Aktywne sesje" - ] - }, - { - "name": "Limity i ograniczenia", - "tags": [ - "Limity i ograniczenia" - ] - }, - { - "name": "Szyfrowanie danych", - "tags": [ - "Certyfikaty klucza publicznego" - ] - }, - { - "name": "Faktury", - "tags": [ - "Wysyłka interaktywna", - "Wysyłka wsadowa", - "Status wysyłki i UPO", - "Pobieranie faktur" - ] - }, - { - "name": "Uprawnienia", - "tags": [ - "Nadawanie uprawnień", - "Odbieranie uprawnień", - "Wyszukiwanie nadanych uprawnień", - "Operacje" - ] - }, - { - "name": "Certyfikaty", - "tags": [ - "Certyfikaty" - ] - }, - { - "name": "Tokeny KSeF", - "tags": [ - "Tokeny KSeF" - ] - }, - { - "name": "Usługi Peppol", - "tags": [ - "Usługi Peppol" - ] - }, - { - "name": "Dane testowe", - "tags": [ - "Dane testowe" - ] - } - ] -} \ No newline at end of file diff --git a/src/ksef_client/openapi_models.py b/src/ksef_client/openapi_models.py index 3c7426b..2b74e64 100644 --- a/src/ksef_client/openapi_models.py +++ b/src/ksef_client/openapi_models.py @@ -1,4 +1,5 @@ # Generated from ksef-docs/open-api.json. Do not edit manually. +# ruff: noqa from __future__ import annotations from dataclasses import MISSING, dataclass, field, fields @@ -63,7 +64,7 @@ def from_dict(cls: type[T], data: dict[str, Any]) -> T: raise ValueError("data is None") type_map = _get_type_map(cls) kwargs: dict[str, Any] = {} - for model_field in fields(cls): + for model_field in fields(cls): # type: ignore[arg-type] json_key = model_field.metadata.get("json_key", model_field.name) if json_key in data: type_hint = type_map.get(model_field.name, Any) @@ -72,7 +73,7 @@ def from_dict(cls: type[T], data: dict[str, Any]) -> T: def to_dict(self, omit_none: bool = True) -> dict[str, Any]: result: dict[str, Any] = {} - for model_field in fields(self): + for model_field in fields(self): # type: ignore[arg-type] json_key = model_field.metadata.get("json_key", model_field.name) value = getattr(self, model_field.name) if omit_none and value is None: From 07fd209f1cefc890d937613f92803a337636a4aa Mon Sep 17 00:00:00 2001 From: smkc Date: Sun, 18 Jan 2026 17:42:32 +0100 Subject: [PATCH 5/7] fix: Update openapi_models.py to match latest generator changes (Ruff noqa placement) --- src/ksef_client/openapi_models.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ksef_client/openapi_models.py b/src/ksef_client/openapi_models.py index 2b74e64..e0a7879 100644 --- a/src/ksef_client/openapi_models.py +++ b/src/ksef_client/openapi_models.py @@ -1,5 +1,5 @@ -# Generated from ksef-docs/open-api.json. Do not edit manually. # ruff: noqa +# Generated from ksef-docs/open-api.json. Do not edit manually. from __future__ import annotations from dataclasses import MISSING, dataclass, field, fields @@ -64,7 +64,7 @@ def from_dict(cls: type[T], data: dict[str, Any]) -> T: raise ValueError("data is None") type_map = _get_type_map(cls) kwargs: dict[str, Any] = {} - for model_field in fields(cls): # type: ignore[arg-type] + for model_field in fields(cls): # type: ignore json_key = model_field.metadata.get("json_key", model_field.name) if json_key in data: type_hint = type_map.get(model_field.name, Any) @@ -73,7 +73,7 @@ def from_dict(cls: type[T], data: dict[str, Any]) -> T: def to_dict(self, omit_none: bool = True) -> dict[str, Any]: result: dict[str, Any] = {} - for model_field in fields(self): # type: ignore[arg-type] + for model_field in fields(self): # type: ignore json_key = model_field.metadata.get("json_key", model_field.name) value = getattr(self, model_field.name) if omit_none and value is None: From 7450b0188e6b054c01ac7e5fdc54402e74fc127a Mon Sep 17 00:00:00 2001 From: smkc Date: Sun, 18 Jan 2026 17:44:21 +0100 Subject: [PATCH 6/7] fix(tools): Auto-fix import sorting in check_coverage.py to satisfy Ruff --- tools/check_coverage.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tools/check_coverage.py b/tools/check_coverage.py index 618cd89..6a4e575 100644 --- a/tools/check_coverage.py +++ b/tools/check_coverage.py @@ -7,7 +7,6 @@ from pathlib import Path - def normalize_path(path: str) -> str: # Replace {param} with {} to compare structure return re.sub(r"{[^}]+}", "{}", path) From 119982eb6a3dcfa363fc7cbe27f8b7e0a4d6414b Mon Sep 17 00:00:00 2001 From: smkc Date: Sun, 18 Jan 2026 17:51:37 +0100 Subject: [PATCH 7/7] feat(ci): Enhance coverage check with Deprecation and Status Code validation - Updated check_coverage.py to verify success codes and deprecation status. - Fixed missing expected_status={204} in certificates.revoke_certificate. --- src/ksef_client/clients/certificates.py | 2 + tools/check_coverage.py | 69 +++++++++++++++++++++++++ 2 files changed, 71 insertions(+) diff --git a/src/ksef_client/clients/certificates.py b/src/ksef_client/clients/certificates.py index ba9c20c..1e90af7 100644 --- a/src/ksef_client/clients/certificates.py +++ b/src/ksef_client/clients/certificates.py @@ -67,6 +67,7 @@ def revoke_certificate( f"/certificates/{certificate_serial_number}/revoke", json=request_payload, access_token=access_token, + expected_status={204}, ) @@ -134,4 +135,5 @@ async def revoke_certificate( f"/certificates/{certificate_serial_number}/revoke", json=request_payload, access_token=access_token, + expected_status={204}, ) diff --git a/tools/check_coverage.py b/tools/check_coverage.py index 6a4e575..780404c 100644 --- a/tools/check_coverage.py +++ b/tools/check_coverage.py @@ -24,6 +24,8 @@ class EndpointSpec: normalized_path: str path_params: set[str] query_params: set[str] + deprecated: bool + success_codes: set[int] @dataclass @@ -35,6 +37,7 @@ class ImplementedEndpoint: detected_path_vars: set[str] # Parameters passed to params={} argument detected_query_vars: set[str] + expected_status: set[int] file_path: str line_no: int @@ -59,12 +62,20 @@ def get_openapi_specs(openapi_path: Path) -> dict[tuple[str, str], EndpointSpec] if param.get("in") == "query": query_params.add(param["name"]) + deprecated = details.get("deprecated", False) + success_codes = set() + for code_str in details.get("responses", {}): + if code_str.startswith("2") and code_str.isdigit(): + success_codes.add(int(code_str)) + spec = EndpointSpec( method=method, path=path, normalized_path=norm_path, path_params=path_params, query_params=query_params, + deprecated=deprecated, + success_codes=success_codes, ) specs[(method, norm_path)] = spec return specs @@ -107,6 +118,7 @@ def _analyze_request_call(self, node: ast.Call): # Extract Query Params detected_query_vars = self._extract_query_params(node) + expected_status = self._extract_expected_status(node) self.found_endpoints.append( ImplementedEndpoint( @@ -115,6 +127,7 @@ def _analyze_request_call(self, node: ast.Call): normalized_path=normalized_path, detected_path_vars=detected_path_vars, detected_query_vars=detected_query_vars, + expected_status=expected_status, file_path=self.filename, line_no=node.lineno, ) @@ -168,6 +181,45 @@ def _extract_query_params(self, node: ast.Call) -> set[str]: # For now, we only statically analyze inline dict definitions or assume manual review if dynamic return found_keys + def _extract_expected_status(self, node: ast.Call) -> set[int]: + # Default is {200} if not specified + default_status = {200} + + status_keywords = [kw for kw in node.keywords if kw.arg == "expected_status"] + if not status_keywords: + return default_status + + val = status_keywords[0].value + + # Parse set: {200, 201} + if isinstance(val, ast.Set): + result = set() + for el in val.elts: + if isinstance(el, ast.Constant) and isinstance(el.value, int): + result.add(el.value) + return result + + # Parse list/tuple: [200, 202] + if isinstance(val, (ast.List, ast.Tuple)): + result = set() + for el in val.elts: + if isinstance(el, ast.Constant) and isinstance(el.value, int): + result.add(el.value) + return result + + # Parse constant: 200 (if passed as single int, though type hint says set) + if isinstance(val, ast.Constant) and isinstance(val.value, int): + return {val.value} + + # If passed as None, treat as default check (usually 200) + if isinstance(val, ast.Constant) and val.value is None: + return default_status + + # If dynamic variable, we can't infer easily -> return empty set or default? + # Let's return default to avoid noise, or empty to skip check. + # Returning empty set effectively disables the check for this call. + return set() + def get_implemented_endpoints_deep(source_dir: Path) -> list[ImplementedEndpoint]: endpoints = [] @@ -268,6 +320,23 @@ def main(): ) print(f" Allowed: {spec.query_params} at {impl.file_path}:{impl.line_no}") + # Check Deprecated + if spec.deprecated: + print(f" [WARN] Endpoint is DEPRECATED: {impl.method} {spec.path} at {impl.file_path}:{impl.line_no}") + + # Check Status Codes + # We warn if OpenAPI declares success codes that are NOT covered by expect_status + # Example: API returns 201, code expects {200} -> Mismatch + if impl.expected_status and spec.success_codes: + # We want expected_status to match success_codes exactly? Or be a superset? + # Usually: expected_status should contain ALL success_codes returned by API. + # If API returns 201 and we only handle 200, client might throw error. + missing_codes = spec.success_codes - impl.expected_status + if missing_codes: + print(f" [WARN] Status code mismatch for {impl.method} {spec.path}") + print(f" OpenAPI returns: {spec.success_codes}") + print(f" Code expects: {impl.expected_status}") + if issues_found: print("\nCoverage check FAILED.") exit(1)