{ "openapi": "3.0.4", "info": { "title": "KSeF API TR", "description": "**Wersja API:** 2.6.1 (build 2.6.1-tr-20260716.1+834cace82749bfafdd4c3d3870c3473c1e5680d2)
\n**Klucze publiczne** Ministerstwa Finansów (dla danego środowiska): [Pobierz klucze](#tag/Certyfikaty-klucza-publicznego)
\n**Historia zmian:** [Changelog](https://github.com/CIRFMF/ksef-api/blob/main/api-changelog.md)
\n**Rozszerzona dokumentacja API:** [ksef-docs](https://github.com/CIRFMF/ksef-api/tree/main)\n\n**Adres serwera API:**\n- Środowisko DEMO: `https://api-demo.ksef.mf.gov.pl/v2`\n", "version": "v2" }, "servers": [ { "url": "https://api-demo.ksef.mf.gov.pl/v2", "description": "Środowisko DEMO" } ], "paths": { "/auth/sessions": { "get": { "tags": [ "Aktywne sesje" ], "summary": "Pobranie listy aktywnych sesji", "description": "Zwraca listę aktywnych sesji uwierzytelnienia.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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", "authenticationMethodInfo": { "category": "XadesSignature", "code": "xades.qualified-seal", "displayName": "Pieczęć kwalifikowana" }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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`.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "204": { "description": "No Content", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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.**\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "parameters": [ { "name": "referenceNumber", "in": "path", "description": "Numer referencyjny sesji uwierzytelnienia.", "required": true, "schema": { "$ref": "#/components/schemas/ReferenceNumber" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateLimitsResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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-api/blob/main/certyfikaty-KSeF.md#2-pobranie-danych-do-wniosku-certyfikacyjnego)\n> - [Przygotowanie wniosku](https://github.com/CIRFMF/ksef-api/blob/main/certyfikaty-KSeF.md#3-przygotowanie-csr-certificate-signing-request)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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-api/blob/main/certyfikaty-KSeF.md#4-wys%C5%82anie-wniosku-certyfikacyjnego)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/certificates/enrollments/{referenceNumber}": { "get": { "tags": [ "Certyfikaty" ], "summary": "Pobranie statusu przetwarzania wniosku certyfikacyjnego\n\nStatus wniosku jest dostępny przez 30 dni.", "description": "Zwraca informacje o statusie wniosku certyfikacyjnego.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "parameters": [ { "name": "referenceNumber", "in": "path", "description": "Numer referencyjny wniosku certyfikacyjnego", "required": true, "schema": { "$ref": "#/components/schemas/ReferenceNumber" } } ], "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } } } } }, "410": { "description": "Gone", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GoneProblemDetails" }, "example": { "title": "Gone", "status": 410, "instance": "{{uri_path}}", "detail": "Operacja wygasła i nie jest już dostępna.", "timestamp": "2025-07-11T12:23:56.0154302+00:00", "traceId": "673843e023c432286660bc0501a3af44" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "requestBody": { "description": "", "content": { "application/json": { "schema": { "required": [ "certificateSerialNumbers" ], "allOf": [ { "$ref": "#/components/schemas/RetrieveCertificatesRequest" } ] }, "example": { "certificateSerialNumbers": [ "0321C82DA41B4362", "0321F21DA462A362" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/certificates/{certificateSerialNumber}/revoke": { "post": { "tags": [ "Certyfikaty" ], "summary": "Unieważnienie certyfikatu", "description": "Unieważnia certyfikat o podanym numerze seryjnym. Operacja nie jest dostępna dla podmiotu uwierzytelnionego tokenem KSeF.\n\nPodmiot może unieważnić wyłącznie certyfikat wygenerowany na jego identyfikator uwierzytelnienia \nlub na identyfikator powiązany w ramach powiązania NIP–PESEL.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "parameters": [ { "name": "certificateSerialNumber", "in": "path", "description": "Numer seryjny certyfikatu (w formacie szesnastkowym).", "required": true, "schema": { "maxLength": 16, "minLength": 16, "pattern": "^[0-9A-F]{16}$", "type": "string" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RevokeCertificateRequest" } ] } } } }, "responses": { "204": { "description": "No Content", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCertificate" } }, "example": [ { "certificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwocTwdNgt2+PXJ2fcB7k1kn5eFUTXBeep9pH...", "certificateId": "35k6IVMTxUPZKQdg4Fbx36T5/v3aoJK5hIY7sS7mt3U=", "publicKeyId": "QIoAK/Yc3s27Z4t3SZY4Mhp8JNLH7Vl4N3lNlJAEig8=", "validFrom": "2024-07-11T12:23:56.0154302+00:00", "validTo": "2028-07-11T12:23:56.0154302+00:00", "usage": [ "KsefTokenEncryption" ] }, { "certificate": "MIIGWDCCBECgAwIBAgIQe4NvS/i3yyDCcnaXiiC6BTANBgkqhkiG9w0BAQsFADBOMQswCQYDVQQGEwJa...", "certificateId": "sivtxip78UcnFLzXVsAz2FE1XIpLpySOZsn/f99fDmI=", "publicKeyId": "tmtCidSRzR4fvNpLU5hMOM6FzamxJf0BBR8IkXIAwsY=", "validFrom": "2024-07-11T12:23:56.0154302+00:00", "validTo": "2028-07-11T12:23:56.0154302+00:00", "usage": [ "SymmetricKeyEncryption" ] } ] } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectiveSubjectLimits" }, "example": { "enrollment": { "maxEnrollments": 12 }, "certificate": { "maxCertificates": 6 } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectiveApiRateLimits" }, "example": { "onlineSession": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "batchSession": { "perSecond": 10, "perMinute": 20, "perHour": 60 }, "invoiceSend": { "perSecond": 10, "perMinute": 30, "perHour": 180 }, "invoiceStatus": { "perSecond": 30, "perMinute": 120, "perHour": 1200 }, "sessionList": { "perSecond": 5, "perMinute": 10, "perHour": 60 }, "sessionInvoiceList": { "perSecond": 10, "perMinute": 20, "perHour": 200 }, "sessionMisc": { "perSecond": 10, "perMinute": 120, "perHour": 1200 }, "invoiceMetadata": { "perSecond": 8, "perMinute": 16, "perHour": 20 }, "invoiceExport": { "perSecond": 8, "perMinute": 16, "perHour": 20 }, "invoiceExportStatus": { "perSecond": 10, "perMinute": 60, "perHour": 600 }, "invoiceDownload": { "perSecond": 8, "perMinute": 16, "perHour": 64 }, "other": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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-api/blob/main/uprawnienia.md#nadawanie-uprawnie%C5%84-osobom-fizycznym-do-pracy-w-ksef)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#nadanie-podmiotom-uprawnie%C5%84-do-obs%C5%82ugi-faktur)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-podmiotowych)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-w-spos%C3%B3b-po%C5%9Bredni)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-podrz%C4%99dnego)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-unijnego)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-reprezentanta-podmiotu-unijnego)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84-podmiotowych)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\n\n**Wymagane uprawnienia**: `CredentialsManage`.", "parameters": [ { "name": "permissionId", "in": "path", "description": "Id uprawnienia.", "required": true, "schema": { "$ref": "#/components/schemas/PermissionId" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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ń. \n\nStatus operacji jest dostępny przez 30 dni.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "parameters": [ { "name": "referenceNumber", "in": "path", "description": "Numer referencyjny operacji nadania lub odbierania uprawnień.", "required": true, "schema": { "$ref": "#/components/schemas/ReferenceNumber" } } ], "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionsOperationStatusResponse" }, "example": { "status": { "code": 200, "description": "Operacja zakończona sukcesem" } } } } }, "410": { "description": "Gone", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GoneProblemDetails" }, "example": { "title": "Gone", "status": 410, "instance": "{{uri_path}}", "detail": "Operacja wygasła i nie jest już dostępna.", "timestamp": "2025-07-11T12:23:56.0154302+00:00", "traceId": "673843e023c432286660bc0501a3af44" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 8 | 16 | 64 | invoiceDownload\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 8, "perMinute": 16, "perHour": 64 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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.3881234+00:00", "acquisitionDate": "2025-08-28T09:22:56.3881234+00:00", "permanentStorageDate": "2025-08-28T09:23:01.388123+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.3881234+00:00", "acquisitionDate": "2025-08-28T10:23:56.3881234+00:00", "permanentStorageDate": "2025-08-28T10:24:01.388123+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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 8 | 16 | 20 | invoiceMetadata\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 8, "perMinute": 16, "perHour": 20 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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=", "publicKeyId": "tmtCidSRzR4fvNpLU5hMOM6FzamxJf0BBR8IkXIAwsY=" }, "onlyMetadata": false, "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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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| 21470 | Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz. | Klucz o identyfikatorze {keyId} nie jest wspierany. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 8 | 16 | 20 | invoiceExport\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 8, "perMinute": 16, "perHour": 20 }, "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\nStatus eksportu paczki faktur jest dostępny przez 7 dni.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } } } } }, "410": { "description": "Gone", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GoneProblemDetails" }, "example": { "title": "Gone", "status": 410, "instance": "{{uri_path}}", "detail": "Operacja wygasła i nie jest już dostępna.", "timestamp": "2025-07-11T12:23:56.0154302+00:00", "traceId": "673843e023c432286660bc0501a3af44" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 60 | 600 | invoiceExportStatus\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 60, "perHour": 600 }, "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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 5 | 10 | 60 | sessionList\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 5, "perMinute": 10, "perHour": 60 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 120 | 1200 | sessionMisc\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 120, "perHour": 1200 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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.015432+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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 20 | 200 | sessionInvoiceList\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 20, "perHour": 200 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 30 | 120 | 1200 | invoiceStatus\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 30, "perMinute": 120, "perHour": 1200 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 20 | 200 | sessionInvoiceList\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 20, "perHour": 200 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 120 | 1200 | sessionMisc\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 120, "perHour": 1200 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 120 | 1200 | sessionMisc\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 120, "perHour": 1200 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 120 | 1200 | sessionMisc\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 120, "perHour": 1200 }, "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`.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } }, "get": { "tags": [ "Tokeny KSeF" ], "summary": "Pobranie listy wygenerowanych tokenów", "description": "Zwraca listę metadanych tokenów. Zakres wyników zależy od sposobu uwierzytelnienia oraz uprawnień podmiotu wywołującego.\n\nJeżeli podmiot posiada uprawnienie **CredentialsManage** lub **CredentialsRead**, \nusługa zwraca wszystkie tokeny wygenerowane w danym kontekście niezależnie od metody uwierzytelnienia. \n\nJeżeli podmiot nie posiada żadnego z powyższych uprawnień, zakres wyników jest ograniczony: \n- Dla podmiotu uwierzytelnionego tokenem zwracany jest wyłącznie token użyty do uwierzytelnienia.\n- Dla pozostałych metod uwierzytelnienia zwracane są tokeny, \nktórych autorem jest wywołujący podmiot – z uwzględnieniem powiązania NIP–PESEL.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "x-sort": [ { "field": "dateCreated", "direction": "Desc" } ] } }, "/tokens/{referenceNumber}": { "get": { "tags": [ "Tokeny KSeF" ], "summary": "Pobranie statusu tokena", "description": "\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "parameters": [ { "name": "referenceNumber", "in": "path", "description": "Numer referencyjny tokena KSeF.", "required": true, "schema": { "$ref": "#/components/schemas/ReferenceNumber" } } ], "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } }, "delete": { "tags": [ "Tokeny KSeF" ], "summary": "Unieważnienie tokena", "description": "Unieważnia token o podanym numerze referencyjnym. Zakres tokenów dostępnych do unieważnienia zależy od sposobu uwierzytelnienia oraz uprawnień podmiotu wywołującego.\n\nJeżeli podmiot posiada uprawnienie **CredentialsManage**, \nmoże unieważnić dowolny aktywny token w danym kontekście niezależnie od metody uwierzytelnienia.\n\nJeżeli podmiot nie posiada powyższego uprawnienia, zakres unieważnienia jest ograniczony: \n- Dla podmiotu uwierzytelnionego tokenem możliwe jest unieważnienie wyłącznie tokena użytego do uwierzytelnienia. \n- Dla pozostałych metod uwierzytelnienia podmiot może unieważnić tokeny, \nktórych jest autorem – z uwzględnieniem powiązania NIP–PESEL.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "parameters": [ { "name": "referenceNumber", "in": "path", "description": "Numer referencyjny tokena KSeF.", "required": true, "schema": { "$ref": "#/components/schemas/ReferenceNumber" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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, "clientIp": "127.0.0.1" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "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-api/blob/main/uwierzytelnianie.md#1-przygotowanie-dokumentu-xml-authtokenrequest)\n> - [Podpis dokumentu XML](https://github.com/CIRFMF/ksef-api/blob/main/uwierzytelnianie.md#2-podpisanie-dokumentu-xades)\n> - Obsługiwane schematy:\n> - [auth v2.0](https://github.com/CIRFMF/ksef-api/blob/main/auth/schemy/schemat_auth_v2-0.xsd)\n> - [auth v2.1](https://github.com/CIRFMF/ksef-api/blob/main/auth/schemy/schemat_auth_v2-1.xsd)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "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)**.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "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": "...", "publicKeyId": "QIoAK/Yc3s27Z4t3SZY4Mhp8JNLH7Vl4N3lNlJAEig8=" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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| 21470 | Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz. | Klucz o identyfikatorze {keyId} nie jest wspierany. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "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.\nOperacja jest dostępna przez 7 dni.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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})" } } } } } } }, "410": { "description": "Gone", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GoneProblemDetails" }, "example": { "title": "Gone", "status": 410, "instance": "{{uri_path}}", "detail": "Operacja wygasła i nie jest już dostępna.", "timestamp": "2025-07-11T12:23:56.0154302+00:00", "traceId": "673843e023c432286660bc0501a3af44" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "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.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "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`.\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).", "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "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-api/blob/main/sesja-interaktywna.md#1-otwarcie-sesji)\n> - [Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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==", "publicKeyId": "tmtCidSRzR4fvNpLU5hMOM6FzamxJf0BBR8IkXIAwsY=" } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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| 21470 | Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz. | Klucz o identyfikatorze {keyId} nie jest wspierany. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | onlineSession\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/sesja-interaktywna.md#2-wys%C5%82anie-faktury)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 180 | invoiceSend\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 180 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | onlineSession\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/sesja-wsadowa.md)\n> - [Klucz publiczny Ministerstwa Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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==", "publicKeyId": "tmtCidSRzR4fvNpLU5hMOM6FzamxJf0BBR8IkXIAwsY=" }, "offlineMode": false } } } }, "responses": { "201": { "description": "Created", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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| 21470 | Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz. | Klucz o identyfikatorze {keyId} nie jest wspierany. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 20 | 60 | batchSession\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 20, "perHour": 60 }, "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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 20 | 60 | batchSession\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 20, "perHour": 60 }, "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-api/blob/main/uprawnienia.md#pobranie-listy-w%C5%82asnych-uprawnie%C5%84)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-do-pracy-w-ksef-nadanych-osobom-fizycznym-lub-podmiotom)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-administrator%C3%B3w-jednostek-i-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "x-sort": [ { "field": "startDate", "direction": "Desc" }, { "field": "id", "direction": "Asc" } ], "x-required-permissions": [ "CredentialsManage", "CredentialsRead", "SubunitManage" ] } }, "/permissions/query/entities/grants": { "post": { "tags": [ "Wyszukiwanie nadanych uprawnień" ], "summary": "Pobranie listy uprawnień do obsługi faktur w bieżącym kontekście", "description": " Metoda pozwala na odczytanie otrzymanych uprawnień do obsługi faktur w bieżącym kontekście logowania. \n\n W odpowiedzi przekazywane są następujące uprawnienia: \n - nadane podmiotowi do obsługi faktur przez inny podmiot \n\n Uprawnienia zwracane przez operację obejmują: \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \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\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-api/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-do-obs%C5%82ugi-faktur-w-bie%C5%BC%C4%85cym-kontek%C5%9Bcie)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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 } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityPermissionsQueryRequest" } ] }, "example": { "contextIdentifier": { "type": "Nip", "value": "3568707925" } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryEntityPermissionsResponse" }, "example": { "permissions": [ { "id": "0c9a72e8-f344-457f-9c16-7c640eb60242", "contextIdentifier": { "type": "Nip", "value": "3568707925" }, "permissionScope": "InvoiceWrite", "description": "Opis uprawnienia", "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "x-sort": [ { "field": "startDate", "direction": "Desc" }, { "field": "id", "direction": "Asc" } ], "x-required-permissions": [ "CredentialsManage", "CredentialsRead" ] } }, "/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-api/blob/main/uprawnienia.md#pobranie-listy-r%C3%B3l-podmiotu)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#pobranie-listy-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-podmiotowych-do-obs%C5%82ugi-faktur)\n\n**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "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-api/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**Headers:**\n\n`X-Error-Format: problem-details` - ustawienie tego nagłówka powoduje zwracanie błędów w formacie **Problem Details** (`application/problem+json`).\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", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "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" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestProblemDetails" } } }, "x-summary": "Bad Request" }, "429": { "description": "| | req / s | req / min | req / h | grupa\n| --- | --- | --- | --- | --- |\n| **Limity liczby żądań** | 10 | 30 | 120 | other\n", "headers": { "Retry-After": { "schema": { "$ref": "#/components/schemas/RetryAfter" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsProblemDetails" } } }, "x-summary": "Too Many Requests" }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ], "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 }, "x-sort": [ { "field": "startDate", "direction": "Desc" }, { "field": "id", "direction": "Asc" } ], "x-required-permissions": [ "CredentialsManage", "CredentialsRead", "VatUeManage" ] } } }, "components": { "schemas": { "AllowedIps": { "type": "object", "properties": { "ip4Addresses": { "maximum": 10, "minimum": 0, "type": "array", "items": { "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$", "type": "string" }, "description": "Lista adresów IPv4 w notacji dziesiętnej kropkowanej, np. `192.168.0.10`.", "nullable": true }, "ip4Ranges": { "maximum": 10, "minimum": 0, "type": "array", "items": { "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])-((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$", "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": { "maximum": 10, "minimum": 0, "type": "array", "items": { "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])/(0|[1-9]|[12][0-9]|3[0-2])$", "type": "string" }, "description": "Lista adresów IPv4 w notacji CIDR, np. `172.16.0.0/16`.", "nullable": true } } }, "AmountType": { "enum": [ "Brutto", "Netto", "Vat" ], "type": "string" }, "ApiError": { "required": [ "code", "description" ], "type": "object", "properties": { "code": { "type": "integer", "description": "Kod błędu.", "format": "int32" }, "description": { "type": "string", "description": "Ogólny opis błędu odpowiadający danemu kodowi." }, "details": { "type": "array", "items": { "type": "string" }, "description": "Lista szczegółowych komunikatów opisujących konkretny błąd.\nMoże zawierać wiele wpisów dla jednego kodu błędu.", "nullable": true } } }, "AuthenticationChallengeResponse": { "required": [ "challenge", "clientIp", "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" }, "clientIp": { "type": "string", "description": "Adres IP klienta." } } }, "AuthenticationContextIdentifier": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/AuthenticationContextIdentifierType" } ], "description": "Typ identyfikatora" }, "value": { "type": "string", "description": "Wartość identyfikatora" } } }, "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." } } }, "AuthenticationListItem": { "required": [ "authenticationMethod", "authenticationMethodInfo", "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", "deprecated": true }, "authenticationMethodInfo": { "required": [ "category", "code", "displayName" ], "allOf": [ { "$ref": "#/components/schemas/AuthenticationMethodInfo" } ], "description": "Użyta metoda uwierzytelnienia." }, "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| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe szyfrowanie tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe kodowanie tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nie może być użyty w kontekście {contextIdentifier} |\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 | Certyfikat zawieszony |\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 } } }, "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." } } }, "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" }, "AuthenticationMethodCategory": { "enum": [ "XadesSignature", "NationalNode", "Token", "Other" ], "type": "string", "description": "| Wartość | Opis |\n| --- | --- |\n| XadesSignature | Uwierzytelnienie podpisem Xades. |\n| NationalNode | Uwierzytelnienie za pomocą Węzła Krajowego (login.gov.pl). |\n| Token | Uwierzytelnienie tokenem. |\n| Other | Uwierzytelnienie inną metodą. |\n" }, "AuthenticationMethodInfo": { "required": [ "category", "code", "displayName" ], "type": "object", "properties": { "category": { "allOf": [ { "$ref": "#/components/schemas/AuthenticationMethodCategory" } ], "description": "Kategoria metody uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| XadesSignature | Uwierzytelnienie podpisem Xades. |\n| NationalNode | Uwierzytelnienie za pomocą Węzła Krajowego (login.gov.pl). |\n| Token | Uwierzytelnienie tokenem. |\n| Other | Uwierzytelnienie inną metodą. |\n" }, "code": { "type": "string", "description": "Kod metody uwierzytelnienia." }, "displayName": { "type": "string", "description": "Nazwa metody uwierzytelnienia do wyświetlenia użytkownikowi.", "readOnly": true } } }, "AuthenticationOperationStatusResponse": { "required": [ "authenticationMethod", "authenticationMethodInfo", "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", "deprecated": true }, "authenticationMethodInfo": { "required": [ "category", "code", "displayName" ], "allOf": [ { "$ref": "#/components/schemas/AuthenticationMethodInfo" } ], "description": "Użyta metoda uwierzytelnienia." }, "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| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe szyfrowanie tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowe kodowanie tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nie może być użyty w kontekście {contextIdentifier} |\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 | Certyfikat zawieszony |\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 } } }, "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." } } }, "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-api/blob/main/uwierzytelnianie.md#5-od%C5%9Bwie%C5%BCenie-tokena-dost%C4%99powego-accesstoken)" } } }, "AuthorizationPolicy": { "type": "object", "properties": { "allowedIps": { "allOf": [ { "$ref": "#/components/schemas/AllowedIps" } ], "description": "Lista dozwolonych adresów IP.", "nullable": true } } }, "BadRequestProblemDetails": { "required": [ "detail", "errors", "instance", "status", "timestamp", "title", "traceId" ], "type": "object", "properties": { "title": { "type": "string", "description": "Bad Request" }, "status": { "type": "integer", "description": "400", "format": "int32" }, "instance": { "type": "string", "description": "URI identyfikujące konkretne wystąpienie błędu." }, "detail": { "type": "string", "description": "Ogólny opis problemu." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ApiError" }, "description": "Lista błędów powiązanych z żądaniem." }, "timestamp": { "type": "string", "description": "Data i czas wystąpienia błędu w UTC.", "format": "date-time" }, "traceId": { "type": "string", "description": "Identyfikator śledzenia błędu." } }, "example": { "title": "Bad Request", "status": 400, "instance": "{{uri_path}}", "detail": "Żądanie jest nieprawidłowe.", "errors": [ { "code": 21405, "description": "Błąd walidacji danych wejściowych.", "details": [ "Wskazany kod formularza nie jest wspierany." ] }, { "code": 21157, "description": "Nieprawidłowy rozmiar części pakietu.", "details": [ "Rozmiar części 1 przekroczył dozwolony rozmiar 100MB." ] } ], "timestamp": "2025-07-11T12:23:56.0154302+00:00", "traceId": "673843e023c432286660bc0501a3af44" } }, "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." }, "compressionType": { "allOf": [ { "$ref": "#/components/schemas/CompressionType" } ], "description": "Typ kompresji pliku paczki. Obsługiwane typy: Zip oraz TarGz. Domyślna kompresja to Zip.", "nullable": true }, "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." } } }, "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." } } }, "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" } } }, "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" } } }, "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 } } }, "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": { "maxLength": 16, "minLength": 16, "pattern": "^[0-9A-F]{16}$", "type": "string", "description": "Numer seryjny wygenerowanego certyfikatu (w formacie szesnastkowym). \nZwracany w przypadku prawidłowego przeprocesowania wniosku certyfikacyjnego.", "nullable": true } } }, "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" } } }, "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." } }, "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": { "maxLength": 16, "minLength": 16, "pattern": "^[0-9A-F]{16}$", "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" } } }, "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." } }, "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" }, "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 } } }, "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" }, "CompressionType": { "enum": [ "Zip", "TarGz" ], "type": "string" }, "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" } } }, "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." } } }, "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." } } }, "EffectiveSubjectLimits": { "type": "object", "properties": { "enrollment": { "allOf": [ { "$ref": "#/components/schemas/EnrollmentEffectiveSubjectLimits" } ], "nullable": true }, "certificate": { "allOf": [ { "$ref": "#/components/schemas/CertificateEffectiveSubjectLimits" } ], "nullable": true } } }, "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" }, "publicKeyId": { "maxLength": 44, "minLength": 44, "type": "string", "description": "Identyfikator klucza publicznego użytego do szyfrowania.", "format": "byte", "nullable": true } } }, "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 } } }, "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" } } }, "EnrollmentEffectiveSubjectLimits": { "type": "object", "properties": { "maxEnrollments": { "type": "integer", "format": "int32" } } }, "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" } } }, "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." } } }, "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 } } }, "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." } }, "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." } }, "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." } }, "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." } }, "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." } } }, "EntityDetails": { "required": [ "fullName" ], "type": "object", "properties": { "fullName": { "maxLength": 90, "minLength": 5, "type": "string", "description": "Pełna nazwa podmiotu." } } }, "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" } } }, "EntityPermissionItem": { "required": [ "canDelegate", "contextIdentifier", "description", "id", "permissionScope", "startDate" ], "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/PermissionId" } ], "description": "Identyfikator uprawnienia." }, "contextIdentifier": { "required": [ "type", "value" ], "allOf": [ { "$ref": "#/components/schemas/EntityPermissionsContextIdentifier" } ], "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}` |" }, "permissionScope": { "allOf": [ { "$ref": "#/components/schemas/EntityPermissionItemScope" } ], "description": "Rodzaj uprawnienia." }, "description": { "maxLength": 256, "minLength": 5, "type": "string", "description": "Opis 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." } } }, "EntityPermissionItemScope": { "enum": [ "InvoiceWrite", "InvoiceRead" ], "type": "string" }, "EntityPermissionType": { "enum": [ "InvoiceWrite", "InvoiceRead" ], "type": "string" }, "EntityPermissionsContextIdentifier": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/EntityPermissionsContextIdentifierType" } ], "description": "Typ identyfikatora." }, "value": { "maxLength": 16, "minLength": 10, "type": "string", "description": "Wartość identyfikatora." } }, "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}` |" }, "EntityPermissionsContextIdentifierType": { "enum": [ "Nip", "InternalId" ], "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." } } }, "EntityPermissionsQueryRequest": { "type": "object", "properties": { "contextIdentifier": { "required": [ "type", "value" ], "allOf": [ { "$ref": "#/components/schemas/EntityPermissionsContextIdentifier" } ], "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 } } }, "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." } }, "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." } }, "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" } } }, "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." } }, "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." } }, "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." } } }, "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." } }, "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." } } }, "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" } } }, "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 } } }, "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." } }, "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." } } }, "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 } } }, "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." } }, "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 } } }, "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" } } }, "ExceptionResponse": { "type": "object", "properties": { "exception": { "allOf": [ { "$ref": "#/components/schemas/ExceptionInfo" } ], "nullable": true } }, "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" } }, "deprecated": true }, "ExportInvoicesResponse": { "required": [ "referenceNumber" ], "type": "object", "properties": { "referenceNumber": { "allOf": [ { "$ref": "#/components/schemas/ReferenceNumber" } ], "description": "Numer referencyjny eksportu faktur." } } }, "ForbiddenProblemDetails": { "required": [ "detail", "reasonCode", "status", "timestamp", "title" ], "type": "object", "properties": { "title": { "type": "string", "description": "Forbidden" }, "status": { "type": "integer", "description": "403", "format": "int32" }, "detail": { "type": "string", "description": "Szczegółowy opis przyczyny odmowy dostępu." }, "instance": { "type": "string", "description": "URI identyfikujące konkretne wystąpienie błędu.", "nullable": true }, "reasonCode": { "type": "string", "description": " Kod przyczyny odmowy dostępu.\n| Code | Opis | \n|------|-------------|\n| missing-permissions | Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście. | \n| ip-not-allowed | Żądanie pochodzi z adresu IP innego niż wskazany podczas uwierzytelnienia. | \n| insufficient-resource-access | Brak dostępu do wskazanego zasobu. | \n| auth-method-not-allowed | Ta operacja nie jest dostępna dla użytej metody uwierzytelnienia. | \n| security-service-blocked | Żądanie zostało zablokowane przez mechanizmy bezpieczeństwa. | \n| context-type-not-allowed | Operacja nie jest dostępna dla uwierzytelnionego typu kontekstu. |" }, "security": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Dodatkowe dane zależne od `reasonCode`.\n| Code | Security |\n|------| ------------ |\n| missing-permissions | requiredAnyOfPermissions: string[], presentPermissions: string[] |\n| ip-not-allowed | clientIp: string |\n| insufficient-resource-access ||\n| auth-method-not-allowed | authenticationMethodCategory: string |\n| security-service-blocked | incidentId: string, clientIp: string |\n| context-type-not-allowed | contextIdentifierType: string |", "nullable": true }, "traceId": { "type": "string", "description": "Identyfikator śledzenia błędu.", "nullable": true }, "timestamp": { "type": "string", "description": "Data i czas wystąpienia błędu w UTC.", "format": "date-time" } }, "example": { "title": "Forbidden", "status": 403, "detail": "Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście.", "instance": "{{uri_path}}", "reasonCode": "missing-permissions", "security": { "requiredAnyOfPermissions": [ "InvoiceRead", "InvoiceWrite" ], "presentPermissions": [ "CredentialsRead" ] }, "traceId": "673843e023c432286660bc0501a3af44", "timestamp": "2025-07-11T12:23:56.0154302+00:00" } }, "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ść" } } }, "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." } } }, "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." } } }, "GoneProblemDetails": { "required": [ "detail", "instance", "status", "timestamp", "title", "traceId" ], "type": "object", "properties": { "title": { "type": "string", "description": "Gone" }, "status": { "type": "integer", "description": "410", "format": "int32" }, "instance": { "type": "string", "description": "URI identyfikujące konkretne wystąpienie błędu." }, "detail": { "type": "string", "description": "Ogólny opis problemu." }, "timestamp": { "type": "string", "description": "Data i czas wystąpienia błędu w UTC.", "format": "date-time" }, "traceId": { "type": "string", "description": "Identyfikator śledzenia błędu." } } }, "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." } }, "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." } } }, "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." } }, "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 } }, "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" }, "publicKeyId": { "maxLength": 44, "minLength": 44, "type": "string", "description": "Identyfikator klucza publicznego użytego do szyfrowania tokena.", "format": "byte", "nullable": true }, "authorizationPolicy": { "allOf": [ { "$ref": "#/components/schemas/AuthorizationPolicy" } ], "description": "Polityka autoryzacji żądań przy każdym użyciu tokena dostępu.", "nullable": true } } }, "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." }, "onlyMetadata": { "type": "boolean", "description": "Określa, czy zwrócić tylko metadane faktur (plik _metadata.json bez faktur).", "default": false }, "filters": { "required": [ "subjectType", "dateRange" ], "allOf": [ { "$ref": "#/components/schemas/InvoiceQueryFilters" } ], "description": "Zestaw filtrów do wyszukiwania faktur." }, "compressionType": { "allOf": [ { "$ref": "#/components/schemas/CompressionType" } ], "description": "Typ kompresji. Obsługiwane typy: Zip oraz TarGz. Domyślna kompresja to Zip.", "nullable": true } } }, "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 } } }, "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 wyrażona w PLN.", "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 | (FA_RR) Podstawowa |\n| KorVatRr | (FA_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-api/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n| [PEF (3)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/PEF/Schemat_PEF(3)_v2-1.xsd) | 2-1 | PEF |\n| [PEF_KOR (3)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/PEF/Schemat_PEF_KOR(3)_v2-1.xsd) | 2-1 | PEF |\n| [FA_RR (1)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/RR/schemat_FA_RR(1)_v1-1E.xsd) | 1-1E | FA_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 } } }, "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" } } }, "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 } } }, "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 } } }, "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 } } }, "InvoiceMetadataThirdSubject": { "required": [ "identifier", "role" ], "type": "object", "properties": { "identifier": { "allOf": [ { "$ref": "#/components/schemas/InvoiceMetadataThirdSubjectIdentifier" } ], "description": "Identyfikator podmiotu trzeciego.\n| Type | Value |\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 |" }, "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" } } }, "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 } }, "description": "Identyfikator podmiotu trzeciego.\n| Type | Value |\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 |" }, "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 } } }, "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" } } }, "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 } } }, "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 } } }, "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 } } }, "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 filtrowane są faktury.\nMaksymalny dozwolony okres wynosi 3 miesiące w strefie UTC lub w strefie Europe/Warsaw (WAW).\n \nFormat daty:\n * Daty muszą być przekazane w formacie ISO 8601, np. `yyyy-MM-ddTHH:mm:ss`.\n * Dopuszczalne są następujące warianty:\n - z sufiksem `Z` (czas UTC),\n - z jawnym offsetem, np. `+01:00`, `+03:00`,\n - bez offsetu (interpretowane jako czas lokalny strefy Europe/Warsaw)." }, "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| FA_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 | (FA_RR) Podstawowa |\n| KorVatRr | (FA_RR) Korygująca |\n", "nullable": true }, "hasAttachment": { "type": "boolean", "description": "Czy faktura ma załącznik.", "nullable": true } } }, "InvoiceQueryFormType": { "enum": [ "FA", "PEF", "FA_RR" ], "type": "string", "description": "| Wartość | Opis |\n| --- | --- |\n| FA | Faktura VAT |\n| PEF | Faktura PEF |\n| FA_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 } } }, "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 | (FA_RR) Podstawowa |\n| KorVatRr | (FA_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." }, "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" } } }, "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-api/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n| [FA_RR (1)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/RR/schemat_FA_RR(1)_v1-1E.xsd) | 1-1E | FA_RR |\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 } } }, "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)." } } }, "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-api/blob/main/faktury/schemy/FA/schemat_FA(2)_v1-0E.xsd) | 1-0E | FA |\n| [FA (3)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd) | 1-0E | FA |\n| [PEF (3)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/PEF/Schemat_PEF(3)_v2-1.xsd) | 2-1 | PEF |\n| [PEF_KOR (3)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/PEF/Schemat_PEF_KOR(3)_v2-1.xsd) | 2-1 | PEF |\n| [FA_RR (1)](https://github.com/CIRFMF/ksef-api/blob/main/faktury/schemy/RR/schemat_FA_RR(1)_v1-1E.xsd) | 1-1E | FA_RR |\n" }, "encryption": { "required": [ "encryptedSymmetricKey", "initializationVector" ], "allOf": [ { "$ref": "#/components/schemas/EncryptionInfo" } ], "description": "Symetryczny klucz szyfrujący pliki XML, zaszyfrowany kluczem publicznym Ministerstwa Finansów." } } }, "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" } } }, "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." } } }, "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" } } }, "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." } } }, "PermissionsOperationResponse": { "required": [ "referenceNumber" ], "type": "object", "properties": { "referenceNumber": { "allOf": [ { "$ref": "#/components/schemas/ReferenceNumber" } ], "description": "Numer referencyjny operacji nadania lub odbierania uprawnień." } } }, "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. |" } } }, "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 } } }, "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." } } }, "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 } } }, "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 } } }, "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 } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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 } } }, "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 } }, "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." } }, "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." } }, "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." } } }, "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 |" } } }, "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." } }, "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 } }, "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" }, "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." } } }, "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." } }, "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." } }, "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 } } }, "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 } }, "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", "certificateId", "publicKeyId", "usage", "validFrom", "validTo" ], "type": "object", "properties": { "certificate": { "type": "string", "description": "Certyfikat klucza publicznego w formacie DER, zakodowany w formacie Base64.", "format": "byte" }, "certificateId": { "type": "string", "description": "Identyfikator certyfikatu.", "format": "byte" }, "publicKeyId": { "type": "string", "description": "Identyfikator klucza, używany jako selektor w wywołaniach, w których klient wskazuje, jakiego klucza publicznego użył do szyfrowania.", "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" } } }, "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": { "maxLength": 16, "minLength": 16, "pattern": "^[0-9A-F]{16}$", "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 } } }, "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." } } }, "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." } } }, "QueryEntityPermissionsResponse": { "required": [ "hasMore", "permissions" ], "type": "object", "properties": { "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/EntityPermissionItem" }, "description": "Lista odczytanych uprawnień." }, "hasMore": { "type": "boolean", "description": "Flaga informująca o dostępności kolejnej strony wyników." } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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." } } }, "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 } } }, "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": { "maxLength": 16, "minLength": 16, "pattern": "^[0-9A-F]{16}$", "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" } } }, "RetrieveCertificatesRequest": { "required": [ "certificateSerialNumbers" ], "type": "object", "properties": { "certificateSerialNumbers": { "maxItems": 10, "minItems": 1, "type": "array", "items": { "maxLength": 16, "minLength": 16, "pattern": "^[0-9A-F]{16}$", "type": "string" }, "description": "Numery seryjne certyfikatów do pobrania." } } }, "RetrieveCertificatesResponse": { "required": [ "certificates" ], "type": "object", "properties": { "certificates": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieveCertificatesListItem" }, "description": "Pobrane certyfikaty." } } }, "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 } } }, "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 } } }, "SendInvoiceResponse": { "required": [ "referenceNumber" ], "type": "object", "properties": { "referenceNumber": { "allOf": [ { "$ref": "#/components/schemas/ReferenceNumber" } ], "description": "Numer referencyjny faktury." } } }, "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 |- |" } } }, "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." } } }, "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 } } }, "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." } } }, "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" } } }, "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 } } }, "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" } } }, "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 } } }, "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." } }, "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" }, "SubordinateRoleSubordinateEntityIdentifierType": { "enum": [ "Nip" ], "type": "string" }, "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" } } }, "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." } }, "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." } }, "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." } }, "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." } } }, "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 } } }, "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." } }, "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." } }, "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" }, "SystemWarning": { "type": "string", "description": "Ostrzeżenie techniczne dla systemu integratora. Ostrzeżenie nie wpływa na bieżący wynik operacji. Wartość nagłówka jest normalizowana z użyciem ASCII folding.\n\nFormat:\n`[code]: message | [code]: message`\n\nRegex pojedynczego ostrzeżenia: `\\[(?[^\\]]+)\\]: (?[^|]+)`" }, "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." } } }, "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." } } }, "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" } } }, "TokenPermissionType": { "enum": [ "InvoiceRead", "InvoiceWrite", "CredentialsRead", "CredentialsManage", "SubunitManage", "EnforcementOperations", "Introspection" ], "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 } } }, "TooManyRequestsProblemDetails": { "required": [ "detail", "instance", "status", "timestamp", "title", "traceId" ], "type": "object", "properties": { "title": { "type": "string", "description": "Too Many Requests" }, "status": { "type": "integer", "description": "429", "format": "int32" }, "instance": { "type": "string", "description": "URI identyfikujące konkretne wystąpienie błędu." }, "detail": { "type": "string", "description": "Informacja o przyczynie przekroczenia limitu żądań oraz wskazówki dotyczące ponowienia żądania." }, "timestamp": { "type": "string", "description": "Data i czas wystąpienia błędu w UTC.", "format": "date-time" }, "traceId": { "type": "string", "description": "Identyfikator śledzenia błędu." } }, "example": { "title": "Too Many Requests", "status": 429, "instance": "{{uri_path}}", "detail": "Przekroczono limit 20 żądań na minutę. Spróbuj ponownie po 30 sekundach.", "timestamp": "2025-07-11T12:23:56.0154302+00:00", "traceId": "673843e023c432286660bc0501a3af44" } }, "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." ] } }, "deprecated": true }, "UnauthorizedProblemDetails": { "required": [ "detail", "status", "timestamp", "title" ], "type": "object", "properties": { "title": { "type": "string", "description": "Unauthorized" }, "status": { "type": "integer", "description": "401", "format": "int32" }, "detail": { "type": "string", "description": "Szczegółowy opis przyczyny odmowy dostępu." }, "instance": { "type": "string", "description": "URI identyfikujące konkretne wystąpienie błędu.", "nullable": true }, "traceId": { "type": "string", "description": "Identyfikator śledzenia błędu.", "nullable": true }, "timestamp": { "type": "string", "description": "Data i czas wystąpienia błędu w UTC.", "format": "date-time" } }, "example": { "title": "Unauthorized", "status": 401, "detail": "Wymagane jest uwierzytelnienie.", "instance": "{{uri_path}}", "traceId": "673843e023c432286660bc0501a3af44", "timestamp": "2025-07-11T12:23:56.0154302+00:00" } }, "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" } } }, "UpoResponse": { "required": [ "pages" ], "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/UpoPageResponse" }, "description": "Lista stron UPO." } } } }, "securitySchemes": { "Bearer": { "type": "http", "description": "Token dostępu uzyskany w wyniku operacji uwierzytelnienia.", "scheme": "bearer", "bearerFormat": "JWT" } } }, "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": "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-api/blob/main/uwierzytelnianie.md#21-uwierzytelnianie-kwalifikowanym-podpisem-elektronicznym) — umożliwia [uwierzytelnienie](https://github.com/CIRFMF/ksef-api/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-api/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-api/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" ] } ] }