Imixs/office-alexander-logistics
3
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
office-alexander-logistics/doc/KSeF/openapi.json

11183 lines
418 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"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)<br>\n**Klucze publiczne** Ministerstwa Finansów (dla danego środowiska): [Pobierz klucze](#tag/Certyfikaty-klucza-publicznego)<br>\n**Historia zmian:** [Changelog](https://github.com/CIRFMF/ksef-docs/blob/main/api-changelog.md)<br>\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 <b>isTruncated = true</b> i należy ponownie ustawić <b>dateRange</b>, 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ć <b>pageOffset</b>.\n\n`Do scenariusza przyrostowego należy używać daty PermanentStorage oraz kolejność sortowania Asc`.\n \n<b>Scenariusz pobierania przyrostowego (skrót):</b>\n* Gdy <b>hasMore = false</b>, należy zakończyć,\n* Gdy <b>hasMore = true</b> i <b>isTruncated = false</b>, należy zwiększyć <b>pageOffset</b>,\n* Gdy <b>hasMore = true</b> i <b>isTruncated = true</b>, należy zawęzić <b>dateRange</b> (ustawić from od daty ostatniego rekordu), wyzerować <b>pageOffset</b> 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 <b>Encryption</b>, 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: <b>{ksefNumber}.xml</b>) 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ą <b>invoices</b>, gdzie każdy element jest obiektem typu <b>InvoiceMetadata</b>\n(taki jak zwracany przez endpoint `POST /invoices/query/metadata`).\n\n<b>Plik z metadanymi(_metadata.json) nie jest wliczany do limitów algorytmu budowania paczki</b>. \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 <b>IsTruncated = true</b> oraz odpowiednia data, którą należy wykorzystać do wykonania kolejnego eksportu, aż do momentu, gdy flaga <b>IsTruncated = false</b>.\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": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<AuthTokenRequest xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns=\"http://ksef.mf.gov.pl/auth/token/2.0\">\n <Challenge>20250625-CR-20F5EE4000-DA48AE4124-46</Challenge>\n <ContextIdentifier>\n <Nip>5265877635</Nip>\n </ContextIdentifier>\n <SubjectIdentifierType>certificateSubject</SubjectIdentifierType>\n <ds:Signature xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\" Id=\"Signature-9707709\">\n <!-- Tu powinien być podpis XAdES -->\n </ds:Signature>\n</AuthTokenRequest>"
}
},
"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 <b>fileParts</b> należy przesłać zgodnie z odpowiadającym jej obiektem w <b>partUploadRequests</b>.\nŁącznikiem pomiędzy deklaracją a instrukcją wysyłki jest pole <b>ordinalNumber</b>.\n\nDla każdej części należy:\n* zastosować metodę HTTP wskazaną w <b>method</b>,\n* ustawić adres z <b>url</b>,\n* dołączyć nagłówki z <b>headers</b>,\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 * <b>201</b> – poprawne przyjęcie pliku,\n * <b>400</b> – błędne dane,\n * <b>401</b> – nieprawidłowe uwierzytelnienie,\n * <b>403</b> – 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ż <b>acquisitionDate</b>. 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 <b>nie należy</b> 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 <b>nie należy</b> 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!** <br>\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"
]
}
]
}
Reference in a new issue View git blame Copy permalink