{ "openapi": "3.0.3", "info": { "title": "Fakturnia External REST API", "version": "1.0.0", "description": "\nOficjalne API pozwalające na integrację z systemem Fakturnia.\n\n## 🔑 Uprawnienia (OAuth Scopes)\nDo wywoływania endpointów API wymagane są odpowiednie uprawnienia nadawane podczas tworzenia Konta API. Wymagane uprawnienie jest widoczne przy każdym z endpointów.\n\n### Dostępne uprawnienia\n\n#### documents\n\n| Uprawnienie | Opis |\n|---|---|\n| `documents:browse` | Wyszukiwanie dokumentów |\n| `documents:read` | Pobieranie dokumentu po ID |\n| `documents:download` | Pobieranie PDF dokumentu |\n| `documents:create` | Tworzenie dokumentów |\n| `documents:delete` | Usuwanie dokumentów |\n| `documents:update` | Edycja dokumentów |\n| `documents:update-payment-status` | Zmiana statusu płatności dokumentu |\n| `documents:update-external-reference` | Powiązanie dokumentu z zamówieniem zewnętrznym |\n| `documents:send-to-ksef` | Wysyłka dokumentów do KSeF |\n\n#### ksef\n\n| Uprawnienie | Opis |\n|---|---|\n| `ksef:read` | Podgląd statusu połączenia KSeF |\n| `ksef:configure` | Konfiguracja połączenia KSeF |\n| `ksef:test` | Test połączenia KSeF |\n\n#### webhooks\n\n| Uprawnienie | Opis |\n|---|---|\n| `webhooks:read` | Podgląd webhooków |\n| `webhooks:create` | Tworzenie webhooków |\n\n#### settings\n\n| Uprawnienie | Opis |\n|---|---|\n| `settings:read` | Podgląd ustawień |\n| `settings:update` | Edycja ustawień |\n\n#### gus\n\n| Uprawnienie | Opis |\n|---|---|\n| `gus:company:read` | Pobieranie danych firmy po NIP z GUS |\n\n#### clients\n\n| Uprawnienie | Opis |\n|---|---|\n| `clients:browse` | Wyszukiwanie klientów |\n| `clients:read` | Pobieranie klienta po ID |\n| `clients:create` | Tworzenie klientów |\n| `clients:update` | Edycja klientów |\n| `clients:delete` | Usuwanie klientów |\n\n#### products\n\n| Uprawnienie | Opis |\n|---|---|\n| `products:browse` | Wyszukiwanie produktów |\n| `products:read` | Pobieranie produktu po ID |\n| `products:create` | Tworzenie produktów |\n| `products:update` | Edycja produktów |\n| `products:delete` | Usuwanie produktów |\n\n## 🪝 Webhooki i weryfikacja autentyczności (X-Webhook-Signature)\nSystem wysyła powiadomienia do zdefiniowanych webhooków, gdy zajdą odpowiednie zdarzenia w systemie. Aby zweryfikować, czy żądanie faktycznie pochodzi z systemu Fakturnia, powinieneś walidować podpis wiadomości.\n\n### Jak to działa?\nDo każdego nagłówka HTTP w żądaniu webhooka dołączany jest podpis pod kluczem `X-Webhook-Signature`. Podpis to hash **HMAC SHA-256** wygenerowany na podstawie całego (surowego) ciała żądania (body payload) używając unikalnego klucza `secret` przydzielonego do danego webhooka. Więcej informacji o weryfikacji i gotowe przykłady implementacyjne (Node.js, PHP, Python) można znaleźć w dokumentacji deweloperskiej SDK.\n\n### Przykład weryfikacji\nGotowe, działające przykłady weryfikacji podpisu (Node.js/Express, PHP, Python) znajdziesz w dokumentacji deweloperskiej: [Weryfikacja podpisu webhooka](https://developers.fakturnia.pl/pl/docs/webhooks#weryfikacja-podpisu).\n\n### Mechanizm ponawiania (Retry Mechanism)\n\n![Schemat ponawiania wysyłki webhooków](/retry-flow.pl.svg)\n\nW przypadku gdy serwer docelowy (twój endpoint) nie odpowie statusem `200 OK`, system Fakturnia zakolejkuje zdarzenie do ponownej wysyłki.\nMechanizm podejmie maksymalnie 5 prób doręczenia webhooka, w następujących odstępach czasu:\n1. Natychmiastowa próba\n2. Po 5 minutach\n3. Po 30 minutach\n4. Po 2 godzinach\n5. Po 8 godzinach\n\nJeżeli po 5 próbie serwer nadal nie odpowie poprawnie (status 200), zdarzenie zostanie oznaczone jako zakończone niepowodzeniem (`FAILED`), a po 10 następujących po sobie niepowodzeniach dla tego samego webhooka (niezależnie od zdarzenia), webhook zostanie automatycznie wyłączony.\n\n### Lista zdarzeń\n\n#### client\n\n| Zdarzenie | Opis |\n|---|---|\n| `client.created` | Gdy nowy kontrahent zostanie dodany |\n| `client.updated` | Gdy dane kontrahenta zostaną zaktualizowane |\n| `client.deleted` | Gdy kontrahent zostanie usunięty |\n\n#### product\n\n| Zdarzenie | Opis |\n|---|---|\n| `product.created` | Gdy produkt zostanie dodany |\n| `product.updated` | Gdy dane produktu ulegną zmianie |\n| `product.deleted` | Gdy produkt zostanie usunięty |\n\n#### document\n\n| Zdarzenie | Opis |\n|---|---|\n| `document.created` | Gdy dokument zostanie utworzony |\n| `document.updated` | Gdy dokument zostanie zmodyfikowany |\n| `document.deleted` | Gdy dokument zostanie usunięty |\n| `document.sentToKSeF` | Gdy dokument zostanie wysłany do KSeF |\n " }, "servers": [ { "url": "https://prod.api.fakturnia.pl/external/v1", "description": "Produkcja" }, { "url": "https://sandbox.api.fakturnia.pl/external/v1", "description": "Środowisko testowe (sandbox) — wysyłki do KSeF bez skutków prawnych" } ], "components": { "schemas": { "CreateDocumentRequestBody": { "type": "object", "required": [ "documentType", "issueDate" ], "properties": { "documentType": { "type": "string", "enum": [ "Faktura", "FakturaVAT", "FakturaKorygujaca", "FakturaKorygujacaZaliczkowa", "FakturaKorygujacaRozliczeniowa", "FakturaZaliczka", "FakturaRozliczeniowa", "Zamowienie" ], "description": "Typ dokumentu", "example": "FakturaVAT" }, "issueDate": { "type": "string", "format": "date", "description": "Data wystawienia (ISO 8601)", "example": "2026-05-07" }, "documentNo": { "type": "integer", "minimum": 1, "description": "Opcjonalny numer dokumentu" }, "numberingFormat": { "type": "string", "example": "/MM/YYYY" }, "symbol": { "type": "string", "example": "FV/" }, "documentNumber": { "type": "string", "example": "FV/1/05/2026" }, "invoiceName": { "type": "string" }, "buyerId": { "type": "string", "description": "ID istniejącego klienta (nie stosować z buyer)" }, "buyer": { "$ref": "#/components/schemas/ClientReference" }, "receiverId": { "type": "string" }, "receiver": { "$ref": "#/components/schemas/ClientReference" }, "products": { "type": "array", "items": { "type": "object", "required": [ "name", "unitOfMeasure", "quantity", "vatRate" ], "properties": { "name": { "type": "string", "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true }, "pkwiu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "example": "szt." }, "quantity": { "type": "number", "example": 1 }, "netPrice": { "type": "number", "nullable": true, "example": 100 }, "grossPrice": { "type": "number", "nullable": true, "example": 123 }, "netValue": { "type": "number", "nullable": true, "example": 100 }, "grossValue": { "type": "number", "nullable": true, "example": 123 }, "amountOfVat": { "type": "number", "nullable": true, "example": 23 }, "vatRate": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 23 }, "discount": { "type": "number", "example": 0 }, "currency": { "type": "string", "example": "PLN" } } } }, "currency": { "type": "string", "example": "PLN" }, "exchangeRate": { "type": "number" }, "issuePlace": { "type": "string", "example": "Warszawa" }, "comments": { "type": "string" }, "paymentDescription": { "type": "string" }, "showPaymentSection": { "type": "boolean", "example": true }, "paymentDeadlineDate": { "type": "string", "format": "date" }, "additionalPaymentDate": { "type": "string", "format": "date" }, "additionalPaymentDateHeaderId": { "type": "number", "example": 2 }, "subDate": { "type": "string", "format": "date" }, "subDateHeaderId": { "type": "number", "example": 2 }, "bankAccounts": { "type": "array", "description": "Pierwsze konto trafia do bankAccountNumber, kolejne do additionalBankAccounts", "items": { "type": "object", "required": [ "accountNumber" ], "properties": { "bank": { "type": "string", "nullable": true }, "accountNumber": { "type": "string" }, "swift": { "type": "string" }, "accountDescription": { "type": "string" }, "bankOwnAccountType": { "type": "number", "enum": [ 1, 2, 3 ], "nullable": true } } } }, "paymentMethodId": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Id metody płatności: 1=Gotówka, 2=Karta, 3=Bon, 4=Czek, 5=Kredyt, 6=Przelew, 7=Płatność mobilna", "example": 6 }, "paymentStatusId": { "type": "integer", "enum": [ 0, 1 ], "description": "0=Zapłacono (wymaga additionalPaymentDate), 1=Do zapłaty (wymaga paymentDeadlineDate)", "example": 1 }, "annotations": { "$ref": "#/components/schemas/AnnotationsInput" }, "linkedOrderId": { "type": "string" }, "advancePaymentAmount": { "type": "number", "minimum": 0.01 }, "correctedInvoiceId": { "type": "string" }, "correctionReason": { "type": "string" }, "linkedAdvanceInvoiceIds": { "type": "array", "items": { "type": "string" } }, "prepaymentIds": { "type": "array", "items": { "type": "string" } }, "ksefJst": { "type": "boolean" } } }, "ValidatePreviewResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "documentNo": { "type": "integer", "example": 1 }, "documentNumber": { "type": "string", "example": "FV/1/05/2026" }, "symbol": { "type": "string", "example": "FV/" }, "numberingFormat": { "type": "string", "example": "/MM/YYYY" }, "seller": { "$ref": "#/components/schemas/CompanyExternal" }, "buyer": { "$ref": "#/components/schemas/CompanyExternal" }, "receiver": { "$ref": "#/components/schemas/CompanyExternal" }, "hasReceiver": { "type": "boolean", "example": false }, "totals": { "type": "object", "properties": { "netSum": { "type": "number", "example": 100 }, "vatSum": { "type": "number", "example": 23 }, "grossSum": { "type": "number", "example": 123 } } }, "receivedPayment": { "type": "string", "example": "NOT_RECEIVED" } } }, "valid": { "type": "boolean", "example": true } } } } } ] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "null", "example": null }, "message": { "type": "string", "nullable": true, "example": "ERROR_CODE" }, "executionTime": { "type": "number", "nullable": true, "example": 50 }, "errors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } } }, "example": [ { "field": "documentType", "code": "REQUIRED", "message": "documentType jest wymagany." } ] } }, "required": [ "success", "data", "message" ] }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "example": null }, "message": { "type": "string", "nullable": true, "example": "OPERATION_SUCCESSFUL" }, "executionTime": { "type": "number", "nullable": true, "example": 50 } }, "required": [ "success", "data" ] }, "DocumentSuccessResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/DocumentExternal" } } } } } ] }, "DictionariesResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentTypes": { "type": "array", "items": { "type": "string" }, "example": [ "FakturaVAT", "FakturaKorygujaca" ] }, "paymentMethods": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Przelew" }, "paymentMethodId": { "type": "integer", "example": 6 } } } }, "paymentStatuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Do zapłaty" } } } }, "marginProcedures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "text": { "type": "string", "example": "Procedura marży dla biur podróży" } } } }, "vatExemptionTypes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "A" }, "label": { "type": "string" }, "placeholder": { "type": "string" } } } }, "gtu": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "GTU_01" }, "description": { "type": "string", "example": "Dostawa napojów alkoholowych" } } } }, "vatRates": { "type": "array", "description": "Stawki VAT, wartość na druku (value), etykieta (label) i opis. 0% KR/WDT/EX to różne stawki.", "items": { "type": "object", "properties": { "value": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": "0 KR" }, "label": { "type": "string", "example": "0% - KR" }, "description": { "type": "string", "nullable": true } } }, "example": [ { "value": 23, "label": "23%" }, { "value": "zw", "label": "zw.", "description": "Zwolnione od podatku" }, { "value": "0 WDT", "label": "0% - WDT", "description": "0% w przypadku wewnątrzwspólnotowej dostawy towarów (WDT)" } ] }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "PLN" }, "name": { "type": "string", "example": "Złoty polski" }, "availableExchangeRate": { "type": "boolean", "example": false } } } }, "paymentDateHeaders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 0 }, "name": { "type": "string", "example": "Data płatności" } } } }, "additionalDateHeaders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 0 }, "name": { "type": "string", "example": "Data sprzedaży" } } } } } } } } ] }, "DocumentExternal": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "userId": { "type": "string", "nullable": true }, "documentNumber": { "type": "string", "nullable": true, "example": "FV/1/05/2026" }, "documentNo": { "type": "integer", "nullable": true, "example": 1 }, "symbol": { "type": "string", "nullable": true, "example": "FV/" }, "documentType": { "type": "string", "nullable": true, "example": "FakturaVAT" }, "issueDate": { "type": "string", "nullable": true, "example": "2026-05-07" }, "issuePlace": { "type": "string", "nullable": true, "example": "Warszawa" }, "subDate": { "type": "string", "nullable": true }, "subDateHeader": { "type": "string", "nullable": true }, "additionalPaymentDate": { "type": "string", "nullable": true }, "additionalPaymentDateHeader": { "type": "string", "nullable": true }, "paymentDeadlineDate": { "type": "string", "nullable": true, "example": "2026-05-14" }, "buyer": { "$ref": "#/components/schemas/CompanyExternal" }, "seller": { "$ref": "#/components/schemas/CompanyExternal" }, "receiver": { "$ref": "#/components/schemas/CompanyExternal" }, "grossSum": { "type": "number", "nullable": true, "example": 123 }, "currency": { "type": "string", "nullable": true, "example": "PLN" }, "exchangeRate": { "type": "number", "nullable": true }, "prepaymentIds": { "type": "array", "nullable": true }, "correctedInvoiceId": { "type": "string", "nullable": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "example": "szt." }, "discount": { "type": "number", "example": 0 }, "quantity": { "type": "number", "example": 1 }, "netPrice": { "type": "number", "example": 100 }, "netValue": { "type": "number", "example": 100 }, "grossValue": { "type": "number", "example": 123 }, "amountOfVat": { "type": "number", "example": 23 }, "vatRate": { "type": "number", "example": 23 } } } }, "payment": { "type": "object", "nullable": true, "properties": { "method": { "type": "integer", "nullable": true, "description": "KSeF FormaPlatnosci: 1=Gotówka, 2=Karta, 3=Bon, 4=Czek, 5=Kredyt, 6=Przelew, 7=Płatność mobilna", "example": 6 }, "status": { "type": "integer", "nullable": true, "description": "0=Zapłacono, 1=Do zapłaty", "example": 1 }, "bankAccountNumber": { "type": "string", "nullable": true, "example": "1212 1212 1212 1212 1212 1212" } } }, "comments": { "type": "string", "nullable": true }, "marginProcedureId": { "type": "integer", "nullable": true }, "vatAccountNumber": { "type": "string", "nullable": true }, "isSent": { "type": "boolean", "example": false }, "isDownloaded": { "type": "boolean", "example": false }, "isPrinted": { "type": "boolean", "example": false }, "hasReceiver": { "type": "boolean", "example": false }, "hasComments": { "type": "boolean", "example": false }, "hasGTU": { "type": "boolean", "example": false }, "hasDiscount": { "type": "boolean", "example": false }, "hasPaymentDescription": { "type": "boolean", "example": false }, "signatures": { "type": "object", "nullable": true }, "createdAt": { "type": "string", "example": "2026-05-07T10:30:00.000Z" }, "updatedAt": { "type": "string", "example": "2026-05-07T10:30:00.000Z" } } }, "CompanyExternal": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "example": "company" }, "name": { "type": "string", "nullable": true, "example": "Acme Corp Sp. z o.o." }, "nip": { "type": "string", "nullable": true, "example": "5271012345" }, "vatUE": { "type": "string", "nullable": true }, "regon": { "type": "string", "nullable": true }, "krs": { "type": "string", "nullable": true }, "bdo": { "type": "string", "nullable": true }, "pesel": { "type": "string", "nullable": true }, "street": { "type": "string", "nullable": true, "example": "Marszałkowska 1" }, "postalCode": { "type": "string", "nullable": true, "example": "00-001" }, "city": { "type": "string", "nullable": true, "example": "Warszawa" }, "country": { "type": "string", "nullable": true, "example": "Polska" }, "countryCode": { "type": "string", "nullable": true, "example": "PL" }, "phoneNumber": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "www": { "type": "string", "nullable": true } } }, "ClientReference": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "company", "person" ] }, "name": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "nip": { "type": "string", "nullable": true, "example": "5271012345" }, "vatUE": { "type": "string", "nullable": true }, "pesel": { "type": "string", "nullable": true }, "regon": { "type": "string", "nullable": true }, "krs": { "type": "string", "nullable": true }, "bdo": { "type": "string", "nullable": true }, "identifierType": { "type": "string", "nullable": true, "example": "idWew" }, "otherTaxIdentifier": { "type": "string", "nullable": true }, "idWew": { "type": "string", "nullable": true }, "street": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "www": { "type": "string", "nullable": true }, "fieldsToShow": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "AnnotationsInput": { "type": "object", "properties": { "isSplitPayment": { "type": "boolean", "description": "MPP - split payment. Wyklucza się z isCashMethod.", "example": false }, "isReverseCharge": { "type": "boolean", "description": "Odwrotne obciążenie" }, "isCashMethod": { "type": "boolean", "description": "Metoda kasowa. Wyklucza się z isSplitPayment.", "example": false }, "isSelfInvoicing": { "type": "boolean", "description": "Samofakturowanie" }, "marginProcedure": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "procedureId": { "type": "integer", "description": "ID procedury marży (1-5)", "example": 2 } } }, "vatExemption": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": false }, "exemptionType": { "type": "string", "enum": [ "A", "B", "C" ] }, "legalBasis": { "type": "string" }, "showOnDocument": { "type": "boolean", "example": false } } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://prod.api.fakturnia.pl/v1/oauth/token", "scopes": {} } } } } }, "paths": { "/documents/": { "get": { "summary": "Pobierz listę dokumentów", "description": "**Wymagane uprawnienie (Scope)**: `documents:browse`", "parameters": [ { "name": "searchQuery", "in": "query", "required": false, "description": "Filtruj dokumenty według numeru dokumentu", "schema": { "type": "string" } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Liczba dokumentów na stronę (maks. 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } }, { "name": "currentPage", "in": "query", "required": false, "description": "Numer bieżącej strony (liczony od 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "buyerNip", "in": "query", "required": false, "description": "Filtruj dokumenty według NIP nabywcy", "schema": { "type": "string" } }, { "name": "buyerVatUE", "in": "query", "required": false, "description": "Filtruj dokumenty według numeru VAT UE nabywcy", "schema": { "type": "string" } }, { "name": "buyerIdentifier", "in": "query", "required": false, "description": "Filtruj dokumenty według innego identyfikatora podatkowego nabywcy", "schema": { "type": "string" } }, { "name": "excludeIds", "in": "query", "required": false, "description": "Lista identyfikatorów dokumentów (oddzielona przecinkami) do wykluczenia z wyników", "schema": { "type": "string" } }, { "name": "onlyUnlinked", "in": "query", "required": false, "description": "Jeśli ustawiono na true, zwracane są tylko dokumenty bez externalSource (niepowiązane z żadnym zamówieniem zewnętrznym)", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Lista dokumentów", "content": { "application/json": { "example": { "success": true, "data": { "documents": [], "currentPage": 1, "totalPages": 5, "totalCount": 50, "itemsPerPage": 10, "searchQuery": "FV/2023/001" }, "executionTime": 50 } } } }, "400": { "description": "Nieprawidłowe parametry zapytania", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] }, "post": { "summary": "Utwórz nowy dokument", "description": "**Wymagane uprawnienie (Scope)**: `documents:create`", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unikalny klucz idempotencyjności (UUID v4 zalecane). Zabezpiecza przed duplikowaniem operacji przy retry. Przechowywany 24h.", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "201": { "description": "Dokument utworzony pomyślnie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSuccessResponse" }, "example": { "success": true, "data": { "document": { "id": "681a3b2c4d5e6f7a8b9c0d1e", "documentNumber": "FV/1/05/2026", "documentNo": 1, "symbol": "FV/", "documentType": "FakturaVAT", "issueDate": "2026-05-07", "issuePlace": "Warszawa", "subDate": null, "additionalPaymentDate": null, "paymentDeadlineDate": "2026-05-14", "buyer": { "id": "681a3b2c4d5e6f7a8b9c0d2e", "type": "company", "name": "Acme Corp Sp. z o.o.", "nip": "5271012345", "street": "Marszałkowska 1", "postalCode": "00-001", "city": "Warszawa", "country": "Polska", "countryCode": "PL" }, "seller": { "id": null, "type": "company", "name": "Nasza Firma Sp. z o.o.", "nip": "1234567890", "street": "ul. Główna 10", "postalCode": "00-100", "city": "Kraków", "country": "Polska", "countryCode": "PL" }, "receiver": null, "grossSum": 123, "currency": "PLN", "exchangeRate": null, "prepaymentIds": null, "correctedInvoiceId": null, "products": [ { "id": "681a3b2c4d5e6f7a8b9c0d3f", "name": "Usługa programistyczna", "gtu": null, "unitOfMeasure": "szt.", "discount": 0, "quantity": 1, "netPrice": 100, "netValue": 100, "grossValue": 123, "amountOfVat": 23, "vatRate": 23 } ], "payment": { "method": 6, "status": 1, "bankAccountNumber": "1212 1212 1212 1212 1212 1212" }, "comments": null, "marginProcedureId": null, "vatAccountNumber": null, "isSent": false, "isDownloaded": false, "isPrinted": false, "hasReceiver": false, "hasComments": false, "hasGTU": false, "hasDiscount": false, "hasPaymentDescription": false, "signatures": null, "createdAt": "2026-05-07T10:30:00.000Z", "updatedAt": "2026-05-07T10:30:00.000Z" } }, "message": "DOCUMENT_CREATED", "executionTime": 142 } } } }, "400": { "description": "Nieprawidłowe ciało żądania (brak wymaganych pól, nieprawidłowe typy, niejednoznaczny nabywca/odbiorca)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "VALIDATION_ERROR", "executionTime": 5, "errors": [ { "field": "documentType", "code": "REQUIRED", "message": "documentType jest wymagany." }, { "field": "buyerId + buyer", "code": "AMBIGUOUS_PARTY", "message": "Podaj albo buyerId, albo buyer, ale nie oba." } ] } } } }, "401": { "description": "Nieautoryzowany (brak lub nieprawidłowy token JWT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "UNAUTHORIZED", "executionTime": 2, "errors": null } } } }, "403": { "description": "Brak dostępu (przekroczony limit lub brak wymaganego uprawnienia)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "DOCUMENT_LIMIT_EXCEEDED", "executionTime": 18, "errors": [ { "code": "LIMIT_REACHED", "message": "Osiągnięto limit dokumentów dla twojego planu." } ] } } } }, "404": { "description": "Nie znaleziono powiązanego zasobu (nabywca, korygowana faktura, powiązane zamówienie itp.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "BUYER_NOT_FOUND", "executionTime": 8, "errors": [ { "code": "NOT_FOUND", "message": "Klient o podanym ID nie został znaleziony." } ] } } } }, "409": { "description": "Numer dokumentu już istnieje", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "NUMBER_ALREADY_EXISTS", "executionTime": 15, "errors": [ { "code": "CONFLICT", "message": "Dokument o numerze \"FV/5/05/2026\" już istnieje." } ] } } } }, "422": { "description": "Walidacja biznesowa nie powiodła się (konflikty adnotacji, brakujące daty płatności, wymagania zależne od typu)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "ANNOTATIONS_VALIDATION_ERROR", "executionTime": 11, "errors": [ { "code": "ANNOTATION_CONFLICT", "message": "isSplitPayment (MPP) wyklucza się z isCashMethod (metoda kasowa)." } ] } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "INTERNAL_SERVER_ERROR", "executionTime": 5, "errors": [ { "code": "INTERNAL", "message": "Unexpected error" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}": { "get": { "summary": "Pobierz szczegóły dokumentu", "description": "**Wymagane uprawnienie (Scope)**: `documents:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Szczegóły dokumentu", "content": { "application/json": { "example": { "success": true, "data": { "document": {} }, "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe ID dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] }, "delete": { "summary": "Usuń dokument", "description": "**Wymagane uprawnienie (Scope)**: `documents:delete`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu do usunięcia", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dokument usunięty pomyślnie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Document deleted.", "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe żądanie, KSeF zablokowany lub brakujące parametry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany, brak lub nieprawidłowy token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Brak dostępu, brak uprawnienia documents:delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu lub dokument nie należy do uwierzytelnionego użytkownika.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] }, "put": { "summary": "Pełna aktualizacja istniejącego dokumentu", "description": "**Wymagane uprawnienie (Scope)**: `documents:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu do aktualizacji", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dokument zaktualizowany.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Document updated.", "data": { "document": { "id": "64dddddddddddddddddddddd", "documentType": "FakturaVAT", "documentNumber": "FV/1/05/2026", "issueDate": "2026-06-01", "comments": "Updated comment" } }, "executionTime": 12 } } } }, "400": { "description": "Nieprawidłowe dane wejściowe, KSeF zablokowany lub brakujące parametry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany, brak lub nieprawidłowy token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Brak dostępu, brak uprawnienia documents:update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu lub dokument nie należy do uwierzytelnionego użytkownika.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Numer dokumentu już istnieje w tym samym miesiącu/roku.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Błąd walidacji, nieprawidłowo sformułowane dane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] }, "patch": { "summary": "Częściowa aktualizacja pola lub pól dokumentu", "description": "**Wymagane uprawnienie (Scope)**: `documents:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu do częściowej aktualizacji", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dokument częściowo zaktualizowany.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Document updated.", "data": { "document": { "id": "64dddddddddddddddddddddd", "documentType": "FakturaVAT", "documentNumber": "FV/1/05/2026", "comments": "Updated via PATCH", "paymentDeadlineDate": "2026-06-15" } }, "executionTime": 8 } } } }, "400": { "description": "Nieprawidłowe dane wejściowe, puste ciało żądania lub KSeF zablokowany.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany, brak lub nieprawidłowy token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Brak dostępu, brak uprawnienia documents:update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu lub dokument nie należy do uwierzytelnionego użytkownika.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Numer dokumentu już istnieje w tym samym miesiącu/roku.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Błąd walidacji, nieprawidłowo sformułowane dane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/download": { "get": { "summary": "Pobierz dokument", "description": "**Wymagane uprawnienie (Scope)**: `documents:download`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plik PDF" }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/validate": { "post": { "summary": "Walidacja próbna danych dokumentu (bez zapisu do bazy danych)", "description": "**Wymagane uprawnienie (Scope)**: `documents:create`", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unikalny klucz idempotencyjności. Dla /validate osobny keyPrefix niż dla /create.", "schema": { "type": "string", "example": "660e8400-e29b-41d4-a716-446655440001" } } ], "responses": { "200": { "description": "Walidacja powiodła się, zwraca podgląd (bez zapisu do bazy danych)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatePreviewResponse" }, "example": { "success": true, "data": { "preview": { "documentNo": 1, "documentNumber": "FV/1/05/2026", "symbol": "FV/", "numberingFormat": "/MM/YYYY", "seller": { "type": "company", "name": "Nasza Firma Sp. z o.o.", "nip": "1234567890", "street": "ul. Główna 10", "postalCode": "00-100", "city": "Kraków", "country": "Polska", "countryCode": "PL" }, "buyer": { "type": "company", "name": "Acme Corp Sp. z o.o.", "nip": "5271012345", "street": "Marszałkowska 1", "postalCode": "00-001", "city": "Warszawa", "country": "Polska", "countryCode": "PL" }, "receiver": null, "hasReceiver": false, "totals": { "netSum": 100, "vatSum": 23, "grossSum": 123 }, "receivedPayment": "NOT_RECEIVED" }, "valid": true }, "message": "VALIDATION_SUCCESSFUL", "executionTime": 38 } } } }, "400": { "description": "Nieprawidłowe ciało żądania", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "VALIDATION_ERROR", "executionTime": 4, "errors": [ { "field": "documentType", "code": "REQUIRED", "message": "documentType jest wymagany." } ] } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "UNAUTHORIZED", "executionTime": 2, "errors": null } } } }, "403": { "description": "Brak dostępu (brak wymaganego uprawnienia)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "NO_PERMISSIONS", "executionTime": 3, "errors": [ { "code": "MISSING_SCOPE", "message": "Wymagany scope: documents:create" } ] } } } }, "404": { "description": "Nie znaleziono powiązanego zasobu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "BUYER_NOT_FOUND", "executionTime": 9, "errors": [ { "code": "NOT_FOUND", "message": "Klient o podanym ID nie został znaleziony." } ] } } } }, "409": { "description": "Numer dokumentu już istnieje", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "NUMBER_ALREADY_EXISTS", "executionTime": 12, "errors": [ { "code": "CONFLICT", "message": "Dokument o numerze \"FV/5/05/2026\" już istnieje." } ] } } } }, "422": { "description": "Walidacja biznesowa nie powiodła się", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "PAYMENT_DEADLINE_REQUIRED", "executionTime": 7, "errors": [ { "code": "MISSING_FIELD", "message": "paymentStatusId=1 (Do zapłaty) wymaga paymentDeadlineDate." } ] } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "INTERNAL_SERVER_ERROR", "executionTime": 5, "errors": [ { "code": "INTERNAL", "message": "Unexpected error" } ] } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/payment-status": { "patch": { "summary": "Zaktualizuj status płatności dokumentu", "description": "**Wymagane uprawnienie (Scope)**: `documents:update-payment-status`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status płatności zaktualizowany.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Nieprawidłowe dane wejściowe lub nieobsługiwany status płatności dokumentu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Brak dostępu (brak wymaganego uprawnienia)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/external-reference": { "patch": { "summary": "Powiąż dokument z zewnętrznym numerem zamówienia", "description": "**Wymagane uprawnienie (Scope)**: `documents:update-external-reference`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Powiązanie zewnętrzne zaktualizowane", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Brak dostępu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] }, "delete": { "summary": "Usuń powiązanie z zewnętrznym zamówieniem z dokumentu", "description": "**Wymagane uprawnienie (Scope)**: `documents:update-external-reference`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Powiązanie zewnętrzne usunięte", "content": { "application/json": { "example": { "success": true, "message": "External reference removed.", "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/send-to-ksef": { "post": { "summary": "Wyślij dokument do KSeF", "description": "**Wymagane uprawnienie (Scope)**: `documents:send-to-ksef`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu do wysłania", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opcjonalny klucz idempotencyjności umożliwiający bezpieczne ponawianie żądań wysyłki.", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Dokument wysłany i przetworzony w KSeF (dostępny ksefNumber).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Nieprawidłowe żądanie lub dokument nie może zostać wysłany do KSeF.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Brak dostępu (brak wymaganego uprawnienia)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Konflikt (już wysłany / już przetwarzany / brak połączenia z KSeF).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Połączenie z KSeF istnieje, ale jest nieprawidłowe lub nieautoryzowane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/ksef-status": { "get": { "summary": "Pobierz status wysyłki dokumentu do KSeF", "description": "**Wymagane uprawnienie (Scope)**: `documents:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID dokumentu", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dane statusu KSeF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono dokumentu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/clients/": { "get": { "summary": "Pobierz listę klientów", "description": "**Wymagane uprawnienie (Scope)**: `clients:browse`", "parameters": [ { "name": "searchQuery", "in": "query", "required": false, "description": "Filtruj klientów według nazwy, NIP lub adresu e-mail", "schema": { "type": "string" } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Liczba klientów na stronę (maks. 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } }, { "name": "currentPage", "in": "query", "required": false, "description": "Numer bieżącej strony (liczony od 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Lista klientów", "content": { "application/json": { "example": { "success": true, "data": { "clients": [], "currentPage": 1, "totalPages": 5, "totalCount": 50, "itemsPerPage": 10, "searchQuery": "" }, "executionTime": 50 } } } }, "400": { "description": "Nieprawidłowe parametry zapytania", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "clients" ] }, "post": { "summary": "Utwórz nowego klienta", "description": "**Wymagane uprawnienie (Scope)**: `clients:create`", "responses": { "200": { "description": "Klient utworzony pomyślnie", "content": { "application/json": { "example": { "success": true, "data": { "client": {} }, "executionTime": 10 } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Klient z tym NIP już istnieje", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Błąd walidacji", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "clients" ] } }, "/clients/{id}": { "get": { "summary": "Pobierz szczegóły klienta", "description": "**Wymagane uprawnienie (Scope)**: `clients:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID klienta", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Szczegóły klienta", "content": { "application/json": { "example": { "success": true, "data": { "client": {} }, "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe ID klienta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono klienta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "clients" ] }, "put": { "summary": "Zaktualizuj istniejącego klienta", "description": "**Wymagane uprawnienie (Scope)**: `clients:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID klienta do aktualizacji", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Klient zaktualizowany pomyślnie", "content": { "application/json": { "example": { "success": true, "data": { "client": {} }, "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono klienta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Konflikt NIP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Błąd walidacji", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "clients" ] }, "delete": { "summary": "Usuń klienta", "description": "**Wymagane uprawnienie (Scope)**: `clients:delete`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID klienta do usunięcia", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Klient usunięty pomyślnie", "content": { "application/json": { "example": { "success": true, "message": "Client deleted.", "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono klienta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "clients" ] } }, "/products/": { "get": { "summary": "Pobierz listę produktów", "description": "**Wymagane uprawnienie (Scope)**: `products:browse`", "parameters": [ { "name": "searchQuery", "in": "query", "required": false, "description": "Filtruj produkty według nazwy", "schema": { "type": "string" } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Liczba produktów na stronę (maks. 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } }, { "name": "currentPage", "in": "query", "required": false, "description": "Numer bieżącej strony (liczony od 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Lista produktów", "content": { "application/json": { "example": { "success": true, "data": { "products": [], "currentPage": 1, "totalPages": 5, "totalCount": 50, "itemsPerPage": 10, "searchQuery": "" }, "executionTime": 50 } } } }, "400": { "description": "Nieprawidłowe parametry zapytania", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "products" ] }, "post": { "summary": "Utwórz nowy produkt", "description": "**Wymagane uprawnienie (Scope)**: `products:create`", "responses": { "200": { "description": "Produkt utworzony", "content": { "application/json": { "example": { "success": true, "data": { "product": {} }, "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Błąd walidacji", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "products" ] } }, "/products/{id}": { "get": { "summary": "Pobierz szczegóły produktu", "description": "**Wymagane uprawnienie (Scope)**: `products:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID produktu", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Szczegóły produktu", "content": { "application/json": { "example": { "success": true, "data": { "product": {} }, "executionTime": 10 } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono produktu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "products" ] }, "put": { "summary": "Zaktualizuj istniejący produkt", "description": "**Wymagane uprawnienie (Scope)**: `products:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID produktu do aktualizacji", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Produkt zaktualizowany", "content": { "application/json": { "example": { "success": true, "data": { "product": {} }, "executionTime": 10 } } } }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono produktu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Błąd walidacji", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "products" ] }, "delete": { "summary": "Usuń produkt", "description": "**Wymagane uprawnienie (Scope)**: `products:delete`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID produktu do usunięcia", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Produkt usunięty", "content": { "application/json": { "example": { "success": true, "message": "Product deleted.", "executionTime": 10 } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono produktu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "products" ] } }, "/dictionaries/": { "get": { "summary": "Pobierz słowniki statyczne (typy dokumentów, metody płatności itp.)", "description": "", "responses": { "200": { "description": "Dane słownika", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DictionariesResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "ERROR_CODE", "executionTime": 42, "errors": null } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "dictionaries" ] } }, "/ksef/connection": { "get": { "summary": "Pobierz status połączenia z KSeF", "description": "**Wymagane uprawnienie (Scope)**: `ksef:read`", "responses": { "200": { "description": "Status połączenia z KSeF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "ksef" ] }, "post": { "summary": "Utwórz lub zaktualizuj połączenie z KSeF (tryb certyfikatu)", "description": "**Wymagane uprawnienie (Scope)**: `ksef:configure`", "responses": { "200": { "description": "Połączenie z KSeF zapisane", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Nieprawidłowe żądanie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono użytkownika", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "ksef" ] }, "delete": { "summary": "Dezaktywuj połączenie z KSeF", "description": "**Wymagane uprawnienie (Scope)**: `ksef:configure`", "responses": { "200": { "description": "Połączenie z KSeF dezaktywowane", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono połączenia", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "ksef" ] } }, "/ksef/connection/test": { "post": { "summary": "Przetestuj autoryzację i uprawnienia połączenia z KSeF", "description": "**Wymagane uprawnienie (Scope)**: `ksef:test`", "responses": { "200": { "description": "Wynik testu połączenia z KSeF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Nie znaleziono połączenia", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Wewnętrzny błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "ksef" ] } }, "/webhooks/": { "get": { "summary": "Wyświetl listę webhooków i status początkowego webhooka", "description": "**Wymagane uprawnienie (Scope)**: `webhooks:read`", "parameters": [ { "name": "endpoint", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opcjonalny adres URL endpointu do sprawdzenia, czy istnieje początkowy webhook." } ], "responses": { "200": { "description": "Sukces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/webhooks/initial": { "post": { "summary": "Utwórz pierwszy automatycznie generowany webhook dla wtyczki", "description": "**Wymagane uprawnienie (Scope)**: `webhooks:create`", "responses": { "200": { "description": "Sukces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/settings/": { "get": { "summary": "Pobierz ustawienia ogólne i ustawienia numeracji", "description": "**Wymagane uprawnienie (Scope)**: `settings:read`", "responses": { "200": { "description": "Sukces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "settings" ] } }, "/settings/general": { "patch": { "summary": "Zaktualizuj ustawienia ogólne (format daty, newsletter)", "description": "**Wymagane uprawnienie (Scope)**: `settings:update`", "responses": { "200": { "description": "Sukces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "settings" ] } }, "/settings/numbering": { "patch": { "summary": "Zaktualizuj ustawienia numeracji (typ, format, symbole)", "description": "**Wymagane uprawnienie (Scope)**: `settings:update`", "responses": { "200": { "description": "Sukces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "settings" ] } }, "/company/nip-lookup": { "get": { "summary": "Wyszukaj dane firmy w GUS po numerze NIP", "description": "**Wymagane uprawnienie (Scope)**: `gus:company:read`", "parameters": [ { "in": "query", "name": "nip", "required": true, "schema": { "type": "string", "example": "5271012345" }, "description": "Polski numer NIP (10 cyfr)" } ], "responses": { "200": { "description": "Sukces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "company" ] } }, "/auth/me": { "get": { "summary": "Pobierz informacje o aktualnym koncie", "description": "", "responses": { "200": { "description": "Poprawnie pobrano dane konta", "content": { "application/json": { "example": { "success": true, "data": { "clientId": "507f1f77bcf86cd799439011", "name": "Integracja z e-Sklepem", "scopes": [ "documents:read", "clients:browse" ], "userId": "507f1f77bcf86cd799439012" }, "executionTime": 10 } } } }, "401": { "description": "Nieautoryzowany", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Błąd serwera", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "OAuth2": [] } ], "tags": [ "auth" ] } } }, "security": [ { "BearerAuth": [] }, { "OAuth2": [ "documents:browse", "documents:read", "documents:download", "documents:create", "documents:delete", "documents:update", "documents:update-payment-status", "documents:update-external-reference", "documents:send-to-ksef", "ksef:read", "ksef:configure", "ksef:test", "webhooks:read", "webhooks:create", "settings:read", "settings:update", "gus:company:read", "clients:browse", "clients:read", "clients:create", "clients:update", "clients:delete", "products:browse", "products:read", "products:create", "products:update", "products:delete" ] } ], "tags": [] }