{
"openapi": "3.0.4",
"info": {
"title": "KSeF API TE",
"description": "**Wersja API:** 2.0.0 (build 2.0.0-rc5.7-te-20251127.1+390ad3e147d90ab086bf22c3fcd354002449bf11)
\n**Klucze publiczne** Ministerstwa Finansów (dla danego środowiska): [Pobierz klucze](#tag/Certyfikaty-klucza-publicznego)
\n**Historia zmian:** [Changelog](https://github.com/CIRFMF/ksef-docs/blob/main/api-changelog.md)
\n**Rozszerzona dokumentacja API:** [ksef-docs](https://github.com/CIRFMF/ksef-docs/tree/main)\n",
"version": "v2"
},
"paths": {
"/api/v2/auth/sessions": {
"get": {
"tags": [
"Aktywne sesje"
],
"summary": "Pobranie listy aktywnych sesji",
"description": "Zwraca listę aktywnych sesji uwierzytelnienia.\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n",
"parameters": [
{
"name": "x-continuation-token",
"in": "header",
"description": "Token służący do pobrania kolejnej strony wyników.",
"schema": {
"type": "string"
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationListResponse"
},
"example": {"continuationToken":"W3siY29tcG9zaXRlVG9rZW4iOnsidG9rZW4iOm51bGwsInJhbmdlIjp7Im1pbiI6IjA1QzFFMCIsIm1heCI6IkZGIn19LCJyZXN1bWVWYWx1ZXMiOlsiMjAyNS0xMC0wM1QxMjoxODo0OS4zNDY2ODQ3WiJdLCJyaWQiOiIzeHd0QVBJWDVRRlVoZ0FBQUFBQUJBPT0iLCJza2lwQ291bnQiOjF9XQ==","items":[{"referenceNumber":"20251010-AU-19F5E39000-39B5B182BA-B8","isCurrent":false,"startDate":"2025-10-11T12:23:56.0154302+00:00","authenticationMethod":"QualifiedSeal","status":{"code":200,"description":"Uwierzytelnianie zakończone sukcesem"},"isTokenRedeemed":true,"refreshTokenValidUntil":"2025-11-28T09:22:13.388+00:00"}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
]
}
},
"/api/v2/auth/sessions/current": {
"delete": {
"tags": [
"Aktywne sesje"
],
"summary": "Unieważnienie aktualnej sesji uwierzytelnienia",
"description": "Unieważnia sesję powiązaną z tokenem użytym do wywołania tej operacji.\n\nUnieważnienie sesji sprawia, że powiązany z nią refresh token przestaje działać i nie można już za jego pomocą uzyskać kolejnych access tokenów.\n**Aktywne access tokeny działają do czasu minięcia ich termin ważności.**\n\nSposób uwierzytelnienia: `RefreshToken` lub `AccessToken`.",
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/auth/sessions/{referenceNumber}": {
"delete": {
"tags": [
"Aktywne sesje"
],
"summary": "Unieważnienie sesji uwierzytelnienia",
"description": "Unieważnia sesję o podanym numerze referencyjnym.\n\nUnieważnienie sesji sprawia, że powiązany z nią refresh token przestaje działać i nie można już za jego pomocą uzyskać kolejnych access tokenów.\n**Aktywne access tokeny działają do czasu minięcia ich termin ważności.**",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny sesji uwierzytelnienia.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/certificates/limits": {
"get": {
"tags": [
"Certyfikaty"
],
"summary": "Pobranie danych o limitach certyfikatów",
"description": "Zwraca informacje o limitach certyfikatów oraz informacje czy użytkownik może zawnioskować o certyfikat KSeF.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CertificateLimitsResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/certificates/enrollments/data": {
"get": {
"tags": [
"Certyfikaty"
],
"summary": "Pobranie danych do wniosku certyfikacyjnego",
"description": "Zwraca dane wymagane do przygotowania wniosku certyfikacyjnego PKCS#10.\n\nDane te są zwracane na podstawie certyfikatu użytego w procesie uwierzytelnienia i identyfikują podmiot, który składa wniosek o certyfikat.\n\n\n> Więcej informacji:\n> - [Pobranie danych do wniosku certyfikacyjnego](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#2-pobranie-danych-do-wniosku-certyfikacyjnego)\n> - [Przygotowanie wniosku](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#3-przygotowanie-csr-certificate-signing-request)",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CertificateEnrollmentDataResponse"
},
"example": {"commonName":"Firma Kowalski Certyfikat","countryName":"PL","serialNumber":"ABC123456789","uniqueIdentifier":"d9d22724-4696-460c-9e5e-b9e3aafb0af3","organizationName":"Firma Kowalski Sp. z o.o.","organizationIdentifier":"7762811692"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|-------------------------------------------------------------------------------------------|---------|\n| 25001 | Brak możliwości pobrania danych do CSR dla wykorzystanego sposobu uwierzytelnienia. | |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/certificates/enrollments": {
"post": {
"tags": [
"Certyfikaty"
],
"summary": "Wysyłka wniosku certyfikacyjnego",
"description": "Przyjmuje wniosek certyfikacyjny i rozpoczyna jego przetwarzanie.\n\nDozwolone typy kluczy prywatnych:\n- RSA (OID: 1.2.840.113549.1.1.1), długość klucza równa 2048 bitów,\n- EC (klucze oparte na krzywych eliptycznych, OID: 1.2.840.10045.2.1), krzywa NIST P-256 (secp256r1)\n\nZalecane jest stosowanie kluczy EC.\n\nDozwolone algorytmy podpisu:\n- RSA PKCS#1 v1.5,\n- RSA PSS,\n- ECDSA (format podpisu zgodny z RFC 3279)\n\nDozwolone funkcje skrótu użyte do podpisu CSR:\n- SHA1,\n- SHA256,\n- SHA384,\n- SHA512\n\n> Więcej informacji:\n> - [Wysłanie wniosku certyfikacyjnego](https://github.com/CIRFMF/ksef-docs/blob/main/certyfikaty-KSeF.md#4-wys%C5%82anie-wniosku-certyfikacyjnego)",
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"required": [
"certificateName",
"certificateType",
"csr"
],
"allOf": [
{
"$ref": "#/components/schemas/EnrollCertificateRequest"
}
]
},
"example": {"certificateName":"Certyfikat-Auth-004","certificateType":"Authentication","csr":"MIIDJjCCAd4CAQAwgbAxIjAgBgNVBAMMGUZpcm1hIEtvd2Fsc2tpIENlcnR5ZmlrYXQxIjAgBgNVBAoMGUZpcm1hIEtvd2Fsc2tpIFNwLiB6IG8uby4xEzARBgNVBGEMCjc3NjI4MTE2OTIxCzAJBgNVBAYTAlBMMRUwEwYDVQQFEwxBQkMxMjM0NTY3ODkxLTArBgNVBC0MJGQ5ZDIyNzI0LTQ2OTYtNDYwYy05ZTVlLWI5ZTNhYWZiMGFmMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANZC1hJiB4ZBsxGy/a4yvtOUP0HQxDt7EUZrfKO78+cmI7KCO9aW96yr6O0R928/Y9vmymbgh6KvMUTzZZj24uyxar849O1laor5t8Wv63RDx/I4+9Rt7w+QPPofmpenOokJH+Fm+FDQwo2l07o8SppGfaZpvMak+cDSrh+73wfM37fvPImr9p4ckzzxA9q6f4uoqGqcGSDlSwRjfLQKzWZaEklpZBpY4jeCh54uN3+YLsMQYKdcIbW0Jart1UbwMd/wbHfzFhVmPGOAMMpwVEBw6E4A0CTWIiAX3Alqbx4+IkuqC+gEs3ETTec7eOqhxe9V9cywi7WR+Mz6JO6DJcUCAwEAAaAAMD0GCSqGSIb3DQEBCjAwoA0wCwYJYIZIAWUDBAIBoRowGAYJKoZIhvcNAQEIMAsGCWCGSAFlAwQCAaIDAgEgA4IBAQCJhtF2/2E+JmkWitE/BGbm3NU4fIxr1Z+w0UnHsP+F8n9UDwAnuncG1GH5wZFervldEMooegzEDnYaqxnEUnbZ4wxeAHqpbTZjOOfqrk7o0r66+mXUs5NnyD4M3j3ig98GcvhEdbcNH+RsIwi7FaLNXnOE4SLYL9KvW0geriywWjS+5MmA0Gcn1e4vCD6FeEls8EHzkhrWE+rUsoM5zT2a0OPNXG3fScyOqOZe+OdjT4Y7ScRGy711u3v2X9RoTqQUDfCJ3cob/KRcrzvs1TQVazGZPfcIa6an6SigUvZ7XAMHlUTyOeM4AwKqiEqQ0qfe/HhlDylgZSwulb9u0utT","validFrom":"2025-08-28T09:22:13.388+00:00"}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnrollCertificateResponse"
},
"example": {"referenceNumber":"20251010-EH-1B6C9EB000-4B15D3AEB9-89","timestamp":"2025-10-11T12:23:56.0154302+00:00"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25002 | Brak możliwości złożenia wniosku certyfikacyjnego dla wykorzystanego sposobu uwierzytelnienia. | |\n| 25003 | Dane w CSR nie zgadzają się z danymi w użytym wektorze uwierzytelniającym. | |\n| 25004 | Niepoprawny format CSR lub niepoprawny podpis CSR. | |\n| 25006 | Osiągnięto limit możliwych do złożenia wniosków certyfikacyjnych. | |\n| 25007 | Osiągnięto limit dopuszczalnej liczby posiadanych certyfikatów. | |\n| 25010 | Nieprawidłowy typ lub długość klucza. | |\n| 25011 | Nieprawidłowy algorytm podpisu CSR. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/certificates/enrollments/{referenceNumber}": {
"get": {
"tags": [
"Certyfikaty"
],
"summary": "Pobranie statusu przetwarzania wniosku certyfikacyjnego",
"description": "Zwraca informacje o statusie wniosku certyfikacyjnego.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny wniosku certyfikacyjnego",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CertificateEnrollmentStatusResponse"
},
"example": {"requestDate":"2025-10-11T12:23:56.0154302+00:00","status":{"code":100,"description":"Wniosek przyjęty do realizacji"}}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25005 | Wniosek certyfikacyjny o podanym numerze referencyjnym nie istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/certificates/retrieve": {
"post": {
"tags": [
"Certyfikaty"
],
"summary": "Pobranie certyfikatu lub listy certyfikatów",
"description": "Zwraca certyfikaty o podanych numerach seryjnych w formacie DER zakodowanym w Base64.",
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"required": [
"certificateSerialNumbers"
],
"allOf": [
{
"$ref": "#/components/schemas/RetrieveCertificatesRequest"
}
]
},
"example": {"certificateSerialNumbers":["0321C82DA41B4362","0321F21DA462A362"]}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetrieveCertificatesResponse"
},
"example": {"certificates":[{"certificate":"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/wABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3ODk6Ozw9Pj9AQUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVpbXF1eX2BhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ent8fX5/gIGCg4SFhoeIiYqLjI2Oj5CRkpOUlZaXmJmam5ydnp+goaKjpKWmp6ipqqusra6vsLGys7S1tre4ubq7vL2+v8DBwsPExcbHyMnKy8zNzs/Q0dLT1NXW19jZ2tvc3d7f4OHi4+Tl5ufo6err7O3u7/Dx8vP09fb3+Pn6+/z9/v8AAQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5Ojs8PT4/QEFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaW1xdXl9gYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+f4CBgoOEhYaHiImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6u7y9vr/AwcLDxMXGx8jJysvMzc7P0NHS09TV1tfY2drb3N3e3+Dh4uPk5ebn6Onq6+zt7u/w8fLz9PX29/j5+vv8/f7/AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w==","certificateName":"Cert 00023","certificateSerialNumber":"0321C82DA41B4362","certificateType":"Authentication"}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/certificates/{certificateSerialNumber}/revoke": {
"post": {
"tags": [
"Certyfikaty"
],
"summary": "Unieważnienie certyfikatu",
"description": "Unieważnia certyfikat o podanym numerze seryjnym.",
"parameters": [
{
"name": "certificateSerialNumber",
"in": "path",
"description": "Numer seryjny certyfikatu (w formacie szesnastkowym).",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/RevokeCertificateRequest"
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------------------------------------------|---------|\n| 25008 | Certyfikat o podanym numerze seryjnym nie istnieje. | |\n| 25009 | Nie można odwołać wskazanego certyfikatu, ponieważ jest już odwołany, zablokowany lub nieważny.| |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/certificates/query": {
"post": {
"tags": [
"Certyfikaty"
],
"summary": "Pobranie listy metadanych certyfikatów",
"description": "Zwraca listę certyfikatów spełniających podane kryteria wyszukiwania.\nW przypadku braku podania kryteriów wyszukiwania zwrócona zostanie nieprzefiltrowana lista.\n\n**Sortowanie:**\n\n- requestDate (Desc)\n\n",
"parameters": [
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników",
"schema": {
"maximum": 50,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
}
],
"requestBody": {
"description": "Kryteria filtrowania",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/QueryCertificatesRequest"
}
]
},
"example": {"type":"Offline","status":"Active"}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryCertificatesResponse"
},
"example": {"certificates":[{"certificateSerialNumber":"018209160C631F1E","name":"Certyfikat 1","type":"Authentication","commonName":"Jan Kowalski","status":"Active","subjectIdentifier":{"type":"Nip","value":"1234445678"},"validFrom":"2025-08-24T14:15:22+00:00","validTo":"2027-08-24T14:15:22+00:00","lastUseDate":"2025-08-25T14:15:22+00:00","requestDate":"2025-08-24T14:15:22+00:00"}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "requestDate",
"direction": "Desc"
}
]
}
},
"/api/v2/security/public-key-certificates": {
"get": {
"tags": [
"Certyfikaty klucza publicznego"
],
"summary": "Pobranie certyfikatów",
"description": "Zwraca informacje o kluczach publicznych używanych do szyfrowania danych przesyłanych do systemu KSeF.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicKeyCertificate"
}
},
"example": [{"certificate":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwocTwdNgt2+PXJ2fcB7k1kn5eFUTXBeep9pH...","validFrom":"2024-07-11T12:23:56.0154302+00:00","validTo":"2028-07-11T12:23:56.0154302+00:00","usage":["KsefTokenEncryption","SymmetricKeyEncryption"]}]
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/subject": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Utworzenie podmiotu",
"description": "Tworzenie nowego podmiotu testowego. W przypadku grupy VAT i JST istnieje możliwość stworzenia jednostek podrzędnych. W wyniku takiego działania w systemie powstanie powiązanie między tymi podmiotami.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectNip",
"subjectType",
"description"
],
"allOf": [
{
"$ref": "#/components/schemas/SubjectCreateRequest"
}
]
},
"example": {"subjectNip":"7762811692","subjectType":"EnforcementAuthority","description":"Centrala","createdDate":"2025-08-25T14:15:22+00:00"}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/subject/remove": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Usunięcie podmiotu",
"description": "Usuwanie podmiotu testowego. W przypadku grupy VAT i JST usunięte zostaną również jednostki podrzędne.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectNip"
],
"allOf": [
{
"$ref": "#/components/schemas/SubjectRemoveRequest"
}
]
},
"example": {"subjectNip":"7762811692"}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/person": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Utworzenie osoby fizycznej",
"description": "Tworzenie nowej osoby fizycznej, której system nadaje uprawnienia właścicielskie. Można również określić, czy osoba ta jest komornikiem – wówczas otrzyma odpowiednie uprawnienie egzekucyjne.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"nip",
"pesel",
"isBailiff",
"description"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonCreateRequest"
}
]
},
"example": {"nip":"7762811692","pesel":"15062788702","isBailiff":true,"description":"TestPerson_01","isDeceased":false,"createdDate":"2025-08-25T14:15:22+00:00"}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 30001 | Podmiot lub uprawnienie już istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/person/remove": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Usunięcie osoby fizycznej",
"description": "Usuwanie testowej osoby fizycznej. System automatycznie odbierze jej wszystkie uprawnienia.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"nip"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonRemoveRequest"
}
]
},
"example": {"nip":"7762811692"}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/permissions": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Nadanie uprawnień testowemu podmiotowi/osobie fizycznej",
"description": "Nadawanie uprawnień testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"contextIdentifier",
"authorizedIdentifier",
"permissions"
],
"allOf": [
{
"$ref": "#/components/schemas/TestDataPermissionsGrantRequest"
}
]
},
"example": {"contextIdentifier":{"type":"Nip","value":"7762811692"},"authorizedIdentifier":{"type":"Nip","value":"7762811692"},"permissions":[{"description":"Opis testowy","permissionType":"InvoiceRead"}]}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/permissions/revoke": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Odebranie uprawnień testowemu podmiotowi/osobie fizycznej",
"description": "Odbieranie uprawnień nadanych testowemu podmiotowi lub osobie fizycznej, a także w ich kontekście.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"contextIdentifier",
"authorizedIdentifier"
],
"allOf": [
{
"$ref": "#/components/schemas/TestDataPermissionsRevokeRequest"
}
]
},
"example": {"contextIdentifier":{"type":"Nip","value":"5265877635"},"authorizedIdentifier":{"type":"Nip","value":"7762811692"}}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/attachment": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Umożliwienie wysyłania faktur z załącznikiem",
"description": "Dodaje możliwość wysyłania faktur z załącznikiem przez wskazany podmiot",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"nip"
],
"allOf": [
{
"$ref": "#/components/schemas/AttachmentPermissionGrantRequest"
}
]
},
"example": {"nip":"7762811692"}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/testdata/attachment/revoke": {
"post": {
"tags": [
"Dane testowe"
],
"summary": "Odebranie możliwości wysyłania faktur z załącznikiem",
"description": "Odbiera możliwość wysyłania faktur z załącznikiem przez wskazany podmiot",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"nip"
],
"allOf": [
{
"$ref": "#/components/schemas/AttachmentPermissionRevokeRequest"
}
]
},
"example": {"nip":"7762811692"}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/limits/context": {
"get": {
"tags": [
"Limity i ograniczenia"
],
"summary": "Pobranie limitów dla bieżącego kontekstu",
"description": "Zwraca wartości aktualnie obowiązujących limitów dla bieżącego kontekstu.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EffectiveContextLimits"
},
"example": {"onlineSession":{"maxInvoiceSizeInMB":1,"maxInvoiceWithAttachmentSizeInMB":3,"maxInvoices":10000},"batchSession":{"maxInvoiceSizeInMB":1,"maxInvoiceWithAttachmentSizeInMB":3,"maxInvoices":10000}}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/limits/subject": {
"get": {
"tags": [
"Limity i ograniczenia"
],
"summary": "Pobranie limitów dla bieżącego podmiotu",
"description": "Zwraca wartoście aktualnie obowiązujących limitów dla bieżącego podmiotu.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EffectiveSubjectLimits"
},
"example": {"enrollment":{"maxEnrollments":6},"certificate":{"maxCertificates":2}}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/rate-limits": {
"get": {
"tags": [
"Limity i ograniczenia"
],
"summary": "Pobranie aktualnie obowiązujących limitów API",
"description": "Zwraca wartości aktualnie obowiązujących limitów ilości żądań przesyłanych do API.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EffectiveApiRateLimits"
},
"example": {"onlineSession":{"perSecond":10,"perMinute":30,"perHour":120},"batchSession":{"perSecond":10,"perMinute":20,"perHour":120},"invoiceSend":{"perSecond":10,"perMinute":30,"perHour":180},"invoiceStatus":{"perSecond":30,"perMinute":120,"perHour":720},"sessionList":{"perSecond":5,"perMinute":10,"perHour":60},"sessionInvoiceList":{"perSecond":10,"perMinute":20,"perHour":200},"sessionMisc":{"perSecond":10,"perMinute":120,"perHour":720},"invoiceMetadata":{"perSecond":8,"perMinute":16,"perHour":20},"invoiceExport":{"perSecond":4,"perMinute":8,"perHour":20},"invoiceDownload":{"perSecond":8,"perMinute":16,"perHour":64},"other":{"perSecond":10,"perMinute":30,"perHour":120}}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/testdata/limits/context/session": {
"post": {
"tags": [
"Limity i ograniczenia"
],
"summary": "Zmiana limitów sesji dla bieżącego kontekstu",
"description": "Zmienia wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu. **Tylko na środowiskach testowych.**",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"onlineSession",
"batchSession"
],
"allOf": [
{
"$ref": "#/components/schemas/SetSessionLimitsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
},
"delete": {
"tags": [
"Limity i ograniczenia"
],
"summary": "Przywrócenie domyślnych wartości limitów sesji dla bieżącego kontekstu",
"description": "Przywraca wartości aktualnie obowiązujących limitów sesji dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/testdata/limits/subject/certificate": {
"post": {
"tags": [
"Limity i ograniczenia"
],
"summary": "Zmiana limitów certyfikatów dla bieżącego podmiotu",
"description": "Zmienia wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu. **Tylko na środowiskach testowych.**",
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SetSubjectLimitsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
},
"delete": {
"tags": [
"Limity i ograniczenia"
],
"summary": "Przywrócenie domyślnych wartości limitów certyfikatów dla bieżącego podmiotu",
"description": "Przywraca wartości aktualnie obowiązujących limitów certyfikatów dla bieżącego podmiotu do wartości domyślnych. **Tylko na środowiskach testowych.**",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/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łąnych do API dla bieżącego kontekstu. **Tylko na środowiskach testowych.**",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"rateLimits"
],
"allOf": [
{
"$ref": "#/components/schemas/SetRateLimitsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
},
"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łąnych do API dla bieżącego kontekstu do wartości domyślnych. **Tylko na środowiskach testowych.**",
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/permissions/persons/grants": {
"post": {
"tags": [
"Nadawanie uprawnień"
],
"summary": "Nadanie osobom fizycznym uprawnień do pracy w KSeF",
"description": "Metoda pozwala na nadanie osobie wskazanej w żądaniu uprawnień do pracy w KSeF \nw kontekście bieżącym.\n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur, \n- **InvoiceRead** – przeglądanie faktur, \n- **CredentialsManage** – zarządzanie uprawnieniami, \n- **CredentialsRead** – przeglądanie uprawnień, \n- **Introspection** – przeglądanie historii sesji i generowanie UPO, \n- **SubunitManage** – zarządzanie jednostkami podrzędnymi, \n- **EnforcementOperations** – wykonywanie operacji egzekucyjnych.\n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień. \nUprawnienie **EnforcementOperations** może być nadane wyłącznie wtedy, \ngdy podmiot kontekstu ma rolę **EnforcementAuthority** (organ egzekucyjny) \nlub **CourtBailiff** (komornik sądowy).\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadawanie-uprawnie%C5%84-osobom-fizycznym-do-pracy-w-ksef)\n\n**Wymagane uprawnienia**: `CredentialsManage`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectIdentifier",
"permissions",
"description"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsGrantRequest"
}
]
},
"example": {"subjectIdentifier":{"type":"Pesel","value":"15062788702"},"permissions":["InvoiceRead","InvoiceWrite","Introspection","CredentialsRead"],"description":"Opis uprawnienia"}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage"
]
}
},
"/api/v2/permissions/entities/grants": {
"post": {
"tags": [
"Nadawanie uprawnień"
],
"summary": "Nadanie podmiotom uprawnień do obsługi faktur",
"description": "Metoda pozwala na nadanie podmiotowi wskazanemu w żądaniu uprawnień do obsługi faktur podmiotu kontekstu. \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień. \nDla każdego uprawnienia może być ustawiona flaga **canDelegate**, mówiąca o możliwości jego dalszego przekazywania poprzez nadawanie w sposób pośredni.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-podmiotom-uprawnie%C5%84-do-obs%C5%82ugi-faktur)\n\n**Wymagane uprawnienia**: `CredentialsManage`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectIdentifier",
"permissions",
"description"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityPermissionsGrantRequest"
}
]
},
"example": {"subjectIdentifier":{"type":"Nip","value":"7762811692"},"permissions":[{"type":"InvoiceRead","canDelegate":true},{"type":"InvoiceWrite","canDelegate":true}],"description":"Opis uprawnienia"}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage"
]
}
},
"/api/v2/permissions/authorizations/grants": {
"post": {
"tags": [
"Nadawanie uprawnień"
],
"summary": "Nadanie uprawnień podmiotowych",
"description": "Metoda pozwala na nadanie jednego z uprawnień podmiotowych do obsługi podmiotu kontekstu podmiotowi wskazanemu w żądaniu.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-podmiotowych)\n\n**Wymagane uprawnienia**: `CredentialsManage`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectIdentifier",
"permission",
"description"
],
"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."}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage"
]
}
},
"/api/v2/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 /api/v2/permissions/entities/grants](/docs/v2/index.html#tag/Nadawanie-uprawnien/paths/~1api~1v2~1permissions~1entities~1grants/post)). \n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-w-spos%C3%B3b-po%C5%9Bredni)\n\n**Wymagane uprawnienia**: `CredentialsManage`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectIdentifier",
"permissions",
"description"
],
"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"}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage"
]
}
},
"/api/v2/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ą. \nW żądaniu podaje się również nazwę tej jednostki. \n \nUprawnienia administratora jednostki podrzędnej obejmują: \n- **CredentialsManage** – zarządzanie uprawnieniami \n \nMetoda automatycznie nadaje powyższe uprawnienie, bez konieczności podawania go w żądaniu.\n \n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-podrz%C4%99dnego)\n\n**Wymagane uprawnienia**: `SubunitManage`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectIdentifier",
"contextIdentifier",
"description"
],
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsGrantRequest"
}
]
},
"example": {"subjectIdentifier":{"type":"Pesel","value":"15062788702"},"contextIdentifier":{"type":"InternalId","value":"7762811692-12345"},"description":"Opis uprawnienia","subunitName":"Jednostka 014"}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"SubunitManage"
]
}
},
"/api/v2/permissions/eu-entities/administration/grants": {
"post": {
"tags": [
"Nadawanie uprawnień"
],
"summary": "Nadanie uprawnień administratora podmiotu unijnego",
"description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień administratora w kontekście złożonym z identyfikatora NIP podmiotu kontekstu bieżącego oraz numeru VAT UE podmiotu unijnego wskazanego w żądaniu. \nWraz z utworzeniem administratora podmiotu unijnego tworzony jest kontekst złożony składający się z numeru NIP podmiotu kontekstu logowania oraz wskazanego numeru identyfikacyjnego VAT UE podmiotu unijnego. \nW żądaniu podaje się również nazwę i adres podmiotu unijnego. \n \nJedynym sposobem identyfikacji uprawnianego jest odcisk palca certyfikatu kwalifikowanego: \n- certyfikat podpisu elektronicznego dla osób fizycznych \n- certyfikat pieczęci elektronicznej dla podmiotów \n \nUprawnienia administratora podmiotu unijnego obejmują: \n- **VatEuManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n- **Introspection** – przeglądanie historii sesji \n \nMetoda automatycznie nadaje wszystkie powyższe uprawnienia, bez konieczności ich wskazywania w żądaniu.\n \n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-administratora-podmiotu-unijnego)\n\n**Wymagane uprawnienia**: `CredentialsManage`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectIdentifier",
"contextIdentifier",
"description",
"euEntityName"
],
"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."}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage"
]
}
},
"/api/v2/permissions/eu-entities/grants": {
"post": {
"tags": [
"Nadawanie uprawnień"
],
"summary": "Nadanie uprawnień reprezentanta podmiotu unijnego",
"description": "Metoda pozwala na nadanie wskazanemu w żądaniu podmiotowi lub osobie fizycznej uprawnień do wystawiania i/lub przeglądania faktur w kontekście złożonym kontekstu bieżącego. \n \nJedynym sposobem identyfikacji uprawnianego jest odcisk palca certyfikatu kwalifikowanego: \n- certyfikat podpisu elektronicznego dla osób fizycznych \n- certyfikat pieczęci elektronicznej dla podmiotów \n \nW żądaniu określane są nadawane uprawnienia ze zbioru: \n- **InvoiceWrite** – wystawianie faktur \n- **InvoiceRead** – przeglądanie faktur \n \nMetoda pozwala na wybór dowolnej kombinacji powyższych uprawnień.\n\n> Więcej informacji:\n> - [Nadawanie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#nadanie-uprawnie%C5%84-reprezentanta-podmiotu-unijnego)\n\n**Wymagane uprawnienia**: `VatUeManage`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"subjectIdentifier",
"permissions",
"description"
],
"allOf": [
{
"$ref": "#/components/schemas/EuEntityPermissionsGrantRequest"
}
]
},
"example": {"subjectIdentifier":{"type":"Fingerprint","value":"CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59"},"permissions":["InvoiceRead","InvoiceWrite"],"description":"Opis uprawnienia"}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"VatUeManage"
]
}
},
"/api/v2/permissions/common/grants/{permissionId}": {
"delete": {
"tags": [
"Odbieranie uprawnień"
],
"summary": "Odebranie uprawnień",
"description": "Metoda pozwala na odebranie uprawnienia o wskazanym identyfikatorze. \nWymagane jest wcześniejsze odczytanie uprawnień w celu uzyskania \nidentyfikatora uprawnienia, które ma zostać odebrane.\n\n> Więcej informacji:\n> - [Odbieranie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84)\n\n**Wymagane uprawnienia**: `CredentialsManage`, `VatUeManage`, `SubunitManage`.",
"parameters": [
{
"name": "permissionId",
"in": "path",
"description": "Id uprawnienia.",
"required": true,
"schema": {
"$ref": "#/components/schemas/PermissionId"
}
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage",
"VatUeManage",
"SubunitManage"
]
}
},
"/api/v2/permissions/authorizations/grants/{permissionId}": {
"delete": {
"tags": [
"Odbieranie uprawnień"
],
"summary": "Odebranie uprawnień podmiotowych",
"description": "Metoda pozwala na odebranie uprawnienia podmiotowego o wskazanym identyfikatorze. \nWymagane jest wcześniejsze odczytanie uprawnień w celu uzyskania \nidentyfikatora uprawnienia, które ma zostać odebrane.\n \n> Więcej informacji:\n> - [Odbieranie uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#odebranie-uprawnie%C5%84-podmiotowych)\n\n**Wymagane uprawnienia**: `CredentialsManage`.",
"parameters": [
{
"name": "permissionId",
"in": "path",
"description": "Id uprawnienia.",
"required": true,
"schema": {
"$ref": "#/components/schemas/PermissionId"
}
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationResponse"
},
"example": {"referenceNumber":"20250626-EG-333C814000-C529F710D8-D2"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage"
]
}
},
"/api/v2/permissions/operations/{referenceNumber}": {
"get": {
"tags": [
"Operacje"
],
"summary": "Pobranie statusu operacji",
"description": "Zwraca status operacji asynchronicznej związanej z nadaniem lub odebraniem uprawnień.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny operacji nadania lub odbierania uprawnień.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PermissionsOperationStatusResponse"
},
"example": {"status":{"code":200,"description":"Operacja zakończona sukcesem"}}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/permissions/attachments/status": {
"get": {
"tags": [
"Operacje"
],
"summary": "Sprawdzenie statusu zgody na wystawianie faktur z załącznikiem",
"description": "Sprawdzenie czy obecny kontekst posiada zgodę na wystawianie faktur z załącznikiem.\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckAttachmentPermissionStatusResponse"
}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"CredentialsManage",
"CredentialsRead"
]
}
},
"/api/v2/invoices/ksef/{ksefNumber}": {
"get": {
"tags": [
"Pobieranie faktur"
],
"summary": "Pobranie faktury po numerze KSeF",
"description": "Zwraca fakturę o podanym numerze KSeF.\n\n**Wymagane uprawnienia**: `InvoiceRead`.",
"parameters": [
{
"name": "ksefNumber",
"in": "path",
"description": "Numer KSeF faktury.",
"required": true,
"schema": {
"$ref": "#/components/schemas/KsefNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/xml": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|\n| 21164 | Faktura o podanym identyfikatorze nie istnieje. | Faktura o numerze KSeF {ksefNumber} nie została znaleziona. |\n| 21165 | Faktura o podanym numerze KSeF nie jest jeszcze dostępna. | Faktura o numerze KSeF {ksefNumber} została przetworzona, ale nie jest jeszcze dostępna do pobrania. Spróbuj ponownie później. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceRead"
]
}
},
"/api/v2/invoices/query/metadata": {
"post": {
"tags": [
"Pobieranie faktur"
],
"summary": "Pobranie listy metadanych faktur",
"description": "Zwraca metadane faktur spełniających filtry.\n\nLimit techniczny: ≤ 10 000 rekordów na zestaw filtrów, po jego osiągnięciu isTruncated = true i należy ponownie ustawić dateRange, używając ostatniej daty z wyników (tj. ustawić from/to - w zależności od kierunku sortowania, od daty ostatniego zwróconego rekordu) oraz wyzerować pageOffset.\n\n`Do scenariusza przyrostowego należy używać daty PermanentStorage oraz kolejność sortowania Asc`.\n \nScenariusz pobierania przyrostowego (skrót):\n* Gdy hasMore = false, należy zakończyć,\n* Gdy hasMore = true i isTruncated = false, należy zwiększyć pageOffset,\n* Gdy hasMore = true i isTruncated = true, należy zawęzić dateRange (ustawić from od daty ostatniego rekordu), wyzerować pageOffset i kontynuować\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc | Desc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.",
"parameters": [
{
"name": "sortOrder",
"in": "query",
"description": "Kolejność sortowania wyników.\n| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n",
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SortOrder"
}
],
"description": "| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n",
"default": "Asc"
}
},
{
"name": "pageOffset",
"in": "query",
"description": "Indeks pierwszej strony wyników (0 = pierwsza strona).",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 250,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"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:22:13.388+00:00"},"amount":{"type":"Brutto","from":100.50,"to":250.00},"currencyCodes":["PLN","EUR"],"invoicingMode":"Online","formType":"FA","invoiceTypes":["Vat"],"hasAttachment":true}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryInvoicesMetadataResponse"
},
"example": {"hasMore":false,"isTruncated":false,"invoices":[{"ksefNumber":"5555555555-20250828-010080615740-E4","invoiceNumber":"FA/KUDYO1a7dddfe-610e-4843-84ba-6b887e35266e","issueDate":"2025-08-27","invoicingDate":"2025-08-28T09:22:13.388+00:00","acquisitionDate":"2025-08-28T09:22:56.388+00:00","permanentStorageDate":"2025-08-28T09:23:01.388+00:00","seller":{"nip":"5555555555","name":"Test Company 1"},"buyer":{"identifier":{"type":"Nip","value":"7352765225"},"name":"Test Company 4"},"netAmount":35260.63,"grossAmount":43370.57,"vatAmount":8109.94,"currency":"PLN","invoicingMode":"Offline","invoiceType":"Vat","formCode":{"systemCode":"FA (3)","schemaVersion":"1-0E","value":"FA"},"isSelfInvoicing":false,"hasAttachment":false,"invoiceHash":"mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=","thirdSubjects":[]},{"ksefNumber":"5555555555-20250828-010080615740-E4","invoiceNumber":"5265877635-20250925-010020A0A242-0A","issueDate":"2025-08-28","invoicingDate":"2025-08-28T10:23:13.388+00:00","acquisitionDate":"2025-08-28T10:23:56.388+00:00","permanentStorageDate":"2025-08-28T10:24:01.388+00:00","seller":{"nip":"5555555555","name":"Test Company 1"},"buyer":{"identifier":{"type":"Nip","value":"3225081610"},"name":"Test Company 2"},"netAmount":35260.63,"grossAmount":43370.57,"vatAmount":8109.94,"currency":"PLN","invoicingMode":"Online","invoiceType":"Vat","formCode":{"systemCode":"FA (3)","schemaVersion":"1-0E","value":"FA"},"isSelfInvoicing":false,"hasAttachment":true,"invoiceHash":"o+nMBU8n8TAhy6EjbcdYdHSZVbUspqmCKqOPLhy3zIQ=","thirdSubjects":[{"identifier":{"type":"InternalId","value":"5555555555-12345"},"name":"Wystawca faktury","role":4}]}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"allowedFields": [
"permanentStorageDate",
"invoicingDate",
"issueDate"
],
"allowedDirections": [
"Asc",
"Desc"
]
}
],
"x-required-permissions": [
"InvoiceRead"
]
}
},
"/api/v2/invoices/exports": {
"post": {
"tags": [
"Pobieranie faktur"
],
"summary": "Eksport paczki faktur",
"description": "Rozpoczyna asynchroniczny proces wyszukiwania faktur w systemie KSeF na podstawie przekazanych filtrów oraz przygotowania ich w formie zaszyfrowanej paczki.\nWymagane jest przekazanie informacji o szyfrowaniu w polu Encryption, które służą do zabezpieczenia przygotowanej paczki z fakturami.\nMaksymalnie można uruchomić 10 równoczesnych eksportów w zalogowanym kontekście.\n \nSystem pobiera faktury rosnąco według daty określonej w filtrze (Invoicing, Issue, PermanentStorage) i dodaje faktury(nazwa pliku: {ksefNumber}.xml) do paczki aż do osiągnięcia jednego z poniższych limitów:\n* Limit liczby faktur: 10 000 sztuk\n* Limit rozmiaru danych(skompresowanych): 1GB\n\nPaczka eksportu zawiera dodatkowy plik z metadanymi faktur w formacie JSON (`_metadata.json`). Zawartość pliku to\nobiekt z tablicą invoices, gdzie każdy element jest obiektem typu InvoiceMetadata\n(taki jak zwracany przez endpoint `POST /invoices/query/metadata`).\n\nPlik z metadanymi(_metadata.json) nie jest wliczany do limitów algorytmu budowania paczki. \n\n`Do realizacji pobierania przyrostowego należy stosować filtrowanie po dacie PermanentStorage`.\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.",
"requestBody": {
"description": "Dane wejściowe określające kryteria i format eksportu paczki faktur.",
"content": {
"application/json": {
"schema": {
"required": [
"encryption",
"filters"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceExportRequest"
}
]
},
"example": {"encryption":{"encryptedSymmetricKey":"Rk1Qb1VhVjMyQ3NxQ1h1WlVtZUdHcDJSZ0pTbE5IbWQ=","initializationVector":"c29tZUluaXRWZWN0b3I="},"filters":{"subjectType":"Subject1","dateRange":{"dateType":"Issue","from":"2025-08-28T09:22:13.388+00:00","to":"2025-09-28T09:22:13.388+00:00"}}}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportInvoicesResponse"
},
"example": {"referenceNumber":"20251010-EH-1B6C9EB000-4B15D3AEB9-89"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------|\n| 21181 | Nieprawidłowe żądanie eksportu faktur. | Nie można wyeksportować paczki faktur dla wybranego podmiotu ({subjecttype}) i zalogowanego identyfikatoru kontekstu ({type}). |\n| 21182 | Osiągnięto limit trwających eksportów. | Dla uwierzytelnionego podmiotu w bieżącym kontekście osiągnięto maksymalny limit {count} równoczesnych eksportów faktur. Spróbuj ponownie później. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"allowedFields": [
"permanentStorageDate",
"invoicingDate",
"issueDate"
],
"allowedDirections": "Asc"
}
],
"x-required-permissions": [
"InvoiceRead"
]
}
},
"/api/v2/invoices/exports/{referenceNumber}": {
"get": {
"tags": [
"Pobieranie faktur"
],
"summary": "Pobranie statusu eksportu paczki faktur",
"description": "Paczka faktur jest dzielona na części o maksymalnym rozmiarze 50 MB. Każda część jest zaszyfrowana algorytmem AES-256-CBC z dopełnieniem PKCS#7, przy użyciu klucza symetrycznego przekazanego podczas inicjowania eksportu. \n\nW przypadku ucięcia wyniku eksportu z powodu przekroczenia limitów, zwracana jest flaga IsTruncated = true oraz odpowiednia data, którą należy wykorzystać do wykonania kolejnego eksportu, aż do momentu, gdy flaga IsTruncated = false.\n\n**Sortowanie:**\n\n- permanentStorageDate | invoicingDate | issueDate (Asc) - pole wybierane na podstawie filtrów\n\n\n\n**Wymagane uprawnienia**: `InvoiceRead`.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny eksportu faktur.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvoiceExportStatusResponse"
},
"example": {"status":{"code":200,"description":"Eksport faktur zakończony sukcesem"},"completedDate":"2025-09-16T16:09:40.901091+00:00","package":{"invoiceCount":10000,"size":22425060,"parts":[{"ordinalNumber":1,"partName":"20250925-EH-2D2C11B000-E9C9ED8340-EE-001.zip.aes","method":"GET","url":"https://ksef-api-storage/storage/00/20250626-eh-2d2c11b000-e9c9ed8340-ee/invoice-part/20250925-EH-2D2C11B000-E9C9ED8340-EE-001.zip.aes?skoid=1ad7cfe8-2cb2-406b-b96c-6eefb55794db&sktid=647754c7-3974-4442-a425-c61341b61c69&skt=2025-06-26T09%3A40%3A54Z&ske=2025-06-26T10%3A10%3A54Z&sks=b&skv=2025-01-05&sv=2025-01-05&se=2025-06-26T10%3A10%3A54Z&sr=b&sp=w&sig=8mKZEU8Reuz%2Fn7wHi4T%2FY8BzLeD5l8bR2xJsBxIgDEY%3D","partSize":22425060,"partHash":"BKH9Uy1CjBFXiQdDUM2CJYk5LxWTm4fE1lljnl83Ajw=","encryptedPartSize":22425072,"encryptedPartHash":"HlvwRLc59EJH7O5GoeHEZxTQO5TJ/WP1QH0aFi4x2Ss=","expirationDate":"2025-09-16T17:09:40.901091+00:00"}],"isTruncated":true,"lastPermanentStorageDate":"2025-09-11T11:40:40.266578+00:00"}}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------|\n| 21175 | Wynik zapytania o podanym identyfikatorze nie istnieje. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"allowedFields": [
"permanentStorageDate",
"invoicingDate",
"issueDate"
],
"allowedDirections": "Asc"
}
],
"x-required-permissions": [
"InvoiceRead"
]
}
},
"/api/v2/sessions": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie listy sesji",
"description": "Zwraca listę sesji spełniających podane kryteria wyszukiwania.\n\n\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n\n**Wymagane uprawnienia**:\n- `Introspection` – pozwala pobrać wszystkie sesje w bieżącym kontekście uwierzytelnienia `(ContextIdentifier)`.\n- `InvoiceWrite` – pozwala pobrać wyłącznie sesje utworzone przez podmiot uwierzytelniający, czyli podmiot inicjujący uwierzytelnienie.",
"parameters": [
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony.",
"schema": {
"maximum": 500,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"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",
"style": "form",
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommonSessionStatus"
}
}
},
{
"name": "x-continuation-token",
"in": "header",
"description": "Token służący do pobrania kolejnej strony wyników.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionsQueryResponse"
},
"example": {"continuationToken":"W3sidG9rZW4iOiIrUklEOn4zeHd0QU1SM3dYYjRCd0FBQUFBQUNBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBZ2dBQUFBQUFDQUFBQVlBQUFBQUlBQUFBQUFBQUFBZ0FBQVVBUEVIQUVGdGdJUUFFUUJBQUJBRUFCQVVoZ1NBQXdBQUFBQWdBQUFHQUhFa0NFQWxnQVFBQUFBQUlBQUFGZ0F5Q0FVZ0VBRC9nRE9BRFlFdWdIcUF5SXBEZ0IrQUJnQUFBQUFnQUFBQ0FPNlYiLCJyYW5nZSI6eyJtaW4iOiIiLCJtYXgiOiIwNUMxREYyQjVGMzU5OCJ9fV0=","sessions":[{"referenceNumber":"20250925-SO-2F67776000-97273B191A-65","status":{"code":200,"description":"Sesja interaktywna przetworzona pomyślnie"},"dateCreated":"2025-09-25T13:48:26.8700925+00:00","dateUpdated":"2025-09-26T02:16:07+00:00","validUntil":"2025-09-26T01:48:26.8700925+00:00","totalInvoiceCount":2,"successfulInvoiceCount":2,"failedInvoiceCount":0},{"referenceNumber":"20250928-SO-494B541000-3AD87C01BA-5D","status":{"code":200,"description":"Sesja interaktywna przetworzona pomyślnie"},"dateCreated":"2025-09-28T21:20:54.5936927+00:00","dateUpdated":"2025-09-29T10:19:28+00:00","validUntil":"2025-09-29T09:20:54.5936927+00:00","totalInvoiceCount":3,"successfulInvoiceCount":3,"failedInvoiceCount":0}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "dateCreated",
"direction": "Desc"
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection"
]
}
},
"/api/v2/sessions/{referenceNumber}": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie statusu sesji",
"description": "Sprawdza bieżący status sesji o podanym numerze referencyjnym.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny sesji.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionStatusResponse"
},
"example": {"status":{"code":200,"description":"Sesja interaktywna przetworzona pomyślnie"},"upo":{"pages":[{"referenceNumber":"20250918-EU-2EBD6FA000-242EB9B66D-43","downloadUrl":"https://ksef-test.mf.gov.pl/storage/01/20250918-sb-3789a40000-20373e1269-a3/session-upo/upo_00.xml?sv=2025-01-05&st=2025-09-18T14%3A55%3A50Z&se=2025-09-21T15%3A00%3A50Z&sr=b&sp=r&sig=ZlQO6Xtzu3VQQDwmEMfb0VryMxe9WcUgWtkdiB6X2Qo%3D","downloadUrlExpirationDate":"2025-09-21T15:00:50+00:00"}]},"invoiceCount":10,"successfulInvoiceCount":8,"failedInvoiceCount":2}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/{referenceNumber}/invoices": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie faktur sesji",
"description": "Zwraca listę faktur przesłanych w sesji wraz z ich statusami, oraz informacje na temat ilości poprawnie i niepoprawnie przetworzonych faktur.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`.",
"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": 500,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInvoicesResponse"
},
"example": {"continuationToken":"W34idG9rZW4iOiIrUklEOn4xUE5BQU5hcXJVOUFBQUFBQUFBQUFBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBVUFBQUFBQUFBQUFRZ0FBQUFBQUFBQT0iLCJyYW5nZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fV0=","invoices":[{"ordinalNumber":1,"invoiceNumber":"FA/XPWIC-7900685789/06/2025","ksefNumber":"5265877635-20250626-010080DD2B5E-26","referenceNumber":"20250918-EE-2F15D39000-242207E5C4-1B","invoiceHash":"mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=","acquisitionDate":"2025-09-18T12:24:16.0154302+00:00","invoicingDate":"2025-09-18T12:23:56.0154302+00:00","permanentStorageDate":"2025-09-18T12:24:01.0154302+00:00","upoDownloadUrl":"https://ksef-test.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"]}}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie statusu faktury z sesji",
"description": "Zwraca fakturę przesłaną w sesji wraz ze statusem.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny sesji.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
},
{
"name": "invoiceReferenceNumber",
"in": "path",
"description": "Numer referencyjny faktury.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInvoiceStatusResponse"
},
"example": {"ordinalNumber":2,"referenceNumber":"20250626-EE-2F20AD2000-242386DF86-52","invoicingDate":"2025-07-11T12:23:56.0154302+00:00","status":{"code":440,"description":"Duplikat faktury","details":["Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4"]}}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/{referenceNumber}/invoices/failed": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie niepoprawnie przetworzonych faktur sesji",
"description": "Zwraca listę niepoprawnie przetworzonych faktur przesłanych w sesji wraz z ich statusami.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`.",
"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": 500,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionInvoicesResponse"
},
"example": {"continuationToken":"...","invoices":[{"ordinalNumber":2,"referenceNumber":"20250626-EE-2F20AD2000-242386DF86-52","invoiceHash":"mkht+3m5trnfxlTYhq3QFn74LkEO69MFNlsMAkCDSPA=","invoiceFileName":"invoice1.xml","invoicingDate":"2025-07-11T12:23:56.0154302+00:00","status":{"code":440,"description":"Duplikat faktury","details":["Duplikat faktury. Faktura o numerze KSeF: 5265877635-20250626-010080DD2B5E-26 została już prawidłowo przesłana do systemu w sesji: 20250626-SO-2F14610000-242991F8C9-B4"]}}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie UPO faktury z sesji na podstawie numeru KSeF",
"description": "Zwraca UPO faktury przesłanego w sesji na podstawie jego numeru KSeF.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`.",
"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",
"content": {
"application/xml": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 21178 | Nie znaleziono UPO dla podanych kryteriów. | UPO o numerze KSeF {ksefNumber} i numerze referencyjnym sesji {referenceNumber} nie zostało znalezione. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie UPO faktury z sesji na podstawie numeru referencyjnego faktury",
"description": "Zwraca UPO faktury przesłanego w sesji na podstawie jego numeru KSeF.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny sesji.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
},
{
"name": "invoiceReferenceNumber",
"in": "path",
"description": "Numer referencyjny faktury.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/xml": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/{referenceNumber}/upo/{upoReferenceNumber}": {
"get": {
"tags": [
"Status wysyłki i UPO"
],
"summary": "Pobranie UPO dla sesji",
"description": "Zwraca XML zawierający zbiorcze UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `Introspection`, `PefInvoiceWrite`.",
"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",
"content": {
"application/xml": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21178 | Nie znaleziono UPO dla podanych kryteriów. | UPO o numerze referencyjnym {referenceNumber} dla sesji {referenceNumber} nie zostało znalezione. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"Introspection",
"PefInvoiceWrite"
]
}
},
"/api/v2/tokens": {
"post": {
"tags": [
"Tokeny KSeF"
],
"summary": "Wygenerowanie nowego tokena",
"description": "Zwraca token, który może być użyty do uwierzytelniania się w KSeF.\n\nToken może być generowany tylko w kontekście NIP lub identyfikatora wewnętrznego. Jest zwracany tylko raz. Zaczyna być aktywny w momencie gdy jego status zmieni się na `Active`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"permissions",
"description"
],
"allOf": [
{
"$ref": "#/components/schemas/GenerateTokenRequest"
}
]
},
"example": {"permissions":["InvoiceRead","InvoiceWrite"],"description":"Wystawianie i przeglądanie faktur."}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateTokenResponse"
},
"example": {"referenceNumber":"20251010-EC-1DCE3E3000-12ECB5B36E-45","token":"20251010-EC-1DCE3E3000-12ECB5B36E-45|internalId-5265877635-12345|919f704466624ce29cd5ac7b65ded5e7cccc112eee314f2aaa76e02cd16df7b9"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|---------------------|------------------------------------------------------------|---------|\n| 26001 | Nie można nadać tokenowi uprawnień których nie posiadasz. | Informacja o brakujących uprawnieniach. |\n| 26002 | Nie można wygenerować tokena dla obecnego typu kontekstu. | Informacja o aktualnym i dozwolonych typach kontekstu. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
},
"get": {
"tags": [
"Tokeny KSeF"
],
"summary": "Pobranie listy wygenerowanych tokenów",
"description": "\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n",
"parameters": [
{
"name": "status",
"in": "query",
"description": "Status tokenów do zwrócenia. W przypadku braku parametru zwracane są wszystkie tokeny. Parametr można przekazać wielokrotnie.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n",
"style": "form",
"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,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
},
{
"name": "x-continuation-token",
"in": "header",
"description": "Token służący do pobrania kolejnej strony wyników.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryTokensResponse"
},
"example": {"continuationToken":"W3sidG9rZW4iOiIrUklEOn4zeHd0QUlqZUc5VkhCQUFBQUFBQUJBPT0jUlQ6MSNUUkM6MTAjSVNWOjIjSUVPOjY1NTY3I1FDRjo4I0ZQQzpBZ2dBQUFBQUFCQUFBQUFBQUFBQUVBQUFBQUFBQUFBUUFBQUVBRWVFMllFPSIsInJhbmdlIjp7Im1pbiI6IjA1QzFERjIxOUY5OTIwIiwibWF4IjoiRkYifX1d","tokens":[{"referenceNumber":"20251001-EC-2DD3AFF000-A6B7F19A95-11","authorIdentifier":{"type":"Nip","value":"5265877635"},"contextIdentifier":{"type":"Nip","value":"5265877635"},"description":"Wystawianie i przeglądanie faktur.","requestedPermissions":["InvoiceRead","InvoiceWrite"],"dateCreated":"2025-10-01T13:20:52.9919681+00:00","status":"Active","statusDetails":[]}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-------------------------------------------------------------|\n| 21418 | Przekazany token kontynuacji ma nieprawidłowy format. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "dateCreated",
"direction": "Desc"
}
]
}
},
"/api/v2/tokens/{referenceNumber}": {
"get": {
"tags": [
"Tokeny KSeF"
],
"summary": "Pobranie statusu tokena",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny tokena KSeF.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenStatusResponse"
},
"example": {"referenceNumber":"20251001-EC-220B0CE000-E228129563-96","authorIdentifier":{"type":"Nip","value":"7762811692"},"contextIdentifier":{"type":"Nip","value":"5265877635"},"description":"Wystawianie i przeglądanie faktur.","requestedPermissions":["InvoiceWrite","InvoiceRead"],"dateCreated":"2025-07-11T12:23:56.0154302+00:00","lastUseDate":"2025-07-11T12:23:56.0154302+00:00","status":"Pending","statusDetails":[]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
},
"delete": {
"tags": [
"Tokeny KSeF"
],
"summary": "Unieważnienie tokena",
"description": "Unieważniony token nie pozwoli już na uwierzytelnienie się za jego pomocą. Unieważnienie nie może zostać cofnięte.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny tokena KSeF.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/peppol/query": {
"get": {
"tags": [
"Usługi Peppol"
],
"summary": "Pobranie listy dostawców usług Peppol",
"description": "Zwraca listę dostawców usług Peppol zarejestrowanych w systemie.\n\n**Sortowanie:**\n\n- dateCreated (Desc)\n\n",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryPeppolProvidersResponse"
},
"example": {"peppolProviders":[{"id":"P123456789","name":"Dostawca usług Peppol","dateCreated":"2025-07-11T12:23:56.0154302+00:00"}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
},
"x-sort": [
{
"field": "dateCreated",
"direction": "Desc"
}
]
}
},
"/api/v2/auth/challenge": {
"post": {
"tags": [
"Uzyskiwanie dostępu"
],
"summary": "Inicjalizacja uwierzytelnienia",
"description": "Generuje unikalny challenge wymagany w kolejnym kroku operacji uwierzytelnienia.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationChallengeResponse"
},
"example": {"challenge":"20250514-CR-226FB7B000-3ACF9BE4C0-10","timestamp":"2025-07-11T12:23:56.0154302+00:00"}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/auth/xades-signature": {
"post": {
"tags": [
"Uzyskiwanie dostępu"
],
"summary": "Uwierzytelnienie z wykorzystaniem podpisu XAdES",
"description": "Rozpoczyna operację uwierzytelniania za pomocą dokumentu XML podpisanego podpisem elektronicznym XAdES.\n\n> Więcej informacji:\n> - [Przygotowanie dokumentu XML](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#1-przygotowanie-dokumentu-xml-authtokenrequest)\n> - [Podpis dokumentu XML](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#2-podpisanie-dokumentu-xades)\n> - [Schemat XSD](/docs/v2/schemas/authv2.xsd)",
"parameters": [
{
"name": "verifyCertificateChain",
"in": "query",
"description": "Wymuszenie weryfikacji zaufania łańcucha certyfikatu wraz ze sprawdzeniem statusu certyfikatu (OCSP/CRL) na środowiskach które umożliwiają wykorzystanie samodzielnie wygenerowanych certyfikatów.",
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"content": {
"application/xml": {
"schema": {
"type": "string"
},
"example": "\n\n 20250625-CR-20F5EE4000-DA48AE4124-46\n \n 5265877635\n \n certificateSubject\n \n \n \n"
}
},
"required": true
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationInitResponse"
},
"example": {"referenceNumber":"20250514-AU-2DFC46C000-3AC6D5877F-D4","authenticationToken":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiT3BlcmF0aW9uVG9rZW4iLCJvcGVyYXRpb24tcmVmZXJlbmNlLW51bWJlciI6IjIwMjUwNTE0LUFVLTJERkM0NkMwMDAtM0FDNkQ1ODc3Ri1ENCIsImV4cCI6MTc0NzIzMTcxOSwiaWF0IjoxNzQ3MjI5MDE5LCJpc3MiOiJrc2VmLWFwaS10aSIsImF1ZCI6ImtzZWYtYXBpLXRpIn0.rtRcV2mR9SiuJwpQaQHsbAXvvVsdNKG4DJsdiJctIeU","validUntil":"2025-07-11T12:23:56.0154302+00:00"}}
}
}
},
"400": {
"description": " | ExceptionCode | ExceptionDescription | Details | \n|---------------------|---------------------------------------------------------------------|-------------------------------------------------------------|\n| 21001 | Nieczytelna treść. | |\n| 21111 | Nieprawidłowe wyzwanie autoryzacyjne. | |\n| 21115 | Nieprawidłowy certyfikat. | |\n| 21117 | Nieprawidłowy identyfikator podmiotu dla wskazanego typu kontekstu. | |\n| 21217 | Nieprawidłowe kodowanie znaków. | |\n| 21401 | Dokument nie jest zgodny ze schemą (xsd). | {treść błędu walidacji} |\n| 21406 | Konflikt podpisu i typu uwierzytelnienia. | |\n| 9101 | Nieprawidłowy dokument. | |\n| 9102 | Brak podpisu. | |\n| 9103 | Przekroczona liczba dozwolonych podpisów. | |\n| 9105 | Nieprawidłowy podpis. | |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/auth/ksef-token": {
"post": {
"tags": [
"Uzyskiwanie dostępu"
],
"summary": "Uwierzytelnienie z wykorzystaniem tokena KSeF",
"description": "Rozpoczyna operację uwierzytelniania z wykorzystaniem wcześniej wygenerowanego tokena KSeF.\n\nToken KSeF wraz z timestampem ze wcześniej wygenerowanego challenge'a (w formacie ```token|timestamp```) powinien zostać zaszyfrowany dedykowanym do tego celu kluczem publicznym.\n- Timestamp powinien zostać przekazany jako **liczba milisekund od 1 stycznia 1970 roku (Unix timestamp)**.\n- Algorytm szyfrowania: **RSA-OAEP (z użyciem SHA-256 jako funkcji skrótu)**.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"challenge",
"contextIdentifier",
"encryptedToken"
],
"allOf": [
{
"$ref": "#/components/schemas/InitTokenAuthenticationRequest"
}
]
},
"example": {"challenge":"20250625-CR-2FDC223000-C2BFC98A9C-4E","contextIdentifier":{"type":"Nip","value":"5265877635"},"encryptedToken":"..."}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationInitResponse"
},
"example": {"referenceNumber":"20250514-AU-2DFC46C000-3AC6D5877F-D4","authenticationToken":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiT3BlcmF0aW9uVG9rZW4iLCJvcGVyYXRpb24tcmVmZXJlbmNlLW51bWJlciI6IjIwMjUwNTE0LUFVLTJERkM0NkMwMDAtM0FDNkQ1ODc3Ri1ENCIsImV4cCI6MTc0NzIzMTcxOSwiaWF0IjoxNzQ3MjI5MDE5LCJpc3MiOiJrc2VmLWFwaS10aSIsImF1ZCI6ImtzZWYtYXBpLXRpIn0.rtRcV2mR9SiuJwpQaQHsbAXvvVsdNKG4DJsdiJctIeU","validUntil":"2025-07-11T12:23:56.0154302+00:00"}}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
}
}
}
},
"/api/v2/auth/{referenceNumber}": {
"get": {
"tags": [
"Uzyskiwanie dostępu"
],
"summary": "Pobranie statusu uwierzytelniania",
"description": "Sprawdza bieżący status operacji uwierzytelniania dla podanego tokena.\n\nSposób uwierzytelnienia: `AuthenticationToken` otrzymany przy rozpoczęciu operacji uwierzytelniania.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny tokena otrzymanego przy inicjalizacji operacji uwierzytelniania.",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationOperationStatusResponse"
},
"examples": {
"Kod 100 | Uwierzytelnianie w toku": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":100,"description":"Uwierzytelnianie w toku"}}
},
"Kod 200 | Uwierzytelnianie zakończone sukcesem": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":200,"description":"Uwierzytelnianie zakończone sukcesem"}}
},
"Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Nieważny certyfikat": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":400,"description":"Uwierzytelnianie zakończone niepowodzeniem","details":["Nieważny certyfikat."]}}
},
"Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Błąd weryfikacji łańcucha certyfikatów": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":400,"description":"Uwierzytelnianie zakończone niepowodzeniem","details":["Błąd weryfikacji łańcucha certyfikatów."]}}
},
"Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Niezaufany łańcuch certyfikatów": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":400,"description":"Uwierzytelnianie zakończone niepowodzeniem","details":["Niezaufany łańcuch certyfikatów."]}}
},
"Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Certyfikat odwołany": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":400,"description":"Uwierzytelnianie zakończone niepowodzeniem","details":["Certyfikat odwołany."]}}
},
"Kod 400 | Uwierzytelnianie zakończone niepowodzeniem | Niepoprawny certyfikat": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":400,"description":"Uwierzytelnianie zakończone niepowodzeniem","details":["Niepoprawny certyfikat."]}}
},
"Kod 500 | Nieznany błąd": {
"value": {"startDate":"0001-01-01T00:00:00+00:00","authenticationMethod":"Token","status":{"code":500,"description":"Nieznany błąd ({statusCode})"}}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/auth/token/redeem": {
"post": {
"tags": [
"Uzyskiwanie dostępu"
],
"summary": "Pobranie tokenów dostępowych",
"description": "Pobiera parę tokenów (access token i refresh token) wygenerowanych w ramach pozytywnie zakończonego procesu uwierzytelniania.\n**Tokeny można pobrać tylko raz.**\n\nSposób uwierzytelnienia: `AuthenticationToken` otrzymany przy rozpoczęciu operacji uwierzytelniania.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationTokensResponse"
},
"example": {"accessToken":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE","validUntil":"2025-07-11T12:23:56.0154302+00:00"},"refreshToken":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE","validUntil":"2025-07-11T12:23:56.0154302+00:00"}}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/auth/token/refresh": {
"post": {
"tags": [
"Uzyskiwanie dostępu"
],
"summary": "Odświeżenie tokena dostępowego",
"description": "Generuje nowy token dostępu na podstawie ważnego refresh tokena.\n\nSposób uwierzytelnienia: `RefreshToken`.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationTokenRefreshResponse"
},
"example": {"accessToken":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbi10eXBlIjoiQ29udGV4dFRva2VuIiwiY29udGV4dC1pZGVudGlmaWVyLXR5cGUiOiJOaXAiLCJjb250ZXh0LWlkZW50aWZpZXItdmFsdWUiOiIzNzU2OTc3MDQ5IiwiYXV0aGVudGljYXRpb24tbWV0aG9kIjoiUXVhbGlmaWVkU2VhbCIsInN1YmplY3QtZGV0YWlscyI6IntcIlN1YmplY3RJZGVudGlmaWVyXCI6e1wiVHlwZVwiOlwiTmlwXCIsXCJWYWx1ZVwiOlwiMzc1Njk3NzA0OVwifX0iLCJleHAiOjE3NDcyMjAxNDksImlhdCI6MTc0NzIxOTI0OSwiaXNzIjoia3NlZi1hcGktdGkiLCJhdWQiOiJrc2VmLWFwaS10aSJ9.R_3_R2PbdCk8T4WP_0XGOO1iVNu2ugNxmkDvsD0soIE","validUntil":"2025-07-11T12:23:56.0154302+00:00"}}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|-----------------------------------------------------------------------------|\n| 21304 | Brak uwierzytelnienia. | Operacja uwierzytelniania o numerze referencyjnym {referenceNumber} nie została znaleziona. |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
]
}
},
"/api/v2/sessions/online": {
"post": {
"tags": [
"Wysyłka interaktywna"
],
"summary": "Otwarcie sesji interaktywnej",
"description": "Otwiera sesję do wysyłki pojedynczych faktur. Należy przekazać schemat wysyłanych faktur oraz informacje o kluczu używanym do szyfrowania.\n\n> Więcej informacji:\n> - [Otwarcie sesji interaktywnej](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md#1-otwarcie-sesji)\n> - [Klucz publiczny Ministersta Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"formCode",
"encryption"
],
"allOf": [
{
"$ref": "#/components/schemas/OpenOnlineSessionRequest"
}
]
},
"example": {"formCode":{"systemCode":"FA (3)","schemaVersion":"1-0E","value":"FA"},"encryption":{"encryptedSymmetricKey":"bdUVjqLj+y2q6aBUuLxxXYAMqeDuIBRTyr+hB96DaWKaGzuVHw9p+Nk9vhzgF/Q5cavK2k6eCh6SdsrWI0s9mFFj4A4UJtsyD8Dn3esLfUZ5A1juuG3q3SBi/XOC/+9W+0T/KdwdE393mbiUNyx1K/0bw31vKJL0COeJIDP7usAMDl42/H1TNvkjk+8iZ80V0qW7D+RZdz+tdiY1xV0f2mfgwJ46V0CpZ+sB9UAssRj+eVffavJ0TOg2b5JaBxE8MCAvrF6rO5K4KBjUmoy7PP7g1qIbm8xI2GO0KnfPOO5OWj8rsotRwBgu7x19Ine3qYUvuvCZlXRGGZ5NHIzWPM4O74+gNalaMgFCsmv8mMhETSU4SfAGmJr9edxPjQSbgD5i2X4eDRDMwvyaAa7CP1b2oICju+0L7Fywd2ZtUcr6El++eTVoi8HYsTArntET++gULT7XXjmb8e3O0nxrYiYsE9GMJ7HBGv3NOoJ1NTm3a7U6+c0ZJiBVLvn6xXw10LQX243xH+ehsKo6djQJKYtqcNPaXtCwM1c9RrsOx/wRXyWCtTffqLiaR0LbYvfMJAcEWceG+RaeAx4p37OiQqdJypd6LAv9/0ECWK8Bip8yyoA+0EYiAJb9YuDz2YlQX9Mx9E9FzFIAsgEQ2w723HZYWgPywLb+dlsum4lTZKQ=","initializationVector":"OmtDQdl6vkOI1GLKZSjgEg=="}}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenOnlineSessionResponse"
},
"example": {"referenceNumber":"20250625-SO-2C3E6C8000-B675CF5D68-07","validUntil":"2025-07-11T12:23:56.0154302+00:00"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/online/{referenceNumber}/invoices": {
"post": {
"tags": [
"Wysyłka interaktywna"
],
"summary": "Wysłanie faktury",
"description": "Przyjmuje zaszyfrowaną fakturę oraz jej metadane i rozpoczyna jej przetwarzanie.\n\n> Więcej informacji:\n> - [Wysłanie faktury](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md#2-wys%C5%82anie-faktury)\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny sesji",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"requestBody": {
"description": "Dane faktury",
"content": {
"application/json": {
"schema": {
"required": [
"invoiceHash",
"invoiceSize",
"encryptedInvoiceHash",
"encryptedInvoiceSize",
"encryptedInvoiceContent"
],
"allOf": [
{
"$ref": "#/components/schemas/SendInvoiceRequest"
}
]
},
"example": {"invoiceHash":"EbrK4cOSjW4hEpJaHU71YXSOZZmqP5++dK9nLgTzgV4=","invoiceSize":6480,"encryptedInvoiceHash":"miYb1z3Ljw5VucTZslv3Tlt+V/EK1V8Q8evD8HMQ0dc=","encryptedInvoiceSize":6496,"encryptedInvoiceContent":"...","offlineMode":false}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendInvoiceResponse"
},
"example": {"referenceNumber":"20250625-EE-319D7EE000-B67F415CDC-2C"}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została odnaleziona. |\n| 21155 | Przekroczono dozwoloną liczbę faktur w sesji. | Sesja o numerze referencyjnym {referenceNumber} osiągnęła dozwolony limit liczby faktur {invoiceLimit}. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia wysyłkę faktur. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"PefInvoiceWrite"
]
}
},
"/api/v2/sessions/online/{referenceNumber}/close": {
"post": {
"tags": [
"Wysyłka interaktywna"
],
"summary": "Zamknięcie sesji interaktywnej",
"description": "Zamyka sesję interaktywną i rozpoczyna generowanie zbiorczego UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`, `PefInvoiceWrite`.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny sesji",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|----------------------------------------------------------------------------|\n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została odnaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia jej zamknięcie. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite",
"PefInvoiceWrite"
]
}
},
"/api/v2/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> - [Przygotwanie paczki faktur](https://github.com/CIRFMF/ksef-docs/blob/main/sesja-wsadowa.md)\n> - [Klucz publiczny Ministersta Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)\n\n**Wymagane uprawnienia**: `InvoiceWrite`.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"formCode",
"batchFile",
"encryption"
],
"allOf": [
{
"$ref": "#/components/schemas/OpenBatchSessionRequest"
}
]
},
"example": {"formCode":{"systemCode":"FA (2)","schemaVersion":"1-0E","value":"FA"},"batchFile":{"fileSize":16037,"fileHash":"WO86CC+1Lef11wEosItld/NPwxGN8tobOMLqk9PQjgs=","fileParts":[{"ordinalNumber":1,"fileSize":16048,"fileHash":"23ZyDAN0H/+yhC/En2xbNfF0tajAWSfejDaXD7fc2AE="}]},"encryption":{"encryptedSymmetricKey":"bYqmPAglF01AxZim4oNa+1NerhZYfFgLMnvksBprUur1aesQ0Y5jsmOIfCrozfMkF2tjdO+uOsBg4FPlDgjChwN2/tz2Hqwtxq3RkTr1SjY4x8jxJFpPedcS7EI+XO8C+i9mLj7TFx9p/bg07yM9vHtMAk5b88Ay9Qc3+T5Ch1DM2ClR3sVu2DqdlKzmbINY+rhfGtXn58Qo0XRyESGgc6M0iTZVBRPuPXLnD8a1KpOneCpNzLwxgT6Ei3ivLOpPWT53PxkRTaQ8puj6CIiCKo4FHQzHuI/NmrAhYU7TkNm2kymP/OxBgWdg3XB74tqNFfT8RZN1bZXuPhBidDOqa+xsqY3E871FSDmQwZf58HmoNl31XNvpnryiRGfnAISt+m+ELqgksAresVu6E9poUL1yiff+IOHSZABoYpNiqwnbT8qyW1uk8lKLyFVFu+kOsbzBk1OWWHqSkNFDaznDa2MKjHonOXI0uyKaKWvoBFC4dWN1PVumfpSSFAeYgNpAyVrZdcVOuiliEWepTDjGzJoOafTvwr5za2S6B5bPECDpX7JXazV7Olkq7ezG0w8y3olx+0C+NHoCk8B5/cm4gtVHTgKjiLSGpKJVOJABLXFkOyIOjbQsVe4ryX0Qy+SfL7JIQvTWvM5xkCoOMbzLdMo9tNo5qE34sguFI+lIevY=","initializationVector":"jWpJLNBHJ5pQEGCBglmIAw=="},"offlineMode":false}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenBatchSessionResponse"
},
"example": {"referenceNumber":"20250626-SB-213D593000-4DE10D80A5-E9","partUploadRequests":[{"ordinalNumber":1,"method":"PUT","url":"https://ksef-api-storage/storage/00/20250626-sb-213d593000-4de10d80a5-e9/batch-parts/1?skoid=1ad7cfe8-2cb2-406b-b96c-6eefb55794db&sktid=647754c7-3974-4442-a425-c61341b61c69&skt=2025-06-26T09%3A40%3A54Z&ske=2025-06-26T10%3A10%3A54Z&sks=b&skv=2025-01-05&sv=2025-01-05&se=2025-06-26T10%3A10%3A54Z&sr=b&sp=w&sig=8mKZEU8Reuz%2Fn7wHi4T%2FY8BzLeD5l8bR2xJsBxIgDEY%3D","headers":{"x-ms-blob-type":"BlockBlob"}}]}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------------------|\n| 21157 | Nieprawidłowy rozmiar części pakietu. | {treść błędu walidacji} | \n| 21161 | Przekroczono dozwoloną liczbę części pakietu. | {treść błędu walidacji} |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite"
]
}
},
"/api/v2/sessions/batch/{referenceNumber}/close": {
"post": {
"tags": [
"Wysyłka wsadowa"
],
"summary": "Zamknięcie sesji wsadowej",
"description": "Zamyka sesję wsadową, rozpoczyna procesowanie paczki faktur i generowanie UPO dla prawidłowych faktur oraz zbiorczego UPO dla sesji.\n\n**Wymagane uprawnienia**: `InvoiceWrite`.",
"parameters": [
{
"name": "referenceNumber",
"in": "path",
"description": "Numer referencyjny sesji",
"required": true,
"schema": {
"$ref": "#/components/schemas/ReferenceNumber"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details | \n|---------------------|-----------------------------------------------------|---------------------------------------------------------------------------|\n| 21157 | Nieprawidłowy rozmiar części pakietu. | Zadeklarowany rozmiar części '{ordinalNumber}' nie zgadza się z rzeczywistym. | \n| 21173 | Brak sesji o wskazanym numerze referencyjnym. | Sesja o numerze referencyjnym {referenceNumber} nie została znaleziona. |\n| 21180 | Status sesji nie pozwala na wykonanie operacji. | Status sesji {code} uniemożliwia jej zamknięcie. |\n| 21205 | Pakiet nie może być pusty. | Nie przesłano zadeklarowanej '{ordinalNumber}' części pliku. |\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-required-permissions": [
"InvoiceWrite"
]
}
},
"/api/v2/permissions/query/personal/grants": {
"post": {
"tags": [
"Wyszukiwanie nadanych uprawnień"
],
"summary": "Pobranie listy własnych uprawnień",
"description": " Metoda pozwala na odczytanie własnych uprawnień uwierzytelnionego klienta API w bieżącym kontekście logowania. \n\n W odpowiedzi przekazywane są następujące uprawnienia: \n - nadane w sposób bezpośredni w bieżącym kontekście \n - nadane przez podmiot nadrzędny \n - nadane w sposób pośredni, jeżeli podmiot kontekstu logowania jest w uprawnieniu pośrednikiem lub podmiotem docelowym \n - nadane podmiotowi do obsługi faktur przez inny podmiot, jeśli podmiot uwierzytelniony ma w bieżącym kontekście uprawnienia właścicielskie \n\n Uprawnienia zwracane przez operację obejmują: \n - **CredentialsManage** – zarządzanie uprawnieniami \n - **CredentialsRead** – przeglądanie uprawnień \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n - **SubunitManage** – zarządzanie podmiotami podrzędnymi \n - **EnforcementOperations** – wykonywanie operacji egzekucyjnych \n - **VatEuManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **contextIdentifier** – identyfikator podmiotu, który nadał uprawnienie do obsługi faktur \n - **targetIdentifier** – identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n - **permissionState** – status uprawnienia \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-w%C5%82asnych-uprawnie%C5%84)\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PersonalPermissionsQueryRequest"
}
]
},
"example": {"contextIdentifier":{"type":"Nip","value":"3568707925"},"permissionTypes":["InvoiceWrite"],"permissionState":"Active"}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryPersonalPermissionsResponse"
},
"example": {"permissions":[{"id":"0c9a72e8-f344-457f-9c16-7c640eb60242","contextIdentifier":{"type":"Nip","value":"3568707925"},"authorizedIdentifier":{"type":"Nip","value":"5247677742"},"permissionScope":"InvoiceWrite","description":"Opis uprawnienia","permissionState":"Active","startDate":"2025-06-22T10:41:11+00:00","canDelegate":false}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
]
}
},
"/api/v2/permissions/query/persons/grants": {
"post": {
"tags": [
"Wyszukiwanie nadanych uprawnień"
],
"summary": "Pobranie listy uprawnień do pracy w KSeF nadanych osobom fizycznym lub podmiotom",
"description": " Metoda pozwala na odczytanie uprawnień nadanych osobie fizycznej lub podmiotowi. \n Lista pobranych uprawnień może być dwóch rodzajów: \n - Lista wszystkich uprawnień obowiązujących w bieżącym kontekście logowania (używana, gdy administrator chce przejrzeć uprawnienia wszystkich użytkowników w bieżącym kontekście) \n - Lista wszystkich uprawnień nadanych w bieżącym kontekście przez uwierzytelnionego klienta API (używana, gdy administrator chce przejrzeć listę nadanych przez siebie uprawnień w bieżącym kontekście) \n\n Dla pierwszej listy (obowiązujących uprawnień) w odpowiedzi przekazywane są: \n - osoby i podmioty mogące pracować w bieżącym kontekście z wyjątkiem osób uprawnionych w sposób pośredni \n - osoby uprawnione w sposób pośredni przez podmiot bieżącego kontekstu \n\n Dla drugiej listy (nadanych uprawnień) w odpowiedzi przekazywane są: \n - uprawnienia nadane w sposób bezpośredni do pracy w bieżącym kontekście lub w kontekście jednostek podrzędnych \n - uprawnienia nadane w sposób pośredni do obsługi klientów podmiotu bieżącego kontekstu \n\n Uprawnienia zwracane przez operację obejmują: \n - **CredentialsManage** – zarządzanie uprawnieniami \n - **CredentialsRead** – przeglądanie uprawnień \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n - **SubunitManage** – zarządzanie podmiotami podrzędnymi \n - **EnforcementOperations** – wykonywanie operacji egzekucyjnych \n\n Odpowiedź może być filtrowana na podstawie parametrów: \n - **authorIdentifier** – identyfikator osoby, która nadała uprawnienie \n - **authorizedIdentifier** – identyfikator osoby lub podmiotu uprawnionego \n - **targetIdentifier** – identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n - **permissionState** – status uprawnienia \n - **queryType** – typ zapytania określający, która z dwóch list ma zostać zwrócona \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-do-pracy-w-ksef-nadanych-osobom-fizycznym-lub-podmiotom)\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"queryType"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsQueryRequest"
}
]
},
"example": {"authorIdentifier":{"type":"Nip","value":"7762811692"},"permissionTypes":["CredentialsManage","CredentialsRead","InvoiceWrite"],"permissionState":"Active","queryType":"PermissionsInCurrentContext"}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryPersonPermissionsResponse"
},
"example": {"permissions":[{"id":"0c9a72e8-f344-457f-9c16-7c640eb60242","authorizedIdentifier":{"type":"Nip","value":"7762811692"},"targetIdentifier":{"type":"Nip","value":"9786214922"},"authorIdentifier":{"type":"Pesel","value":"15062788702"},"permissionScope":"InvoiceWrite","description":"praca dla klienta 9786214922; uprawniony NIP: 7762811692, Adam Abacki; pośrednik 3936518395","permissionState":"Active","startDate":"2025-06-22T10:41:11+00:00","canDelegate":false}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
],
"x-required-permissions": [
"CredentialsManage",
"CredentialsRead",
"SubunitManage"
]
}
},
"/api/v2/permissions/query/subunits/grants": {
"post": {
"tags": [
"Wyszukiwanie nadanych uprawnień"
],
"summary": "Pobranie listy uprawnień administratorów jednostek i podmiotów podrzędnych",
"description": " Metoda pozwala na odczytanie uprawnień do zarządzania uprawnieniami nadanych administratorom: \n - jednostek podrzędnych identyfikowanych identyfikatorem wewnętrznym \n - podmiotów podrzędnych (podrzędnych JST lub członków grupy VAT) identyfikowanych przez NIP \n\n Lista zwraca wyłącznie uprawnienia do zarządzania uprawnieniami nadane z kontekstu bieżącego (z podmiotu nadrzędnego). \n Nie są odczytywane uprawnienia nadane przez administratorów jednostek podrzędnych wewnątrz tych jednostek. \n\n Odpowiedź może być filtrowana na podstawie parametru: \n - **subunitIdentifier** – identyfikator jednostki lub podmiotu podrzędnego \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-administrator%C3%B3w-jednostek-i-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsQueryRequest"
}
]
},
"example": {"subunitIdentifier":{"type":"InternalId","value":"7762811692-12345"}}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuerySubunitPermissionsResponse"
},
"example": {"permissions":[{"id":"0c9a72e8-f344-457f-9c16-7c640eb60242","authorizedIdentifier":{"type":"Fingerprint","value":"CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59"},"subunitIdentifier":{"type":"InternalId","value":"7762811692-12345"},"authorIdentifier":{"type":"Pesel","value":"15062788702"},"permissionScope":"CredentialsManage","description":"Opis uprawnienia","startDate":"2025-06-22T10:41:11+00:00"}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
],
"x-required-permissions": [
"CredentialsManage",
"CredentialsRead",
"SubunitManage"
]
}
},
"/api/v2/permissions/query/entities/roles": {
"get": {
"tags": [
"Wyszukiwanie nadanych uprawnień"
],
"summary": "Pobranie listy ról podmiotu",
"description": " Metoda pozwala na **odczytanie listy ról podmiotu bieżącego kontekstu logowania**.\n\n#### Role podmiotów zwracane przez operację:\n- **CourtBailiff** – komornik sądowy \n- **EnforcementAuthority** – organ egzekucyjny \n- **LocalGovernmentUnit** – nadrzędna JST \n- **LocalGovernmentSubUnit** – podrzędne JST \n- **VatGroupUnit** – grupa VAT \n- **VatGroupSubUnit** – członek grupy VAT\n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy ról](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-r%C3%B3l-podmiotu)\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryEntityRolesResponse"
},
"example": {"roles":[{"role":"EnforcementAuthority","description":"Organ egzekucyjny","startDate":"2025-06-22T10:41:11+00:00"}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
],
"x-required-permissions": [
"CredentialsManage",
"CredentialsRead"
]
}
},
"/api/v2/permissions/query/subordinate-entities/roles": {
"post": {
"tags": [
"Wyszukiwanie nadanych uprawnień"
],
"summary": "Pobranie listy podmiotów podrzędnych",
"description": " Metoda pozwala na odczytanie listy podmiotów podrzędnych, \n jeżeli podmiot bieżącego kontekstu ma rolę podmiotu nadrzędnego:\n - **nadrzędna JST** – odczytywane są podrzędne JST, \n - **grupa VAT** – odczytywane są podmioty będące członkami grupy VAT.\n\n Role podmiotów zwracane przez operację obejmują: \n - **LocalGovernmentSubUnit** – podrzędne JST, \n - **VatGroupSubUnit** – członek grupy VAT.\n\n Odpowiedź może być filtrowana według parametru: \n - **subordinateEntityIdentifier** – identyfikator podmiotu podrzędnego.\n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy podmiotów podrzędnych](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-podmiot%C3%B3w-podrz%C4%99dnych)\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `SubunitManage`.",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SubordinateEntityRolesQueryRequest"
}
]
},
"example": {"subordinateEntityIdentifier":{"type":"Nip","value":"7762811692"}}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuerySubordinateEntityRolesResponse"
},
"example": {"roles":[{"subordinateEntityIdentifier":{"type":"Nip","value":"7762811692"},"role":"VatGroupSubUnit","description":"Członek grupy VAT 8373740478","startDate":"2025-06-22T10:41:11+00:00"}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
],
"x-required-permissions": [
"CredentialsManage",
"CredentialsRead",
"SubunitManage"
]
}
},
"/api/v2/permissions/query/authorizations/grants": {
"post": {
"tags": [
"Wyszukiwanie nadanych uprawnień"
],
"summary": "Pobranie listy uprawnień podmiotowych do obsługi faktur",
"description": " Metoda pozwala na odczytanie uprawnień podmiotowych: \n - otrzymanych przez podmiot bieżącego kontekstu \n - nadanych przez podmiot bieżącego kontekstu \n\n Wybór listy nadanych lub otrzymanych uprawnień odbywa się przy użyciu parametru **queryType**. \n\n Uprawnienia zwracane przez operację obejmują: \n - **SelfInvoicing** – wystawianie faktur w trybie samofakturowania \n - **TaxRepresentative** – wykonywanie operacji przedstawiciela podatkowego \n - **RRInvoicing** – wystawianie faktur VAT RR \n - **PefInvoicing** – wystawianie faktur PEF \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **authorizingIdentifier** – identyfikator podmiotu uprawniającego (stosowane przy queryType = Received) \n - **authorizedIdentifier** – identyfikator podmiotu uprawnionego (stosowane przy queryType = Granted) \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n\n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-podmiotowych-do-obs%C5%82ugi-faktur)\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`.",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"queryType"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationPermissionsQueryRequest"
}
]
},
"example": {"authorizedIdentifier":{"type":"Nip","value":"7762811692"},"queryType":"Granted","permissionTypes":["SelfInvoicing","TaxRepresentative","RRInvoicing"]}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryEntityAuthorizationPermissionsResponse"
},
"example": {"authorizationGrants":[{"id":"0c9a72e8-f344-457f-9c16-7c640eb60242","authorIdentifier":{"type":"Pesel","value":"15062788702"},"authorizedEntityIdentifier":{"type":"Nip","value":"7762811692"},"authorizingEntityIdentifier":{"type":"Nip","value":"1134256681"},"authorizationScope":"SelfInvoicing","description":"Uprawnienie podmiotowe do samofakturowania","startDate":"2025-06-22T10:41:11+00:00"}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
],
"x-required-permissions": [
"CredentialsManage",
"CredentialsRead"
]
}
},
"/api/v2/permissions/query/eu-entities/grants": {
"post": {
"tags": [
"Wyszukiwanie nadanych uprawnień"
],
"summary": "Pobranie listy uprawnień administratorów lub reprezentantów podmiotów unijnych uprawnionych do samofakturowania",
"description": " Metoda pozwala na odczytanie uprawnień administratorów lub reprezentantów podmiotów unijnych: \n - Jeżeli kontekstem logowania jest NIP, możliwe jest odczytanie uprawnień administratorów podmiotów unijnych powiązanych z podmiotem bieżącego kontekstu, czyli takich, dla których pierwszy człon kontekstu złożonego jest równy NIP-owi kontekstu logowania. \n - Jeżeli kontekst logowania jest złożony (NIP-VAT UE), możliwe jest pobranie wszystkich uprawnień administratorów i reprezentantów podmiotu w bieżącym kontekście złożonym. \n\n Uprawnienia zwracane przez operację obejmują: \n - **VatUeManage** – zarządzanie uprawnieniami w ramach podmiotu unijnego \n - **InvoiceWrite** – wystawianie faktur \n - **InvoiceRead** – przeglądanie faktur \n - **Introspection** – przeglądanie historii sesji \n\n Odpowiedź może być filtrowana na podstawie następujących parametrów: \n - **vatUeIdentifier** – identyfikator podmiotu unijnego \n - **authorizedFingerprintIdentifier** – odcisk palca certyfikatu uprawnionej osoby lub podmiotu \n - **permissionTypes** – lista rodzajów wyszukiwanych uprawnień \n\n#### Stronicowanie wyników\nZapytanie zwraca **jedną stronę wyników** o numerze i rozmiarze podanym w ścieżce.\n- Przy pierwszym wywołaniu należy ustawić parametr `pageOffset = 0`. \n- Jeżeli dostępna jest kolejna strona wyników, w odpowiedzi pojawi się flaga **`hasMore`**. \n- W takim przypadku można wywołać zapytanie ponownie z kolejnym numerem strony.\n \n > Więcej informacji:\n > - [Pobieranie listy uprawnień](https://github.com/CIRFMF/ksef-docs/blob/main/uprawnienia.md#pobranie-listy-uprawnie%C5%84-administrator%C3%B3w-lub-reprezentant%C3%B3w-podmiot%C3%B3w-unijnych-uprawnionych-do-samofakturowania)\n\n**Sortowanie:**\n\n- startDate (Desc)\n\n\n\n**Wymagane uprawnienia**: `CredentialsManage`, `CredentialsRead`, `VatUeManage`.",
"parameters": [
{
"name": "pageOffset",
"in": "query",
"description": "Numer strony wyników.",
"schema": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "pageSize",
"in": "query",
"description": "Rozmiar strony wyników.",
"schema": {
"maximum": 100,
"exclusiveMaximum": false,
"minimum": 10,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"default": 10
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/EuEntityPermissionsQueryRequest"
}
]
},
"example": {"vatUeIdentifier":"DE123456789012","permissionTypes":["VatUeManage","Introspection"]}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryEuEntityPermissionsResponse"
},
"example": {"permissions":[{"id":"0c9a72e8-f344-457f-9c16-7c640eb60242","authorIdentifier":{"type":"Pesel","value":"15062788702"},"vatUeIdentifier":"DE123456789012","euEntityName":"Podmiot unijny","authorizedFingerprintIdentifier":"CEB3643BAC2C111ADDE971BDA5A80163441867D65389FC0BC0DFF8B4C1CD4E59","permissionScope":"VatUeManage","description":"Opis uprawnienia","startDate":"2025-06-22T10:41:11+00:00"}],"hasMore":false}
}
}
},
"400": {
"description": "| ExceptionCode | ExceptionDescription | Details |\n|-|-|-|\n| 21405 | Błąd walidacji danych wejściowych. | {treść błędu z walidatora} |",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExceptionResponse"
}
}
},
"x-summary": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"Bearer": [ ]
}
],
"x-sort": [
{
"field": "startDate",
"direction": "Desc"
}
],
"x-required-permissions": [
"CredentialsManage",
"CredentialsRead",
"VatUeManage"
]
}
}
},
"components": {
"schemas": {
"AllowedIps": {
"type": "object",
"properties": {
"ip4Addresses": {
"type": "array",
"items": {
"pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$",
"type": "string"
},
"description": "Lista adresów IPv4 w notacji dziesiętnej kropkowanej, np. `192.168.0.10`.",
"nullable": true
},
"ip4Ranges": {
"type": "array",
"items": {
"pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}-((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$",
"type": "string"
},
"description": "Lista adresów IPv4 podana w formie zakresu początek–koniec, oddzielonego pojedynczym myślnikiem, np. `10.0.0.1–10.0.0.254`.",
"nullable": true
},
"ip4Masks": {
"type": "array",
"items": {
"pattern": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}\\/(0|[1-9]|1[0-9]|2[0-9]|3[0-2])$",
"type": "string"
},
"description": "Lista adresów IPv4 w notacji CIDR, np. `172.16.0.0/16`.",
"nullable": true
}
},
"additionalProperties": false
},
"AmountType": {
"enum": [
"Brutto",
"Netto",
"Vat"
],
"type": "string"
},
"ApiRateLimitValuesOverride": {
"required": [
"perHour",
"perMinute",
"perSecond"
],
"type": "object",
"properties": {
"perSecond": {
"type": "integer",
"description": "Limit na sekundę.",
"format": "int32"
},
"perMinute": {
"type": "integer",
"description": "Limit na minutę.",
"format": "int32"
},
"perHour": {
"type": "integer",
"description": "Limit na godzinę.",
"format": "int32"
}
},
"additionalProperties": false
},
"ApiRateLimitsOverride": {
"required": [
"batchSession",
"invoiceDownload",
"invoiceExport",
"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 paczku faktur."
},
"invoiceDownload": {
"required": [
"perSecond",
"perMinute",
"perHour"
],
"allOf": [
{
"$ref": "#/components/schemas/ApiRateLimitValuesOverride"
}
],
"description": "Limity dla pobierania faktur po numerze KSeF."
},
"other": {
"required": [
"perSecond",
"perMinute",
"perHour"
],
"allOf": [
{
"$ref": "#/components/schemas/ApiRateLimitValuesOverride"
}
],
"description": "Limity dla pozostałych operacji API."
}
},
"additionalProperties": false
},
"AttachmentPermissionGrantRequest": {
"required": [
"nip"
],
"type": "object",
"properties": {
"nip": {
"$ref": "#/components/schemas/Nip"
}
},
"additionalProperties": false
},
"AttachmentPermissionRevokeRequest": {
"required": [
"nip"
],
"type": "object",
"properties": {
"nip": {
"$ref": "#/components/schemas/Nip"
}
},
"additionalProperties": false
},
"AuthenticationChallengeResponse": {
"required": [
"challenge",
"timestamp"
],
"type": "object",
"properties": {
"challenge": {
"$ref": "#/components/schemas/Challenge"
},
"timestamp": {
"type": "string",
"description": "Czas wygenerowania challenge-a.",
"format": "date-time"
}
},
"additionalProperties": false
},
"AuthenticationContextIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/AuthenticationContextIdentifierType"
}
],
"description": "Typ identyfikatora"
},
"value": {
"type": "string",
"description": "Wartość identyfikatora"
}
},
"additionalProperties": false
},
"AuthenticationContextIdentifierType": {
"enum": [
"Nip",
"InternalId",
"NipVatUe",
"PeppolId"
],
"type": "string"
},
"AuthenticationInitResponse": {
"required": [
"authenticationToken",
"referenceNumber"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny sesji uwierzytelnienia."
},
"authenticationToken": {
"required": [
"token",
"validUntil"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenInfo"
}
],
"description": "Token operacji uwierzytelnienia."
}
},
"additionalProperties": false
},
"AuthenticationListItem": {
"required": [
"authenticationMethod",
"referenceNumber",
"startDate",
"status"
],
"type": "object",
"properties": {
"startDate": {
"type": "string",
"description": "Data rozpoczęcia operacji uwierzytelnienia.",
"format": "date-time"
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/AuthenticationMethod"
}
],
"description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy uslug Peppol. |\n"
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/StatusInfo"
}
],
"description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Uwierzytelnianie w toku | - |\n| 200 | Uwierzytelnianie zakończone sukcesem | - |\n| 415 | Uwierzytelnianie zakończone niepowodzeniem | Brak przypisanych uprawnień |\n| 425 | Uwierzytelnienie unieważnione | Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy token |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy czas tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token unieważniony |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nieaktywny |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Nieważny certyfikat |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Błąd weryfikacji łańcucha certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niezaufany łańcuch certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Certyfikat odwołany |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niepoprawny certyfikat |\n| 470 | Uwierzytelnianie zakończone niepowodzeniem | Próba wykorzystania metod autoryzacyjnych osoby zmarłej |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |"
},
"isTokenRedeemed": {
"type": "boolean",
"description": "Czy został już wydany refresh token powiązany z danym uwierzytelnieniem.",
"nullable": true
},
"lastTokenRefreshDate": {
"type": "string",
"description": "Data ostatniego odświeżenia tokena.",
"format": "date-time",
"nullable": true
},
"refreshTokenValidUntil": {
"type": "string",
"description": "Termin ważności refresh tokena (o ile nie zostanie wcześniej unieważniony).",
"format": "date-time",
"nullable": true
},
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny sesji uwierzytelnienia."
},
"isCurrent": {
"type": "boolean",
"description": "Czy sesja jest powiązana z aktualnie używanym tokenem.",
"readOnly": true
}
},
"additionalProperties": false
},
"AuthenticationListResponse": {
"required": [
"items"
],
"type": "object",
"properties": {
"continuationToken": {
"type": "string",
"description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.",
"nullable": true
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthenticationListItem"
},
"description": "Lista sesji uwierzytelniania."
}
},
"additionalProperties": false
},
"AuthenticationMethod": {
"enum": [
"Token",
"TrustedProfile",
"InternalCertificate",
"QualifiedSignature",
"QualifiedSeal",
"PersonalSignature",
"PeppolSignature"
],
"type": "string",
"description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy uslug Peppol. |\n"
},
"AuthenticationOperationStatusResponse": {
"required": [
"authenticationMethod",
"startDate",
"status"
],
"type": "object",
"properties": {
"startDate": {
"type": "string",
"description": "Data rozpoczęcia operacji uwierzytelnienia.",
"format": "date-time"
},
"authenticationMethod": {
"allOf": [
{
"$ref": "#/components/schemas/AuthenticationMethod"
}
],
"description": "Metoda uwierzytelnienia.\n| Wartość | Opis |\n| --- | --- |\n| Token | Token KSeF. |\n| TrustedProfile | Profil Zaufany. |\n| InternalCertificate | Certyfikat KSeF. |\n| QualifiedSignature | Podpis kwalifikowany. |\n| QualifiedSeal | Pieczęć kwalifikowana. |\n| PersonalSignature | Podpis osobisty. |\n| PeppolSignature | Podpis dostawcy uslug Peppol. |\n"
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/StatusInfo"
}
],
"description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Uwierzytelnianie w toku | - |\n| 200 | Uwierzytelnianie zakończone sukcesem | - |\n| 415 | Uwierzytelnianie zakończone niepowodzeniem | Brak przypisanych uprawnień |\n| 425 | Uwierzytelnienie unieważnione | Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy token |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Nieprawidłowy czas tokena |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token unieważniony |\n| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token nieaktywny |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Nieważny certyfikat |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Błąd weryfikacji łańcucha certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niezaufany łańcuch certyfikatów |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Certyfikat odwołany |\n| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Niepoprawny certyfikat |\n| 470 | Uwierzytelnianie zakończone niepowodzeniem | Próba wykorzystania metod autoryzacyjnych osoby zmarłej |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |"
},
"isTokenRedeemed": {
"type": "boolean",
"description": "Czy został już wydany refresh token powiązany z danym uwierzytelnieniem.",
"nullable": true
},
"lastTokenRefreshDate": {
"type": "string",
"description": "Data ostatniego odświeżenia tokena.",
"format": "date-time",
"nullable": true
},
"refreshTokenValidUntil": {
"type": "string",
"description": "Termin ważności refresh tokena (o ile nie zostanie wcześniej unieważniony).",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"AuthenticationTokenRefreshResponse": {
"required": [
"accessToken"
],
"type": "object",
"properties": {
"accessToken": {
"required": [
"token",
"validUntil"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenInfo"
}
],
"description": "Token dostępu, którego należy używać w wywołaniach chronionych zasobów API."
}
},
"additionalProperties": false
},
"AuthenticationTokenStatus": {
"enum": [
"Pending",
"Active",
"Revoking",
"Revoked",
"Failed"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n"
},
"AuthenticationTokensResponse": {
"required": [
"accessToken",
"refreshToken"
],
"type": "object",
"properties": {
"accessToken": {
"required": [
"token",
"validUntil"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenInfo"
}
],
"description": "Token dostępu."
},
"refreshToken": {
"required": [
"token",
"validUntil"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenInfo"
}
],
"description": "Token umożliwiający odświeżenie tokenu dostępu.\n> Więcej informacji:\n> - [Odświeżanie tokena](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#od%C5%9Bwie%C5%BCenie-tokena-accesstoken)"
}
},
"additionalProperties": false
},
"AuthorizationPolicy": {
"type": "object",
"properties": {
"allowedIps": {
"allOf": [
{
"$ref": "#/components/schemas/AllowedIps"
}
],
"description": "Lista dozwolonych adresów IP.",
"nullable": true
}
},
"additionalProperties": false
},
"BatchFileInfo": {
"required": [
"fileHash",
"fileParts",
"fileSize"
],
"type": "object",
"properties": {
"fileSize": {
"maximum": 5000000000,
"exclusiveMaximum": false,
"minimum": 1,
"exclusiveMinimum": false,
"type": "integer",
"description": "Rozmiar pliku paczki w bajtach. Maksymalny rozmiar paczki to 5GB.",
"format": "int64"
},
"fileHash": {
"allOf": [
{
"$ref": "#/components/schemas/Sha256HashBase64"
}
],
"description": "Skrót SHA256 pliku paczki, zakodowany w formacie Base64."
},
"fileParts": {
"maxItems": 50,
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchFilePartInfo"
},
"description": "Informacje o częściach pliku paczki. Maksymalna liczba części to 50. Maksymalny dozwolony rozmiar części przed zaszyfrowaniem to 100MB."
}
},
"additionalProperties": false
},
"BatchFilePartInfo": {
"required": [
"fileHash",
"fileSize",
"ordinalNumber"
],
"type": "object",
"properties": {
"ordinalNumber": {
"minimum": 1,
"exclusiveMinimum": false,
"type": "integer",
"description": "Numer sekwencyjny części pliku paczki.",
"format": "int32"
},
"fileName": {
"maxLength": 100,
"type": "string",
"description": "Nazwa części pliku paczki.",
"nullable": true,
"deprecated": true,
"x-removal-date": "2025-12-07"
},
"fileSize": {
"minimum": 1,
"exclusiveMinimum": false,
"type": "integer",
"description": "Rozmiar zaszyfrowanej części pliku paczki w bajtach.",
"format": "int64"
},
"fileHash": {
"allOf": [
{
"$ref": "#/components/schemas/Sha256HashBase64"
}
],
"description": "Skrót SHA256 zaszyfrowanej części pliku paczki, zakodowany w formacie Base64."
}
},
"additionalProperties": false
},
"BatchSessionContextLimitsOverride": {
"required": [
"maxInvoices",
"maxInvoiceSizeInMB",
"maxInvoiceWithAttachmentSizeInMB"
],
"type": "object",
"properties": {
"maxInvoiceSizeInMB": {
"maximum": 5,
"exclusiveMaximum": false,
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury w MB.",
"format": "int32"
},
"maxInvoiceWithAttachmentSizeInMB": {
"maximum": 10,
"exclusiveMaximum": false,
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury z załącznikiem w MB.",
"format": "int32"
},
"maxInvoices": {
"maximum": 100000,
"exclusiveMaximum": false,
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.",
"format": "int32"
}
},
"additionalProperties": false
},
"BatchSessionEffectiveContextLimits": {
"required": [
"maxInvoices",
"maxInvoiceSizeInMB",
"maxInvoiceWithAttachmentSizeInMB"
],
"type": "object",
"properties": {
"maxInvoiceSizeInMB": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury w MB.",
"format": "int32"
},
"maxInvoiceWithAttachmentSizeInMB": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury z załącznikiem w MB.",
"format": "int32"
},
"maxInvoices": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.",
"format": "int32"
}
},
"additionalProperties": false
},
"BuyerIdentifierType": {
"enum": [
"None",
"Other",
"Nip",
"VatUe"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| None | Brak identyfikatora nabywcy |\n| Other | Inny identyfikator |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n"
},
"CertificateEffectiveSubjectLimits": {
"type": "object",
"properties": {
"maxCertificates": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false
},
"CertificateEnrollmentDataResponse": {
"required": [
"commonName",
"countryName"
],
"type": "object",
"properties": {
"commonName": {
"type": "string",
"description": "Nazwa powszechna."
},
"countryName": {
"type": "string",
"description": "Kraj, kod ISO 3166."
},
"givenName": {
"type": "string",
"description": "Imię.",
"nullable": true
},
"surname": {
"type": "string",
"description": "Nazwisko.",
"nullable": true
},
"serialNumber": {
"type": "string",
"description": "Numer seryjny podmiotu.",
"nullable": true
},
"uniqueIdentifier": {
"type": "string",
"description": "Unikalny identyfikator.",
"nullable": true
},
"organizationName": {
"type": "string",
"description": "Nazwa organizacji.",
"nullable": true
},
"organizationIdentifier": {
"type": "string",
"description": "Identyfikator organizacji.",
"nullable": true
}
},
"additionalProperties": false
},
"CertificateEnrollmentStatusResponse": {
"required": [
"requestDate",
"status"
],
"type": "object",
"properties": {
"requestDate": {
"type": "string",
"description": "Data złożenia wniosku certyfikacyjnego.",
"format": "date-time"
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/StatusInfo"
}
],
"description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Wniosek przyjęty do realizacji | - |\n| 200 | Wniosek obsłużony (certyfikat wygenerowany) | - |\n| 400 | Wniosek odrzucony | Klucz publiczny został już certyfikowany przez inny podmiot. |\n| 400 | Wniosek odrzucony | Osiągnięto dopuszczalny limit posiadanych certyfikatów. |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |"
},
"certificateSerialNumber": {
"type": "string",
"description": "Numer seryjny wygenerowanego certyfikatu (w formacie szesnastkowym). \nZwracany w przypadku prawidłowego przeprocesowania wniosku certyfikacyjnego.",
"nullable": true
}
},
"additionalProperties": false
},
"CertificateLimit": {
"required": [
"limit",
"remaining"
],
"type": "object",
"properties": {
"remaining": {
"type": "integer",
"description": "Pozostała wartość limitu.",
"format": "int32"
},
"limit": {
"type": "integer",
"description": "Maksymalna liczba zasobów dozwolona w ramach limitu.",
"format": "int32"
}
},
"additionalProperties": false
},
"CertificateLimitsResponse": {
"required": [
"canRequest",
"certificate",
"enrollment"
],
"type": "object",
"properties": {
"canRequest": {
"type": "boolean",
"description": "Flaga informująca czy uwierzytelniony podmiot może złożyć nowy wniosek o certyfikat.",
"readOnly": true
},
"enrollment": {
"required": [
"remaining",
"limit"
],
"allOf": [
{
"$ref": "#/components/schemas/CertificateLimit"
}
],
"description": "Informacje o limitach związanych z liczbą możliwych do złożenia wniosków certyfikacyjnych."
},
"certificate": {
"required": [
"remaining",
"limit"
],
"allOf": [
{
"$ref": "#/components/schemas/CertificateLimit"
}
],
"description": "Informacje o limitach dotyczących liczby aktywnych certyfikatów wydanych dla danego podmiotu."
}
},
"additionalProperties": false,
"description": "Informacje o limitach wniosków oraz certyfikatów dla uwierzytelnionego podmiotu."
},
"CertificateListItem": {
"required": [
"certificateSerialNumber",
"commonName",
"name",
"requestDate",
"status",
"subjectIdentifier",
"type",
"validFrom",
"validTo"
],
"type": "object",
"properties": {
"certificateSerialNumber": {
"type": "string",
"description": "Numer seryjny certyfikatu (w formacie szesnastkowym)."
},
"name": {
"maxLength": 100,
"type": "string",
"description": "Nazwa własna certyfikatu."
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/KsefCertificateType"
}
],
"description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n"
},
"commonName": {
"type": "string",
"description": "Nazwa powszechna (CN) podmiotu, dla którego wystawiono certyfikat."
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/CertificateListItemStatus"
}
],
"description": "Status certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n"
},
"subjectIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/CertificateSubjectIdentifier"
}
],
"description": "Identyfikator podmiotu, dla którego wystawiono certyfikat."
},
"validFrom": {
"type": "string",
"description": "Data rozpoczęcia ważności certyfikatu.",
"format": "date-time"
},
"validTo": {
"type": "string",
"description": "Data wygaśnięcia certyfikatu.",
"format": "date-time"
},
"lastUseDate": {
"type": "string",
"description": "Data ostatniego użycia certyfikatu.",
"format": "date-time",
"nullable": true
},
"requestDate": {
"type": "string",
"description": "Data złożenia wniosku certyfikacyjnego.",
"format": "date-time"
}
},
"additionalProperties": false
},
"CertificateListItemStatus": {
"enum": [
"Active",
"Blocked",
"Revoked",
"Expired"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n"
},
"CertificateRevocationReason": {
"enum": [
"Unspecified",
"Superseded",
"KeyCompromise"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Unspecified | Nieokreślony. |\n| Superseded | Certyfikat został zastąpiony przez inny. |\n| KeyCompromise | Klucz prywatny powiązany z certyfikatem został skompromitowany. |\n"
},
"CertificateSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/CertificateSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu dla którego wystawiono certyfikat.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"CertificateSubjectIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"CertificateSubjectLimitsOverride": {
"type": "object",
"properties": {
"maxCertificates": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false
},
"Challenge": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "Unikalny challenge."
},
"CheckAttachmentPermissionStatusResponse": {
"type": "object",
"properties": {
"isAttachmentAllowed": {
"type": "boolean",
"description": "Informacja czy Podmiot ma obecnie możliwość dodawania Załączników do Faktur"
},
"revokedDate": {
"type": "string",
"description": "Data i czas zakończenia możliwość dodawania przez Podmiot Załączników do Faktur.\nBrak podanej daty oznacza bezterminową możliwość dodawania Załączników do Faktur",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"CommonSessionStatus": {
"enum": [
"InProgress",
"Succeeded",
"Failed",
"Cancelled"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| InProgress | Sesja aktywna. |\n| Succeeded | Sesja przetworzona poprawnie. W trakcie przetwarzania sesji nie wystąpiły żadne błędy, ale część faktur nadal mogła zostać odrzucona. |\n| Failed | Sesja nie przetworzona z powodu błędów. Na etapie rozpoczynania lub kończenia sesji wystąpiły błędy, które nie pozwoliły na jej poprawne przetworzenie. |\n| Cancelled | Sesja anulowania. Został przekroczony czas na wysyłkę w sesji wsadowej, lub nie przesłano żadnych faktur w sesji interaktywnej. |\n"
},
"CurrencyCode": {
"enum": [
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
"ARS",
"AUD",
"AWG",
"AZN",
"BAM",
"BBD",
"BDT",
"BGN",
"BHD",
"BIF",
"BMD",
"BND",
"BOB",
"BOV",
"BRL",
"BSD",
"BTN",
"BWP",
"BYN",
"BZD",
"CAD",
"CDF",
"CHE",
"CHF",
"CHW",
"CLF",
"CLP",
"CNY",
"COP",
"COU",
"CRC",
"CUC",
"CUP",
"CVE",
"CZK",
"DJF",
"DKK",
"DOP",
"DZD",
"EGP",
"ERN",
"ETB",
"EUR",
"FJD",
"FKP",
"GBP",
"GEL",
"GGP",
"GHS",
"GIP",
"GMD",
"GNF",
"GTQ",
"GYD",
"HKD",
"HNL",
"HRK",
"HTG",
"HUF",
"IDR",
"ILS",
"IMP",
"INR",
"IQD",
"IRR",
"ISK",
"JEP",
"JMD",
"JOD",
"JPY",
"KES",
"KGS",
"KHR",
"KMF",
"KPW",
"KRW",
"KWD",
"KYD",
"KZT",
"LAK",
"LBP",
"LKR",
"LRD",
"LSL",
"LYD",
"MAD",
"MDL",
"MGA",
"MKD",
"MMK",
"MNT",
"MOP",
"MRU",
"MUR",
"MVR",
"MWK",
"MXN",
"MXV",
"MYR",
"MZN",
"NAD",
"NGN",
"NIO",
"NOK",
"NPR",
"NZD",
"OMR",
"PAB",
"PEN",
"PGK",
"PHP",
"PKR",
"PLN",
"PYG",
"QAR",
"RON",
"RSD",
"RUB",
"RWF",
"SAR",
"SBD",
"SCR",
"SDG",
"SEK",
"SGD",
"SHP",
"SLL",
"SOS",
"SRD",
"SSP",
"STN",
"SVC",
"SYP",
"SZL",
"THB",
"TJS",
"TMT",
"TND",
"TOP",
"TRY",
"TTD",
"TWD",
"TZS",
"UAH",
"UGX",
"USD",
"USN",
"UYI",
"UYU",
"UYW",
"UZS",
"VES",
"VND",
"VUV",
"WST",
"XAF",
"XAG",
"XAU",
"XBA",
"XBB",
"XBC",
"XBD",
"XCD",
"XCG",
"XDR",
"XOF",
"XPD",
"XPF",
"XPT",
"XSU",
"XUA",
"XXX",
"YER",
"ZAR",
"ZMW",
"ZWL"
],
"type": "string"
},
"EffectiveApiRateLimitValues": {
"required": [
"perHour",
"perMinute",
"perSecond"
],
"type": "object",
"properties": {
"perSecond": {
"type": "integer",
"description": "Limit na sekundę.",
"format": "int32"
},
"perMinute": {
"type": "integer",
"description": "Limit na minutę.",
"format": "int32"
},
"perHour": {
"type": "integer",
"description": "Limit na godzinę.",
"format": "int32"
}
},
"additionalProperties": false
},
"EffectiveApiRateLimits": {
"required": [
"batchSession",
"invoiceDownload",
"invoiceExport",
"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 paczku faktur."
},
"invoiceDownload": {
"required": [
"perSecond",
"perMinute",
"perHour"
],
"allOf": [
{
"$ref": "#/components/schemas/EffectiveApiRateLimitValues"
}
],
"description": "Limity dla pobierania faktur po numerze KSeF."
},
"other": {
"required": [
"perSecond",
"perMinute",
"perHour"
],
"allOf": [
{
"$ref": "#/components/schemas/EffectiveApiRateLimitValues"
}
],
"description": "Limity dla pozostałych operacji API."
}
},
"additionalProperties": false
},
"EffectiveContextLimits": {
"required": [
"batchSession",
"onlineSession"
],
"type": "object",
"properties": {
"onlineSession": {
"required": [
"maxInvoiceSizeInMB",
"maxInvoiceWithAttachmentSizeInMB",
"maxInvoices"
],
"allOf": [
{
"$ref": "#/components/schemas/OnlineSessionEffectiveContextLimits"
}
],
"description": "Limity dla sesji interaktywnych."
},
"batchSession": {
"required": [
"maxInvoiceSizeInMB",
"maxInvoiceWithAttachmentSizeInMB",
"maxInvoices"
],
"allOf": [
{
"$ref": "#/components/schemas/BatchSessionEffectiveContextLimits"
}
],
"description": "Limity dla sesji wsadowych."
}
},
"additionalProperties": false
},
"EffectiveSubjectLimits": {
"type": "object",
"properties": {
"enrollment": {
"allOf": [
{
"$ref": "#/components/schemas/EnrollmentEffectiveSubjectLimits"
}
],
"nullable": true
},
"certificate": {
"allOf": [
{
"$ref": "#/components/schemas/CertificateEffectiveSubjectLimits"
}
],
"nullable": true
}
},
"additionalProperties": false
},
"EncryptionInfo": {
"required": [
"encryptedSymmetricKey",
"initializationVector"
],
"type": "object",
"properties": {
"encryptedSymmetricKey": {
"type": "string",
"description": "Klucz symetryczny o długości 32 bajtów, zaszyfrowany algorytmem RSA (Padding: OAEP z SHA-256), zakodowany w formacie Base64.\n\n[Klucz publiczny Ministersta Finansów](/docs/v2/index.html#tag/Certyfikaty-klucza-publicznego)",
"format": "byte"
},
"initializationVector": {
"type": "string",
"description": "Wektor inicjalizujący (IV) o długości 16 bajtów, używany do szyfrowania symetrycznego, zakodowany w formacie Base64.",
"format": "byte"
}
},
"additionalProperties": false
},
"EnrollCertificateRequest": {
"required": [
"certificateName",
"certificateType",
"csr"
],
"type": "object",
"properties": {
"certificateName": {
"maxLength": 100,
"minLength": 5,
"pattern": "^[a-zA-Z0-9_\\-\\ ąćęłńóśźżĄĆĘŁŃÓŚŹŻ]+$",
"type": "string",
"description": "Nazwa własna certyfikatu."
},
"certificateType": {
"allOf": [
{
"$ref": "#/components/schemas/KsefCertificateType"
}
],
"description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n"
},
"csr": {
"type": "string",
"description": "Wniosek certyfikacyjny PKCS#10 (CSR) w formacie DER zakodowany w Base64.",
"format": "byte"
},
"validFrom": {
"type": "string",
"description": "Data rozpoczęcia ważności certyfikatu.\nJeśli nie zostanie podana, certyfikat będzie ważny od momentu jego wystawienia.",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"EnrollCertificateResponse": {
"required": [
"referenceNumber",
"timestamp"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny wniosku certyfikacyjnego."
},
"timestamp": {
"type": "string",
"description": "Data złożenia wniosku certyfikacyjnego.",
"format": "date-time"
}
},
"additionalProperties": false
},
"EnrollmentEffectiveSubjectLimits": {
"type": "object",
"properties": {
"maxEnrollments": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false
},
"EnrollmentSubjectLimitsOverride": {
"type": "object",
"properties": {
"maxEnrollments": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false
},
"EntityAuthorizationGrant": {
"required": [
"authorizationScope",
"authorizedEntityIdentifier",
"authorizingEntityIdentifier",
"description",
"id",
"startDate"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PermissionId"
}
],
"description": "Identyfikator uprawnienia."
},
"authorIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorIdentifier"
}
],
"description": "Identyfikator osoby nadającej uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |",
"nullable": true
},
"authorizedEntityIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifier"
}
],
"description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |"
},
"authorizingEntityIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifier"
}
],
"description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"authorizationScope": {
"allOf": [
{
"$ref": "#/components/schemas/InvoicePermissionType"
}
],
"description": "Rodzaj uprawnienia."
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Opis uprawnienia."
},
"startDate": {
"type": "string",
"description": "Data rozpoczęcia obowiązywania uprawnienia.",
"format": "date-time"
}
},
"additionalProperties": false
},
"EntityAuthorizationPermissionType": {
"enum": [
"SelfInvoicing",
"RRInvoicing",
"TaxRepresentative",
"PefInvoicing"
],
"type": "string"
},
"EntityAuthorizationPermissionsGrantRequest": {
"required": [
"description",
"permission",
"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"
}
},
"additionalProperties": false
},
"EntityAuthorizationPermissionsQueryRequest": {
"required": [
"queryType"
],
"type": "object",
"properties": {
"authorizingIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifier"
}
],
"description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |",
"nullable": true
},
"authorizedIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifier"
}
],
"description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |",
"nullable": true
},
"queryType": {
"allOf": [
{
"$ref": "#/components/schemas/QueryType"
}
],
"description": "Typ zapytania.\n| Type | Value |\n| --- | --- |\n| Granted | Uprawnienia nadane innym podmiotom |\n| Received | Uprawnienia otrzymane od innych podmiotów |"
},
"permissionTypes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicePermissionType"
},
"description": "Lista rodzajów wyszukiwanych uprawnień.",
"nullable": true
}
},
"additionalProperties": false
},
"EntityAuthorizationPermissionsSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |"
},
"EntityAuthorizationPermissionsSubjectIdentifierType": {
"enum": [
"Nip",
"PeppolId"
],
"type": "string"
},
"EntityAuthorizationsAuthorIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator osoby nadającej uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"EntityAuthorizationsAuthorIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"EntityAuthorizationsAuthorizedEntityIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorizedEntityIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| PeppolId | Identyfikator dostawcy usług Peppol |"
},
"EntityAuthorizationsAuthorizedEntityIdentifierType": {
"enum": [
"Nip",
"PeppolId"
],
"type": "string"
},
"EntityAuthorizationsAuthorizingEntityIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityAuthorizationsAuthorizingEntityIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"EntityAuthorizationsAuthorizingEntityIdentifierType": {
"enum": [
"Nip"
],
"type": "string"
},
"EntityPermission": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityPermissionType"
}
],
"description": "Rodzaj uprawnienia."
},
"canDelegate": {
"type": "boolean",
"description": "Flaga pozwalająca na pośrednie przekazywanie danego uprawnienia"
}
},
"additionalProperties": false
},
"EntityPermissionType": {
"enum": [
"InvoiceWrite",
"InvoiceRead"
],
"type": "string"
},
"EntityPermissionsGrantRequest": {
"required": [
"description",
"permissions",
"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"
}
},
"additionalProperties": false
},
"EntityPermissionsSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"EntityPermissionsSubjectIdentifierType": {
"enum": [
"Nip"
],
"type": "string"
},
"EntityPermissionsSubordinateEntityIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityPermissionsSubordinateEntityIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"EntityPermissionsSubordinateEntityIdentifierType": {
"enum": [
"Nip"
],
"type": "string"
},
"EntityRole": {
"required": [
"description",
"role",
"startDate"
],
"type": "object",
"properties": {
"parentEntityIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityRolesParentEntityIdentifier"
}
],
"description": "Identyfikator podmiotu nadrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |",
"nullable": true
},
"role": {
"allOf": [
{
"$ref": "#/components/schemas/EntityRoleType"
}
],
"description": "Typ roli - powiązania z podmiotem nadrzędnym."
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Opis roli."
},
"startDate": {
"type": "string",
"description": "Data rozpoczęcia obowiązywania roli.",
"format": "date-time"
}
},
"additionalProperties": false
},
"EntityRoleType": {
"enum": [
"CourtBailiff",
"EnforcementAuthority",
"LocalGovernmentUnit",
"LocalGovernmentSubUnit",
"VatGroupUnit",
"VatGroupSubUnit"
],
"type": "string"
},
"EntityRolesParentEntityIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EntityRolesParentEntityIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu nadrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"EntityRolesParentEntityIdentifierType": {
"enum": [
"Nip"
],
"type": "string"
},
"EuEntityAdministrationPermissionsContextIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EuEntityAdministrationPermissionsContextIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator kontekstu złożonego.\n| Type | Value |\n| --- | --- |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}` |"
},
"EuEntityAdministrationPermissionsContextIdentifierType": {
"enum": [
"NipVatUe"
],
"type": "string"
},
"EuEntityAdministrationPermissionsGrantRequest": {
"required": [
"contextIdentifier",
"description",
"euEntityName",
"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}`"
}
},
"additionalProperties": false
},
"EuEntityAdministrationPermissionsSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EuEntityAdministrationPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"EuEntityAdministrationPermissionsSubjectIdentifierType": {
"enum": [
"Fingerprint"
],
"type": "string"
},
"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": {
"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."
},
"startDate": {
"type": "string",
"description": "Data rozpoczęcia obowiązywania uprawnienia.",
"format": "date-time"
}
},
"additionalProperties": false
},
"EuEntityPermissionType": {
"enum": [
"InvoiceWrite",
"InvoiceRead"
],
"type": "string"
},
"EuEntityPermissionsAuthorIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EuEntityPermissionsAuthorIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"EuEntityPermissionsAuthorIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"EuEntityPermissionsGrantRequest": {
"required": [
"description",
"permissions",
"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"
}
},
"additionalProperties": false
},
"EuEntityPermissionsQueryPermissionType": {
"enum": [
"VatUeManage",
"InvoiceWrite",
"InvoiceRead",
"Introspection"
],
"type": "string"
},
"EuEntityPermissionsQueryRequest": {
"type": "object",
"properties": {
"vatUeIdentifier": {
"pattern": "^(ATU\\d{8}|BE[01]{1}\\d{9}|BG\\d{9,10}|CY\\d{8}[A-Z]|CZ\\d{8,10}|DE\\d{9}|DK\\d{8}|EE\\d{9}|EL\\d{9}|ES([A-Z]\\d{8}|\\d{8}[A-Z]|[A-Z]\\d{7}[A-Z])|FI\\d{8}|FR[A-Z0-9]{2}\\d{9}|HR\\d{11}|HU\\d{8}|IE(\\d{7}[A-Z]{2}|\\d[A-Z0-9+*]\\d{5}[A-Z])|IT\\d{11}|LT(\\d{9}|\\d{12})|LU\\d{8}|LV\\d{11}|MT\\d{8}|NL[A-Z0-9+*]{12}|PT\\d{9}|RO\\d{2,10}|SE\\d{12}|SI\\d{8}|SK\\d{10}|XI((\\d{9}|\\d{12})|(GD|HA)\\d{3}))$",
"type": "string",
"description": "Wartość identyfikatora (numeru identyfikacyjnego VAT) podmiotu unijnego.",
"nullable": true
},
"authorizedFingerprintIdentifier": {
"pattern": "^[0-9A-F]{64}$",
"type": "string",
"description": "Odcisk palca certyfikatu kwalifikowanego uprawnionego.",
"nullable": true
},
"permissionTypes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EuEntityPermissionsQueryPermissionType"
},
"description": "Lista rodzajów wyszukiwanych uprawnień.",
"nullable": true
}
},
"additionalProperties": false
},
"EuEntityPermissionsSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/EuEntityPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu uprawnianego.\n| Type | Value |\n| --- | --- |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"EuEntityPermissionsSubjectIdentifierType": {
"enum": [
"Fingerprint"
],
"type": "string"
},
"ExceptionDetails": {
"type": "object",
"properties": {
"exceptionCode": {
"type": "integer",
"format": "int32"
},
"exceptionDescription": {
"type": "string",
"nullable": true
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
},
"additionalProperties": false
},
"ExceptionInfo": {
"type": "object",
"properties": {
"exceptionDetailList": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExceptionDetails"
},
"nullable": true
},
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"nullable": true
},
"serviceCode": {
"type": "string",
"nullable": true
},
"serviceCtx": {
"type": "string",
"nullable": true
},
"serviceName": {
"type": "string",
"nullable": true
},
"timestamp": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"ExceptionResponse": {
"type": "object",
"properties": {
"exception": {
"allOf": [
{
"$ref": "#/components/schemas/ExceptionInfo"
}
],
"nullable": true
}
},
"additionalProperties": false,
"example": {
"Exception": {
"ExceptionDetailList": [
{
"ExceptionCode": 12345,
"ExceptionDescription": "Opis błędu.",
"Details": [
"Opcjonalne dodatkowe szczegóły błędu."
]
}
],
"ReferenceNumber": "a1b2c3d4-e5f6-4789-ab12-cd34ef567890",
"ServiceCode": "00-c02cc3747020c605be02159bf3324f0e-eee7647dc67aa74a-00",
"ServiceCtx": "srvABCDA",
"ServiceName": "Undefined",
"Timestamp": "2025-10-11T12:23:56.0154302"
}
}
},
"ExportInvoicesResponse": {
"required": [
"referenceNumber"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny eksportu faktur."
}
},
"additionalProperties": false
},
"FormCode": {
"required": [
"schemaVersion",
"systemCode",
"value"
],
"type": "object",
"properties": {
"systemCode": {
"type": "string",
"description": "Kod systemowy"
},
"schemaVersion": {
"type": "string",
"description": "Wersja schematu"
},
"value": {
"type": "string",
"description": "Wartość"
}
},
"additionalProperties": false
},
"GenerateTokenRequest": {
"required": [
"description",
"permissions"
],
"type": "object",
"properties": {
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenPermissionType"
},
"description": "Uprawnienia przypisane tokenowi."
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Opis tokena."
}
},
"additionalProperties": false
},
"GenerateTokenResponse": {
"required": [
"referenceNumber",
"token"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny tokena KSeF."
},
"token": {
"maxLength": 160,
"type": "string",
"description": "Token KSeF."
}
},
"additionalProperties": false
},
"IndirectPermissionType": {
"enum": [
"InvoiceRead",
"InvoiceWrite"
],
"type": "string"
},
"IndirectPermissionsGrantRequest": {
"required": [
"description",
"permissions",
"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"
}
},
"additionalProperties": false
},
"IndirectPermissionsSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/IndirectPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"IndirectPermissionsSubjectIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"IndirectPermissionsTargetIdentifier": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/IndirectPermissionsTargetIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Identyfikator kontekstu klienta. Nie przekazanie identyfikatora oznacza, że uprawnienie nadane w sposób pośredni jest typu generalnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |"
},
"IndirectPermissionsTargetIdentifierType": {
"enum": [
"Nip",
"AllPartners",
"InternalId"
],
"type": "string"
},
"InitTokenAuthenticationRequest": {
"required": [
"challenge",
"contextIdentifier",
"encryptedToken"
],
"type": "object",
"properties": {
"challenge": {
"allOf": [
{
"$ref": "#/components/schemas/Challenge"
}
],
"description": "Wygenerowany wcześniej challenge."
},
"contextIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/AuthenticationContextIdentifier"
}
],
"description": "Indentyfikator kontekstu do którego następuje uwierzytelnienie."
},
"encryptedToken": {
"type": "string",
"description": "Zaszyfrowany token wraz z timestampem z challenge'a, w formacie `token|timestamp`.",
"format": "byte"
},
"authorizationPolicy": {
"allOf": [
{
"$ref": "#/components/schemas/AuthorizationPolicy"
}
],
"description": "Polityka autoryzacji żądań przy każdym użyciu tokena dostępu.",
"nullable": true
}
},
"additionalProperties": false
},
"InternalId": {
"maxLength": 16,
"minLength": 16,
"pattern": "^[1-9]((\\d[1-9])|([1-9]\\d))\\d{7}-\\d{5}$",
"type": "string",
"description": "Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr."
},
"InvoiceExportRequest": {
"required": [
"encryption",
"filters"
],
"type": "object",
"properties": {
"encryption": {
"required": [
"encryptedSymmetricKey",
"initializationVector"
],
"allOf": [
{
"$ref": "#/components/schemas/EncryptionInfo"
}
],
"description": "Informacje wymagane do zaszyfrowania wyniku zapytania."
},
"filters": {
"required": [
"subjectType",
"dateRange"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceQueryFilters"
}
],
"description": "Zestaw filtrów do wyszukiwania faktur."
}
},
"additionalProperties": false
},
"InvoiceExportStatusResponse": {
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"allOf": [
{
"$ref": "#/components/schemas/StatusInfo"
}
],
"description": "Status eksportu.\n\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Eksport faktur w toku | - |\n| 200 | Eksport faktur zakończony sukcesem | - |\n| 210 | Eksport faktur wygasł i nie jest już dostępny do pobrania | - |\n| 415 | Błąd odszyfrowania dostarczonego klucza | - |\n| 500 | Nieznany błąd ({statusCode}) | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |"
},
"completedDate": {
"type": "string",
"description": "Data zakończenia przetwarzania żądania eksportu faktur.",
"format": "date-time",
"nullable": true
},
"packageExpirationDate": {
"type": "string",
"description": "Data wygaśnięcia paczki faktur przygotowanej do pobrania.\nPo upływie tej daty paczka nie będzie już dostępna do pobrania.",
"format": "date-time",
"nullable": true
},
"package": {
"required": [
"invoiceCount",
"size",
"parts",
"isTruncated"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoicePackage"
}
],
"description": "Dane paczki faktur przygotowanej do pobrania.",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceMetadata": {
"required": [
"acquisitionDate",
"buyer",
"currency",
"formCode",
"grossAmount",
"hasAttachment",
"invoiceHash",
"invoiceNumber",
"invoiceType",
"invoicingDate",
"invoicingMode",
"isSelfInvoicing",
"issueDate",
"ksefNumber",
"netAmount",
"permanentStorageDate",
"seller",
"vatAmount"
],
"type": "object",
"properties": {
"ksefNumber": {
"allOf": [
{
"$ref": "#/components/schemas/KsefNumber"
}
],
"description": "Numer KSeF faktury."
},
"invoiceNumber": {
"maxLength": 256,
"type": "string",
"description": "Numer faktury nadany przez wystawcę."
},
"issueDate": {
"type": "string",
"description": "Data wystawienia faktury.",
"format": "date"
},
"invoicingDate": {
"type": "string",
"description": "Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania).",
"format": "date-time"
},
"acquisitionDate": {
"type": "string",
"description": "Data nadania numeru KSeF.",
"format": "date-time"
},
"permanentStorageDate": {
"type": "string",
"description": "Data trwałego zapisu faktury w repozytorium systemu KSeF.",
"format": "date-time"
},
"seller": {
"required": [
"nip"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceMetadataSeller"
}
],
"description": "Dane identyfikujące sprzedawcę."
},
"buyer": {
"required": [
"identifier"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceMetadataBuyer"
}
],
"description": "Dane identyfikujące nabywcę."
},
"netAmount": {
"type": "number",
"description": "Łączna kwota netto.",
"format": "double"
},
"grossAmount": {
"type": "number",
"description": "Łączna kwota brutto.",
"format": "double"
},
"vatAmount": {
"type": "number",
"description": "Łączna kwota VAT.",
"format": "double"
},
"currency": {
"maxLength": 3,
"minLength": 3,
"type": "string",
"description": "Kod waluty."
},
"invoicingMode": {
"allOf": [
{
"$ref": "#/components/schemas/InvoicingMode"
}
],
"description": "Tryb fakturowania (online/offline)."
},
"invoiceType": {
"allOf": [
{
"$ref": "#/components/schemas/InvoiceType"
}
],
"description": "Rodzaj faktury.\n| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n"
},
"formCode": {
"required": [
"systemCode",
"schemaVersion",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/FormCode"
}
],
"description": "Struktura dokumentu faktury.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| FA (2) | 1-0E | FA |\n| FA (3) | 1-0E | FA |\n| PEF (3) | 2-1 | PEF |\n| PEF_KOR (3) | 2-1 | PEF |\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."
},
"hashOfCorrectedInvoice": {
"allOf": [
{
"$ref": "#/components/schemas/Sha256HashBase64"
}
],
"description": "Skrót SHA256 korygowanej faktury.",
"nullable": true
},
"thirdSubjects": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceMetadataThirdSubject"
},
"description": "Lista podmiotów trzecich.",
"nullable": true
},
"authorizedSubject": {
"required": [
"nip",
"role"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceMetadataAuthorizedSubject"
}
],
"description": "Podmiot upoważniony.",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceMetadataAuthorizedSubject": {
"required": [
"nip",
"role"
],
"type": "object",
"properties": {
"nip": {
"allOf": [
{
"$ref": "#/components/schemas/Nip"
}
],
"description": "Nip podmiotu upoważnionego"
},
"name": {
"maxLength": 512,
"type": "string",
"description": "Nazwa podmiotu upoważnionego.",
"nullable": true
},
"role": {
"type": "integer",
"description": "Rola podmiotu upoważnionego.\n| Wartość | Opis |\n| ---- | --- |\n| 1 | Organ egzekucyjny - w przypadku, o którym mowa w art. 106c pkt 1 ustawy |\n| 2 | Komornik sądowy - w przypadku, o którym mowa w art. 106c pkt 2 ustawy |\n| 3 | Przedstawiciel podatkowy - w przypadku gdy na fakturze występują dane przedstawiciela podatkowego, o którym mowa w art. 18a - 18d ustawy |",
"format": "int32"
}
},
"additionalProperties": false
},
"InvoiceMetadataBuyer": {
"required": [
"identifier"
],
"type": "object",
"properties": {
"identifier": {
"required": [
"type"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceMetadataBuyerIdentifier"
}
],
"description": "Identyfikator nabywcy.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator|\n| None | Brak identyfikatora nabywcy |"
},
"name": {
"maxLength": 512,
"type": "string",
"description": "Nazwa nabywcy.",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceMetadataBuyerIdentifier": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/BuyerIdentifierType"
}
],
"description": "Typ identyfikatora nabywcy.\n| Wartość | Opis |\n| --- | --- |\n| None | Brak identyfikatora nabywcy |\n| Other | Inny identyfikator |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n"
},
"value": {
"type": "string",
"description": "Wartośc identyfikatora nabywcy.",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceMetadataSeller": {
"required": [
"nip"
],
"type": "object",
"properties": {
"nip": {
"allOf": [
{
"$ref": "#/components/schemas/Nip"
}
],
"description": "Nip sprzedawcy."
},
"name": {
"maxLength": 512,
"type": "string",
"description": "Nazwa sprzedawcy.",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceMetadataThirdSubject": {
"required": [
"identifier",
"role"
],
"type": "object",
"properties": {
"identifier": {
"allOf": [
{
"$ref": "#/components/schemas/InvoiceMetadataThirdSubjectIdentifier"
}
]
},
"name": {
"maxLength": 512,
"type": "string",
"description": "Nazwa podmiotu trzeciego.",
"nullable": true
},
"role": {
"type": "integer",
"description": "Rola podmiotu trzeciego.\n| Wartość | Opis |\n| ---- | --- |\n| 0 | Inna rola |\n| 1 | Faktor - w przypadku gdy na fakturze występują dane faktora |\n| 2 | Odbiorca - w przypadku gdy na fakturze występują dane jednostek wewnętrznych, oddziałów, wyodrębnionych w ramach nabywcy, które same nie stanowią nabywcy w rozumieniu ustawy |\n| 3 | Podmiot pierwotny - w przypadku gdy na fakturze występują dane podmiotu będącego w stosunku do podatnika podmiotem przejętym lub przekształconym, który dokonywał dostawy lub świadczył usługę. Z wyłączeniem przypadków, o których mowa w art. 106j ust.2 pkt 3 ustawy, gdy dane te wykazywane są w części Podmiot1K |\n| 4 | Dodatkowy nabywca - w przypadku gdy na fakturze występują dane kolejnych (innych niż wymieniony w części Podmiot2) nabywców |\n| 5 | Wystawca faktury - w przypadku gdy na fakturze występują dane podmiotu wystawiającego fakturę w imieniu podatnika. Nie dotyczy przypadku, gdy wystawcą faktury jest nabywca |\n| 6 | Dokonujący płatności - w przypadku gdy na fakturze występują dane podmiotu regulującego zobowiązanie w miejsce nabywcy |\n| 7 | Jednostka samorządu terytorialnego - wystawca |\n| 8 | Jednostka samorządu terytorialnego - odbiorca |\n| 9 | Członek grupy VAT - wystawca |\n| 10 | Członek grupy VAT - odbiorca |\n| 11 | Pracownik |",
"format": "int32"
}
},
"additionalProperties": false
},
"InvoiceMetadataThirdSubjectIdentifier": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/ThirdSubjectIdentifierType"
}
],
"description": "Typ identyfikatora podmiotu trzeciego.\n| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr. |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora podmiotu trzeciego |\n"
},
"value": {
"type": "string",
"description": "Wartość identyfikatora podmiotu trzeciego.",
"nullable": true
}
},
"additionalProperties": false
},
"InvoicePackage": {
"required": [
"invoiceCount",
"isTruncated",
"parts",
"size"
],
"type": "object",
"properties": {
"invoiceCount": {
"maximum": 10000,
"exclusiveMaximum": false,
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Łączna liczba faktur w paczce.",
"format": "int64"
},
"size": {
"minimum": 0,
"exclusiveMinimum": false,
"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
}
},
"additionalProperties": false
},
"InvoicePackagePart": {
"required": [
"encryptedPartHash",
"encryptedPartSize",
"expirationDate",
"method",
"ordinalNumber",
"partHash",
"partName",
"partSize",
"url"
],
"type": "object",
"properties": {
"ordinalNumber": {
"minimum": 1,
"exclusiveMinimum": false,
"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.",
"format": "uri"
},
"partSize": {
"minimum": 1,
"exclusiveMinimum": false,
"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,
"exclusiveMinimum": false,
"type": "integer",
"description": "Rozmiar zaszyfrowanej części paczki w bajtach.",
"format": "int64"
},
"encryptedPartHash": {
"allOf": [
{
"$ref": "#/components/schemas/Sha256HashBase64"
}
],
"description": "Skrót SHA256 zaszyfrowanej części paczki, zakodowany w formacie Base64."
},
"expirationDate": {
"type": "string",
"description": "Data i godzina wygaśnięcia linku umożliwiającego pobranie części paczki.\nPo upływie tego momentu link przestaje być aktywny.",
"format": "date-time"
}
},
"additionalProperties": false
},
"InvoicePermissionType": {
"enum": [
"SelfInvoicing",
"TaxRepresentative",
"RRInvoicing",
"PefInvoicing"
],
"type": "string"
},
"InvoiceQueryAmount": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/AmountType"
}
]
},
"from": {
"type": "number",
"format": "double",
"nullable": true
},
"to": {
"type": "number",
"format": "double",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceQueryBuyerIdentifier": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/BuyerIdentifierType"
}
],
"description": "Typ identyfikatora nabywcy.\n| Wartość | Opis |\n| --- | --- |\n| None | Brak identyfikatora nabywcy |\n| Other | Inny identyfikator |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n"
},
"value": {
"type": "string",
"description": "Wartość identyfikatora nabywcy (exact match).",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceQueryDateRange": {
"required": [
"dateType",
"from"
],
"type": "object",
"properties": {
"dateType": {
"allOf": [
{
"$ref": "#/components/schemas/InvoiceQueryDateType"
}
],
"description": "Typ daty, według której ma być zastosowany zakres.\n| Wartość | Opis |\n| --- | --- |\n| Issue | Data wystawienia faktury. |\n| Invoicing | Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania). |\n| PermanentStorage | Data trwałego zapisu faktury w repozytorium systemu KSeF. |\n"
},
"from": {
"type": "string",
"description": "Data początkowa zakresu(UTC).",
"format": "date-time"
},
"to": {
"type": "string",
"description": "Data końcowa zakresu(UTC). Jeśli nie zostanie podana, przyjmowana jest bieżąca data i czas w UTC.",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceQueryDateType": {
"enum": [
"Issue",
"Invoicing",
"PermanentStorage"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Issue | Data wystawienia faktury. |\n| Invoicing | Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania). |\n| PermanentStorage | Data trwałego zapisu faktury w repozytorium systemu KSeF. |\n"
},
"InvoiceQueryFilters": {
"required": [
"dateRange",
"subjectType"
],
"type": "object",
"properties": {
"subjectType": {
"allOf": [
{
"$ref": "#/components/schemas/InvoiceQuerySubjectType"
}
],
"description": "Typ podmiotu, którego dotyczą kryteria filtrowania metadanych faktur.\nOkreśla kontekst, w jakim przeszukiwane są dane.\n| Wartość | Opis |\n| --- | --- |\n| Subject1 | Podmiot 1 - sprzedawca |\n| Subject2 | Podmiot 2 - nabywca |\n| Subject3 | Podmiot 3 |\n| SubjectAuthorized | Podmiot upoważniony |\n"
},
"dateRange": {
"required": [
"dateType",
"from"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceQueryDateRange"
}
],
"description": "Typ i zakres dat, według którego mają być filtrowane faktury. Dozwolony maksymalny okres wynosi 2 lata."
},
"ksefNumber": {
"allOf": [
{
"$ref": "#/components/schemas/KsefNumber"
}
],
"description": "Numer KSeF faktury (exact match).",
"nullable": true
},
"invoiceNumber": {
"maxLength": 256,
"type": "string",
"description": "Numer faktury nadany przez wystawcę (exact match).",
"nullable": true
},
"amount": {
"required": [
"type"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceQueryAmount"
}
],
"description": "Filtr kwotowy – brutto, netto lub VAT (z wartością).",
"nullable": true
},
"sellerNip": {
"allOf": [
{
"$ref": "#/components/schemas/Nip"
}
],
"description": "Nip sprzedawcy (exact match).",
"nullable": true
},
"buyerIdentifier": {
"required": [
"type"
],
"allOf": [
{
"$ref": "#/components/schemas/InvoiceQueryBuyerIdentifier"
}
],
"description": "Identyfikator nabywcy.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| VatUe | Identyfikator VAT UE podmiotu unijnego. |\n| Other | Inny identyfikator|\n| None | Brak identyfikatora nabywcy |",
"nullable": true
},
"currencyCodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CurrencyCode"
},
"description": "Kody walut.",
"nullable": true
},
"invoicingMode": {
"allOf": [
{
"$ref": "#/components/schemas/InvoicingMode"
}
],
"description": "Tryb wystawienia faktury: online lub offline.",
"nullable": true
},
"isSelfInvoicing": {
"type": "boolean",
"description": "Czy faktura została wystawiona w trybie samofakturowania.",
"nullable": true
},
"formType": {
"allOf": [
{
"$ref": "#/components/schemas/InvoiceQueryFormType"
}
],
"description": "Typ dokumentu.\n| Wartość | Opis |\n| --- | --- |\n| FA | Faktura VAT |\n| PEF | Faktura PEF |\n| RR | Faktura RR |\n",
"nullable": true
},
"invoiceTypes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceType"
},
"description": "Rodzaje faktur.\n| Wartość | Opis |\n| --- | --- |\n| Vat | (FA) Podstawowa |\n| Zal | (FA) Zaliczkowa |\n| Kor | (FA) Korygująca |\n| Roz | (FA) Rozliczeniowa |\n| Upr | (FA) Uproszczona |\n| KorZal | (FA) Korygująca fakturę zaliczkową |\n| KorRoz | (FA) Korygująca fakturę rozliczeniową |\n| VatPef | (PEF) Podstawowowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n",
"nullable": true
},
"hasAttachment": {
"type": "boolean",
"description": "Czy faktura ma załącznik.",
"nullable": true
}
},
"additionalProperties": false
},
"InvoiceQueryFormType": {
"enum": [
"FA",
"PEF",
"RR"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| FA | Faktura VAT |\n| PEF | Faktura PEF |\n| RR | Faktura RR |\n"
},
"InvoiceQuerySubjectType": {
"enum": [
"Subject1",
"Subject2",
"Subject3",
"SubjectAuthorized"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Subject1 | Podmiot 1 - sprzedawca |\n| Subject2 | Podmiot 2 - nabywca |\n| Subject3 | Podmiot 3 |\n| SubjectAuthorized | Podmiot upoważniony |\n"
},
"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) Podstawowowa |\n| VatPefSp | (PEF) Specjalizowana |\n| KorPef | (PEF) Korygująca |\n| VatRr | (RR) Podstawowa |\n| KorVatRr | (RR) Korygująca |\n"
},
"InvoicingMode": {
"enum": [
"Online",
"Offline"
],
"type": "string"
},
"KsefCertificateType": {
"enum": [
"Authentication",
"Offline"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n"
},
"KsefNumber": {
"maxLength": 36,
"minLength": 35,
"pattern": "^([1-9](\\d[1-9]|[1-9]\\d)\\d{7})-(20[2-9][0-9]|2[1-9]\\d{2}|[3-9]\\d{3})(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])-([0-9A-F]{6})-?([0-9A-F]{6})-([0-9A-F]{2})$",
"type": "string",
"description": "Numer KSeF o długości 35 znaków jest akceptowany, by zachować kompatybilność wsteczna z KSeF 1.0. W KSeF 2.0 numery są generowane wyłącznie w formacie 36-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,
"exclusiveMaximum": false,
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury w MB.",
"format": "int32"
},
"maxInvoiceWithAttachmentSizeInMB": {
"maximum": 10,
"exclusiveMaximum": false,
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury z załącznikiem w MB.",
"format": "int32"
},
"maxInvoices": {
"maximum": 100000,
"exclusiveMaximum": false,
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.",
"format": "int32"
}
},
"additionalProperties": false
},
"OnlineSessionEffectiveContextLimits": {
"required": [
"maxInvoices",
"maxInvoiceSizeInMB",
"maxInvoiceWithAttachmentSizeInMB"
],
"type": "object",
"properties": {
"maxInvoiceSizeInMB": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury w MB.",
"format": "int32"
},
"maxInvoiceWithAttachmentSizeInMB": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalny rozmiar faktury z załącznikiem w MB.",
"format": "int32"
},
"maxInvoices": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Maksymalna ilość faktur które można przesłać w pojedynczej sesji.",
"format": "int32"
}
},
"additionalProperties": false
},
"OpenBatchSessionRequest": {
"required": [
"batchFile",
"encryption",
"formCode"
],
"type": "object",
"properties": {
"formCode": {
"required": [
"systemCode",
"schemaVersion",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/FormCode"
}
],
"description": "Schemat faktur wysyłanych w ramach sesji.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| FA (2) | 1-0E | FA |\n| FA (3) | 1-0E | FA |\n"
},
"batchFile": {
"required": [
"fileSize",
"fileHash",
"fileParts"
],
"allOf": [
{
"$ref": "#/components/schemas/BatchFileInfo"
}
],
"description": "Informacje o przesyłanej paczce faktur."
},
"encryption": {
"required": [
"encryptedSymmetricKey",
"initializationVector"
],
"allOf": [
{
"$ref": "#/components/schemas/EncryptionInfo"
}
],
"description": "Symetryczny klucz szyfrujący plik paczki, zaszyfrowany kluczem publicznym Ministerstwa Finansów."
},
"offlineMode": {
"type": "boolean",
"description": "Określa, czy podatnik deklaruje tryb fakurowania \"offline\" dla dokumentów przesyłanych w sesji wsadowej.",
"default": false
}
},
"additionalProperties": false
},
"OpenBatchSessionResponse": {
"required": [
"partUploadRequests",
"referenceNumber"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny sesji."
},
"partUploadRequests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PartUploadRequest"
},
"description": "Dane wymagane do poprawnego przesłania poszczególnych części pliku paczki faktur.\n\nKażdą część pliku paczki zadeklarowaną w fileParts należy przesłać zgodnie z odpowiadającym jej obiektem w partUploadRequests.\nŁącznikiem pomiędzy deklaracją a instrukcją wysyłki jest pole ordinalNumber.\n\nDla każdej części należy:\n* zastosować metodę HTTP wskazaną w method,\n* ustawić adres z url,\n* dołączyć nagłówki z headers,\n* dołączyć treść części pliku w korpusie żądania.\n\n`Uwaga: nie należy dodawać do nagłówków token dostępu (accessToken).`\n \nKażdą część przesyła się oddzielnym żądaniem HTTP.Zwracane kody odpowiedzi:\n * 201 – poprawne przyjęcie pliku,\n * 400 – błędne dane,\n * 401 – nieprawidłowe uwierzytelnienie,\n * 403 – brak uprawnień do zapisu (np.upłynął czas na zapis)."
}
},
"additionalProperties": false
},
"OpenOnlineSessionRequest": {
"required": [
"encryption",
"formCode"
],
"type": "object",
"properties": {
"formCode": {
"required": [
"systemCode",
"schemaVersion",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/FormCode"
}
],
"description": "Schemat faktur wysyłanych w ramach sesji.\n\nObsługiwane schematy:\n| SystemCode | SchemaVersion | Value |\n| --- | --- | --- |\n| FA (2) | 1-0E | FA |\n| FA (3) | 1-0E | FA |\n| PEF (3) | 2-1 | PEF |\n| PEF_KOR (3) | 2-1 | PEF |\n"
},
"encryption": {
"required": [
"encryptedSymmetricKey",
"initializationVector"
],
"allOf": [
{
"$ref": "#/components/schemas/EncryptionInfo"
}
],
"description": "Symetryczny klucz szyfrujący pliki XML, zaszyfrowany kluczem publicznym Ministerstwa Finansów."
}
},
"additionalProperties": false
},
"OpenOnlineSessionResponse": {
"required": [
"referenceNumber",
"validUntil"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny sesji."
},
"validUntil": {
"type": "string",
"description": "Termin ważności sesji. Po jego upływie sesja zostanie automatycznie zamknięta.",
"format": "date-time"
}
},
"additionalProperties": false
},
"PartUploadRequest": {
"required": [
"headers",
"method",
"ordinalNumber",
"url"
],
"type": "object",
"properties": {
"ordinalNumber": {
"minimum": 1,
"exclusiveMinimum": false,
"type": "integer",
"description": "Numer sekwencyjny części pliku paczki.",
"format": "int32"
},
"method": {
"type": "string",
"description": "Metoda HTTP, której należy użyć przy wysyłce części pliku paczki."
},
"url": {
"type": "string",
"description": "Adres pod który należy wysłać część pliku paczki.",
"format": "uri"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
},
"description": "Nagłówki, których należy użyć przy wysyłce części pliku paczki."
}
},
"additionalProperties": false
},
"PeppolId": {
"maxLength": 9,
"minLength": 9,
"pattern": "^P[A-Z]{2}[0-9]{6}$",
"type": "string",
"description": "Identyfikator dostawcy usług Peppol."
},
"PeppolProvider": {
"required": [
"dateCreated",
"id",
"name"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PeppolId"
}
],
"description": "Identyfikator dostawcy usług Peppol."
},
"name": {
"maxLength": 256,
"type": "string",
"description": "Nazwa dostawcy usług Peppol."
},
"dateCreated": {
"type": "string",
"description": "Data rejestracji dostawcy usług Peppol w systemie.",
"format": "date-time"
}
},
"additionalProperties": false
},
"PermissionId": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "Techniczny identyfikator nadanego uprawnienia – wymagany m.in. przy operacjach odbierania."
},
"PermissionState": {
"enum": [
"Active",
"Inactive"
],
"type": "string"
},
"PermissionsOperationResponse": {
"required": [
"referenceNumber"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny operacji nadania lub odbierania uprawnień."
}
},
"additionalProperties": false
},
"PermissionsOperationStatusResponse": {
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"allOf": [
{
"$ref": "#/components/schemas/StatusInfo"
}
],
"description": "Informacje o aktualnym statusie.\n| Code | Description | Details |\n| --- | --- | --- |\n| 100 | Operacja przyjęta do realizacji | - |\n| 200 | Operacja zakończona sukcesem | - |\n| 400 | Operacja zakończona niepowodzeniem | - |\n| 410 | Podane identyfikatory są niezgodne lub pozostają w niewłaściwej relacji | - |\n| 420 | Użyte poświadczenia nie mają uprawnień do wykonania tej operacji | - |\n| 430 | Kontekst identyfikatora nie odpowiada wymaganej roli lub uprawnieniom | - |\n| 440 | Operacja niedozwolona dla wskazanych powiązań identyfikatorów | - |\n| 450 | Operacja niedozwolona dla wskazanego identyfikatora lub jego typu | - |\n| 500 | Nieznany błąd | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie później. |"
}
},
"additionalProperties": false
},
"PersonCreateRequest": {
"required": [
"description",
"isBailiff",
"nip",
"pesel"
],
"type": "object",
"properties": {
"nip": {
"$ref": "#/components/schemas/Nip"
},
"pesel": {
"$ref": "#/components/schemas/Pesel"
},
"isBailiff": {
"type": "boolean"
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string"
},
"isDeceased": {
"type": "boolean"
},
"createdDate": {
"type": "string",
"description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"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."
},
"permissionState": {
"allOf": [
{
"$ref": "#/components/schemas/PermissionState"
}
],
"description": "Stan uprawnienia."
},
"startDate": {
"type": "string",
"description": "Data rozpoczęcia obowiązywania uprawnienia.",
"format": "date-time"
},
"canDelegate": {
"type": "boolean",
"description": "Flaga określająca, czy uprawnienie ma być możliwe do dalszego przekazywania."
}
},
"additionalProperties": false
},
"PersonPermissionScope": {
"enum": [
"CredentialsManage",
"CredentialsRead",
"InvoiceWrite",
"InvoiceRead",
"Introspection",
"SubunitManage",
"EnforcementOperations"
],
"type": "string"
},
"PersonPermissionType": {
"enum": [
"CredentialsManage",
"CredentialsRead",
"InvoiceWrite",
"InvoiceRead",
"Introspection",
"SubunitManage",
"EnforcementOperations"
],
"type": "string"
},
"PersonPermissionsAuthorIdentifier": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsAuthorIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora. W przypadku typu System należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |"
},
"PersonPermissionsAuthorIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint",
"System"
],
"type": "string"
},
"PersonPermissionsAuthorizedIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"PersonPermissionsAuthorizedIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"PersonPermissionsContextIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsContextIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |"
},
"PersonPermissionsContextIdentifierType": {
"enum": [
"Nip",
"InternalId"
],
"type": "string"
},
"PersonPermissionsGrantRequest": {
"required": [
"description",
"permissions",
"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"
}
},
"additionalProperties": false
},
"PersonPermissionsQueryRequest": {
"required": [
"queryType"
],
"type": "object",
"properties": {
"authorIdentifier": {
"required": [
"type"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsAuthorIdentifier"
}
],
"description": "Identyfikator osoby lub podmiotu nadającego uprawnienie.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |\n| System | Identyfikator systemowy KSeF |",
"nullable": true
},
"authorizedIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsAuthorizedIdentifier"
}
],
"description": "Identyfikator osoby lub podmiotu uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |",
"nullable": true
},
"contextIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsContextIdentifier"
}
],
"description": "Identyfikator kontekstu uprawnienia (dla uprawnień nadanych administratorom jednostek podrzędnych).\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |",
"nullable": true
},
"targetIdentifier": {
"required": [
"type"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsTargetIdentifier"
}
],
"description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |",
"nullable": true
},
"permissionTypes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonPermissionType"
},
"description": "Lista rodzajów wyszukiwanych uprawnień.",
"nullable": true
},
"permissionState": {
"allOf": [
{
"$ref": "#/components/schemas/PermissionState"
}
],
"description": "Stan uprawnienia. \n| Type | Value |\n| --- | --- |\n| Active | Uprawnienia aktywne |\n| Inactive | Uprawnienia nieaktywne, nadane w sposób poœredni |",
"nullable": true
},
"queryType": {
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsQueryType"
}
],
"description": "Typ zapytania.\n| Type | Value |\n| --- | --- |\n| PermissionsInCurrentContext | Lista uprawnień obowiązujących w bieżącym kontekście |\n| PermissionsGrantedInCurrentContext | Lista uprawmoeń nadanych w bieżącym kontekście |"
}
},
"additionalProperties": false
},
"PersonPermissionsQueryType": {
"enum": [
"PermissionsInCurrentContext",
"PermissionsGrantedInCurrentContext"
],
"type": "string"
},
"PersonPermissionsSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"PersonPermissionsSubjectIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"PersonPermissionsTargetIdentifier": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonPermissionsTargetIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu docelowego dla uprawnień nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że uprawnienie nadane w sposób pośredni jest typu generalnego |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |"
},
"PersonPermissionsTargetIdentifierType": {
"enum": [
"Nip",
"AllPartners",
"InternalId"
],
"type": "string"
},
"PersonRemoveRequest": {
"required": [
"nip"
],
"type": "object",
"properties": {
"nip": {
"$ref": "#/components/schemas/Nip"
}
},
"additionalProperties": false
},
"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 |",
"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."
},
"permissionState": {
"allOf": [
{
"$ref": "#/components/schemas/PermissionState"
}
],
"description": "Stan uprawnienia."
},
"startDate": {
"type": "string",
"description": "Data rozpoczęcia obowiązywania uprawnienia.",
"format": "date-time"
},
"canDelegate": {
"type": "boolean",
"description": "Flaga określająca, czy uprawnienie ma być możliwe do dalszego przekazywania."
}
},
"additionalProperties": false
},
"PersonalPermissionScope": {
"enum": [
"CredentialsManage",
"CredentialsRead",
"InvoiceWrite",
"InvoiceRead",
"Introspection",
"SubunitManage",
"EnforcementOperations",
"VatUeManage"
],
"type": "string"
},
"PersonalPermissionType": {
"enum": [
"CredentialsManage",
"CredentialsRead",
"InvoiceWrite",
"InvoiceRead",
"Introspection",
"SubunitManage",
"EnforcementOperations",
"VatUeManage"
],
"type": "string"
},
"PersonalPermissionsAuthorizedIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonalPermissionsAuthorizedIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu uprawnionego, jeżeli jest inny niż identyfikator uwierzytelnionego klienta API.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"PersonalPermissionsAuthorizedIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"PersonalPermissionsContextIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonalPermissionsContextIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator kontekstu podmiotu, który nadał uprawnienia do obsługi faktur.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"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 |",
"nullable": true
},
"targetIdentifier": {
"required": [
"type"
],
"allOf": [
{
"$ref": "#/components/schemas/PersonalPermissionsTargetIdentifier"
}
],
"description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |",
"nullable": true
},
"permissionTypes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonalPermissionType"
},
"description": "Lista rodzajów wyszukiwanych uprawnień.",
"nullable": true
},
"permissionState": {
"allOf": [
{
"$ref": "#/components/schemas/PermissionState"
}
],
"description": "Stan uprawnienia. \n| Type | Value |\n| --- | --- |\n| Active | Uprawnienia aktywne |\n| Inactive | Uprawnienia nieaktywne |",
"nullable": true
}
},
"additionalProperties": false
},
"PersonalPermissionsTargetIdentifier": {
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/PersonalPermissionsTargetIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora. W przypadku typu AllPartners należy pozostawić puste. W pozostałych przypadkach pole jest wymagane.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu docelowego dla uprawnień selektywnych nadanych pośrednio.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| AllPartners | Identyfikator oznaczający, że wyszukiwanie dotyczy uprawnień generalnych nadanych w sposób pośredni |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |"
},
"PersonalPermissionsTargetIdentifierType": {
"enum": [
"Nip",
"AllPartners",
"InternalId"
],
"type": "string"
},
"Pesel": {
"maxLength": 11,
"minLength": 11,
"pattern": "^\\d{2}(?:0[1-9]|1[0-2]|2[1-9]|3[0-2]|4[1-9]|5[0-2]|6[1-9]|7[0-2]|8[1-9]|9[0-2])\\d{7}$",
"type": "string",
"description": "11 cyfrowy numer PESEL."
},
"PublicKeyCertificate": {
"required": [
"certificate",
"usage",
"validFrom",
"validTo"
],
"type": "object",
"properties": {
"certificate": {
"type": "string",
"description": "Certyfikat klucza publicznego w formacie DER zakodowany w Base64."
},
"validFrom": {
"type": "string",
"description": "Data początku obowiązywania certyfikatu.",
"format": "date-time"
},
"validTo": {
"type": "string",
"description": "Data końca obowiązywania certyfikatu.",
"format": "date-time"
},
"usage": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicKeyCertificateUsage"
},
"description": "Operacje do których może być używany certyfikat.\n| Wartość | Opis |\n| --- | --- |\n| KsefTokenEncryption | Szyfrowanie tokenów KSeF przesyłanych w trakcie procesu uwierzytelniania. |\n| SymmetricKeyEncryption | Szyfrowanie klucza symetrycznego wykorzystywanego do szyfrowania przesyłanych faktur. |\n"
}
},
"additionalProperties": false
},
"PublicKeyCertificateUsage": {
"enum": [
"KsefTokenEncryption",
"SymmetricKeyEncryption"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| KsefTokenEncryption | Szyfrowanie tokenów KSeF przesyłanych w trakcie procesu uwierzytelniania. |\n| SymmetricKeyEncryption | Szyfrowanie klucza symetrycznego wykorzystywanego do szyfrowania przesyłanych faktur. |\n"
},
"QueryCertificatesRequest": {
"type": "object",
"properties": {
"certificateSerialNumber": {
"type": "string",
"description": "Numer seryjny certyfikatu. Wyszukiwanie odbywa się na zasadzie dokładnego dopasowania (exact match).",
"nullable": true
},
"name": {
"type": "string",
"description": "Nazwa własna certyfikatu. Wyszukiwanie jest częściowe, czyli zwracane są certyfikaty, których nazwa zawiera podany ciąg znaków (contains).",
"nullable": true
},
"type": {
"allOf": [
{
"$ref": "#/components/schemas/KsefCertificateType"
}
],
"description": "Typ certyfikatu KSeF.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n",
"nullable": true
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/CertificateListItemStatus"
}
],
"description": "Status certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Active | Certyfikat jest aktywny i może zostać użyty do uwierzytelnienia lub realizacji operacji w trybie offline (w zależności od typu certyfikatu). |\n| Blocked | Certyfikat został zablokowany i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. Status przejściowy do czasu zakończenia procesu unieważniania. |\n| Revoked | Certyfikat został unieważniony i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n| Expired | Certyfikat wygasł i nie może zostać użyty do uwierzytelnienia i realizacji operacji w trybie offline. |\n",
"nullable": true
},
"expiresAfter": {
"type": "string",
"description": "Filtruje certyfikaty, które wygasają po podanej dacie.",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"QueryCertificatesResponse": {
"required": [
"certificates",
"hasMore"
],
"type": "object",
"properties": {
"certificates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CertificateListItem"
},
"description": "Lista certyfikatów spełniających kryteria wyszukiwania."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QueryEntityAuthorizationPermissionsResponse": {
"required": [
"authorizationGrants",
"hasMore"
],
"type": "object",
"properties": {
"authorizationGrants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityAuthorizationGrant"
},
"description": "Lista odczytanych uprawnień."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QueryEntityRolesResponse": {
"required": [
"hasMore",
"roles"
],
"type": "object",
"properties": {
"roles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRole"
},
"description": "Lista odczytanych ról podmiotu."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QueryEuEntityPermissionsResponse": {
"required": [
"hasMore",
"permissions"
],
"type": "object",
"properties": {
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EuEntityPermission"
},
"description": "Lista odczytanych uprawnień."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QueryInvoicesMetadataResponse": {
"required": [
"hasMore",
"invoices",
"isTruncated"
],
"type": "object",
"properties": {
"hasMore": {
"type": "boolean",
"description": "Określa, czy istnieją kolejne wyniki zapytania."
},
"isTruncated": {
"type": "boolean",
"description": "Określa, czy osiągnięto maksymalny dopuszczalny zakres wyników zapytania (10 000)."
},
"invoices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceMetadata"
},
"description": "Lista faktur spełniających kryteria."
}
},
"additionalProperties": false
},
"QueryPeppolProvidersResponse": {
"required": [
"hasMore",
"peppolProviders"
],
"type": "object",
"properties": {
"peppolProviders": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PeppolProvider"
},
"description": "Lista dostawców usług Peppol."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QueryPersonPermissionsResponse": {
"required": [
"hasMore",
"permissions"
],
"type": "object",
"properties": {
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonPermission"
},
"description": "Lista odczytanych uprawnień."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QueryPersonalPermissionsResponse": {
"required": [
"hasMore",
"permissions"
],
"type": "object",
"properties": {
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonalPermission"
},
"description": "Lista odczytanych uprawnień."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QuerySubordinateEntityRolesResponse": {
"required": [
"hasMore",
"roles"
],
"type": "object",
"properties": {
"roles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SubordinateEntityRole"
},
"description": "Lista odczytanych podmiotów podrzędnych i ich ról."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QuerySubunitPermissionsResponse": {
"required": [
"hasMore",
"permissions"
],
"type": "object",
"properties": {
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SubunitPermission"
},
"description": "Lista odczytanych uprawnień."
},
"hasMore": {
"type": "boolean",
"description": "Flaga informująca o dostępności kolejnej strony wyników."
}
},
"additionalProperties": false
},
"QueryTokensResponse": {
"required": [
"tokens"
],
"type": "object",
"properties": {
"continuationToken": {
"type": "string",
"description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.",
"nullable": true
},
"tokens": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QueryTokensResponseItem"
},
"description": "Lista tokenów uwierzytelniających."
}
},
"additionalProperties": false
},
"QueryTokensResponseItem": {
"required": [
"authorIdentifier",
"contextIdentifier",
"dateCreated",
"description",
"referenceNumber",
"requestedPermissions",
"status"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny tokena KSeF."
},
"authorIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenAuthorIdentifierTypeIdentifier"
}
],
"description": "Identyfikator osoby która wygenerowała token."
},
"contextIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenContextIdentifierTypeIdentifier"
}
],
"description": "Identyfikator kontekstu, w którym został wygenerowany token i do którego daje dostęp."
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Opis tokena."
},
"requestedPermissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenPermissionType"
},
"description": "Uprawnienia przypisane tokenowi."
},
"dateCreated": {
"type": "string",
"description": "Data i czas utworzenia tokena.",
"format": "date-time"
},
"lastUseDate": {
"type": "string",
"description": "Data ostatniego użycia tokena.",
"format": "date-time",
"nullable": true
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/AuthenticationTokenStatus"
}
],
"description": "Status tokena.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n"
},
"statusDetails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dodatkowe informacje na temat statusu, zwracane w przypadku błędów.",
"nullable": true
}
},
"additionalProperties": false
},
"QueryType": {
"enum": [
"Granted",
"Received"
],
"type": "string"
},
"ReferenceNumber": {
"maxLength": 36,
"minLength": 36,
"type": "string",
"description": "Numer referencyjny."
},
"RetrieveCertificatesListItem": {
"required": [
"certificate",
"certificateName",
"certificateSerialNumber",
"certificateType"
],
"type": "object",
"properties": {
"certificate": {
"type": "string",
"description": "Certyfikat w formacie DER zakodowany w Base64.",
"format": "byte"
},
"certificateName": {
"type": "string",
"description": "Nazwa własna certyfikatu."
},
"certificateSerialNumber": {
"type": "string",
"description": "Numer seryjny certyfikatu."
},
"certificateType": {
"allOf": [
{
"$ref": "#/components/schemas/KsefCertificateType"
}
],
"description": "Typ certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Authentication | Certyfikat używany do uwierzytelnienia w systemie. |\n| Offline | Certyfikat używany wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline |\n"
}
},
"additionalProperties": false
},
"RetrieveCertificatesRequest": {
"required": [
"certificateSerialNumbers"
],
"type": "object",
"properties": {
"certificateSerialNumbers": {
"maxItems": 10,
"minItems": 1,
"type": "array",
"items": {
"type": "string"
},
"description": "Numery seryjne certyfikatów do pobrania."
}
},
"additionalProperties": false
},
"RetrieveCertificatesResponse": {
"required": [
"certificates"
],
"type": "object",
"properties": {
"certificates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RetrieveCertificatesListItem"
},
"description": "Pobrane certyfikaty."
}
},
"additionalProperties": false
},
"RevokeCertificateRequest": {
"type": "object",
"properties": {
"revocationReason": {
"allOf": [
{
"$ref": "#/components/schemas/CertificateRevocationReason"
}
],
"description": "Powód unieważnienia certyfikatu.\n| Wartość | Opis |\n| --- | --- |\n| Unspecified | Nieokreślony. |\n| Superseded | Certyfikat został zastąpiony przez inny. |\n| KeyCompromise | Klucz prywatny powiązany z certyfikatem został skompromitowany. |\n",
"nullable": true
}
},
"additionalProperties": false
},
"SendInvoiceRequest": {
"required": [
"encryptedInvoiceContent",
"encryptedInvoiceHash",
"encryptedInvoiceSize",
"invoiceHash",
"invoiceSize"
],
"type": "object",
"properties": {
"invoiceHash": {
"allOf": [
{
"$ref": "#/components/schemas/Sha256HashBase64"
}
],
"description": "Skrót SHA256 oryginalnej faktury, zakodowany w formacie Base64."
},
"invoiceSize": {
"minimum": 1,
"exclusiveMinimum": false,
"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,
"exclusiveMinimum": false,
"type": "integer",
"description": "Rozmiar zaszyfrowanej faktury w bajtach.",
"format": "int64"
},
"encryptedInvoiceContent": {
"type": "string",
"description": "Faktura zaszyfrowana algorytmem AES-256-CBC z dopełnianiem PKCS#7 (kluczem przekazanym przy otwarciu sesji), zakodowana w formacie Base64.",
"format": "byte"
},
"offlineMode": {
"type": "boolean",
"description": "Określa, czy podatnik deklaruje tryb fakturowania \"offline\" dla przesyłanego dokumentu.",
"default": false
},
"hashOfCorrectedInvoice": {
"allOf": [
{
"$ref": "#/components/schemas/Sha256HashBase64"
}
],
"description": "Skrót SHA256 korygowanej faktury, zakodowany w formacie Base64. Wymagany przy wysyłaniu korekty technicznej faktury.",
"nullable": true
}
},
"additionalProperties": false
},
"SendInvoiceResponse": {
"required": [
"referenceNumber"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny faktury."
}
},
"additionalProperties": false
},
"SessionInvoiceStatusResponse": {
"required": [
"invoiceHash",
"invoicingDate",
"ordinalNumber",
"referenceNumber",
"status"
],
"type": "object",
"properties": {
"ordinalNumber": {
"minimum": 1,
"exclusiveMinimum": false,
"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`.",
"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/StatusInfo"
}
],
"description": "Status faktury.\n\n| Code | Description | Details |\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 | - |\n| 450 | Błąd weryfikacji semantyki dokumentu faktury | - |\n| 500 | Nieznany błąd ({statusCode}) | - |\n| 550 | Operacja została anulowana przez system | Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie |"
}
},
"additionalProperties": false
},
"SessionInvoicesResponse": {
"required": [
"invoices"
],
"type": "object",
"properties": {
"continuationToken": {
"type": "string",
"description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.",
"nullable": true
},
"invoices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SessionInvoiceStatusResponse"
},
"description": "Lista pobranych faktur."
}
},
"additionalProperties": false
},
"SessionStatusResponse": {
"required": [
"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 | - |"
},
"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,
"exclusiveMinimum": false,
"type": "integer",
"description": "Liczba przyjętych faktur w ramach sesji.",
"format": "int32",
"nullable": true
},
"successfulInvoiceCount": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Liczba faktur przeprocesowanych w ramach sesji z sukcesem .",
"format": "int32",
"nullable": true
},
"failedInvoiceCount": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Liczba faktur przeprocesowanych w ramach sesji z błędem.",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false
},
"SessionType": {
"enum": [
"Online",
"Batch"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Online | Wysyłka interaktywna (pojedyncze faktury). |\n| Batch | Wysyłka wsadowa (paczka faktur). |\n"
},
"SessionsQueryResponse": {
"required": [
"sessions"
],
"type": "object",
"properties": {
"continuationToken": {
"type": "string",
"description": "Token służący do pobrania kolejnej strony wyników. Jeśli jest pusty, to nie ma kolejnych stron.",
"nullable": true
},
"sessions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SessionsQueryResponseItem"
},
"description": "Lista sesji."
}
},
"additionalProperties": false
},
"SessionsQueryResponseItem": {
"required": [
"dateCreated",
"dateUpdated",
"failedInvoiceCount",
"referenceNumber",
"status",
"successfulInvoiceCount",
"totalInvoiceCount"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny sesji."
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/StatusInfo"
}
],
"description": "Status sesji."
},
"dateCreated": {
"type": "string",
"description": "Data utworzenia sesji.",
"format": "date-time"
},
"dateUpdated": {
"type": "string",
"description": "Data ostatniej aktywności w ramach sesji.",
"format": "date-time"
},
"validUntil": {
"type": "string",
"description": "Termin ważności sesji. Po jego upływie sesja interaktywna zostanie automatycznie zamknięta.",
"format": "date-time",
"nullable": true
},
"totalInvoiceCount": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Łączna liczba faktur (uwzględnia również te w trakcie przetwarzania).",
"format": "int32"
},
"successfulInvoiceCount": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Liczba poprawnie przetworzonych faktur.",
"format": "int32"
},
"failedInvoiceCount": {
"minimum": 0,
"exclusiveMinimum": false,
"type": "integer",
"description": "Liczba błędnie przetworzonych faktur.",
"format": "int32"
}
},
"additionalProperties": false
},
"SetRateLimitsRequest": {
"required": [
"rateLimits"
],
"type": "object",
"properties": {
"rateLimits": {
"required": [
"onlineSession",
"batchSession",
"invoiceSend",
"invoiceStatus",
"sessionList",
"sessionInvoiceList",
"sessionMisc",
"invoiceMetadata",
"invoiceExport",
"invoiceDownload",
"other"
],
"allOf": [
{
"$ref": "#/components/schemas/ApiRateLimitsOverride"
}
],
"description": "Limity dla ilości żądań do API."
}
},
"additionalProperties": false
},
"SetSessionLimitsRequest": {
"required": [
"batchSession",
"onlineSession"
],
"type": "object",
"properties": {
"onlineSession": {
"required": [
"maxInvoiceSizeInMB",
"maxInvoiceWithAttachmentSizeInMB",
"maxInvoices"
],
"allOf": [
{
"$ref": "#/components/schemas/OnlineSessionContextLimitsOverride"
}
],
"description": "Limity dla sesji interaktywnych."
},
"batchSession": {
"required": [
"maxInvoiceSizeInMB",
"maxInvoiceWithAttachmentSizeInMB",
"maxInvoices"
],
"allOf": [
{
"$ref": "#/components/schemas/BatchSessionContextLimitsOverride"
}
],
"description": "Limity dla sesji wsadowych."
}
},
"additionalProperties": false
},
"SetSubjectLimitsRequest": {
"type": "object",
"properties": {
"subjectIdentifierType": {
"allOf": [
{
"$ref": "#/components/schemas/SubjectIdentifierType"
}
]
},
"enrollment": {
"allOf": [
{
"$ref": "#/components/schemas/EnrollmentSubjectLimitsOverride"
}
],
"nullable": true
},
"certificate": {
"allOf": [
{
"$ref": "#/components/schemas/CertificateSubjectLimitsOverride"
}
],
"nullable": true
}
},
"additionalProperties": false
},
"Sha256HashBase64": {
"maxLength": 44,
"minLength": 44,
"type": "string",
"description": "SHA-256 w Base64.",
"format": "byte"
},
"SortOrder": {
"enum": [
"Asc",
"Desc"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Asc | Sortowanie rosnąco. |\n| Desc | Sortowanie malejąco. |\n"
},
"StatusInfo": {
"required": [
"code",
"description"
],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "Kod statusu",
"format": "int32"
},
"description": {
"minLength": 1,
"type": "string",
"description": "Opis statusu"
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dodatkowe szczegóły statusu",
"nullable": true
}
},
"additionalProperties": false
},
"SubjectCreateRequest": {
"required": [
"description",
"subjectNip",
"subjectType"
],
"type": "object",
"properties": {
"subjectNip": {
"$ref": "#/components/schemas/Nip"
},
"subjectType": {
"allOf": [
{
"$ref": "#/components/schemas/SubjectType"
}
]
},
"subunits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Subunit"
},
"nullable": true
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string"
},
"createdDate": {
"type": "string",
"description": "W przypadku wielokrotnego tworzenia danych testowych z tym samym identyfikatorem nie można podawać daty wcześniejszej ani takiej samej jak poprzednia.",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"SubjectIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint",
"Token"
],
"type": "string"
},
"SubjectRemoveRequest": {
"required": [
"subjectNip"
],
"type": "object",
"properties": {
"subjectNip": {
"$ref": "#/components/schemas/Nip"
}
},
"additionalProperties": false
},
"SubjectType": {
"enum": [
"EnforcementAuthority",
"VatGroup",
"JST"
],
"type": "string"
},
"SubordinateEntityRole": {
"required": [
"description",
"role",
"startDate",
"subordinateEntityIdentifier"
],
"type": "object",
"properties": {
"subordinateEntityIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/SubordinateRoleSubordinateEntityIdentifier"
}
],
"description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"role": {
"allOf": [
{
"$ref": "#/components/schemas/SubordinateEntityRoleType"
}
],
"description": "Typ roli - powiązania z podmiotem nadrzędnym."
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Opis powiązania."
},
"startDate": {
"type": "string",
"description": "Data rozpoczęcia obowiązywania powiązania.",
"format": "date-time"
}
},
"additionalProperties": false
},
"SubordinateEntityRoleType": {
"enum": [
"LocalGovernmentSubUnit",
"VatGroupSubUnit"
],
"type": "string"
},
"SubordinateEntityRolesQueryRequest": {
"type": "object",
"properties": {
"subordinateEntityIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/EntityPermissionsSubordinateEntityIdentifier"
}
],
"description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |",
"nullable": true
}
},
"additionalProperties": false
},
"SubordinateRoleSubordinateEntityIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/SubordinateRoleSubordinateEntityIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |"
},
"SubordinateRoleSubordinateEntityIdentifierType": {
"enum": [
"Nip"
],
"type": "string"
},
"Subunit": {
"required": [
"description",
"subjectNip"
],
"type": "object",
"properties": {
"subjectNip": {
"$ref": "#/components/schemas/Nip"
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string"
}
},
"additionalProperties": false
},
"SubunitPermission": {
"required": [
"authorIdentifier",
"authorizedIdentifier",
"description",
"id",
"permissionScope",
"startDate",
"subunitIdentifier"
],
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/PermissionId"
}
],
"description": "Identyfikator uprawnienia."
},
"authorizedIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsAuthorizedIdentifier"
}
],
"description": "Identyfikator uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"subunitIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifier"
}
],
"description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |"
},
"authorIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsAuthorIdentifier"
}
],
"description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"permissionScope": {
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionScope"
}
],
"description": "Rodzaj uprawnienia."
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Opis uprawnienia."
},
"subunitName": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Nazwa jednostki podrzędnej.",
"nullable": true
},
"startDate": {
"type": "string",
"description": "Data rozpoczęcia obowiązywania uprawnienia.",
"format": "date-time"
}
},
"additionalProperties": false
},
"SubunitPermissionScope": {
"enum": [
"CredentialsManage"
],
"type": "string"
},
"SubunitPermissionsAuthorIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsAuthorIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator uprawniającego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"SubunitPermissionsAuthorIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"SubunitPermissionsAuthorizedIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator uprawnionego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"SubunitPermissionsContextIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsContextIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |"
},
"SubunitPermissionsContextIdentifierType": {
"enum": [
"InternalId",
"Nip"
],
"type": "string"
},
"SubunitPermissionsGrantRequest": {
"required": [
"contextIdentifier",
"description",
"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
}
},
"additionalProperties": false
},
"SubunitPermissionsQueryRequest": {
"type": "object",
"properties": {
"subunitIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifier"
}
],
"description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |",
"nullable": true
}
},
"additionalProperties": false
},
"SubunitPermissionsSubjectIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsSubjectIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator podmiotu lub osoby fizycznej.\n| Type | Value |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| Pesel | 11 cyfrowy numer PESEL |\n| Fingerprint | Odcisk palca certyfikatu |"
},
"SubunitPermissionsSubjectIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"SubunitPermissionsSubunitIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/SubunitPermissionsSubunitIdentifierType"
}
],
"description": "Typ identyfikatora."
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false,
"description": "Identyfikator jednostki lub podmiotu podrzędnego.\n| Type | Value |\n| --- | --- |\n| InternalId | Dwuczłonowy identyfikator składający się z numeru NIP i 5 cyfr: `{nip}-{5_cyfr}` |\n| Nip | 10 cyfrowy numer NIP |"
},
"SubunitPermissionsSubunitIdentifierType": {
"enum": [
"InternalId",
"Nip"
],
"type": "string"
},
"TestDataAuthorizedIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TestDataAuthorizedIdentifierType"
}
]
},
"value": {
"type": "string"
}
},
"additionalProperties": false
},
"TestDataAuthorizedIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string"
},
"TestDataContextIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TestDataContextIdentifierType"
}
]
},
"value": {
"type": "string"
}
},
"additionalProperties": false
},
"TestDataContextIdentifierType": {
"enum": [
"Nip"
],
"type": "string"
},
"TestDataPermission": {
"required": [
"description",
"permissionType"
],
"type": "object",
"properties": {
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string"
},
"permissionType": {
"allOf": [
{
"$ref": "#/components/schemas/TestDataPermissionType"
}
]
}
},
"additionalProperties": false
},
"TestDataPermissionType": {
"enum": [
"InvoiceRead",
"InvoiceWrite",
"Introspection",
"CredentialsRead",
"CredentialsManage",
"EnforcementOperations",
"SubunitManage"
],
"type": "string"
},
"TestDataPermissionsGrantRequest": {
"required": [
"authorizedIdentifier",
"contextIdentifier",
"permissions"
],
"type": "object",
"properties": {
"contextIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TestDataContextIdentifier"
}
]
},
"authorizedIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TestDataAuthorizedIdentifier"
}
]
},
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TestDataPermission"
}
}
},
"additionalProperties": false
},
"TestDataPermissionsRevokeRequest": {
"required": [
"authorizedIdentifier",
"contextIdentifier"
],
"type": "object",
"properties": {
"contextIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TestDataContextIdentifier"
}
]
},
"authorizedIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TestDataAuthorizedIdentifier"
}
]
}
},
"additionalProperties": false
},
"ThirdSubjectIdentifierType": {
"enum": [
"Nip",
"InternalId",
"VatUe",
"Other",
"None"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Nip | 10 cyfrowy numer NIP |\n| InternalId | Identyfikator wewnętrzny, składający się z numeru NIP i 5 cyfr. |\n| VatUe | Identyfikator VAT UE podmiotu unijnego |\n| Other | Inny identyfikator |\n| None | Brak identyfikatora podmiotu trzeciego |\n"
},
"TokenAuthorIdentifierType": {
"enum": [
"Nip",
"Pesel",
"Fingerprint"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n"
},
"TokenAuthorIdentifierTypeIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TokenAuthorIdentifierType"
}
],
"description": "Typ identyfikatora.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| Pesel | PESEL. |\n| Fingerprint | Odcisk palca certyfikatu. |\n"
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false
},
"TokenContextIdentifierType": {
"enum": [
"Nip",
"InternalId",
"NipVatUe",
"PeppolId"
],
"type": "string",
"description": "| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| InternalId | Identyfikator wewnętrzny. |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}`. |\n| PeppolId | Identyfikator dostawcy usług Peppol. |\n"
},
"TokenContextIdentifierTypeIdentifier": {
"required": [
"type",
"value"
],
"type": "object",
"properties": {
"type": {
"allOf": [
{
"$ref": "#/components/schemas/TokenContextIdentifierType"
}
],
"description": "Typ identyfikatora.\n| Wartość | Opis |\n| --- | --- |\n| Nip | NIP. |\n| InternalId | Identyfikator wewnętrzny. |\n| NipVatUe | Dwuczłonowy identyfikator składający się z numeru NIP i numeru VAT-UE: `{nip}-{vat_ue}`. |\n| PeppolId | Identyfikator dostawcy usług Peppol. |\n"
},
"value": {
"type": "string",
"description": "Wartość identyfikatora."
}
},
"additionalProperties": false
},
"TokenInfo": {
"required": [
"token",
"validUntil"
],
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token w formacie JWT."
},
"validUntil": {
"type": "string",
"description": "Data ważności tokena.",
"format": "date-time"
}
},
"additionalProperties": false
},
"TokenPermissionType": {
"enum": [
"InvoiceRead",
"InvoiceWrite",
"CredentialsRead",
"CredentialsManage",
"SubunitManage",
"EnforcementOperations"
],
"type": "string"
},
"TokenStatusResponse": {
"required": [
"authorIdentifier",
"contextIdentifier",
"dateCreated",
"description",
"referenceNumber",
"requestedPermissions",
"status"
],
"type": "object",
"properties": {
"referenceNumber": {
"allOf": [
{
"$ref": "#/components/schemas/ReferenceNumber"
}
],
"description": "Numer referencyjny tokena KSeF."
},
"authorIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenAuthorIdentifierTypeIdentifier"
}
],
"description": "Identyfikator osoby która wygenerowała token."
},
"contextIdentifier": {
"required": [
"type",
"value"
],
"allOf": [
{
"$ref": "#/components/schemas/TokenContextIdentifierTypeIdentifier"
}
],
"description": "Identyfikator kontekstu, w którym został wygenerowany token i do którego daje dostęp."
},
"description": {
"maxLength": 256,
"minLength": 5,
"type": "string",
"description": "Opis tokena."
},
"requestedPermissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenPermissionType"
},
"description": "Uprawnienia przypisane tokenowi."
},
"dateCreated": {
"type": "string",
"description": "Data i czas utworzenia tokena.",
"format": "date-time"
},
"lastUseDate": {
"type": "string",
"description": "Data ostatniego użycia tokena.",
"format": "date-time",
"nullable": true
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/AuthenticationTokenStatus"
}
],
"description": "Status tokena.\n| Wartość | Opis |\n| --- | --- |\n| Pending | Token został utworzony ale jest jeszcze w trakcie aktywacji i nadawania uprawnień. Nie może być jeszcze wykorzystywany do uwierzytelniania. |\n| Active | Token jest aktywny i może być wykorzystywany do uwierzytelniania. |\n| Revoking | Token jest w trakcie unieważniania. Nie może już być wykorzystywany do uwierzytelniania. |\n| Revoked | Token został unieważniony i nie może być wykorzystywany do uwierzytelniania. |\n| Failed | Nie udało się aktywować tokena. Należy wygenerować nowy token, obecny nie może być wykorzystywany do uwierzytelniania. |\n"
},
"statusDetails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dodatkowe informacje na temat statusu, zwracane w przypadku błędów.",
"nullable": true
}
},
"additionalProperties": false
},
"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`.",
"format": "uri"
},
"downloadUrlExpirationDate": {
"type": "string",
"description": "Data i godzina wygaśnięcia adresu. Po tej dacie link `DownloadUrl` nie będzie już aktywny.",
"format": "date-time"
}
},
"additionalProperties": false
},
"UpoResponse": {
"required": [
"pages"
],
"type": "object",
"properties": {
"pages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UpoPageResponse"
},
"description": "Lista stron UPO."
}
},
"additionalProperties": false
}
},
"securitySchemes": {
"Bearer": {
"type": "http",
"description": "Token dostępu uzyskany w wyniku operacji uwierzytelnienia.",
"scheme": "Bearer",
"bearerFormat": "JWT"
},
"SessionToken": {
"type": "apiKey",
"name": "SessionToken",
"in": "header"
}
}
},
"tags": [
{
"name": "Uzyskiwanie dostępu",
"description": "Uwierzytelnianie w systemie KSeF API 2.0 jest obowiązkowym etapem, który należy wykonać przed dostępem do chronionych zasobów systemu. Proces ten oparty jest na **uzyskaniu tokenu dostępu** (```accessToken```) w formacie ```JWT```, który następnie wykorzystywany jest do autoryzacji operacji API.\n\n> Więcej informacji:\n> - [Uwierzytelnianie](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md)"
},
{
"name": "Aktywne sesje"
},
{
"name": "Limity i ograniczenia"
},
{
"name": "Certyfikaty klucza publicznego"
},
{
"name": "Wysyłka interaktywna"
},
{
"name": "Wysyłka wsadowa",
"description": ""
},
{
"name": "Status wysyłki i UPO"
},
{
"name": "Pobieranie faktur"
},
{
"name": "Nadawanie uprawnień"
},
{
"name": "Odbieranie uprawnień"
},
{
"name": "Wyszukiwanie nadanych uprawnień"
},
{
"name": "Operacje"
},
{
"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": "Tokeny KSeF",
"description": "Token KSeF to unikalny, generowany identyfikator uwierzytelniający, który — na równi z [kwalifikowanym podpisem elektronicznym](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#21-uwierzytelnianie-kwalifikowanym-podpisem-elektronicznym) — umożliwia [uwierzytelnienie](https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md#22-uwierzytelnianie-tokenem-ksef) się do API KSeF.\n\nToken KSeF jest wydawany z niezmiennym zestawem uprawnień określonych przy jego tworzeniu; każda modyfikacja tych uprawnień wymaga wygenerowania nowego tokena.\n> **Uwaga!**
\n> Token KSeF pełni rolę **poufnego sekretu** uwierzytelniającego — należy przechowywać go wyłącznie w zaufanym i bezpiecznym magazynie.\n\nWięcej informacji:\n- [Token KSeF](https://github.com/CIRFMF/ksef-docs/blob/main/tokeny-ksef.md)\n"
},
{
"name": "Usługi Peppol",
"description": ""
},
{
"name": "Dane testowe",
"description": "API służy do tworzenia i zarządzania danymi testowymi, takimi jak podmioty, osoby fizyczne oraz uprawnienia. Możliwe do utworzenia podmioty to: organ egzekucyjny, grupa VAT oraz jednostki samorządu terytorialnego. W przypadku osób fizycznych można określić, czy dana osoba jest komornikiem. Funkcjonalność nadawania i odbierania uprawnień ma na celu odwzorowanie działania formularza ZAW-FA w środowisku testowym.\n\nWięcej informacji:\n- [Scenariusze testowe](https://github.com/CIRFMF/ksef-docs/blob/main/dane-testowe-scenariusze.md)"
}
],
"x-tagGroups": [
{
"name": "Uwierzytelnianie",
"tags": [
"Uzyskiwanie dostępu",
"Aktywne sesje"
]
},
{
"name": "Limity i ograniczenia",
"tags": [
"Limity i ograniczenia"
]
},
{
"name": "Szyfrowanie danych",
"tags": [
"Certyfikaty klucza publicznego"
]
},
{
"name": "Faktury",
"tags": [
"Wysyłka interaktywna",
"Wysyłka wsadowa",
"Status wysyłki i UPO",
"Pobieranie faktur"
]
},
{
"name": "Uprawnienia",
"tags": [
"Nadawanie uprawnień",
"Odbieranie uprawnień",
"Wyszukiwanie nadanych uprawnień",
"Operacje"
]
},
{
"name": "Certyfikaty",
"tags": [
"Certyfikaty"
]
},
{
"name": "Tokeny KSeF",
"tags": [
"Tokeny KSeF"
]
},
{
"name": "Usługi Peppol",
"tags": [
"Usługi Peppol"
]
},
{
"name": "Dane testowe",
"tags": [
"Dane testowe"
]
}
]
}