{ "openapi": "3.0.4", "info": { "title": "KSeF API TE", "description": "**Wersja API:** 2.7.0 (build 2.7.0-te-20260721.1+baa2a62ac3c0b55fd0516ef9517ed2589d4a6187)
\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 TEST: `https://api-test.ksef.mf.gov.pl/v2`\n", "version": "v2" }, "servers": [ { "url": "https://api-test.ksef.mf.gov.pl/v2", "description": "Środowisko TEST" } ], "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": { "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" } } } }, "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" } } } } }, "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" } ] } }, "/testdata/certificates/{serialNumber}": { "put": { "tags": [ "Certyfikaty" ], "summary": "Aktualizacja certyfikatu", "description": "Aktualizuje dane wskazanego certyfikatu KSeF uwierzytelnionego podmiotu. **Tylko na środowiskach testowych.**\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": "serialNumber", "in": "path", "description": "Numer seryjny certyfikatu (w formacie szesnastkowym).", "required": true, "schema": { "maxLength": 16, "minLength": 16, "pattern": "^[0-9A-F]{16}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "validTo" ], "allOf": [ { "$ref": "#/components/schemas/TestDataUpdateCertificateRequest" } ] } } } }, "responses": { "200": { "description": "OK", "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| 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 } } }, "/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 } } }, "/testdata/subject": { "post": { "tags": [ "Dane testowe" ], "summary": "Utworzenie podmiotu", "description": "Tworzenie nowego podmiotu testowego. W przypadku grupy VAT i JST istnieje możliwość stworzenia jednostek podrzędnych. W wyniku takiego działania w systemie powstanie powiązanie między tymi podmiotami.\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": [ "subjectNip", "subjectType", "description" ], "allOf": [ { "$ref": "#/components/schemas/SubjectCreateRequest" } ] }, "example": { "subjectNip": "7762811692", "subjectType": "EnforcementAuthority", "description": "Centrala", "createdDate": "2025-08-25T14:15:22+00:00" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "400": { "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "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 } } }, "/testdata/subject/remove": { "post": { "tags": [ "Dane testowe" ], "summary": "Usunięcie podmiotu", "description": "Usuwanie podmiotu testowego. W przypadku grupy VAT i JST usunięte zostaną również jednostki podrzędne.\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": [ "subjectNip" ], "allOf": [ { "$ref": "#/components/schemas/SubjectRemoveRequest" } ] }, "example": { "subjectNip": "7762811692" } } } }, "responses": { "200": { "description": "OK", "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ń** | 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 } } }, "/testdata/person": { "post": { "tags": [ "Dane testowe" ], "summary": "Utworzenie osoby fizycznej", "description": "Tworzenie nowej osoby fizycznej, której system nadaje uprawnienia właścicielskie. Można również określić, czy osoba ta jest komornikiem – wówczas otrzyma odpowiednie uprawnienie egzekucyjne.\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": [ "nip", "pesel", "isBailiff", "description" ], "allOf": [ { "$ref": "#/components/schemas/PersonCreateRequest" } ] }, "example": { "nip": "7762811692", "pesel": "15062788702", "isBailiff": true, "description": "TestPerson_01", "isDeceased": false, "createdDate": "2025-08-25T14:15:22+00:00" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } } }, "400": { "description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResponse" } }, "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 } } }, "/testdata/person/remove": { "post": { "tags": [ "Dane testowe" ], "summary": "Usunięcie osoby fizycznej", "description": "Usuwanie testowej osoby fizycznej. System automatycznie odbierze jej wszystkie uprawnienia.\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": [ "nip" ], "allOf": [ { "$ref": "#/components/schemas/PersonRemoveRequest" } ] }, "example": { "nip": "7762811692" } } } }, "responses": { "200": { "description": "OK", "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ń** | 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 } } }, "/testdata/permissions": { "post": { "tags": [ "Dane testowe" ], "summary": "Nadanie uprawnień testowemu podmiotowi/osobie fizycznej", "description": "Nadawanie uprawnień testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.\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": [ "contextIdentifier", "authorizedIdentifier", "permissions" ], "allOf": [ { "$ref": "#/components/schemas/TestDataPermissionsGrantRequest" } ] }, "example": { "contextIdentifier": { "type": "Nip", "value": "7762811692" }, "authorizedIdentifier": { "type": "Nip", "value": "7762811692" }, "permissions": [ { "description": "Opis testowy", "permissionType": "InvoiceRead" } ] } } } }, "responses": { "200": { "description": "OK", "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ń** | 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 } } }, "/testdata/permissions/revoke": { "post": { "tags": [ "Dane testowe" ], "summary": "Odebranie uprawnień testowemu podmiotowi/osobie fizycznej", "description": "Odbieranie uprawnień nadanych testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.\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": [ "contextIdentifier", "authorizedIdentifier" ], "allOf": [ { "$ref": "#/components/schemas/TestDataPermissionsRevokeRequest" } ] }, "example": { "contextIdentifier": { "type": "Nip", "value": "5265877635" }, "authorizedIdentifier": { "type": "Nip", "value": "7762811692" } } } } }, "responses": { "200": { "description": "OK", "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ń** | 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 } } }, "/testdata/attachment": { "post": { "tags": [ "Dane testowe" ], "summary": "Umożliwienie wysyłania faktur z załącznikiem", "description": "Dodaje możliwość wysyłania faktur z załącznikiem przez wskazany podmiot\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": [ "nip" ], "allOf": [ { "$ref": "#/components/schemas/AttachmentPermissionGrantRequest" } ] }, "example": { "nip": "7762811692" } } } }, "responses": { "200": { "description": "OK", "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ń** | 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 } } }, "/testdata/attachment/revoke": { "post": { "tags": [ "Dane testowe" ], "summary": "Odebranie możliwości wysyłania faktur z załącznikiem", "description": "Odbiera możliwość wysyłania faktur z załącznikiem przez wskazany podmiot\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": [ "nip" ], "allOf": [ { "$ref": "#/components/schemas/AttachmentPermissionRevokeRequest" } ] }, "example": { "nip": "7762811692" } } } }, "responses": { "200": { "description": "OK", "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ń** | 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 } } }, "/testdata/context/block": { "post": { "tags": [ "Dane testowe" ], "summary": "Zablokowanie kontekstu", "description": "Blokuje możliwość uwierzytelniania dla wskazanego kontekstu. Uwierzytelnianie zakończy się błędem 480.\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": { "allOf": [ { "$ref": "#/components/schemas/BlockContextAuthenticationRequest" } ] } } } }, "responses": { "200": { "description": "OK", "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" } }, "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/testdata/context/unblock": { "post": { "tags": [ "Dane testowe" ], "summary": "Odblokowanie kontekstu", "description": "Odblokowuje możliwość uwierzytelniania dla wskazanego 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`).", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UnblockContextAuthenticationRequest" } ] } } } }, "responses": { "200": { "description": "OK", "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" } }, "x-rate-limits": { "perSecond": 10, "perMinute": 30, "perHour": 120 } } }, "/collective-identifiers": { "post": { "tags": [ "Identyfikatory zbiorcze" ], "summary": "Generowanie identyfikatora zbiorczego", "description": "Generuje identyfikator zbiorczy dla przekazanej listy numerów KSeF faktur\nwystawionych przez tego samego sprzedawcę.\n\nMaksymalna liczba faktur przypisanych do jednego identyfikatora zbiorczego wynosi 500.\nJedna faktura może zostać przypisana do maksymalnie 132 identyfikatorów zbiorczych\nw ramach jednego kontekstu.\n \nIdentyfikator zbiorczy ma format:\n`9999999999-IZRRRRMM-FFFFFFFFFFFF-FF`, gdzie:\n- `9999999999` – 10-cyfrowy NIP sprzedawcy,\n- `IZ` – stały prefiks,\n- `RRRRMM` – rok i miesiąc utworzenia,\n- `FFFFFFFFFFFF` – część techniczna składająca się z 12 znaków w zapisie szesnastkowym, tylko [0–9 A–F], wielkie litery,\n- `FF` – suma kontrolna CRC-8 - 2 znaki w zapisie szesnastkowym, tylko [0–9 A–F], wielkie litery.\n \nDo obliczenia sumy kontrolnej stosowany jest algorytm CRC-8 z parametrami:\n- Polinom: 0x07\n- Wartość początkowa: 0x00\n- Format wyniku: 2-znakowy zapis szesnastkowy(HEX, wielkie litery)\n\nPrzykład:\n`1111111111-IZ202607-65ED02180000-E7`.\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 jedno z uprawnień**: `InvoiceRead`, `InvoiceWrite`, `CollectiveIdentifierManage`.", "requestBody": { "content": { "application/json": { "schema": { "required": [ "invoices" ], "allOf": [ { "$ref": "#/components/schemas/GenerateCollectiveIdentifierRequest" } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCollectiveIdentifierResponse" } } } }, "400": { "description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|------------------------------------------------------------------------------|--------------------------------------------------------|\n| 71001 | Faktura nie może zostac przypisana do Identyfikatora Zbiorczego. | Faktura o numerze KSeF {ksefNumber} nie może zostac przypisana do Identyfikatora Zbiorczego. |\n| 71002 | Faktura jest już przypisana do maksymalnej liczby Identyfikatorów Zbiorczych. | Faktura o numerze KSeF {ksefNumber} jest już przypisana do maksymalnej liczby Identyfikatorów Zbiorczych. |\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 | 120 | collectiveIdentifier\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": 120 }, "x-required-permissions": [ "InvoiceRead", "InvoiceWrite", "CollectiveIdentifierManage" ] } }, "/collective-identifiers/query": { "post": { "tags": [ "Identyfikatory zbiorcze" ], "summary": "Pobranie listy identyfikatorów zbiorczych powiązanych z kontekstem", "description": "Zwraca listę identyfikatorów zbiorczych wygenerowanych w kontekście.\nDla kontekstu typu NIP zwracane są również identyfikatory zbiorcze, dla których podmiot występuje w roli Podmiotu 1 na fakturze.\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- collectiveIdentifierNumber (Desc)\n\n\n\n**Wymagane jedno z uprawnień**: `InvoiceRead`, `InvoiceWrite`, `CollectiveIdentifierManage`.", "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", "schema": { "maximum": 200, "minimum": 10, "type": "integer", "format": "int32", "default": 10 } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "dateCreatedFrom", "dateCreatedTo" ], "allOf": [ { "$ref": "#/components/schemas/CollectiveIdentifiersQueryRequest" } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-System-Warning": { "schema": { "$ref": "#/components/schemas/SystemWarning" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectiveIdentifiersQueryResponse" } } } }, "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" }, "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-sort": [ { "field": "dateCreated", "direction": "Desc" }, { "field": "collectiveIdentifierNumber", "direction": "Desc" } ], "x-required-permissions": [ "InvoiceRead", "InvoiceWrite", "CollectiveIdentifierManage" ] } }, "/collective-identifiers/{collectiveIdentifierNumber}/invoices": { "get": { "tags": [ "Identyfikatory zbiorcze" ], "summary": "Pobranie listy faktur wchodzących w skład identyfikatora zbiorczego", "description": "Zwraca listę numerów KSeF faktur wchodzących w skład identyfikatora zbiorczego.\n \nInformacje o kwocie i walucie płatności są zwracane wyłącznie podmiotowi, który utworzył identyfikator zbiorczy, lub podmiotowi występującemu w roli na danej fakturze.\n\nJeżeli kwota i waluta płatności zostały określone podczas tworzenia identyfikatora zbiorczego, a podmiot nie ma dostępu do tych informacji, pola dotyczące kwoty i waluty płatności nie są zwracane, a pole paymentDetailsHidden przyjmuje wartość true.\n\nJeżeli kwota i waluta płatności nie zostały określone podczas tworzenia identyfikatora zbiorczego, ich wartości pozostają puste, a pole paymentDetailsHidden przyjmuje wartość false.\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- ksefNumber (Desc)\n\n\n\n**Wymagane jedno z uprawnień**: `InvoiceRead`, `InvoiceWrite`, `CollectiveIdentifierManage`.", "parameters": [ { "name": "collectiveIdentifierNumber", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-continuation-token", "in": "header", "description": "Token służący do pobrania kolejnej strony wyników.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 200, "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/CollectiveIdentifierInvoicesQueryResponse" } } } }, "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" }, "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-sort": [ { "field": "ksefNumber", "direction": "Desc" } ], "x-required-permissions": [ "InvoiceRead", "InvoiceWrite", "CollectiveIdentifierManage" ] } }, "/collective-identifiers/ksef/{ksefNumber}": { "get": { "tags": [ "Identyfikatory zbiorcze" ], "summary": "Pobranie listy identyfikatorów zbiorczych po numerze KSeF", "description": "Zwraca listę identyfikatorów zbiorczych związanych z podanym numerem 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**Sortowanie:**\n\n- dateCreated (Desc)\n- collectiveIdentifierNumber (Desc)\n\n\n\n**Wymagane jedno z uprawnień**: `InvoiceRead`, `InvoiceWrite`, `CollectiveIdentifierManage`.", "parameters": [ { "name": "ksefNumber", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/KsefNumber" } }, { "name": "x-continuation-token", "in": "header", "description": "Token służący do pobrania kolejnej strony wyników.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "schema": { "maximum": 200, "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/CollectiveIdentifiersByKsefNumberQueryResponse" } } } }, "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" }, "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-sort": [ { "field": "dateCreated", "direction": "Desc" }, { "field": "collectiveIdentifierNumber", "direction": "Desc" } ], "x-required-permissions": [ "InvoiceRead", "InvoiceWrite", "CollectiveIdentifierManage" ] } }, "/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 }, "collectiveIdentifier": { "perSecond": 10, "perMinute": 60, "perHour": 120 }, "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 } } }, "/testdata/limits/context/session": { "post": { "tags": [ "Limity i ograniczenia" ], "summary": "Zmiana limitów sesji dla bieżącego kontekstu", "description": "Zmienia wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu. **Tylko na środowiskach testowych.**\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": [ "onlineSession", "batchSession" ], "allOf": [ { "$ref": "#/components/schemas/SetSessionLimitsRequest" } ] } } } }, "responses": { "200": { "description": "OK", "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 } }, "delete": { "tags": [ "Limity i ograniczenia" ], "summary": "Przywrócenie domyślnych wartości limitów sesji dla bieżącego kontekstu", "description": "Przywraca wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**\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" } } } }, "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 } } }, "/testdata/limits/subject/certificate": { "post": { "tags": [ "Limity i ograniczenia" ], "summary": "Zmiana limitów certyfikatów dla bieżącego podmiotu", "description": "Zmienia wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu. **Tylko na środowiskach testowych.**\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": { "allOf": [ { "$ref": "#/components/schemas/SetSubjectLimitsRequest" } ] } } } }, "responses": { "200": { "description": "OK", "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 } }, "delete": { "tags": [ "Limity i ograniczenia" ], "summary": "Przywrócenie domyślnych wartości limitów certyfikatów dla bieżącego podmiotu", "description": "Przywraca wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu do wartości domyślnych. **Tylko na środowiskach testowych.**\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" } } } }, "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 } } }, "/testdata/rate-limits": { "post": { "tags": [ "Limity i ograniczenia" ], "summary": "Zmiana limitów API dla bieżącego kontekstu", "description": "Zmienia wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu. **Tylko na środowiskach testowych.**\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": [ "rateLimits" ], "allOf": [ { "$ref": "#/components/schemas/SetRateLimitsRequest" } ] } } } }, "responses": { "200": { "description": "OK", "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 } }, "delete": { "tags": [ "Limity i ograniczenia" ], "summary": "Przywrócenie domyślnych wartości limitów API dla bieżącego kontekstu", "description": "Przywraca wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**\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" } } } }, "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 } } }, "/testdata/rate-limits/production": { "post": { "tags": [ "Limity i ograniczenia" ], "summary": "Zmiana limitów API dla bieżącego kontekstu na wartości produkcyjne", "description": "Zmienia wartości aktualnie obowiązujących limitów żądań przesyłanych do API dla bieżącego kontekstu na wartości takie jakie będą na środowisku produkcyjnym. **Tylko na środowiskach testowych.**\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" } } } }, "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/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- **CollectiveIdentifierManage** – zarządzanie identyfikatorami zbiorczymi \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 uprawnienie**: `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 uprawnienie**: `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 uprawnienie**: `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 uprawnienie**: `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 uprawnienie**: `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 uprawnienie**: `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 uprawnienie**: `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 jedno z uprawnień**: `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 uprawnienie**: `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 jedno z uprawnień**: `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 uprawnienie**: `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 uprawnienie**: `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 uprawnienie**: `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 uprawnienie**: `InvoiceRead`.", "parameters": [ { "name": "referenceNumber", "in": "path", "description": "Numer referencyjny eksportu faktur.", "required": true, "schema": { "$ref": "#/components/schemas/ReferenceNumber" } } ], "responses": { "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" } } } }, "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" } } } } }, "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**Wymagane jedno z uprawnień**:\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`).\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n", "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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 - **CollectiveIdentifierManage** – zarządzanie identyfikatorami zbiorczymi \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 - **CollectiveIdentifierManage** – zarządzanie identyfikatorami zbiorczymi \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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 jedno z uprawnień**: `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 } } }, "ApiRateLimitValuesOverride": { "required": [ "perHour", "perMinute", "perSecond" ], "type": "object", "properties": { "perSecond": { "type": "integer", "description": "Limit na sekundę.", "format": "int32" }, "perMinute": { "type": "integer", "description": "Limit na minutę.", "format": "int32" }, "perHour": { "type": "integer", "description": "Limit na godzinę.", "format": "int32" } } }, "ApiRateLimitsOverride": { "required": [ "batchSession", "collectiveIdentifier", "invoiceDownload", "invoiceExport", "invoiceExportStatus", "invoiceMetadata", "invoiceSend", "invoiceStatus", "onlineSession", "other", "sessionInvoiceList", "sessionList", "sessionMisc" ], "type": "object", "properties": { "onlineSession": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla otwierania/zamykania sesji interaktywnych." }, "batchSession": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla otwierania/zamykania sesji wsadowych." }, "invoiceSend": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla wysyłki faktur." }, "invoiceStatus": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pobierania statusu faktury z sesji." }, "sessionList": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pobierania listy sesji." }, "sessionInvoiceList": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pobierania listy faktur w sesji." }, "sessionMisc": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pozostałych operacji w ramach sesji." }, "invoiceMetadata": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pobierania metadanych faktur." }, "invoiceExport": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla eksportu paczki faktur." }, "invoiceExportStatus": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pobierania statusu eksportu paczki faktur." }, "invoiceDownload": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pobierania faktur po numerze KSeF." }, "collectiveIdentifier": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla identyfikatorów zbiorczych." }, "other": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitValuesOverride" } ], "description": "Limity dla pozostałych operacji API." } } }, "AttachmentPermissionGrantRequest": { "required": [ "nip" ], "type": "object", "properties": { "nip": { "$ref": "#/components/schemas/Nip" } } }, "AttachmentPermissionRevokeRequest": { "required": [ "nip" ], "type": "object", "properties": { "nip": { "$ref": "#/components/schemas/Nip" }, "expectedEndDate": { "type": "string", "description": "Data wycofania zgody na przesyłanie faktur z załącznikiem.", "format": "date", "nullable": true } } }, "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." } } }, "BatchSessionContextLimitsOverride": { "required": [ "maxInvoices", "maxInvoiceSizeInMB", "maxInvoiceWithAttachmentSizeInMB" ], "type": "object", "properties": { "maxInvoiceSizeInMB": { "maximum": 5, "minimum": 0, "type": "integer", "description": "Maksymalny rozmiar faktury w MB.", "format": "int32" }, "maxInvoiceWithAttachmentSizeInMB": { "maximum": 10, "minimum": 0, "type": "integer", "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", "format": "int32" }, "maxInvoices": { "maximum": 100000, "minimum": 0, "type": "integer", "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", "format": "int32" } } }, "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" } } }, "BlockContextAuthenticationRequest": { "type": "object", "properties": { "contextIdentifier": { "required": [ "value", "type" ], "allOf": [ { "$ref": "#/components/schemas/TestDataAuthenticationContextIdentifier" } ], "nullable": true } } }, "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" }, "CertificateSubjectLimitsOverride": { "type": "object", "properties": { "maxCertificates": { "minimum": 0, "type": "integer", "format": "int32", "nullable": true } } }, "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 } } }, "CollectiveIdentifierInvoice": { "required": [ "ksefNumber" ], "type": "object", "properties": { "ksefNumber": { "allOf": [ { "$ref": "#/components/schemas/KsefNumber" } ], "description": "Numer ksef faktury." }, "payment": { "required": [ "amount", "currency" ], "allOf": [ { "$ref": "#/components/schemas/CollectiveIdentifierInvoicePayment" } ], "description": "Dane o płatności za fakturę", "nullable": true }, "description": { "maxLength": 512, "type": "string", "description": "Opis", "nullable": true } } }, "CollectiveIdentifierInvoicePayment": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "number", "description": "Kwota płatności za fakturę.", "format": "double" }, "currency": { "allOf": [ { "$ref": "#/components/schemas/CurrencyCode" } ], "description": "Kod waluty." } } }, "CollectiveIdentifierInvoicesQueryResponse": { "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/CollectiveIdentifierInvoicesQueryResponseItem" }, "description": "Lista faktur." } } }, "CollectiveIdentifierInvoicesQueryResponseItem": { "required": [ "detailsHidden", "ksefNumber" ], "type": "object", "properties": { "ksefNumber": { "allOf": [ { "$ref": "#/components/schemas/KsefNumber" } ], "description": "Numer ksef faktury." }, "payment": { "required": [ "amount", "currency" ], "allOf": [ { "$ref": "#/components/schemas/CollectiveIdentifierInvoicesQueryResponseItemPayment" } ], "description": "Dane o płatności za fakturę", "nullable": true }, "description": { "maxLength": 512, "type": "string", "description": "Opis", "nullable": true }, "detailsHidden": { "type": "boolean", "description": "Określa czy informacje o szczegółach zostały ukryte z powodu braku dostępu do faktury." } } }, "CollectiveIdentifierInvoicesQueryResponseItemPayment": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "number", "description": "Kwota płatności za fakturę.", "format": "double" }, "currency": { "maxLength": 3, "minLength": 3, "type": "string", "description": "Kod waluty." } } }, "CollectiveIdentifiersByKsefNumberQueryResponse": { "required": [ "collectiveIdentifiers" ], "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 }, "collectiveIdentifiers": { "type": "array", "items": { "$ref": "#/components/schemas/CollectiveIdentifiersByKsefNumberQueryResponseItem" }, "description": "Lista identyfikatorów zbiorczych." } } }, "CollectiveIdentifiersByKsefNumberQueryResponseItem": { "required": [ "collectiveIdentifierNumber", "createdInCurrentContext", "dateCreated" ], "type": "object", "properties": { "collectiveIdentifierNumber": { "maxLength": 35, "minLength": 35, "type": "string", "description": "Numer identyfikatora zbiorczego." }, "createdInCurrentContext": { "type": "boolean", "description": "Określa czy identyfikator zbiorczy został wygenerowany w bieżącym kontekście." }, "dateCreated": { "type": "string", "description": "Data utworzenia identyfikatora zbiorczego.", "format": "date-time" } } }, "CollectiveIdentifiersQueryRequest": { "required": [ "dateCreatedFrom", "dateCreatedTo" ], "type": "object", "properties": { "collectiveIdentifierNumber": { "type": "string", "description": "Numer identyfikatora zbiorczego.", "nullable": true }, "dateCreatedFrom": { "type": "string", "description": "Data utworzenia identyfikatora zbiorczego (od), maksymalny przedział czasu to 100 dni.", "format": "date-time" }, "dateCreatedTo": { "type": "string", "description": "Data utworzenia identyfikatora zbiorczego (do).", "format": "date-time" }, "invoiceCountFrom": { "type": "integer", "description": "Liczba faktur w identyfikatorze zbiorczym (od).", "format": "int32", "nullable": true }, "invoiceCountTo": { "type": "integer", "description": "Liczba faktur w identyfikatorze zbiorczym (do).", "format": "int32", "nullable": true }, "createdInCurrentContext": { "type": "boolean", "description": "Określa czy identyfikator zbiorczy został wygenerowany w bieżącym kontekście.", "nullable": true } } }, "CollectiveIdentifiersQueryResponse": { "required": [ "collectiveIdentifiers" ], "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 }, "collectiveIdentifiers": { "type": "array", "items": { "$ref": "#/components/schemas/CollectiveIdentifiersQueryResponseItem" }, "description": "Lista identyfikatorów zbiorczych." } } }, "CollectiveIdentifiersQueryResponseItem": { "required": [ "collectiveIdentifierNumber", "createdInCurrentContext", "dateCreated", "invoiceCount" ], "type": "object", "properties": { "collectiveIdentifierNumber": { "maxLength": 35, "minLength": 35, "type": "string", "description": "Numer identyfikatora zbiorczego." }, "dateCreated": { "type": "string", "description": "Data utworzenia identyfikatora zbiorczego.", "format": "date-time" }, "invoiceCount": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "description": "Liczba faktura składająca się na identyfikator zbiorczy.", "format": "int32" }, "createdInCurrentContext": { "type": "boolean", "description": "Określa czy identyfikator zbiorczy został wygenerowany w bieżącym kontekście." } } }, "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", "collectiveIdentifier", "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." }, "collectiveIdentifier": { "required": [ "perSecond", "perMinute", "perHour" ], "allOf": [ { "$ref": "#/components/schemas/EffectiveApiRateLimitValues" } ], "description": "Limity dla identyfikatorów zbiorczych" }, "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" } } }, "EnrollmentSubjectLimitsOverride": { "type": "object", "properties": { "maxEnrollments": { "minimum": 0, "type": "integer", "format": "int32", "nullable": true } } }, "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ść" } } }, "GenerateCollectiveIdentifierRequest": { "required": [ "invoices" ], "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/CollectiveIdentifierInvoice" }, "description": "Lista faktur wchodząca w skład identyfikatora zbiorczego. Limit faktur wynosi 500." } } }, "GenerateCollectiveIdentifierResponse": { "required": [ "collectiveIdentifierNumber" ], "type": "object", "properties": { "collectiveIdentifierNumber": { "maxLength": 35, "minLength": 35, "type": "string", "description": "Wygenerowany identyfikator zbiorczy" } } }, "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ść wsteczną z KSeF 1.0. W KSeF 2.0 numery są generowane wyłącznie w formacie 35-znakowym." }, "Nip": { "maxLength": 10, "minLength": 10, "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}$", "type": "string", "description": "10 cyfrowy numer NIP." }, "NipVatUe": { "pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}-(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))$", "type": "string", "description": "Identyfikator złożony, czyli dwuczłonowy identyfikator składający się z nr NIP podmiotu polskiego oraz numeru VAT UE podmiotu unijnego." }, "OnlineSessionContextLimitsOverride": { "required": [ "maxInvoices", "maxInvoiceSizeInMB", "maxInvoiceWithAttachmentSizeInMB" ], "type": "object", "properties": { "maxInvoiceSizeInMB": { "maximum": 5, "minimum": 0, "type": "integer", "description": "Maksymalny rozmiar faktury w MB.", "format": "int32" }, "maxInvoiceWithAttachmentSizeInMB": { "maximum": 10, "minimum": 0, "type": "integer", "description": "Maksymalny rozmiar faktury z załącznikiem w MB.", "format": "int32" }, "maxInvoices": { "maximum": 100000, "minimum": 0, "type": "integer", "description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.", "format": "int32" } } }, "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." } } }, "PersonCreateRequest": { "required": [ "description", "isBailiff", "nip", "pesel" ], "type": "object", "properties": { "nip": { "$ref": "#/components/schemas/Nip" }, "pesel": { "$ref": "#/components/schemas/Pesel" }, "isBailiff": { "type": "boolean" }, "description": { "maxLength": 256, "minLength": 5, "type": "string" }, "isDeceased": { "type": "boolean" }, "createdDate": { "type": "string", "description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.", "format": "date-time", "nullable": true } } }, "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", "CollectiveIdentifierManage" ], "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", "CollectiveIdentifierManage" ], "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" }, "PersonRemoveRequest": { "required": [ "nip" ], "type": "object", "properties": { "nip": { "$ref": "#/components/schemas/Nip" } } }, "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", "CollectiveIdentifierManage" ], "type": "string" }, "PersonalPermissionType": { "enum": [ "CredentialsManage", "CredentialsRead", "InvoiceWrite", "InvoiceRead", "Introspection", "SubunitManage", "EnforcementOperations", "VatUeManage", "CollectiveIdentifierManage" ], "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" } } }, "SetRateLimitsRequest": { "required": [ "rateLimits" ], "type": "object", "properties": { "rateLimits": { "required": [ "onlineSession", "batchSession", "invoiceSend", "invoiceStatus", "sessionList", "sessionInvoiceList", "sessionMisc", "invoiceMetadata", "invoiceExport", "invoiceExportStatus", "invoiceDownload", "collectiveIdentifier", "other" ], "allOf": [ { "$ref": "#/components/schemas/ApiRateLimitsOverride" } ], "description": "Limity dla ilości żądań do API." } } }, "SetSessionLimitsRequest": { "required": [ "batchSession", "onlineSession" ], "type": "object", "properties": { "onlineSession": { "required": [ "maxInvoiceSizeInMB", "maxInvoiceWithAttachmentSizeInMB", "maxInvoices" ], "allOf": [ { "$ref": "#/components/schemas/OnlineSessionContextLimitsOverride" } ], "description": "Limity dla sesji interaktywnych." }, "batchSession": { "required": [ "maxInvoiceSizeInMB", "maxInvoiceWithAttachmentSizeInMB", "maxInvoices" ], "allOf": [ { "$ref": "#/components/schemas/BatchSessionContextLimitsOverride" } ], "description": "Limity dla sesji wsadowych." } } }, "SetSubjectLimitsRequest": { "type": "object", "properties": { "subjectIdentifierType": { "allOf": [ { "$ref": "#/components/schemas/SubjectIdentifierType" } ] }, "enrollment": { "allOf": [ { "$ref": "#/components/schemas/EnrollmentSubjectLimitsOverride" } ], "nullable": true }, "certificate": { "allOf": [ { "$ref": "#/components/schemas/CertificateSubjectLimitsOverride" } ], "nullable": true } } }, "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 } } }, "SubjectCreateRequest": { "required": [ "description", "subjectNip", "subjectType" ], "type": "object", "properties": { "subjectNip": { "$ref": "#/components/schemas/Nip" }, "subjectType": { "allOf": [ { "$ref": "#/components/schemas/SubjectType" } ] }, "subunits": { "type": "array", "items": { "$ref": "#/components/schemas/Subunit" }, "nullable": true }, "description": { "maxLength": 256, "minLength": 5, "type": "string" }, "createdDate": { "type": "string", "description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.", "format": "date-time", "nullable": true } } }, "SubjectIdentifierType": { "enum": [ "Nip", "Pesel", "Fingerprint" ], "type": "string" }, "SubjectRemoveRequest": { "required": [ "subjectNip" ], "type": "object", "properties": { "subjectNip": { "$ref": "#/components/schemas/Nip" } } }, "SubjectType": { "enum": [ "EnforcementAuthority", "VatGroup", "JST" ], "type": "string" }, "SubordinateEntityRole": { "required": [ "description", "role", "startDate", "subordinateEntityIdentifier" ], "type": "object", "properties": { "subordinateEntityIdentifier": { "required": [ "type", "value" ], "allOf": [ { "$ref": "#/components/schemas/SubordinateRoleSubordinateEntityIdentifier" } ], "description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |" }, "role": { "allOf": [ { "$ref": "#/components/schemas/SubordinateEntityRoleType" } ], "description": "Typ roli - powiązania z podmiotem nadrzędnym." }, "description": { "maxLength": 256, "minLength": 5, "type": "string", "description": "Opis powiązania." }, "startDate": { "type": "string", "description": "Data rozpoczęcia obowiązywania powiązania.", "format": "date-time" } } }, "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" }, "Subunit": { "required": [ "description", "subjectNip" ], "type": "object", "properties": { "subjectNip": { "$ref": "#/components/schemas/Nip" }, "description": { "maxLength": 256, "minLength": 5, "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: `\\[(?[^\\]]+)\\]: (?[^|]+)`

\nGenerowanie ostrzeżeń można wymusić przekazując nagłówek:\n `X-Test-System-Warning`, którego treść zostanie zwrócona w odpowiedzi." }, "TestDataAuthenticationContextIdentifier": { "required": [ "type", "value" ], "type": "object", "properties": { "value": { "type": "string" }, "type": { "allOf": [ { "$ref": "#/components/schemas/TestDataAuthenticationContextIdentifierType" } ] } } }, "TestDataAuthenticationContextIdentifierType": { "enum": [ "Nip", "InternalId", "NipVatUe", "PeppolId" ], "type": "string" }, "TestDataAuthorizedIdentifier": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/TestDataAuthorizedIdentifierType" } ] }, "value": { "maxLength": 64, "minLength": 10, "type": "string" } } }, "TestDataAuthorizedIdentifierType": { "enum": [ "Nip", "Pesel", "Fingerprint" ], "type": "string" }, "TestDataContextIdentifier": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/TestDataContextIdentifierType" } ] }, "value": { "maxLength": 10, "minLength": 10, "type": "string" } } }, "TestDataContextIdentifierType": { "enum": [ "Nip" ], "type": "string" }, "TestDataPermission": { "required": [ "description", "permissionType" ], "type": "object", "properties": { "description": { "maxLength": 256, "minLength": 5, "type": "string" }, "permissionType": { "allOf": [ { "$ref": "#/components/schemas/TestDataPermissionType" } ] } } }, "TestDataPermissionType": { "enum": [ "InvoiceRead", "InvoiceWrite", "Introspection", "CredentialsRead", "CredentialsManage", "EnforcementOperations", "SubunitManage", "CollectiveIdentifierManage" ], "type": "string" }, "TestDataPermissionsGrantRequest": { "required": [ "authorizedIdentifier", "contextIdentifier", "permissions" ], "type": "object", "properties": { "contextIdentifier": { "required": [ "type", "value" ], "allOf": [ { "$ref": "#/components/schemas/TestDataContextIdentifier" } ] }, "authorizedIdentifier": { "required": [ "type", "value" ], "allOf": [ { "$ref": "#/components/schemas/TestDataAuthorizedIdentifier" } ] }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/TestDataPermission" } } } }, "TestDataPermissionsRevokeRequest": { "required": [ "authorizedIdentifier", "contextIdentifier" ], "type": "object", "properties": { "contextIdentifier": { "required": [ "type", "value" ], "allOf": [ { "$ref": "#/components/schemas/TestDataContextIdentifier" } ] }, "authorizedIdentifier": { "required": [ "type", "value" ], "allOf": [ { "$ref": "#/components/schemas/TestDataAuthorizedIdentifier" } ] } } }, "TestDataUpdateCertificateRequest": { "required": [ "validTo" ], "type": "object", "properties": { "validTo": { "type": "string", "description": "Nowa data ważności certyfikatu, nie może być późniejsza niż obecna.", "format": "date-time" } } }, "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", "CollectiveIdentifierManage" ], "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" } }, "UnblockContextAuthenticationRequest": { "type": "object", "properties": { "contextIdentifier": { "required": [ "value", "type" ], "allOf": [ { "$ref": "#/components/schemas/TestDataAuthenticationContextIdentifier" } ], "nullable": true } } }, "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": "Dane testowe", "description": "API służy do tworzenia i zarządzania danymi testowymi, takimi jak podmioty, osoby fizyczne oraz uprawnienia. Możliwe do utworzenia podmioty to: organ egzekucyjny, grupa VAT oraz jednostki samorządu terytorialnego. W przypadku osób fizycznych można określić, czy dana osoba jest komornikiem. Funkcjonalność nadawania i odbierania uprawnień ma na celu odwzorowanie działania formularza ZAW-FA w środowisku testowym.\n\nWięcej informacji:\n- [Scenariusze testowe](https://github.com/CIRFMF/ksef-api/blob/main/dane-testowe-scenariusze.md)" }, { "name": "Identyfikatory zbiorcze" }, { "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": "Identyfikatory zbiorcze", "tags": [ "Identyfikatory zbiorcze" ] }, { "name": "Usługi Peppol", "tags": [ "Usługi Peppol" ] }, { "name": "Dane testowe", "tags": [ "Dane testowe" ] } ] }