{ "openapi": "3.0.3", "info": { "title": "Fakturnia External REST API", "version": "1.3.0", "description": "\nThe official API for integrating with Fakturnia.\n\n## 💎 MAX plan\nThe REST API (API accounts, every `/external/v1` endpoint, webhooks) is a **MAX** plan module. Without an active MAX plan the token endpoint answers `403 access_denied` with `error_code: SUBSCRIPTION_REQUIRED`, and every call made with a previously issued token answers `403 SUBSCRIPTION_REQUIRED`. No webhooks are delivered in that state.\n\n## 📦 Response envelope and error codes\nEvery JSON response has the shape `{ success, data, message, executionTime, errors? }`. On an error `message` is a **stable code** (branch on it, never on prose) and `errors` carries the details: `{ field, code?, message }` objects for field validation, or explanatory sentences.\n\n| Code | Status |\n|---|---|\n| `BAD_REQUEST` | 400 |\n| `INVALID_NIP` | 400 |\n| `INVALID_PARAMS` | 400 |\n| `INVALID_PAYMENT_STATUS` | 400 |\n| `KSEF_CONFIRMED` | 400 |\n| `KSEF_SENT` | 400 |\n| `PAYMENT_STATUS_UPDATE_NOT_ALLOWED` | 400 |\n| `INVALID_API_KEY` | 401 |\n| `TOKEN_EXPIRED` | 401 |\n| `UNAUTHORIZED` | 401 |\n| `DOCUMENT_LIMIT_EXCEEDED` | 403 |\n| `FORBIDDEN` | 403 |\n| `NO_PERMISSIONS` | 403 |\n| `SUBSCRIPTION_REQUIRED` | 403 |\n| `COMPANY_NOT_FOUND` | 404 |\n| `DOCUMENT_NOT_FOUND` | 404 |\n| `KSEF_CONNECTION_NOT_FOUND` | 404 |\n| `NOT_FOUND` | 404 |\n| `PRODUCT_NOT_FOUND` | 404 |\n| `USER_NOT_FOUND` | 404 |\n| `USER_OR_NIP_NOT_FOUND` | 404 |\n| `ADVANCE_INVOICE_SETTLED` | 409 |\n| `CONFLICT` | 409 |\n| `CORRECTED_INVOICE_HAS_CORRECTION` | 409 |\n| `DOCUMENT_CORRECTED` | 409 |\n| `DOCUMENT_NUMBER_EXISTS` | 409 |\n| `EMAIL_TAKEN` | 409 |\n| `EMPLOYEE_LIMIT_REACHED` | 409 |\n| `KSEF_ALREADY_PROCESSING` | 409 |\n| `KSEF_CONNECTION_REQUIRED` | 409 |\n| `KSEF_SEND_NOT_ALLOWED` | 409 |\n| `WAREHOUSE_LINES_LOCKED` | 409 |\n| `ADVANCE_RECEIPTS_INVALID` | 422 |\n| `DOCUMENT_DATES_INVALID` | 422 |\n| `KSEF_CONNECTION_NOT_AUTHORIZED` | 422 |\n| `MARGIN_LINE_NOT_FOUND` | 422 |\n| `MARGIN_PURCHASES_INVALID` | 422 |\n| `PARTIAL_PAYMENTS_INVALID` | 422 |\n| `PAYMENT_INSTALLMENTS_INVALID` | 422 |\n| `STOCK_SHORTAGE` | 422 |\n| `VALIDATION_ERROR` | 422 |\n| `WAREHOUSE_INVALID` | 422 |\n| `RATE_LIMIT_EXCEEDED` | 429 |\n| `WAIT_PDF_QUEUE` | 429 |\n| `INTERNAL_SERVER_ERROR` | 500 |\n| `GUS_UNAVAILABLE` | 503 |\n\n## 🧾 Response headers\n- `X-Request-ID`: request id (quote it when contacting support),\n- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: state of the rate limit,\n- `Retry-After`: with `429`, seconds to wait before retrying,\n- `Idempotent-Replayed: true`: the response was replayed from an earlier request with the same `Idempotency-Key`.\n\n## 🔑 Permissions (OAuth scopes)\nCalling the endpoints requires the permissions granted when the API account is created. The required permission is shown next to every endpoint.\n\n### Available permissions\n- `documents:browse` - Search documents\n- `documents:read` - Get a document by id\n- `documents:download` - Download a document PDF\n- `documents:create` - Create documents\n- `documents:delete` - Delete documents\n- `documents:update` - Edit documents\n- `documents:update-payment-status` - Change the payment status of a document\n- `documents:update-external-reference` - Link a document with an external order\n- `documents:send-to-ksef` - Send documents to KSeF\n- `ksef:read` - View the KSeF connection status\n- `ksef:configure` - Configure the KSeF connection\n- `ksef:test` - Test the KSeF connection\n- `webhooks:read` - View webhooks and delivery history\n- `webhooks:create` - Create webhooks\n- `webhooks:update` - Edit webhooks, rotate the secret and send test deliveries\n- `webhooks:delete` - Delete webhooks\n- `email-accounts:browse` - List connected email accounts\n- `email-accounts:read` - Email account details\n- `settings:read` - View settings\n- `settings:update` - Edit settings\n- `gus:company:read` - Look a company up by NIP in GUS\n- `clients:browse` - Search clients\n- `clients:read` - Get a client by id\n- `clients:create` - Create clients\n- `clients:update` - Edit clients\n- `clients:delete` - Delete clients\n- `products:browse` - Search products\n- `products:read` - Get a product by id\n- `products:create` - Create products\n- `products:update` - Edit products\n- `products:delete` - Delete products\n- `warehouse:browse` - List warehouses\n- `warehouse:create` - Create warehouses\n- `warehouse:update` - Edit warehouses\n- `warehouse:delete` - Delete warehouses\n- `warehouse:stock:read` - Stock report\n- `warehouse:adjust` - Stock adjustments (inventory)\n- `warehouse:wz:create` - Issue WZ documents for invoices\n- `warehouse:documents:create` - Issue warehouse documents (WZ, PZ, PW, RW, MM)\n- `employees:browse` - List employee accounts\n- `employees:create` - Create employee accounts\n- `employees:update` - Edit employee accounts and permissions\n- `employees:delete` - Delete employee accounts\n- `recurring:browse` - List recurring rules\n- `recurring:read` - Rule details and generation history\n- `recurring:toggle` - Pause and resume a rule\n- `activity:read` - Account activity history (owner and employees)\n\n## 🪝 Webhooks and authenticity verification (X-Webhook-Signature)\nFakturnia notifies the registered webhooks when matching events happen. Validate the message signature to verify that a request really comes from Fakturnia.\n\n### How it works\nEvery delivery is a `POST` with a JSON body (schema `WebhookEventPayload`): `{ id, event, timestamp, data, resourceId }`. The `id` (repeated in the `X-Webhook-Delivery` header) stays the same on every retry, so use it to deduplicate. The `X-Webhook-Event` header carries the event name and `X-Webhook-Signature` the signature: an **HMAC SHA-256** hash of the raw request body with the webhook secret (returned once, on creation and on rotation).\n\n### Verification example in Node.js (Express)\n```javascript\nconst crypto = require('crypto');\nconst express = require('express');\nconst app = express();\n\nconst WEBHOOK_SECRET = 'your_webhook_secret';\n\napp.post('/webhook-endpoint', express.raw({type: 'application/json'}), (req, res) => {\n const signatureFromHeader = req.headers['x-webhook-signature'];\n const expectedSignature = crypto.createHmac('sha256', WEBHOOK_SECRET).update(req.body).digest('hex');\n\n if (signatureFromHeader !== expectedSignature) return res.status(401).send('Unauthorized');\n\n const payload = JSON.parse(req.body.toString());\n console.log('Event:', payload.event);\n res.status(200).send('OK');\n});\n```\n\n### Retry mechanism\nWhen the target server (your endpoint) does not answer `200 OK`, Fakturnia queues the event for redelivery.\nUp to 5 delivery attempts are made, at the following intervals:\n1. Immediately\n2. After 5 minutes\n3. After 30 minutes\n4. After 2 hours\n5. After 8 hours\n\nIf the server still does not answer correctly (status 200) after the 5th attempt, the event is marked as failed (`FAILED`); after 10 consecutive failures of the same webhook (regardless of the event) the webhook is switched off automatically.\n\n### Event list\n- `client.created` - When a contractor is added\n- `client.updated` - When contractor data is updated\n- `client.deleted` - When a contractor is deleted\n- `product.created` - When a product is added\n- `product.updated` - When product data changes\n- `product.deleted` - When a product is deleted\n- `document.created` - When a document is created\n- `document.updated` - When a document is modified\n- `document.deleted` - When a document is deleted\n- `document.sentToKSeF` - When KSeF accepts a document (it has a KSeF number)\n- `document.ksefRejected` - When KSeF rejects a document or the send fails\n- `document.paymentStatusChanged` - When the payment mark of a document changes (received / reverted)\n- `document.ksefImported` - When a KSeF sync downloads new invoices (received, or issued outside Fakturnia); ids in documentIds, up to 100 per delivery\n " }, "servers": [ { "url": "https://prod.api.fakturnia.pl/external/v1", "description": "Production" }, { "url": "https://sandbox.api.fakturnia.pl/external/v1", "description": "Test environment (sandbox): KSeF sends have no legal effect" } ], "components": { "schemas": { "CreateDocumentRequestBody": { "type": "object", "required": [ "documentType", "issueDate" ], "properties": { "documentType": { "type": "string", "enum": [ "Faktura", "FakturaVAT", "FakturaKorygujaca", "FakturaKorygujacaZaliczkowa", "FakturaKorygujacaRozliczeniowa", "FakturaZaliczka", "FakturaRozliczeniowa", "FakturaProforma", "FakturaProformaBezVAT", "Zamowienie" ], "description": "Document type", "example": "FakturaVAT" }, "issueDate": { "type": "string", "format": "date", "description": "Issue date (ISO 8601)", "example": "2026-05-07" }, "documentNo": { "type": "integer", "minimum": 1, "description": "Optional document number. If provided, it is used instead of automatic numbering.", "example": 1 }, "numberingFormat": { "type": "string", "enum": [ "/MM/YYYY", "YYYY/MM/", "/YYYY/MM", "MM/YYYY/", "/YYYY", "YYYY/", "-MM-YYYY", "YYYY-MM-", "-YYYY-MM", "MM-YYYY-", "-YYYY", "YYYY-" ], "description": "Numbering format (e.g. \"/MM/YYYY\"). Defaults to the user's settings.", "example": "/MM/YYYY" }, "symbol": { "type": "string", "description": "Document symbol prefix (e.g. \"FV/\"). Defaults to the settings.", "example": "FV/" }, "documentNumber": { "type": "string", "description": "Full document number for exact (1:1) validation. If provided together with documentNo, the two must be consistent.", "example": "FV/1/05/2026" }, "invoiceName": { "type": "string", "description": "Invoice name (e.g. for advance invoices)", "example": "Faktura zaliczkowa" }, "buyerId": { "type": "string", "description": "ID of an existing client. Do not combine with buyer. buyerId or buyer is required (except corrections, which take the buyer from the corrected invoice).", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "buyer": { "$ref": "#/components/schemas/ClientReference" }, "receiverId": { "type": "string", "description": "ID of an optional receiver (for invoices with multiple parties)." }, "receiver": { "$ref": "#/components/schemas/ClientReference" }, "products": { "type": "array", "description": "Document lines. Corrections: the full list of lines AFTER the correction (document totals are the difference to the corrected invoice). FakturaZaliczka: omit, the lines are the split of the advance over the order's VAT rates.", "items": { "type": "object", "required": [ "name", "unitOfMeasure", "quantity" ], "properties": { "name": { "type": "string", "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true, "enum": [ "GTU_01", "GTU_02", "GTU_03", "GTU_04", "GTU_05", "GTU_06", "GTU_07", "GTU_08", "GTU_09", "GTU_10", "GTU_11", "GTU_12", "GTU_13", null ], "description": "GTU code (optional)" }, "pkwiu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "example": "szt." }, "quantity": { "type": "number", "example": 1 }, "netPrice": { "type": "number", "nullable": true, "description": "Net unit price. When provided, netValue/amountOfVat/grossValue are calculated automatically.", "example": 100 }, "grossPrice": { "type": "number", "nullable": true, "description": "Gross unit price (alternative to netPrice).", "example": 123 }, "netValue": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 100 }, "grossValue": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 123 }, "amountOfVat": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 23 }, "vatRate": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 23, "description": "VAT rate from the AppData.VatRates dictionary. Validated by the backend, which also sets taxSymbol. Missing = the account's default rate (settings.defaultTaxRate). \"marza\" = a margin-scheme line (Articles 119 and 120 of the VAT Act): send grossPrice; the invoice shows gross amounts only and KSeF gets the total in P_13_11. Requires annotations.marginProcedure (otherwise 422 MARGIN_LINE_WITHOUT_PROCEDURE)." }, "marginPurchaseValue": { "type": "number", "nullable": true, "minimum": 0, "description": "vatRate \"marza\" only: gross purchase amount of the whole line in PLN (second-hand goods: the purchase price; travel agency: the costs of services bought for the tourist). It never appears on the invoice or in KSeF; it gives the margin and the VAT on the margin in the VAT register and JPK. Missing = to be added later. Left out on a correction: taken from the corrected line with the same name, in proportion to the quantity.", "example": 3000 }, "marginTaxRate": { "type": "number", "nullable": true, "enum": [ 23, 8, 5, 0, null ], "description": "vatRate \"marza\" only: rate of the VAT on the margin (VAT = margin × rate / (100 + rate); a negative margin = VAT 0). Default 23.", "example": 23 }, "discount": { "type": "number", "example": 0 }, "currency": { "type": "string", "example": "PLN" } } } }, "useAccountDefaults": { "type": "boolean", "description": "Defaults to true: missing fields get the account's settings like a new document in the app (comments, signatures, place of issue, automatic annotations MPP/margin with the VAT account, exemption basis for the zw rate, payment method and status, line VAT rate). A field you send always wins. false = no account defaults. A correction still takes the buyer, receiver, currency and annotations from the corrected invoice when you do not send them.", "example": true }, "currency": { "type": "string", "description": "Document currency (ISO 4217)", "example": "PLN" }, "exchangeRate": { "type": "number", "description": "Exchange rate for foreign currencies" }, "issuePlace": { "type": "string", "description": "Place of issue", "example": "Warszawa" }, "comments": { "type": "string", "description": "Document notes" }, "paymentDescription": { "type": "string", "description": "Payment description" }, "showPaymentSection": { "type": "boolean", "description": "Whether to show the payment section on the document/PDF. For Zamowienie documents it can be set to false." }, "paymentDeadlineDate": { "type": "string", "format": "date", "description": "Payment due date (required when paymentStatusId=1). Ignored for the Zapłacono (paid) status." }, "additionalPaymentDate": { "type": "string", "format": "date", "description": "Payment received date (required when paymentStatusId=0). Ignored for the Do zapłaty (to be paid) status." }, "additionalPaymentDateHeaderId": { "type": "number", "description": "Payment date header ID from the paymentDateHeaders dictionary. For paymentStatusId=0 the default is id=2 (\"Data otrzymania zapłaty\").", "example": 2 }, "subDate": { "type": "string", "format": "date", "description": "Sale / service date. For KSeF invoices and Zamowienie documents, issueDate is used by default if not provided." }, "subDateHeaderId": { "type": "number", "description": "Sale date header ID from the additionalDateHeaders dictionary (e.g. 1 => \"Data wykonania usługi\").", "example": 1 }, "subDateTo": { "type": "string", "format": "date", "nullable": true, "description": "End of the sale period (KSeF OkresFa, P_6_Do). With it, subDate is the start of the period, e.g. a service for a whole month. Without it, subDate is a single sale date (P_6). A correction without subDate takes the sale date or period of the corrected invoice." }, "taxPointRule": { "type": "string", "nullable": true, "enum": [ "art19a5p3a", "art19a5p3b", "art19a5p3c", "art19a5p4", null ], "description": "Tax point at the issue of the invoice (art. 19a ust. 5 of the VAT Act): art19a5p3a construction services (at the latest the 30th day after completion), art19a5p3b supply of books and press (60th day), art19a5p3c printing of books and press (90th day), art19a5p4 utilities, telecommunications, rent, lease, leasing, security, ongoing legal and office services (at the latest when the payment is due). Not sent to KSeF; it decides the period in VAT reports and the day of the exchange rate. null = the usual rules (the sale date)." }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true, "description": "Day of the NBP table exchangeRate comes from. Under art. 31a of the VAT Act it is the last business day before the tax point (usually before the sale date), or before the issue date when the invoice comes first. A correction without exchangeRate takes the rate, its day and table from the corrected invoice (art. 31b ust. 1)." }, "exchangeRateTable": { "type": "string", "nullable": true, "maxLength": 32, "example": "190/A/NBP/2026", "description": "NBP table number of exchangeRate, printed on the PDF next to the rate." }, "paymentInstallments": { "type": "array", "maxItems": 100, "description": "Instalments with custom amounts (e.g. a larger first instalment): at least two due dates with amounts (KSeF TerminPlatnosci; the instalment amounts go to DodatkowyOpis). Only with paymentStatusId=1; the instalments must add up to the amount due to the grosz, the dates must be in order and not before the issue date. Without paymentDeadlineDate the first instalment is the document's payment deadline. For equal instalments send paymentInstallmentsSplit instead of computing the amounts (do not combine the two fields).", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-10-20" }, "amount": { "type": "number", "example": 615 } } } }, "paymentInstallmentsSplit": { "type": "object", "nullable": true, "required": [ "count" ], "description": "Equal instalments computed by the API: recommended whenever the instalments should be equal. Send the number of instalments; once the document totals are computed the API splits the amount due to the grosz: every instalment gets the same amount and the rounding remainder goes to the last one (100.00 in 3 instalments = 33.33 + 33.33 + 33.34). The document stores ordinary paymentInstallments (returned in the response and in the preview) and its payment deadline (paymentDeadlineDate) is the date of the first instalment. Only with paymentStatusId=1; on create without paymentStatusId the document becomes unpaid (to pay). Instalments with different amounts (e.g. a larger first instalment) go in paymentInstallments; do not combine the two fields. A PATCH without products splits the amount stored in the document. Errors: 422 PAYMENT_INSTALLMENTS_INVALID. null = no split.", "properties": { "count": { "type": "integer", "minimum": 2, "maximum": 100, "example": 3, "description": "Number of instalments, 2 to 100 (the KSeF limit)." }, "firstDate": { "type": "string", "format": "date", "example": "2026-10-21", "description": "Due date of the first instalment, not before the issue date. Defaults to paymentDeadlineDate from the request; on an update, the stored payment deadline of a document to pay; otherwise the issue date + 14 days." }, "every": { "type": "string", "enum": [ "month", "week", "14days" ], "default": "month", "example": "month", "description": "Interval between instalments: month = monthly (counted from the first date: 31 Jan, 28 Feb, 31 Mar), week = every 7 days, 14days = every 14 days. Default: month." } } }, "paymentDeadlineTerm": { "type": "object", "nullable": true, "description": "Due date in words (KSeF TerminOpis), e.g. 14 days from the invoice date. Printed next to the due date.", "required": [ "count", "unit", "event" ], "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9999, "example": 14 }, "unit": { "type": "string", "enum": [ "day", "week", "month" ], "example": "day" }, "event": { "type": "string", "enum": [ "issue", "invoice_delivery", "supply", "acceptance" ], "example": "issue", "description": "What the term counts from: issue the issue of the invoice, invoice_delivery delivery of the invoice, supply the supply of goods or services, acceptance acceptance." } } }, "advanceReceipts": { "type": "array", "maxItems": 31, "description": "Advance invoice documenting several payments (KSeF ZaliczkaCzesciowa): at least two receipts dated no later than the issue date and adding up to advancePaymentAmount, with paymentStatusId=0. In a foreign currency each receipt has its own rate from the business day before it arrived (art. 31a). Each receipt is a separate tax point in VAT reports. Ignored for other document types.", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-10" }, "amount": { "type": "number", "example": 500 }, "exchangeRate": { "type": "number", "nullable": true, "example": 4.4512 }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true, "example": "2026-09-09" } } } }, "bankAccounts": { "type": "array", "description": "Bank accounts to show on the document. The first account goes to bankAccountNumber, the rest to 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 } } } }, "vatAccountNumber": { "type": "string", "description": "VAT account number (split payment / MPP)." }, "vatAccountBank": { "type": "string", "description": "Bank name of the VAT account." }, "vatAccountSwift": { "type": "string", "description": "SWIFT code of the VAT account." }, "vatAccountDescription": { "type": "string", "description": "VAT account description." }, "paymentMethodId": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Payment method ID: 1=Cash, 2=Card, 3=Voucher, 4=Check, 5=Credit, 6=Bank transfer, 7=Mobile payment", "example": 6 }, "paymentStatusId": { "type": "integer", "enum": [ 0, 1 ], "description": "0=Paid (requires additionalPaymentDate or partialPayments), 1=Due (requires paymentDeadlineDate)", "example": 1 }, "partialPayments": { "type": "array", "maxItems": 100, "description": "Partial payments made by the issue date (KSeF ZaplataCzesciowa). With paymentStatusId=1 their sum must be lower than the amount due. With paymentStatusId=0 at least two payments summing to the amount due. A payment date cannot be later than the issue date.", "items": { "type": "object", "required": [ "amount", "date" ], "properties": { "amount": { "type": "number", "example": 500 }, "date": { "type": "string", "format": "date", "example": "2026-09-14" }, "paymentMethodId": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "nullable": true, "description": "Payment form as paymentMethodId; absent = not given", "example": 1 } } } }, "annotations": { "$ref": "#/components/schemas/AnnotationsInput" }, "additionalInfo": { "$ref": "#/components/schemas/AdditionalInfoInput" }, "linkedOrderId": { "type": "string", "description": "Order ID (required for FakturaZaliczka)" }, "advancePaymentAmount": { "type": "number", "minimum": 0.01, "description": "Advance payment amount (required for FakturaZaliczka)" }, "correctedInvoiceId": { "type": "string", "description": "ID of the corrected invoice (required for FakturaKorygujaca, FakturaKorygujacaZaliczkowa and FakturaKorygujacaRozliczeniowa). When you do not send the buyer, receiver, currency or annotations, the correction takes them from this invoice." }, "correctionReason": { "type": "string", "maxLength": 256, "description": "Correction reason: the description printed on the PDF and sent to KSeF (PrzyczynaKorekty). Optional, at most 256 characters (KSeF limit)." }, "correctionCause": { "type": "string", "nullable": true, "enum": [ "after_sale", "mistake", null ], "example": "after_sale", "description": "Cause of the correction: after_sale (an event after the sale: discount, return of goods, complaint, price or quantity changed after the sale) or mistake (an error on the corrected invoice). Sets the TypKorekty sent to KSeF when you leave out correctionType, and the period in which the correction enters the VAT and KPiR reports. Without a cause the correction goes to KSeF with TypKorekty 2, as before. Applies to correcting invoices only; for other types the field is ignored." }, "correctionType": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, null ], "example": 1, "description": "KSeF TypKorekty set by hand: 1 = effect on the date the original invoice was recorded, 2 = on the issue date of the correcting invoice, 3 = on another date. Leave it out and Fakturnia works it out when sending: after_sale or no cause gives 2; mistake gives 1 when the correction raises the amounts, does not change them or takes the whole invoice to zero (wrong buyer, duplicate), 2 when it lowers them, and 3 when it raises one rate and lowers another. Applies to correcting invoices only." }, "correctionEffectDate": { "type": "string", "format": "date", "nullable": true, "description": "Corrections: the day the correction takes effect for VAT when it is neither the date of the corrected invoice nor the date of the correction. For an increase after the sale (after_sale) it is the day the cause arose, e.g. a price rise was agreed (art. 29a ust. 17); in another month than the correction it gives TypKorekty 3. With correctionType=3 set by hand it is the day of the effect. KSeF has no field for it; the VAT report and JPK place the correction on this day." }, "correctionConfirmationDate": { "type": "string", "format": "date", "nullable": true, "description": "Decreasing corrections issued outside KSeF: the day the buyer's confirmation of receipt arrived. Under art. 29a ust. 13a the decrease counts in the period the confirmation arrived in, and the VAT report places it there." }, "linkedAdvanceInvoiceIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of advance invoices to settle (required for FakturaRozliczeniowa)" }, "prepaymentIds": { "type": "array", "items": { "type": "string" } }, "settlementAmount": { "type": "number", "description": "Settlement amount (FakturaRozliczeniowa). Passed through without automatic calculations." }, "isSettlementAmountManual": { "type": "boolean", "description": "Whether settlementAmount was provided manually." }, "correctionAdvanceAmountAfter": { "type": "number", "description": "Advance payment amount AFTER the correction (FakturaKorygujacaZaliczkowa)." }, "correctionSettlementAmountAfter": { "type": "number", "description": "Settlement amount AFTER the correction (FakturaKorygujacaRozliczeniowa)." }, "signatures": { "type": "object", "description": "Signatures on the PDF (person authorized to issue/receive the document).", "properties": { "issuerSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } }, "receiverSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } } } }, "ksefJst": { "type": "boolean", "description": "Whether the document is for a JST entity (Polish local government unit)" } } }, "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": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CompanyExternal" } ], "description": "Receiver (Podmiot3); null when the document has no receiver." }, "hasReceiver": { "type": "boolean", "example": false }, "totals": { "type": "object", "properties": { "netSum": { "type": "number", "example": 100, "description": "Sum of the lines' net. A margin-scheme line (vatRate \"marza\") has no net and counts here with its gross: the net of the ordinary rates is netSum − marginSaleSum." }, "vatSum": { "type": "number", "example": 23 }, "grossSum": { "type": "number", "example": 123 }, "marginSaleSum": { "type": "number", "example": 0, "description": "Margin-scheme sale inside netSum (KSeF P_13_11, gross, no VAT on the invoice); 0 without \"marza\" lines." } } }, "receivedPayment": { "type": "string", "example": "NOT_RECEIVED" }, "bankAccount": { "type": "object", "nullable": true, "description": "Seller bank account that will be printed on the document (the default account for transfers); null when none applies.", "properties": { "accountNumber": { "type": "string", "example": "61 1090 1014 0000 0712 1981 2874" }, "bank": { "type": "string", "example": "mBank" } } }, "paymentInstallments": { "type": "array", "nullable": true, "description": "Instalments that will be saved: as sent in paymentInstallments or computed from paymentInstallmentsSplit; null for a single due date.", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2026-10-21" }, "amount": { "type": "number", "example": 410 } } } }, "warnings": { "type": "array", "description": "Notes that do not stop the document; show them to the user. A correction whose original invoice has no KSeF number (on accounts connected to KSeF) gets one: CORRECTION_ORIGINAL_KSEF_PENDING (the original waits for its KSeF number), CORRECTION_ORIGINAL_NOT_SENT_TO_KSEF (the original is issued today and not sent: send it first) or CORRECTION_ORIGINAL_OUTSIDE_KSEF (the original can no longer go to KSeF). Without the number the correction goes to KSeF as a correction of an invoice issued outside KSeF. Empty when there is nothing to note.", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "CORRECTION_ORIGINAL_NOT_SENT_TO_KSEF" }, "message": { "type": "string", "example": "Faktura FV/1/10/2026 nie została wysłana do KSeF. Wyślij najpierw fakturę, a potem korektę." } } }, "example": [] } } }, "valid": { "type": "boolean", "example": true }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PartyIdentifierWarning" }, "description": "How the contractor identifiers were read (an empty list when they were sent explicitly and correctly)." } } } } } ] }, "ErrorResponse": { "type": "object", "description": "Error envelope. `message` is a stable code (branch on it), `errors` carries the details: per-field objects or explanatory sentences.", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true, "example": null }, "message": { "type": "string", "nullable": true, "example": "VALIDATION_ERROR", "description": "Error code, e.g. VALIDATION_ERROR, NOT_FOUND, SUBSCRIPTION_REQUIRED." }, "executionTime": { "type": "number", "nullable": true, "example": 50 }, "errors": { "type": "array", "nullable": true, "items": { "oneOf": [ { "type": "string", "description": "Explanatory sentence (errors without a field)." }, { "type": "object", "description": "Error attached to a field.", "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" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PartyIdentifierWarning" }, "description": "How the contractor identifiers were read (an empty list when they were sent explicitly and correctly)." } } } } } ] }, "DictionariesResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentTypes": { "type": "array", "description": "Types supported by the External API (legacy types excluded).", "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": "VAT rates: the value on the form (value), the label (label) and a description. 0% KR/WDT/EX are different rates.", "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": "Tax exempt" }, { "value": "0 WDT", "label": "0% - WDT", "description": "0% for intra-community supply of goods (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 } } } }, "countries": { "type": "array", "description": "Country codes (ISO 3166-1 alpha-2) and names. Send countryCode in the document.", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "PL" }, "name": { "type": "string", "example": "Polska" } } } }, "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" }, "source": { "type": "string", "enum": [ "local", "ksef" ], "example": "local", "description": "local = issued in Fakturnia (app, API, MCP, recurring rule); ksef = downloaded from KSeF (event document.ksefImported)." }, "direction": { "type": "string", "enum": [ "income", "expense", "order" ], "example": "income", "description": "income = sale, expense = purchase (e.g. a supplier invoice downloaded from KSeF), order = order or offer." }, "issueDate": { "type": "string", "nullable": true, "example": "2026-05-07" }, "issuePlace": { "type": "string", "nullable": true, "example": "Warszawa" }, "subDate": { "type": "string", "nullable": true }, "subDateTo": { "type": "string", "format": "date", "nullable": true, "description": "End of the sale period (KSeF OkresFa P_6_Do); null for a single sale date." }, "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": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CompanyExternal" } ], "description": "Receiver (Podmiot3); null when the document has no receiver." }, "grossSum": { "type": "number", "nullable": true, "example": 123 }, "currency": { "type": "string", "nullable": true, "example": "PLN" }, "exchangeRate": { "type": "number", "nullable": true }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true, "description": "NBP table day of exchangeRate (art. 31a of the VAT Act)." }, "exchangeRateTable": { "type": "string", "nullable": true, "description": "NBP table number of exchangeRate." }, "taxPointRule": { "type": "string", "nullable": true, "enum": [ "art19a5p3a", "art19a5p3b", "art19a5p3c", "art19a5p4", null ], "description": "Tax point at the issue of the invoice (art. 19a ust. 5 pkt 3 and 4); null = the usual rules." }, "paymentInstallments": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "amount": { "type": "number" } } }, "description": "Instalments (KSeF TerminPlatnosci); [] = one due date." }, "paymentDeadlineTerm": { "type": "object", "nullable": true, "properties": { "count": { "type": "integer" }, "unit": { "type": "string", "enum": [ "day", "week", "month" ] }, "event": { "type": "string", "enum": [ "issue", "invoice_delivery", "supply", "acceptance" ] } }, "description": "The due date in words (KSeF TerminOpis)." }, "advanceReceipts": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "amount": { "type": "number" }, "exchangeRate": { "type": "number", "nullable": true }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true } } }, "description": "Several advances on an advance invoice (KSeF ZaliczkaCzesciowa); [] = one receipt date." }, "prepaymentIds": { "type": "array", "nullable": true }, "correctedInvoiceId": { "type": "string", "nullable": true }, "externalSource": { "type": "string", "nullable": true, "example": "woocommerce", "description": "Identifier of the source system (e.g. woocommerce, shopify, erp)." }, "externalOrderId": { "type": "string", "nullable": true, "example": "10234", "description": "Order identifier in the source system." }, "externalOrderNumber": { "type": "string", "nullable": true, "example": "#10234", "description": "Order number shown to the user (optional)." }, "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": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 23, "description": "A number or a special code (zw, np I, oo, 0 KR, 0 WDT, 0 EX, marza)." }, "taxSymbol": { "type": "string", "nullable": true, "example": "%" }, "pkwiu": { "type": "string", "nullable": true }, "marginPurchaseValue": { "type": "number", "nullable": true, "description": "vatRate \"marza\" only: purchase amount of the line in PLN (the seller's data, not on the invoice)." }, "marginTaxRate": { "type": "number", "nullable": true, "description": "vatRate \"marza\" only: rate of the VAT on the margin (23, 8, 5, 0)." } } } }, "payment": { "type": "object", "nullable": true, "properties": { "method": { "type": "integer", "nullable": true, "description": "KSeF FormaPlatnosci: 1=Cash, 2=Card, 3=Voucher, 4=Check, 5=Credit, 6=Bank transfer, 7=Mobile payment", "example": 6 }, "status": { "type": "integer", "nullable": true, "description": "0=Paid, 1=To be paid", "example": 1 }, "bankAccountNumber": { "type": "string", "nullable": true, "example": "1212 1212 1212 1212 1212 1212" }, "partialPayments": { "type": "array", "description": "Partial payments made by the issue date (KSeF ZaplataCzesciowa); an empty list when there are none", "items": { "type": "object", "properties": { "amount": { "type": "number", "example": 500 }, "date": { "type": "string", "format": "date", "example": "2026-09-14" }, "paymentMethodId": { "type": "integer", "nullable": true, "description": "KSeF FormaPlatnosci 1-7; null = not given", "example": 1 } } } }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid according to the invoice: the whole amount with status=0, the sum of partial payments with status=1", "example": 500 }, "amountDue": { "type": "number", "nullable": true, "description": "Amount still due according to the invoice (payments registered after issue are not included)", "example": 730 }, "receivedPayment": { "type": "string", "enum": [ "RECEIVED", "NOT_RECEIVED" ], "description": "Payment registered after issue (PATCH /documents/{id}/payment-status or \"Payment received\" in the app), independent of the invoice content", "example": "NOT_RECEIVED" }, "receivedPaymentAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the payment was registered as received (null when it was not registered)", "example": null }, "receivedPaymentDate": { "type": "string", "format": "date", "nullable": true, "description": "Day the payment arrived, given when marking the payment (for the cash method the day of the tax point); null when not given", "example": null }, "settled": { "type": "boolean", "nullable": true, "description": "Whether the document is settled: status \"Paid\" or a registered payment (receivedPayment=RECEIVED); null for documents without a payment status", "example": false }, "outstandingAmount": { "type": "number", "nullable": true, "description": "Amount still to pay today: 0 for a settled document, otherwise amountDue", "example": 730 } } }, "comments": { "type": "string", "nullable": true }, "marginProcedureId": { "type": "integer", "nullable": true }, "vatAccountNumber": { "type": "string", "nullable": true }, "netSum": { "type": "number", "nullable": true, "example": 100, "description": "Sum of the lines' net. A margin-scheme line (vatRate \"marza\") has no net and counts here with its gross (KSeF reports it apart, in P_13_11): subtract the gross of the \"marza\" lines for the net of the ordinary rates." }, "vatSum": { "type": "number", "nullable": true, "example": 23 }, "annotations": { "type": "object", "nullable": true, "description": "KSeF annotations of the document (MPP, reverse charge, cash method, self-invoicing, margin procedure, VAT exemption); null when none.", "properties": { "isSplitPayment": { "type": "boolean" }, "isReverseCharge": { "type": "boolean" }, "isCashMethod": { "type": "boolean" }, "isSelfInvoicing": { "type": "boolean" }, "marginProcedure": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "procedureId": { "type": "integer", "nullable": true } } }, "vatExemption": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "exemptionType": { "type": "string", "nullable": true }, "legalBasis": { "type": "string", "nullable": true }, "showOnDocument": { "type": "boolean" } } } } }, "additionalInfo": { "type": "object", "nullable": true, "properties": { "isInvoiceToReceipt": { "type": "boolean" } } }, "correctionReason": { "type": "string", "nullable": true, "description": "Corrections: the reason printed on the PDF and sent to KSeF (PrzyczynaKorekty)." }, "correctionCause": { "type": "string", "nullable": true, "enum": [ "after_sale", "mistake", null ], "example": "after_sale", "description": "Corrections: why the correction was issued. after_sale = an event after the sale (discount, return, complaint, price or quantity changed later), mistake = an error on the corrected invoice. null when not given." }, "correctionType": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, null ], "example": null, "description": "Corrections: KSeF TypKorekty set by hand (1 = effect on the date of the corrected invoice, 2 = on the issue date of the correction, 3 = on another date). null = derived from correctionCause and the amounts when the correction is sent to KSeF." }, "correctionEffectDate": { "type": "string", "format": "date", "nullable": true, "description": "Corrections: the day the correction takes effect (the cause of an increase, art. 29a ust. 17, or a TypKorekty 3 set by hand)." }, "correctionConfirmationDate": { "type": "string", "format": "date", "nullable": true, "description": "Corrections issued outside KSeF: the day the buyer confirmed receiving a decreasing correction (art. 29a ust. 13a)." }, "isDraft": { "type": "boolean", "description": "A draft saved in the app, not issued yet. Issuing it sets false and sends the document.updated webhook.", "example": false }, "correctionAdvanceAmountAfter": { "type": "number", "nullable": true, "description": "Advance invoice correction: the advance amount after the correction." }, "correctionSettlementAmountAfter": { "type": "number", "nullable": true, "description": "Settlement invoice correction: the settlement amount after the correction." }, "invoiceName": { "type": "string", "nullable": true, "example": "Faktura zaliczkowa", "description": "Invoice name (e.g. for advance invoices)" }, "isCorrected": { "type": "boolean", "description": "A correction of this document exists: edit and delete are locked.", "example": false }, "linkedOrderId": { "type": "string", "nullable": true, "description": "FakturaZaliczka: the order the advance is for." }, "advancePaymentAmount": { "type": "number", "nullable": true }, "linkedAdvanceInvoiceIds": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "FakturaRozliczeniowa: settled advance invoices." }, "linkedDocuments": { "type": "array", "description": "Linked documents: wz_to_invoice (WZ issued for this invoice), invoice_to_wz (the invoice of this WZ), correction, order_to_invoice, prepayment.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "relation": { "type": "string", "enum": [ "correction", "wz_to_invoice", "order_to_invoice", "prepayment", "invoice_to_wz" ] }, "documentNumber": { "type": "string", "nullable": true, "example": "WZ1/09/2026" } } } }, "settlementAmount": { "type": "number", "nullable": true, "description": "FakturaRozliczeniowa: amount left to pay after the advances." }, "warehouseId": { "type": "string", "nullable": true }, "warehouseName": { "type": "string", "nullable": true }, "sourceWarehouseId": { "type": "string", "nullable": true }, "targetWarehouseId": { "type": "string", "nullable": true }, "stockStatus": { "type": "string", "nullable": true, "description": "Warehouse documents: posted or pending." }, "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 }, "ksefNumber": { "type": "string", "nullable": true, "example": "5271012345-20260926-AABBCCDDEEFF-01" }, "ksefReferenceNumber": { "type": "string", "nullable": true }, "ksefStatus": { "type": "object", "nullable": true, "description": "Last status from KSeF.", "properties": { "code": { "type": "integer", "example": 200 }, "description": { "type": "string", "example": "Przyjęto" }, "details": { "type": "array", "items": { "type": "string" }, "example": [] } } }, "ksefSent": { "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": "5261040828" }, "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, "description": "PESEL. For the seller returned only when the document prints it (fieldsToShow contains pesel)." }, "idNumber": { "type": "string", "nullable": true, "description": "ID card number. For the seller returned only when the document prints it (fieldsToShow contains idNumber)." }, "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", "description": "Contractor given as data (buyer or receiver). A saved contractor with this NIP or VAT UE number is taken from the contractor list; a new one is added to the contractors.", "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": "5261040828", "description": "Polish NIP (identifierType=nip): 10 digits; spaces, dashes and the PL prefix are removed, the check digit is verified. Do not put a foreign VAT number here: give an EU VAT number in vatUE." }, "vatUE": { "type": "string", "nullable": true, "example": "DE123456789", "description": "EU VAT number with its country prefix, e.g. DE123456789, ATU12345678, EL123456789 (Greece). Stored in uppercase without spaces; a number without a prefix gets the prefix from countryCode. A Polish company with identifierType=nip may have PL and the same NIP here (intra-EU supply)." }, "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, "enum": [ "nip", "vatEu", "other", "idWew", "none", null ], "example": "nip", "description": "Which identifier identifies the contractor in KSeF. nip: a Polish company, nip = 10 digits, e.g. 5261040828 (spaces, dashes and the PL prefix are removed, the check digit is verified). vatEu: an EU contractor, the VAT UE number with its country prefix in vatUE, e.g. a contractor from Germany: identifierType=vatEu, vatUE=DE123456789 (Greece has the EL prefix; Northern Ireland XI is not an EU country in KSeF, send it as other). other: a contractor outside the EU (or from the EU without a VAT UE number), the country and the identifier, e.g. identifierType=other, countryCode=US, otherTaxIdentifier=12-3456789. idWew: receiver only, an internal unit of the buyer, idWew=NIP-NNNNN; a buyer with idWew is refused. none: a consumer or no identifier. Without identifierType the server infers the type from the data: a Polish NIP in nip is nip, a VAT UE number of an EU country (also one typed in nip) is vatEu and goes to vatUE, an identifier of a non-EU country is other, no identifier is none; the inferred type and every moved number are returned in data.warnings. Send identifierType explicitly. Contradictions: 422 PARTY_IDENTIFIER_INVALID naming the field (e.g. buyer.vatUE). A buyer given by buyerId is taken from the contractor list unchanged." }, "otherTaxIdentifier": { "type": "string", "nullable": true, "description": "Tax identifier for identifierType=other (KSeF NrID), e.g. 12-3456789 for a US company; at most 50 characters, requires countryCode." }, "idWew": { "type": "string", "nullable": true, "description": "Internal unit identifier for identifierType=idWew: NIP-NNNNN (10-digit NIP, a dash, 5 digits), e.g. 5252248481-16006." }, "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, "description": "ISO 3166-1 alpha-2 country code, e.g. PL, DE, GR. For vatEu without countryCode it is taken from the prefix of the VAT UE number." }, "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. Mutually exclusive with isCashMethod.", "example": false }, "isReverseCharge": { "type": "boolean", "description": "Reverse charge" }, "isCashMethod": { "type": "boolean", "description": "Cash method. Mutually exclusive with isSplitPayment.", "example": false }, "isSelfInvoicing": { "type": "boolean", "description": "Self-billing" }, "marginProcedure": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "procedureId": { "type": "integer", "minimum": 1, "maximum": 4, "description": "Margin procedure ID (1-4): 1 travel agencies, 2 second-hand goods, 3 works of art, 4 collectibles and antiques", "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 } } } } }, "AdditionalInfoInput": { "type": "object", "description": "Additional document information: the KSeF FA(3) \"Additional information\" section (separate from annotations).", "properties": { "isInvoiceToReceipt": { "type": "boolean", "description": "Invoice issued to a receipt (art. 109(3d) of the Polish VAT Act). When `true`, the `1` flag is set in the KSeF submission and a corresponding annotation appears on the PDF. RodzajFaktury stays unchanged (e.g. VAT).", "example": true } } }, "DocumentListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentExternal" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." } } } } } ] }, "DeletedResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e", "description": "Id of the deleted resource." } } } } } ] }, "DocumentHistoryEntry": { "type": "object", "description": "Entry of the document journal.", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "type": { "type": "string", "example": "PAYMENT_RECEIVED", "description": "CREATE, UPDATE, DELETE, SENT_BY_EMAIL, DOWNLOAD, DOWNLOAD_XML, DOWNLOAD_UPO, PRINT, KSEF_SENT, KSEF_ERROR, PAYMENT_RECEIVED, PAYMENT_REVERTED, ADVANCE_INVOICE_LINKED, ADVANCE_INVOICE_UNLINKED, SETTLEMENT_INVOICE_LINKED, SETTLEMENT_INVOICE_UNLINKED, DOWNLOAD_CLIENT." }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "actor": { "type": "string", "enum": [ "owner", "employee" ], "example": "owner" }, "employeeId": { "type": "string", "nullable": true }, "employeeName": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true, "enum": [ "external_api", "app", "import", null ], "example": "external_api", "description": "Where the action came from, when the entry records it." }, "channel": { "type": "string", "nullable": true, "enum": [ "mcp", null ], "example": "mcp", "description": "mcp when the action was taken by an AI assistant through the MCP server." }, "channelLabel": { "type": "string", "nullable": true, "example": "Claude", "description": "Name of the assistant credential (e.g. Claude, ChatGPT or the key label)." }, "changes": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Field diff of an UPDATE (field, value before and after)." }, "data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Entry details (e.g. the KSeF result, e-mail recipients)." } } }, "DocumentHistoryResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "documentNumber": { "type": "string", "nullable": true, "example": "FV/12/09/2026" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentHistoryEntry" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." } } } } } ] }, "PaymentStatusInput": { "type": "object", "required": [ "receivedPayment" ], "properties": { "receivedPayment": { "type": "string", "enum": [ "RECEIVED", "NOT_RECEIVED" ], "description": "RECEIVED marks the document as paid, NOT_RECEIVED reverts the mark." }, "paymentDate": { "type": "string", "format": "date", "description": "Day the payment arrived (YYYY-MM-DD), only with RECEIVED. Defaults to today in Poland; it cannot be in the future. For the cash method it is the day of the tax point (art. 21 ust. 1 of the VAT Act)." } } }, "DocumentPaymentStatusResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Document marked as paid." }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "receivedPayment": { "type": "string", "enum": [ "RECEIVED", "NOT_RECEIVED" ], "example": "RECEIVED" }, "receivedPaymentAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z", "description": "When the payment was marked; null after a revert." }, "receivedPaymentDate": { "type": "string", "format": "date", "nullable": true, "example": "2026-05-10", "description": "Day of the payment given when marking it (by default the day of marking); null after undoing." } } } } } ] }, "ExternalReferenceInput": { "type": "object", "required": [ "externalSource", "externalOrderId" ], "properties": { "externalSource": { "type": "string", "example": "woocommerce", "description": "Identifier of the source system (e.g. woocommerce, shopify, erp)." }, "externalOrderId": { "type": "string", "example": "10234", "description": "Order identifier in the source system." }, "externalOrderNumber": { "type": "string", "example": "#10234", "description": "Order number shown to the user (optional)." } } }, "MarginPurchasesInput": { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "index" ], "properties": { "index": { "type": "integer", "minimum": 0, "example": 0, "description": "Position in products (from 0); the line must have vatRate \"marza\"." }, "marginPurchaseValue": { "type": "number", "nullable": true, "minimum": 0, "example": 1500, "description": "Gross purchase amount of the whole line in PLN; null clears it, a missing key keeps it." }, "marginTaxRate": { "type": "number", "nullable": true, "enum": [ 23, 8, 5, 0, null ], "example": 23, "description": "Rate of the VAT on the margin; a missing key keeps it, null = 23." } } } } } }, "DocumentMarginPurchasesResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Margin purchase amounts saved." }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "products": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "example": 0 }, "marginPurchaseValue": { "type": "number", "nullable": true, "example": 1500 }, "marginTaxRate": { "type": "number", "nullable": true, "example": 23 } } } } } } } } ] }, "DocumentExternalReferenceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "External reference updated." }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "externalSource": { "type": "string", "nullable": true, "example": "woocommerce" }, "externalOrderId": { "type": "string", "nullable": true, "example": "10234" }, "externalOrderNumber": { "type": "string", "nullable": true, "example": "#10234" } } } } } ] }, "KsefSendResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "description": "Two shapes: accepted right away (ksefNumber present) or still processing (status = \"processing\").", "properties": { "data": { "type": "object", "properties": { "ksefNumber": { "type": "string", "nullable": true, "example": "5271012345-20260926-AABBCCDDEEFF-01", "description": "KSeF number when the invoice was accepted within the waiting window. Absent = processing status." }, "referenceNumber": { "type": "string", "nullable": true, "example": "20260926-SE-AABBCCDDEE-112233445566-01" }, "invoiceNumber": { "type": "string", "nullable": true, "example": "FV/1/09/2026" }, "ordinalNumber": { "type": "integer", "nullable": true, "example": 1 }, "status": { "oneOf": [ { "type": "string", "enum": [ "processing" ], "description": "KSeF is still processing the invoice: poll GET /documents/{id}/ksef-status or wait for the document.sentToKSeF / document.ksefRejected webhook." }, { "type": "object", "nullable": true, "description": "Last status from KSeF.", "properties": { "code": { "type": "integer", "example": 200 }, "description": { "type": "string", "example": "Przyjęto" }, "details": { "type": "array", "items": { "type": "string" }, "example": [] } } } ], "example": { "code": 200, "description": "Accepted", "details": [] } }, "sessionReferenceNumber": { "type": "string", "nullable": true }, "invoiceReferenceNumber": { "type": "string", "nullable": true }, "documentNumber": { "type": "string", "nullable": true, "example": "FV/1/09/2026" }, "hasUpo": { "type": "boolean", "example": true }, "sendMode": { "type": "string", "example": "instant" } } } } } ] }, "KsefStatusResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "documentNumber": { "type": "string", "example": "FV/1/09/2026" }, "state": { "type": "string", "enum": [ "not_sent", "processing", "sent", "failed" ], "example": "sent", "description": "sent and failed are final states." }, "ksefNumber": { "type": "string", "nullable": true, "example": "5271012345-20260926-AABBCCDDEEFF-01" }, "ksefReferenceNumber": { "type": "string", "nullable": true }, "ksefStatus": { "type": "object", "nullable": true, "description": "Last status from KSeF.", "properties": { "code": { "type": "integer", "example": 200 }, "description": { "type": "string", "example": "Przyjęto" }, "details": { "type": "array", "items": { "type": "string" }, "example": [] } } }, "lastError": { "type": "object", "nullable": true, "description": "Reason for the rejection (state = failed).", "properties": { "code": { "type": "integer", "example": 405 }, "message": { "type": "string", "example": "Błąd walidacji semantycznej" }, "timestamp": { "type": "string", "format": "date-time" }, "details": { "type": "array", "items": { "type": "string" } } } }, "sentAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "processedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } } } } ] }, "ClientExternal": { "type": "object", "description": "Contractor (buyer or supplier) stored in the address book.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "type": { "type": "string", "nullable": true, "enum": [ "company", "person", null ], "example": "company" }, "contractorType": { "type": "string", "nullable": true, "enum": [ "client", "supplier", null ], "example": "client" }, "name": { "type": "string", "nullable": true, "example": "Acme Sp. z o.o." }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "nip": { "type": "string", "nullable": true, "example": "5261040828" }, "vatUE": { "type": "string", "nullable": true }, "identifierType": { "type": "string", "nullable": true, "example": "nip" }, "otherTaxIdentifier": { "type": "string", "nullable": true }, "idWew": { "type": "string", "nullable": true }, "regon": { "type": "string", "nullable": true }, "krs": { "type": "string", "nullable": true }, "bdo": { "type": "string", "nullable": true }, "pesel": { "type": "string", "nullable": true }, "idNumber": { "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 }, "fax": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "emailAddresses": { "type": "array", "items": { "type": "string" } }, "www": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "fieldsToShow": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "ClientInput": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "company", "person" ], "description": "Kind of contractor: a company (name required) or a person (firstName and lastName required)." }, "contractorType": { "type": "string", "enum": [ "client", "supplier" ], "description": "Role: buyer (client, default) or supplier." }, "identifierType": { "type": "string", "enum": [ "nip", "vatEu", "idWew", "other", "none" ], "description": "Which identifier identifies the contractor in KSeF. nip: a Polish company, nip = 10 digits, e.g. 5261040828 (spaces, dashes and the PL prefix are removed, the check digit is verified). vatEu: an EU contractor, the VAT UE number with its country prefix in vatUE, e.g. a contractor from Germany: identifierType=vatEu, vatUE=DE123456789 (Greece has the EL prefix; Northern Ireland XI is not an EU country in KSeF, send it as other). other: a contractor outside the EU (or from the EU without a VAT UE number), the country and the identifier, e.g. identifierType=other, countryCode=US, otherTaxIdentifier=12-3456789. idWew: an internal unit (e.g. a municipal kindergarten) used as the receiver of a document, idWew=NIP-NNNNN. none: a consumer or no identifier. Without identifierType the server infers the type from the data: a Polish NIP in nip is nip, a VAT UE number of an EU country (also one typed in nip) is vatEu and goes to vatUE, an identifier of a non-EU country is other, no identifier is none; the inferred type and every moved number are returned in data.warnings. Send identifierType explicitly. Contradictions (e.g. nip with a DE... number, vatEu with a PL... or XI... number, a NIP with a wrong check digit): 422 VALIDATION_ERROR naming the field.", "example": "nip" }, "name": { "type": "string", "description": "Company name (required for type=company).", "example": "Acme Sp. z o.o." }, "firstName": { "type": "string", "description": "First name (required for type=person)." }, "lastName": { "type": "string", "description": "Last name (required for type=person)." }, "nip": { "type": "string", "description": "Polish NIP (identifierType=nip): 10 digits; spaces, dashes and the PL prefix are removed, the check digit is verified. Do not put a foreign VAT number here: give an EU VAT number in vatUE.", "example": "5261040828" }, "vatUE": { "type": "string", "description": "EU VAT number with its country prefix, e.g. DE123456789, ATU12345678, EL123456789 (Greece). Stored in uppercase without spaces; a number without a prefix gets the prefix from countryCode. A Polish company with identifierType=nip may have PL and the same NIP here (intra-EU supply).", "example": "DE123456789" }, "idWew": { "type": "string", "description": "Internal unit identifier for identifierType=idWew: NIP-NNNNN (10-digit NIP, a dash, 5 digits), e.g. 5252248481-16006." }, "otherTaxIdentifier": { "type": "string", "description": "Tax identifier for identifierType=other (KSeF NrID), e.g. 12-3456789 for a US company; at most 50 characters, requires countryCode." }, "regon": { "type": "string" }, "krs": { "type": "string" }, "bdo": { "type": "string" }, "pesel": { "type": "string" }, "idNumber": { "type": "string", "description": "Identity document number (person)." }, "street": { "type": "string", "description": "Street with the building number.", "example": "Marszałkowska 1" }, "postalCode": { "type": "string", "example": "00-001" }, "city": { "type": "string", "example": "Warszawa" }, "country": { "type": "string", "description": "Country name, e.g. Polska.", "example": "Polska" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code, e.g. PL, DE, GR. For vatEu without countryCode it is taken from the prefix of the VAT UE number.", "example": "PL" }, "phoneNumber": { "type": "string" }, "fax": { "type": "string" }, "email": { "type": "string", "description": "Main e-mail address of the contractor (an invalid address: 422 naming the email field)." }, "www": { "type": "string" }, "description": { "type": "string", "description": "Internal note about the contractor." }, "emailAddresses": { "type": "array", "items": { "type": "string" }, "description": "Additional e-mail addresses for sending documents (an invalid address: 422 naming the emailAddresses field)." }, "fieldsToShow": { "type": "array", "items": { "type": "string" }, "description": "Extra fields printed on the document (e.g. regon, krs)." } }, "description": "Contractor data (create and full update)." }, "PartyIdentifierWarning": { "type": "object", "description": "How the contractor identifiers were read: the inferred identifierType, a moved number, the inferred country, EL instead of GR, an ignored field.", "properties": { "code": { "type": "string", "enum": [ "IDENTIFIER_TYPE_INFERRED", "IDENTIFIER_MOVED", "IDENTIFIER_IGNORED", "COUNTRY_CODE_INFERRED", "VAT_UE_PREFIX_NORMALIZED" ], "example": "IDENTIFIER_MOVED" }, "field": { "type": "string", "example": "buyer.vatUE", "description": "The field concerned (prefixed with buyer. or receiver. on documents)." }, "message": { "type": "string", "example": "Numer DE123456789 przeniesiono z pola nip do vatUE: pole nip jest tylko na polski NIP." } }, "required": [ "code", "field", "message" ] }, "ClientResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "client": { "$ref": "#/components/schemas/ClientExternal" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PartyIdentifierWarning" }, "description": "How the contractor identifiers were read (an empty list when they were sent explicitly and correctly)." } } } } } ] }, "ClientListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/ClientExternal" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." } } } } } ] }, "ProductExternal": { "type": "object", "description": "Product or service from the catalogue.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "name": { "type": "string", "nullable": true, "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true }, "pkwiu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "nullable": true, "example": "szt." }, "discount": { "type": "number", "nullable": true, "example": 0 }, "quantity": { "type": "number", "nullable": true, "example": 1 }, "netPrice": { "type": "number", "nullable": true, "example": 100 }, "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" } ], "nullable": true, "example": 23 }, "taxSymbol": { "type": "string", "nullable": true, "example": "%" }, "currency": { "type": "string", "nullable": true, "example": "PLN" }, "productType": { "type": "string", "enum": [ "goods", "service" ], "nullable": true, "example": "goods", "description": "goods = goods (tracked in stock), service = a service; null = a service (products created before the Warehouse module)." }, "sku": { "type": "string", "nullable": true }, "ean": { "type": "string", "nullable": true }, "purchasePrice": { "type": "number", "nullable": true, "description": "Net purchase price." }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "ProductInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the product or service.", "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true, "enum": [ "GTU_01", "GTU_02", "GTU_03", "GTU_04", "GTU_05", "GTU_06", "GTU_07", "GTU_08", "GTU_09", "GTU_10", "GTU_11", "GTU_12", "GTU_13", null ], "description": "GTU code (GTU_01 ... GTU_13) or empty." }, "pkwiu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "description": "Unit of measure, e.g. szt., godz., usł.", "example": "szt." }, "currency": { "type": "string", "example": "PLN" }, "quantity": { "type": "number", "example": 1 }, "netPrice": { "type": "number", "description": "Net unit price (before discount). Exactly one price is required: netPrice OR grossPrice; both at once = 422.", "example": 100 }, "grossPrice": { "type": "number", "description": "Gross unit price (before discount). Exactly one price is required: netPrice OR grossPrice; both at once = 422." }, "netValue": { "type": "number", "description": "Net value of the line (computed when omitted)." }, "grossValue": { "type": "number", "description": "Gross value of the line (computed when omitted)." }, "amountOfVat": { "type": "number", "description": "VAT amount (computed when omitted)." }, "vatRate": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "VAT rate: a number (23, 8, 5; foreign 19 outside KSeF) or a special code (zw, np I, oo, 0 WDT, 0 EX, 0 KR). Omitted: the account default rate (settings), as on document lines.", "example": 23 }, "discount": { "type": "number", "description": "Discount in percent (0-100), stored in the catalogue; the net value includes the discount.", "example": 0 }, "productType": { "type": "string", "enum": [ "goods", "service" ], "description": "Warehouse module: goods = goods (tracked in stock), service = a service. Missing = a service." }, "sku": { "type": "string", "description": "Stock keeping unit (SKU)." }, "ean": { "type": "string", "description": "EAN barcode." }, "purchasePrice": { "type": "number", "minimum": 0, "description": "Net purchase price: the default price of PZ/PW receipts." } }, "description": "Product data on create: name and one price (netPrice or grossPrice) are required; amounts are computed from the price, VAT rate and discount." }, "ProductUpdateInput": { "type": "object", "required": [ "name" ], "description": "Product data on update: a new price without values = recompute; values sent explicitly must add up (otherwise 422).", "properties": { "name": { "type": "string", "description": "Name of the product or service.", "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true, "enum": [ "GTU_01", "GTU_02", "GTU_03", "GTU_04", "GTU_05", "GTU_06", "GTU_07", "GTU_08", "GTU_09", "GTU_10", "GTU_11", "GTU_12", "GTU_13", null ], "description": "GTU code (GTU_01 ... GTU_13) or empty." }, "pkwiu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "description": "Unit of measure, e.g. szt., godz., usł.", "example": "szt." }, "taxSymbol": { "type": "string", "description": "VAT rate symbol, e.g. % or zw." }, "currency": { "type": "string", "example": "PLN" }, "quantity": { "type": "number", "example": 1 }, "netPrice": { "type": "number", "description": "Net unit price (before discount). Without netValue/amountOfVat/grossValue the values are recomputed." }, "netValue": { "type": "number", "description": "Net value; when sent explicitly it must match the price, rate and total (otherwise 422)." }, "grossValue": { "type": "number", "description": "Gross value; must equal netValue + amountOfVat." }, "amountOfVat": { "type": "number", "description": "VAT amount; must match the rate applied to the net value." }, "vatRate": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "VAT rate: a number (23, 8, 5; foreign 19 outside KSeF) or a special code (zw, np I, oo, 0 WDT, 0 EX, 0 KR)." }, "discount": { "type": "number", "description": "Discount in percent (0-100). Stored only when the field is in the request; a change recomputes the values." }, "productType": { "type": "string", "enum": [ "goods", "service" ], "description": "Warehouse module: goods or service. Saved only when the field is in the request." }, "sku": { "type": "string", "description": "Stock keeping unit (SKU)." }, "ean": { "type": "string", "description": "EAN barcode." }, "purchasePrice": { "type": "number", "minimum": 0, "description": "Net purchase price: the default price of PZ/PW receipts." } } }, "ProductResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductExternal" } } } } } ] }, "ProductListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductExternal" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." } } } } } ] }, "WarehouseExternal": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "name": { "type": "string", "nullable": true, "example": "Magazyn główny" }, "symbol": { "type": "string", "nullable": true, "example": "MAG1", "description": "Symbol used in the numbering of warehouse documents." }, "address": { "type": "string", "nullable": true, "example": "ul. Prosta 1, 00-001 Warszawa" }, "isDefault": { "type": "boolean", "example": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "WarehouseInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Magazyn główny" }, "symbol": { "type": "string", "example": "MAG1", "description": "Symbol used in the numbering of warehouse documents." }, "address": { "type": "string", "example": "ul. Prosta 1, 00-001 Warszawa" }, "isDefault": { "type": "boolean", "example": false } } }, "WarehouseResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "warehouse": { "$ref": "#/components/schemas/WarehouseExternal" } } } } } ] }, "StockMovementExternal": { "type": "object", "description": "Line of the stock ledger. Product level = sum of movements.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "productId": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d2a" }, "warehouseId": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d3b" }, "quantity": { "type": "number", "example": -2, "description": "Positive = receipt, negative = issue." }, "unitCost": { "type": "number", "nullable": true, "example": 12.5, "description": "Net unit cost (on receipts)." }, "type": { "type": "string", "nullable": true, "enum": [ "PZ", "WZ", "PW", "RW", "MM_OUT", "MM_IN", "INW", "WYCENA", null ], "example": "WZ" }, "documentId": { "type": "string", "nullable": true, "description": "Warehouse document the movement comes from (null for manual adjustments)." }, "documentNumber": { "type": "string", "nullable": true, "example": "WZ/3/09/2026" }, "date": { "type": "string", "nullable": true, "example": "2026-09-26", "description": "Movement date (YYYY-MM-DD)." }, "note": { "type": "string", "nullable": true }, "employeeId": { "type": "string", "nullable": true, "description": "Employee who recorded the movement; null for the owner." }, "employeeName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "StockMovementsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockMovementExternal" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." } } } } } ] }, "WarehouseListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "warehouses": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseExternal" } } } } } } ] }, "StockAdjustmentInput": { "type": "object", "required": [ "productId", "warehouseId", "quantity" ], "properties": { "productId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e", "description": "Id of a product from the catalogue." }, "warehouseId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "quantity": { "type": "number", "example": 25, "description": "Stock change: positive = receipt, negative = issue." }, "unitCost": { "type": "number", "nullable": true, "example": 12.5, "description": "Net unit cost (valuation basis for receipts)." }, "date": { "type": "string", "format": "date", "example": "2026-09-26", "description": "YYYY-MM-DD, today by default." }, "note": { "type": "string", "example": "Bilans otwarcia" } } }, "StockAdjustmentResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Stock adjustment recorded." }, "data": { "type": "object", "properties": { "movement": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "productId": { "type": "string" }, "warehouseId": { "type": "string" }, "quantity": { "type": "number", "example": 25 }, "unitCost": { "type": "number", "nullable": true, "example": 12.5 }, "type": { "type": "string", "example": "INW" }, "date": { "type": "string", "example": "2026-09-26" }, "note": { "type": "string", "nullable": true } } } } } } } ] }, "StockReportResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "levels": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "warehouseId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "quantity": { "type": "number", "example": 12 } } } }, "asOf": { "type": "string", "nullable": true, "example": null, "description": "Date of the historical report (YYYY-MM-DD) or null for the current level." } } } } } ] }, "WzFromInvoiceInput": { "type": "object", "properties": { "warehouseId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f", "description": "Warehouse the goods are issued from. Defaults to the default warehouse." }, "issueDate": { "type": "string", "format": "date", "description": "WZ issue date (YYYY-MM-DD). Defaults to the invoice issue date." }, "allowNegativeStock": { "type": "boolean", "description": "true = issue even when goods are missing (stock goes below zero). By default missing goods reject the WZ (422 STOCK_SHORTAGE)." } } }, "WzFromInvoiceResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "documentType": { "type": "string", "example": "WZ" }, "documentNumber": { "type": "string", "example": "WZ/3/09/2026" }, "warehouseId": { "type": "string" }, "grossSum": { "type": "number", "example": 1230 }, "linkedInvoiceId": { "type": "string" } } }, "skipped": { "type": "array", "description": "Invoice lines skipped on the WZ (services, products without a catalogue entry).", "items": { "type": "object", "additionalProperties": true } } } } } } ] }, "EmployeeExternal": { "type": "object", "description": "Employee account. Never contains the password.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "firstName": { "type": "string", "nullable": true, "example": "Jan" }, "lastName": { "type": "string", "nullable": true, "example": "Kowalski" }, "emailAddress": { "type": "string", "nullable": true, "example": "jan@firma.pl" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "documents:read", "documents:write" ] }, "isActive": { "type": "boolean", "example": true }, "lastLoginAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "EmployeeInput": { "type": "object", "required": [ "firstName", "lastName", "emailAddress", "password" ], "properties": { "firstName": { "type": "string", "example": "Jan" }, "lastName": { "type": "string", "example": "Kowalski" }, "emailAddress": { "type": "string", "format": "email", "example": "jan@firma.pl", "description": "Globally unique login e-mail." }, "password": { "type": "string", "minLength": 8, "description": "Minimum 8 characters." }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "documents:read", "documents:write" ], "description": "Keys from GET /employees/permissions. Unknown keys are ignored; implied permissions (the implies field) are added automatically." } } }, "EmployeeUpdateInput": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "emailAddress": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "description": "New password; omit to keep the current one." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Full replacement of the permission list; implied permissions are added automatically." }, "isActive": { "type": "boolean", "description": "false deactivates the account immediately and ends its sessions." } } }, "EmployeeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "$ref": "#/components/schemas/EmployeeExternal" } } } } } ] }, "ActivityFeedItem": { "type": "object", "description": "Activity journal entry: a document action, an employee login or account change, a warehouse operation.", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "scope": { "type": "string", "enum": [ "auth", "management", "document", "warehouse" ], "example": "document", "description": "auth = logins, management = employee account changes, document = document actions, warehouse = warehouse." }, "type": { "type": "string", "example": "CREATE", "description": "Kind of event, e.g. CREATE, UPDATE, SENT_BY_EMAIL, KSEF_SENT, PAYMENT_RECEIVED, LOGIN, PERMISSIONS_CHANGED, ADJUSTMENT." }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "employeeId": { "type": "string", "nullable": true, "description": "Employee who performed the action; null for the owner." }, "employeeName": { "type": "string", "nullable": true }, "entityId": { "type": "string", "nullable": true, "description": "Id of the affected resource (e.g. a document)." }, "entityName": { "type": "string", "nullable": true, "example": "FV/12/09/2026", "description": "Document number or resource name." }, "entityType": { "type": "string", "nullable": true, "example": "DOCUMENT" }, "entityDeleted": { "type": "boolean", "example": false, "description": "true when the document was deleted later." }, "changes": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Field diff of an edit." }, "data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Event details (e.g. origin, e-mail recipients, the KSeF result)." } } }, "ActivityFeedResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityFeedItem" } }, "hasMore": { "type": "boolean", "example": true, "description": "Whether older entries exist." }, "nextBefore": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z", "description": "Cursor: pass it as `before` to fetch the next page." } } } } } ] }, "EmployeeActivityResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "$ref": "#/components/schemas/EmployeeExternal" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityFeedItem" } }, "hasMore": { "type": "boolean", "example": false }, "nextBefore": { "type": "string", "format": "date-time", "nullable": true, "example": null } } } } } ] }, "EmployeeCreatedResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Employee account created." }, "data": { "type": "object", "properties": { "employee": { "$ref": "#/components/schemas/EmployeeExternal" }, "availablePermissions": { "type": "array", "items": { "type": "string" }, "description": "All permission keys, to pick from in later updates." } } } } } ] }, "EmployeeListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "employees": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeExternal" } } } } } } ] }, "EmployeePermissionsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "documents:read" }, "group": { "type": "string", "example": "documents" }, "label": { "type": "string", "example": "Podgląd dokumentów" }, "description": { "type": "string" }, "implies": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted automatically together with this key." } } } } } } } } ] }, "RecurringRuleExternal": { "type": "object", "description": "Recurring document rule. The full document template is not returned; documentSummary describes what the rule generates.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "name": { "type": "string", "nullable": true, "example": "Abonament miesięczny" }, "status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "PAUSED", "FINISHED", null ], "example": "ACTIVE" }, "mode": { "type": "string", "nullable": true, "enum": [ "AUTO", "DRAFT", "REMINDER", null ], "example": "AUTO", "description": "AUTO issues the document, DRAFT creates a draft, REMINDER only reminds." }, "documentSummary": { "type": "object", "properties": { "documentType": { "type": "string", "nullable": true, "example": "FakturaVAT" }, "buyerName": { "type": "string", "nullable": true, "example": "Acme Sp. z o.o." }, "grossSum": { "type": "number", "nullable": true, "example": 1230 }, "currency": { "type": "string", "example": "PLN" } } }, "schedule": { "type": "object", "nullable": true, "description": "Generation schedule (frequency, day, date range); the shape matches the settings in the app.", "additionalProperties": true }, "automation": { "type": "object", "properties": { "sendEmail": { "type": "boolean", "example": true }, "emailRecipients": { "type": "array", "items": { "type": "string" } }, "sendToKsef": { "type": "boolean", "example": false }, "notify": { "type": "object", "properties": { "onGenerate": { "type": "boolean" }, "dayBefore": { "type": "boolean" }, "channels": { "type": "object", "properties": { "email": { "type": "boolean" }, "pushWeb": { "type": "boolean" }, "pushMobile": { "type": "boolean" } } } } }, "notifyOnGenerate": { "type": "boolean", "deprecated": true, "description": "Superseded by notify.onGenerate together with notify.channels.email." }, "notifyDayBefore": { "type": "boolean", "deprecated": true, "description": "Superseded by notify.dayBefore together with notify.channels.email." } } }, "payment": { "type": "object", "nullable": true, "properties": { "status": { "type": "string", "enum": [ "PAID", "UNPAID" ] }, "deadlineDays": { "type": "integer", "example": 14 } } }, "numberingSymbol": { "type": "string", "nullable": true, "example": "FV/" }, "refreshSellerData": { "type": "boolean", "example": true }, "sourceDocumentId": { "type": "string", "nullable": true }, "nextRunAt": { "type": "string", "nullable": true, "example": "2026-10-01", "description": "Date of the next generation (YYYY-MM-DD) or null." }, "lastRunAt": { "type": "string", "nullable": true, "example": "2026-09-01" }, "occurrencesCount": { "type": "integer", "example": 3 }, "documentsIssuedCount": { "type": "integer", "example": 3 }, "skipDates": { "type": "array", "items": { "type": "string" }, "example": [] }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "RecurringRunExternal": { "type": "object", "description": "Entry of the generation history of a rule.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "plannedDate": { "type": "string", "nullable": true, "example": "2026-09-01" }, "issueDate": { "type": "string", "nullable": true, "example": "2026-09-01" }, "documentId": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "documentNumber": { "type": "string", "nullable": true, "example": "FV/7/09/2026" }, "status": { "type": "string", "nullable": true, "enum": [ "GENERATED", "DRAFT", "REMINDED", "SKIPPED", "FAILED", "PENDING", null ], "example": "GENERATED" }, "error": { "type": "string", "nullable": true }, "emailSent": { "type": "boolean", "example": true }, "ksefQueued": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "RecurringRuleResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/RecurringRuleExternal" } } } } } ] }, "RecurringRuleListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringRuleExternal" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." }, "summary": { "type": "object", "description": "Summary computed over every rule of the account (regardless of the status filter).", "properties": { "total": { "type": "integer", "example": 3 }, "active": { "type": "integer", "example": 2 }, "paused": { "type": "integer", "example": 1 }, "finished": { "type": "integer", "example": 0 }, "nextRunAt": { "type": "string", "nullable": true, "example": "2026-10-01" }, "monthlyRecurringGross": { "type": "number", "example": 2460, "description": "Monthly gross revenue from active rules, in PLN." } } } } } } } ] }, "RecurringRuleHistoryResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringRunExternal" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." } } } } } ] }, "RecurringRuleToggleInput": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "description": "true = resume (ACTIVE), false = pause (PAUSED).", "example": false } } }, "EmailAccountExternal": { "type": "object", "description": "Connected sender mailbox. Secrets (SMTP password, OAuth tokens) are never returned.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "provider": { "type": "string", "nullable": true, "enum": [ "smtp", "gmail", "outlook", null ], "example": "smtp" }, "isOAuth": { "type": "boolean", "example": false, "description": "true for Gmail and Outlook (OAuth), false for SMTP." }, "email": { "type": "string", "nullable": true, "example": "faktury@firma.pl" }, "host": { "type": "string", "nullable": true, "example": "smtp.firma.pl", "description": "SMTP only." }, "port": { "type": "integer", "nullable": true, "example": 465 }, "secure": { "type": "boolean", "example": true, "description": "true = SSL (465), false = STARTTLS." }, "verificationStatus": { "type": "string", "enum": [ "unverified", "verified", "error" ], "example": "verified" }, "isVerified": { "type": "integer", "enum": [ 0, 1, 2 ], "example": 1, "description": "Code as in the app: 0 = unverified, 1 = verified, 2 = the last send failed." }, "isDefault": { "type": "boolean", "example": true }, "lastError": { "type": "string", "nullable": true }, "lastVerifiedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "EmailAccountResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "emailAccount": { "$ref": "#/components/schemas/EmailAccountExternal" } } } } } ] }, "EmailAccountListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "emailAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAccountExternal" } } } } } } ] }, "SettingsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "general": { "type": "object", "properties": { "dateFormat": { "type": "string", "enum": [ "dd.MM.yyyy", "dd/MM/yyyy", "dd-MM-yyyy", "yyyy-MM-dd", "yyyy.MM.dd", "MM/dd/yyyy", "d MMMM yyyy", "d MMM yyyy", "dd.MM.yy" ], "example": "dd.MM.yyyy" }, "newsletter": { "type": "boolean", "example": true }, "dateFormatOptions": { "type": "array", "items": { "type": "string" }, "example": [ "dd.MM.yyyy", "dd/MM/yyyy", "dd-MM-yyyy", "yyyy-MM-dd", "yyyy.MM.dd", "MM/dd/yyyy", "d MMMM yyyy", "d MMM yyyy", "dd.MM.yy" ] } } }, "numbering": { "type": "object", "properties": { "numberingType": { "type": "string", "enum": [ "MONTH", "YEAR" ], "example": "MONTH" }, "numberingFormat": { "type": "string", "enum": [ "/MM/YYYY", "YYYY/MM/", "/YYYY/MM", "MM/YYYY/", "/YYYY", "YYYY/", "-MM-YYYY", "YYYY-MM-", "-YYYY-MM", "MM-YYYY-", "-YYYY", "YYYY-" ], "example": "/MM/YYYY" }, "numberingTypeOptions": { "type": "array", "items": { "type": "string" }, "example": [ "MONTH", "YEAR" ] }, "numberingFormatOptions": { "type": "array", "items": { "type": "string" }, "example": [ "/MM/YYYY", "YYYY/MM/", "/YYYY/MM", "MM/YYYY/", "/YYYY", "YYYY/", "-MM-YYYY", "YYYY-MM-", "-YYYY-MM", "MM-YYYY-", "-YYYY", "YYYY-" ] }, "documentSymbols": { "type": "object", "description": "Number prefixes per document type; a missing key = empty prefix.", "properties": { "Faktura": { "type": "string", "example": "F" }, "FakturaVAT": { "type": "string", "example": "FV/" }, "FakturaZaliczka": { "type": "string", "example": "FZ/" }, "FakturaKorygujaca": { "type": "string", "example": "KOR/" }, "FakturaKorygujacaZaliczkowa": { "type": "string" }, "FakturaKorygujacaRozliczeniowa": { "type": "string" }, "FakturaRozliczeniowa": { "type": "string", "example": "FK/" }, "FakturaProforma": { "type": "string", "example": "FP/" }, "FakturaProformaBezVAT": { "type": "string" }, "Zamowienie": { "type": "string", "example": "ZAM/" } } } } } } } } } ] }, "GeneralSettingsInput": { "type": "object", "required": [ "dateFormat", "newsletter" ], "properties": { "dateFormat": { "type": "string", "enum": [ "dd.MM.yyyy", "dd/MM/yyyy", "dd-MM-yyyy", "yyyy-MM-dd", "yyyy.MM.dd", "MM/dd/yyyy", "d MMMM yyyy", "d MMM yyyy", "dd.MM.yy" ], "description": "Date format on documents.", "example": "dd.MM.yyyy" }, "newsletter": { "type": "boolean", "description": "Newsletter consent.", "example": false } } }, "GeneralSettingsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "General settings updated." }, "data": { "type": "object", "properties": { "dateFormat": { "type": "string", "enum": [ "dd.MM.yyyy", "dd/MM/yyyy", "dd-MM-yyyy", "yyyy-MM-dd", "yyyy.MM.dd", "MM/dd/yyyy", "d MMMM yyyy", "d MMM yyyy", "dd.MM.yy" ], "example": "dd.MM.yyyy" }, "newsletter": { "type": "boolean", "example": false } } } } } ] }, "NumberingSettingsInput": { "type": "object", "required": [ "numberingType", "numberingFormat", "documentSymbols" ], "properties": { "numberingType": { "type": "string", "enum": [ "MONTH", "YEAR" ], "description": "Monthly numbering (the format must contain MM) or yearly.", "example": "MONTH" }, "numberingFormat": { "type": "string", "enum": [ "/MM/YYYY", "YYYY/MM/", "/YYYY/MM", "MM/YYYY/", "/YYYY", "YYYY/", "-MM-YYYY", "YYYY-MM-", "-YYYY-MM", "MM-YYYY-", "-YYYY", "YYYY-" ], "description": "Pattern of the date part of the document number.", "example": "/MM/YYYY" }, "documentSymbols": { "type": "object", "description": "Number prefixes per document type; a missing key = empty prefix.", "properties": { "Faktura": { "type": "string", "example": "F" }, "FakturaVAT": { "type": "string", "example": "FV/" }, "FakturaZaliczka": { "type": "string", "example": "FZ/" }, "FakturaKorygujaca": { "type": "string", "example": "KOR/" }, "FakturaKorygujacaZaliczkowa": { "type": "string" }, "FakturaKorygujacaRozliczeniowa": { "type": "string" }, "FakturaRozliczeniowa": { "type": "string", "example": "FK/" }, "FakturaProforma": { "type": "string", "example": "FP/" }, "FakturaProformaBezVAT": { "type": "string" }, "Zamowienie": { "type": "string", "example": "ZAM/" } } } } }, "NumberingSettingsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Numbering settings updated." }, "data": { "type": "object", "properties": { "numberingType": { "type": "string", "enum": [ "MONTH", "YEAR" ], "example": "MONTH" }, "numberingFormat": { "type": "string", "enum": [ "/MM/YYYY", "YYYY/MM/", "/YYYY/MM", "MM/YYYY/", "/YYYY", "YYYY/", "-MM-YYYY", "YYYY-MM-", "-YYYY-MM", "MM-YYYY-", "-YYYY", "YYYY-" ], "example": "/MM/YYYY" }, "documentSymbols": { "type": "object", "description": "Number prefixes per document type; a missing key = empty prefix.", "properties": { "Faktura": { "type": "string", "example": "F" }, "FakturaVAT": { "type": "string", "example": "FV/" }, "FakturaZaliczka": { "type": "string", "example": "FZ/" }, "FakturaKorygujaca": { "type": "string", "example": "KOR/" }, "FakturaKorygujacaZaliczkowa": { "type": "string" }, "FakturaKorygujacaRozliczeniowa": { "type": "string" }, "FakturaRozliczeniowa": { "type": "string", "example": "FK/" }, "FakturaProforma": { "type": "string", "example": "FP/" }, "FakturaProformaBezVAT": { "type": "string" }, "Zamowienie": { "type": "string", "example": "ZAM/" } } } } } } } ] }, "KsefConnectionResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "isAuthorized": { "type": "boolean", "example": true, "description": "Whether the last authorization in KSeF succeeded." }, "hasToken": { "type": "boolean", "example": true, "description": "Whether a KSeF token is stored on the account." }, "hasCertificate": { "type": "boolean", "example": false, "description": "Whether a KSeF certificate is stored on the account." }, "hasConnectionConfig": { "type": "boolean", "example": true, "description": "Whether the connection is configured: a KSeF token or a certificate is stored (hasToken or hasCertificate)." }, "connectionType": { "type": "string", "enum": [ "TOKEN", "CERTIFICATE" ], "example": "TOKEN", "description": "Connection method: KSeF token (TOKEN) or certificate (CERTIFICATE). When the account has no connection yet: CERTIFICATE." }, "lastCheckAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "lastError": { "type": "string", "nullable": true }, "lastErrorAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "environment": { "type": "string", "nullable": true, "enum": [ "prod", "test", "demo", null ], "example": "prod" }, "nip": { "type": "string", "nullable": true, "example": "5261040828" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "InvoiceWrite", "InvoiceRead" ] }, "certificateExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z", "description": "Certificate expiry date. Null for a token connection." } } } } } ] }, "KsefConnectionInput": { "type": "object", "description": "Connection to KSeF by one of two methods. Token: connectionType=TOKEN and token. Certificate: connectionType=CERTIFICATE with certificateContent, privateKeyContent and privateKeyPassword. When connectionType is left out and the body has the certificate fields, the connection is saved as a certificate. Saving one method replaces the other.", "properties": { "connectionType": { "type": "string", "enum": [ "TOKEN", "CERTIFICATE" ], "description": "Connection method: TOKEN (KSeF token) or CERTIFICATE (KSeF certificate). Left out: CERTIFICATE when the certificate fields are given, otherwise TOKEN.", "example": "TOKEN" }, "token": { "type": "string", "description": "KSeF token generated in the KSeF Taxpayer Application (Aplikacja Podatnika KSeF), with permissions to issue and view invoices. Required for connectionType=TOKEN. Whitespace (spaces, line breaks) is removed." }, "certificateContent": { "type": "string", "description": "KSeF certificate in PEM format. Required for connectionType=CERTIFICATE." }, "privateKeyContent": { "type": "string", "description": "Private key in PEM format (may be encrypted). Required for connectionType=CERTIFICATE." }, "privateKeyPassword": { "type": "string", "description": "Private key password. Required for connectionType=CERTIFICATE." }, "environment": { "type": "string", "enum": [ "prod", "test", "demo" ], "description": "KSeF environment. Use test in the sandbox.", "example": "test" } } }, "KsefConnectionSavedResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "KSeF token connection saved." }, "data": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "prod", "test", "demo" ], "example": "test" }, "connectionType": { "type": "string", "enum": [ "TOKEN", "CERTIFICATE" ], "example": "TOKEN" }, "certificateFingerprint": { "type": "string", "example": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678", "description": "SHA-1 fingerprint of the certificate. Only for connectionType=CERTIFICATE." }, "certificateExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z", "description": "Certificate expiry date. Only for connectionType=CERTIFICATE." } } } } } ] }, "KsefConnectionTestResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "KSeF connection test passed." }, "data": { "type": "object", "properties": { "isAuthorized": { "type": "boolean", "example": true }, "environment": { "type": "string", "example": "test" }, "permissions": { "type": "array", "items": { "type": "string" } }, "lastError": { "type": "string", "nullable": true }, "checkedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } } } } ] }, "KsefConnectionDeletedResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "KSeF connection deactivated." }, "data": { "type": "object", "properties": { "isAuthorized": { "type": "boolean", "example": false }, "hasConnectionConfig": { "type": "boolean", "example": false } } } } } ] }, "AuthMeResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "clientId": { "type": "string", "nullable": true, "example": "client_5c62e06900bcbeb2f39a78ac45ed45f5" }, "name": { "type": "string", "example": "Integracja z e-Sklepem" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "documents:read", "clients:browse" ] }, "userId": { "type": "string", "example": "507f1f77bcf86cd799439012" } } } } } ] }, "CompanyLookupResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "company": { "type": "object", "properties": { "nip": { "type": "string", "example": "5261040828" }, "name": { "type": "string", "example": "ACME SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ" }, "regon": { "type": "string", "example": "146000000" }, "street": { "type": "string", "example": "ul. Marszałkowska 1 lok. 2" }, "postcode": { "type": "string", "example": "00-001" }, "postalCode": { "type": "string", "example": "00-001", "description": "Postal code (the same value as postcode; field name as in the client)." }, "city": { "type": "string", "example": "Warszawa" }, "country": { "type": "string", "example": "Polska" }, "countryCode": { "type": "string", "example": "PL" } } }, "buyer": { "type": "object", "description": "The same data with client field names: ready to use as the buyer of a document (POST /documents) or as the body of a new client (POST /clients).", "properties": { "type": { "type": "string", "example": "company" }, "identifierType": { "type": "string", "example": "nip" }, "nip": { "type": "string", "example": "5261040828" }, "name": { "type": "string", "example": "ACME SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ" }, "regon": { "type": "string", "example": "146000000" }, "street": { "type": "string", "example": "ul. Marszałkowska 1 lok. 2" }, "postalCode": { "type": "string", "example": "00-001" }, "city": { "type": "string", "example": "Warszawa" }, "country": { "type": "string", "example": "Polska" }, "countryCode": { "type": "string", "example": "PL" } } } } } } } ] }, "WarehouseDocumentRequestBody": { "type": "object", "required": [ "documentType", "issueDate", "products" ], "properties": { "documentType": { "type": "string", "enum": [ "WZ", "PZ", "PW", "RW", "MM" ], "description": "WZ goods issue (to a recipient), PZ goods receipt (from a supplier), PW internal receipt, RW internal issue, MM transfer between warehouses.", "example": "PZ" }, "issueDate": { "type": "string", "format": "date", "example": "2026-09-26", "description": "Issue date (YYYY-MM-DD)." }, "subDate": { "type": "string", "format": "date", "description": "WZ: goods issue date, PZ: goods receipt date. Defaults to the issue date. PW/RW/MM have none." }, "warehouseId": { "type": "string", "description": "Warehouse of the document (WZ, PZ, PW, RW). Defaults to the account's default warehouse." }, "sourceWarehouseId": { "type": "string", "description": "MM: source warehouse. Defaults to the account's default warehouse." }, "targetWarehouseId": { "type": "string", "description": "MM: target warehouse (required, different from the source)." }, "buyerId": { "type": "string", "description": "WZ: recipient, PZ: supplier (client ID). Not used by PW/RW/MM." }, "buyer": { "$ref": "#/components/schemas/ClientReference", "description": "Contractor given as data instead of buyerId (matched by NIP, otherwise saved as a new client)." }, "products": { "type": "array", "maxItems": 500, "description": "Lines from the product catalogue. Name, unit and price come from the catalogue unless you send them.", "items": { "type": "object", "required": [ "productId", "quantity" ], "properties": { "productId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e", "description": "Catalogue product ID (browseProducts). The stock movement is booked on this product." }, "quantity": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 20, "description": "Quantity (greater than 0)." }, "netPrice": { "type": "number", "minimum": 0, "example": 45.5, "description": "Net unit price. Defaults: PZ/PW the catalogue purchase price, WZ/RW/MM the net sale price." }, "name": { "type": "string", "description": "Name on the document (defaults to the catalogue name)." }, "unitOfMeasure": { "type": "string", "description": "Unit (defaults to the catalogue unit)." } } } }, "sourceInvoiceId": { "type": "string", "description": "WZ for a sales invoice: the documents are linked both ways and the WZ number is printed on the invoice. Without buyerId the recipient comes from the invoice." }, "stockStatus": { "type": "string", "enum": [ "posted", "pending" ], "description": "posted = stock moves at once; pending = waits for the issue/receipt confirmation in the app (goods only reserved). Defaults to the release confirmation setting." }, "allowNegativeStock": { "type": "boolean", "description": "true = issue WZ/RW/MM even when goods are missing (stock goes below zero). By default missing goods reject the document (422 STOCK_SHORTAGE)." }, "issuePlace": { "type": "string", "description": "Place of issue (defaults to the account settings or the company address city)." }, "comments": { "type": "string", "description": "Comments (defaults to the account's comments)." }, "signatures": { "type": "object", "description": "Signature fields on the PDF. Defaults to the warehouse document signature setting (issuer: the owner's or employee's name).", "properties": { "issuerSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } }, "receiverSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } } } }, "useAccountDefaults": { "type": "boolean", "description": "false = no account defaults (place, comments, signatures).", "example": true } } }, "WarehouseDocumentExternal": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "documentType": { "type": "string", "example": "PZ" }, "documentNumber": { "type": "string", "example": "PZ/4/09/2026" }, "invoiceName": { "type": "string", "example": "Przyjęcie zewnętrzne PZ/4/09/2026" }, "issueDate": { "type": "string", "example": "2026-09-26" }, "warehouseId": { "type": "string", "nullable": true }, "warehouseName": { "type": "string", "nullable": true }, "sourceWarehouseId": { "type": "string", "nullable": true }, "sourceWarehouseName": { "type": "string", "nullable": true }, "targetWarehouseId": { "type": "string", "nullable": true }, "targetWarehouseName": { "type": "string", "nullable": true }, "stockStatus": { "type": "string", "enum": [ "posted", "pending" ], "example": "posted" }, "contractor": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Recipient (WZ) or supplier (PZ); null for PW/RW/MM." }, "netSum": { "type": "number", "example": 910 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "name": { "type": "string" }, "unitOfMeasure": { "type": "string" }, "quantity": { "type": "number" }, "netPrice": { "type": "number" }, "netValue": { "type": "number" } } } }, "sourceInvoiceId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "WarehouseDocumentPreview": { "type": "object", "properties": { "documentType": { "type": "string", "example": "PZ" }, "documentNo": { "type": "integer", "example": 4 }, "documentNumber": { "type": "string", "example": "PZ/4/09/2026" }, "issueDate": { "type": "string", "example": "2026-09-26" }, "subDate": { "type": "string", "nullable": true, "example": "2026-09-26" }, "subDateLabel": { "type": "string", "nullable": true, "example": "Data otrzymania towaru" }, "warehouse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "name": { "type": "string", "example": "Magazyn główny" } } }, "sourceWarehouse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "name": { "type": "string", "example": "Magazyn główny" } } }, "targetWarehouse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "name": { "type": "string", "example": "Magazyn główny" } } }, "contractor": { "type": "object", "nullable": true, "additionalProperties": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "name": { "type": "string", "example": "Krzesło biurowe" }, "unitOfMeasure": { "type": "string", "example": "szt." }, "quantity": { "type": "number", "example": 20 }, "netPrice": { "type": "number", "example": 45.5 }, "netValue": { "type": "number", "example": 910 }, "productType": { "type": "string", "nullable": true, "example": "goods", "description": "Catalogue item type (goods). A service on a warehouse document is marked as goods." }, "stockBefore": { "type": "number", "example": 5, "description": "Stock in the document's warehouse (MM: the source) before the document." }, "stockAfter": { "type": "number", "example": 25, "description": "Stock after the document." }, "targetStockBefore": { "type": "number", "description": "MM: stock in the target warehouse before the document." }, "targetStockAfter": { "type": "number", "description": "MM: stock in the target warehouse after the document." } } } }, "totals": { "type": "object", "properties": { "netSum": { "type": "number", "example": 910 }, "vatSum": { "type": "number", "example": 209.3 }, "grossSum": { "type": "number", "example": 1119.3 } } }, "stockStatus": { "type": "string", "enum": [ "posted", "pending" ], "example": "posted" }, "shortages": { "type": "array", "description": "Missing goods for WZ/RW/MM (stock minus reservations of other pending documents). A non-empty list rejects issuing without allowNegativeStock.", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "requested": { "type": "number" }, "available": { "type": "number" }, "shortage": { "type": "number" } } } }, "sourceInvoice": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "documentNumber": { "type": "string" } } }, "issuePlace": { "type": "string", "example": "Kraków" }, "comments": { "type": "string", "example": "" }, "signatures": { "type": "object", "nullable": true, "additionalProperties": true }, "appliedDefaults": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "ISSUE_PLACE" }, "field": { "type": "string", "example": "issuePlace" }, "message": { "type": "string", "example": "Miejsce wystawienia Kraków z ustawień konta." } } }, "description": "Values filled automatically (account settings, default warehouse, recipient from the invoice)." } } }, "WarehouseDocumentResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Utworzono dokument Przyjęcie zewnętrzne PZ/4/09/2026." }, "data": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/WarehouseDocumentExternal" }, "preview": { "$ref": "#/components/schemas/WarehouseDocumentPreview" } } } } } ] }, "WarehouseDocumentPreviewResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "preview": { "$ref": "#/components/schemas/WarehouseDocumentPreview" }, "valid": { "type": "boolean", "example": true } } } } } ] }, "WebhookExternal": { "type": "object", "description": "Webhook registered on the account. The signing secret is not returned.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "endpoint": { "type": "string", "nullable": true, "example": "https://erp.example.com/hooks/fakturnia" }, "description": { "type": "string", "nullable": true, "example": "ERP" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "client.created", "client.updated", "client.deleted", "product.created", "product.updated", "product.deleted", "document.created", "document.updated", "document.deleted", "document.sentToKSeF", "document.ksefRejected", "document.paymentStatusChanged", "document.ksefImported" ] }, "example": [ "document.created", "document.sentToKSeF" ] }, "status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "INACTIVE", "ERROR", null ], "example": "ACTIVE", "description": "ERROR = switched off automatically after 10 consecutive failures; re-enable with PATCH status=ACTIVE." }, "successCount": { "type": "integer", "example": 128 }, "failureCount": { "type": "integer", "example": 2 }, "consecutiveFailures": { "type": "integer", "example": 0 }, "lastDeliveryAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "WebhookDelivery": { "type": "object", "description": "One delivery of an event (with retries). `id` is the value of the X-Webhook-Delivery header and of the `id` field in the body.", "properties": { "id": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "event": { "type": "string", "nullable": true, "enum": [ "client.created", "client.updated", "client.deleted", "product.created", "product.updated", "product.deleted", "document.created", "document.updated", "document.deleted", "document.sentToKSeF", "document.ksefRejected", "document.paymentStatusChanged", "document.ksefImported", "webhook.test", null ], "example": "document.created" }, "resourceId": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "status": { "type": "string", "nullable": true, "enum": [ "PENDING", "SUCCESS", "FAILED", "CANCELLED", null ], "example": "SUCCESS" }, "attempts": { "type": "integer", "example": 1 }, "nextAttemptAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z", "description": "Time of the next attempt (for PENDING)." }, "lastAttemptAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" }, "lastError": { "type": "string", "nullable": true, "example": null }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-09-26T10:30:00.000Z" } } }, "WebhookInput": { "type": "object", "required": [ "endpoint", "events" ], "properties": { "endpoint": { "type": "string", "format": "uri", "example": "https://erp.example.com/hooks/fakturnia", "description": "Public HTTPS address. Private, local and non-HTTP addresses are rejected." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "client.created", "client.updated", "client.deleted", "product.created", "product.updated", "product.deleted", "document.created", "document.updated", "document.deleted", "document.sentToKSeF", "document.ksefRejected", "document.paymentStatusChanged", "document.ksefImported" ] }, "description": "Events to subscribe to (list in the API description)." }, "description": { "type": "string", "maxLength": 200, "example": "ERP" } } }, "WebhookPatchInput": { "type": "object", "description": "Partial update: only the keys sent change.", "properties": { "endpoint": { "type": "string", "format": "uri", "example": "https://erp.example.com/hooks/fakturnia" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "client.created", "client.updated", "client.deleted", "product.created", "product.updated", "product.deleted", "document.created", "document.updated", "document.deleted", "document.sentToKSeF", "document.ksefRejected", "document.paymentStatusChanged", "document.ksefImported" ] }, "description": "Replaces the whole subscription list." }, "description": { "type": "string", "maxLength": 200 }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "ACTIVE enables (also after an automatic switch-off), INACTIVE pauses deliveries." } } }, "InitialWebhookInput": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string", "format": "uri", "example": "https://shop.example.com/wp-json/fakturnia/v1/webhook" }, "siteName": { "type": "string", "example": "Sklep Example" }, "domain": { "type": "string", "example": "shop.example.com" }, "rotateSecret": { "type": "boolean", "example": false, "description": "When the webhook already exists: generate and return a new secret." } } }, "WebhookResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/WebhookExternal" } } } } } ] }, "WebhookCreatedResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Webhook created." }, "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/WebhookExternal" }, "secret": { "type": "string", "example": "9f2a7c1d4e6b8a0c3d5f7e9b1a2c4d6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a5b7c", "description": "Secret for verifying X-Webhook-Signature. Shown only in this response." } } } } } ] }, "WebhookListResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookExternal" } }, "hasInitialWebhook": { "type": "boolean", "example": true, "description": "Whether a webhook exists for the address in the endpoint parameter (false without the parameter)." }, "initialWebhookId": { "type": "string", "nullable": true, "example": "681a3b2c4d5e6f7a8b9c0d1e" } } } } } ] }, "InitialWebhookResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Initial webhook created." }, "data": { "type": "object", "properties": { "created": { "type": "boolean", "example": true }, "rotated": { "type": "boolean", "example": false }, "webhook": { "$ref": "#/components/schemas/WebhookExternal" }, "secret": { "type": "string", "example": "9f2a7c1d4e6b8a0c3d5f7e9b1a2c4d6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a5b7c", "description": "Present only on creation or rotation." } } } } } ] }, "WebhookSecretResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Webhook secret rotated." }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "secret": { "type": "string", "example": "9f2a7c1d4e6b8a0c3d5f7e9b1a2c4d6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a5b7c", "description": "New secret. Shown only in this response." } } } } } ] }, "WebhookDeliveriesResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "currentPage": { "type": "integer", "example": 1, "description": "Current page number (from 1)." }, "totalPages": { "type": "integer", "example": 5, "description": "Number of pages." }, "totalCount": { "type": "integer", "example": 50, "description": "Number of all matching records." }, "itemsPerPage": { "type": "integer", "example": 10, "description": "Page size (max 100)." }, "searchQuery": { "type": "string", "example": "", "description": "The text filter used (empty when none)." } } } } } ] }, "WebhookTestResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "message": { "type": "string", "nullable": true, "example": "Test delivery succeeded." }, "data": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "ok": { "type": "boolean", "example": true, "description": "true when the endpoint answered 2xx." }, "statusCode": { "type": "integer", "example": 200, "description": "HTTP status of the endpoint response (500 on a network error)." }, "status": { "type": "string", "enum": [ "SUCCESS", "FAILED" ], "example": "SUCCESS" }, "lastError": { "type": "string", "nullable": true, "example": null } } } } } } } ] }, "WebhookEventPayload": { "type": "object", "description": "Body of the POST request Fakturnia sends to your endpoint. The HMAC-SHA256 signature (X-Webhook-Signature header) is computed over exactly these bytes.", "required": [ "id", "event", "timestamp", "data", "resourceId" ], "properties": { "id": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e", "description": "Delivery id: the same on every retry, use it to deduplicate. Repeated in the X-Webhook-Delivery header." }, "event": { "type": "string", "enum": [ "client.created", "client.updated", "client.deleted", "product.created", "product.updated", "product.deleted", "document.created", "document.updated", "document.deleted", "document.sentToKSeF", "document.ksefRejected", "document.paymentStatusChanged", "document.ksefImported", "webhook.test" ], "example": "document.created" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-26T10:30:00.000Z", "description": "Time of the event (UTC)." }, "data": { "type": "object", "description": "Resource id named after its type: documentId, clientId, productId or webhookId; bulk events also carry a list (documentIds, clientIds, productIds).", "properties": { "documentId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f" }, "documentIds": { "type": "array", "items": { "type": "string" } }, "clientId": { "type": "string" }, "clientIds": { "type": "array", "items": { "type": "string" } }, "productId": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string" } }, "webhookId": { "type": "string" } } }, "resourceId": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1f", "description": "Resource id (the same as in data, kept for older receivers)." }, "resourceIds": { "type": "array", "items": { "type": "string" }, "description": "Only with bulk events." } } }, "UpdateDocumentRequestBody": { "type": "object", "required": [ "issueDate" ], "description": "Full update (PUT): omitted optional fields are cleared. The document type does not change.", "properties": { "correctionAdvanceAmountAfter": { "type": "number", "description": "Advance payment amount AFTER the correction (FakturaKorygujacaZaliczkowa)." }, "correctionSettlementAmountAfter": { "type": "number", "description": "Settlement amount AFTER the correction (FakturaKorygujacaRozliczeniowa)." }, "issueDate": { "type": "string", "format": "date", "description": "Issue date (ISO 8601)", "example": "2026-05-07" }, "documentNo": { "type": "integer", "minimum": 1, "description": "Optional document number. If provided, it is used instead of automatic numbering.", "example": 1 }, "numberingFormat": { "type": "string", "enum": [ "/MM/YYYY", "YYYY/MM/", "/YYYY/MM", "MM/YYYY/", "/YYYY", "YYYY/", "-MM-YYYY", "YYYY-MM-", "-YYYY-MM", "MM-YYYY-", "-YYYY", "YYYY-" ], "description": "Numbering format (e.g. \"/MM/YYYY\"). Defaults to the user's settings.", "example": "/MM/YYYY" }, "symbol": { "type": "string", "description": "Document symbol prefix (e.g. \"FV/\"). Defaults to the settings.", "example": "FV/" }, "documentNumber": { "type": "string", "description": "Full document number for exact (1:1) validation. If provided together with documentNo, the two must be consistent.", "example": "FV/1/05/2026" }, "invoiceName": { "type": "string", "description": "Invoice name (e.g. for advance invoices)", "example": "Faktura zaliczkowa" }, "buyerId": { "type": "string", "description": "ID of an existing client. Do not combine with buyer. buyerId or buyer is required (except corrections, which take the buyer from the corrected invoice).", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "buyer": { "$ref": "#/components/schemas/ClientReference" }, "receiverId": { "type": "string", "description": "ID of an optional receiver (for invoices with multiple parties)." }, "receiver": { "$ref": "#/components/schemas/ClientReference" }, "products": { "type": "array", "description": "Document lines. Corrections: the full list of lines AFTER the correction (document totals are the difference to the corrected invoice). FakturaZaliczka: omit, the lines are the split of the advance over the order's VAT rates.", "items": { "type": "object", "required": [ "name", "unitOfMeasure", "quantity" ], "properties": { "name": { "type": "string", "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true, "enum": [ "GTU_01", "GTU_02", "GTU_03", "GTU_04", "GTU_05", "GTU_06", "GTU_07", "GTU_08", "GTU_09", "GTU_10", "GTU_11", "GTU_12", "GTU_13", null ], "description": "GTU code (optional)" }, "pkwiu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "example": "szt." }, "quantity": { "type": "number", "example": 1 }, "netPrice": { "type": "number", "nullable": true, "description": "Net unit price. When provided, netValue/amountOfVat/grossValue are calculated automatically.", "example": 100 }, "grossPrice": { "type": "number", "nullable": true, "description": "Gross unit price (alternative to netPrice).", "example": 123 }, "netValue": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 100 }, "grossValue": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 123 }, "amountOfVat": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 23 }, "vatRate": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 23, "description": "VAT rate from the AppData.VatRates dictionary. Validated by the backend, which also sets taxSymbol. Missing = the account's default rate (settings.defaultTaxRate). \"marza\" = a margin-scheme line (Articles 119 and 120 of the VAT Act): send grossPrice; the invoice shows gross amounts only and KSeF gets the total in P_13_11. Requires annotations.marginProcedure (otherwise 422 MARGIN_LINE_WITHOUT_PROCEDURE)." }, "marginPurchaseValue": { "type": "number", "nullable": true, "minimum": 0, "description": "vatRate \"marza\" only: gross purchase amount of the whole line in PLN (second-hand goods: the purchase price; travel agency: the costs of services bought for the tourist). It never appears on the invoice or in KSeF; it gives the margin and the VAT on the margin in the VAT register and JPK. Missing = to be added later. Left out on a correction: taken from the corrected line with the same name, in proportion to the quantity.", "example": 3000 }, "marginTaxRate": { "type": "number", "nullable": true, "enum": [ 23, 8, 5, 0, null ], "description": "vatRate \"marza\" only: rate of the VAT on the margin (VAT = margin × rate / (100 + rate); a negative margin = VAT 0). Default 23.", "example": 23 }, "discount": { "type": "number", "example": 0 }, "currency": { "type": "string", "example": "PLN" } } } }, "useAccountDefaults": { "type": "boolean", "description": "Defaults to true: missing fields get the account's settings like a new document in the app (comments, signatures, place of issue, automatic annotations MPP/margin with the VAT account, exemption basis for the zw rate, payment method and status, line VAT rate). A field you send always wins. false = no account defaults. A correction still takes the buyer, receiver, currency and annotations from the corrected invoice when you do not send them.", "example": true }, "currency": { "type": "string", "description": "Document currency (ISO 4217)", "example": "PLN" }, "exchangeRate": { "type": "number", "description": "Exchange rate for foreign currencies" }, "issuePlace": { "type": "string", "description": "Place of issue", "example": "Warszawa" }, "comments": { "type": "string", "description": "Document notes" }, "paymentDescription": { "type": "string", "description": "Payment description" }, "showPaymentSection": { "type": "boolean", "description": "Whether to show the payment section on the document/PDF. For Zamowienie documents it can be set to false." }, "paymentDeadlineDate": { "type": "string", "format": "date", "description": "Payment due date (required when paymentStatusId=1). Ignored for the Zapłacono (paid) status." }, "additionalPaymentDate": { "type": "string", "format": "date", "description": "Payment received date (required when paymentStatusId=0). Ignored for the Do zapłaty (to be paid) status." }, "additionalPaymentDateHeaderId": { "type": "number", "description": "Payment date header ID from the paymentDateHeaders dictionary. For paymentStatusId=0 the default is id=2 (\"Data otrzymania zapłaty\").", "example": 2 }, "subDate": { "type": "string", "format": "date", "description": "Sale / service date. For KSeF invoices and Zamowienie documents, issueDate is used by default if not provided." }, "subDateHeaderId": { "type": "number", "description": "Sale date header ID from the additionalDateHeaders dictionary (e.g. 1 => \"Data wykonania usługi\").", "example": 1 }, "subDateTo": { "type": "string", "format": "date", "nullable": true, "description": "End of the sale period (KSeF OkresFa, P_6_Do). With it, subDate is the start of the period, e.g. a service for a whole month. Without it, subDate is a single sale date (P_6). A correction without subDate takes the sale date or period of the corrected invoice." }, "taxPointRule": { "type": "string", "nullable": true, "enum": [ "art19a5p3a", "art19a5p3b", "art19a5p3c", "art19a5p4", null ], "description": "Tax point at the issue of the invoice (art. 19a ust. 5 of the VAT Act): art19a5p3a construction services (at the latest the 30th day after completion), art19a5p3b supply of books and press (60th day), art19a5p3c printing of books and press (90th day), art19a5p4 utilities, telecommunications, rent, lease, leasing, security, ongoing legal and office services (at the latest when the payment is due). Not sent to KSeF; it decides the period in VAT reports and the day of the exchange rate. null = the usual rules (the sale date)." }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true, "description": "Day of the NBP table exchangeRate comes from. Under art. 31a of the VAT Act it is the last business day before the tax point (usually before the sale date), or before the issue date when the invoice comes first. A correction without exchangeRate takes the rate, its day and table from the corrected invoice (art. 31b ust. 1)." }, "exchangeRateTable": { "type": "string", "nullable": true, "maxLength": 32, "example": "190/A/NBP/2026", "description": "NBP table number of exchangeRate, printed on the PDF next to the rate." }, "paymentInstallments": { "type": "array", "maxItems": 100, "description": "Instalments with custom amounts (e.g. a larger first instalment): at least two due dates with amounts (KSeF TerminPlatnosci; the instalment amounts go to DodatkowyOpis). Only with paymentStatusId=1; the instalments must add up to the amount due to the grosz, the dates must be in order and not before the issue date. Without paymentDeadlineDate the first instalment is the document's payment deadline. For equal instalments send paymentInstallmentsSplit instead of computing the amounts (do not combine the two fields).", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-10-20" }, "amount": { "type": "number", "example": 615 } } } }, "paymentInstallmentsSplit": { "type": "object", "nullable": true, "required": [ "count" ], "description": "Equal instalments computed by the API: recommended whenever the instalments should be equal. Send the number of instalments; once the document totals are computed the API splits the amount due to the grosz: every instalment gets the same amount and the rounding remainder goes to the last one (100.00 in 3 instalments = 33.33 + 33.33 + 33.34). The document stores ordinary paymentInstallments (returned in the response and in the preview) and its payment deadline (paymentDeadlineDate) is the date of the first instalment. Only with paymentStatusId=1; on create without paymentStatusId the document becomes unpaid (to pay). Instalments with different amounts (e.g. a larger first instalment) go in paymentInstallments; do not combine the two fields. A PATCH without products splits the amount stored in the document. Errors: 422 PAYMENT_INSTALLMENTS_INVALID. null = no split.", "properties": { "count": { "type": "integer", "minimum": 2, "maximum": 100, "example": 3, "description": "Number of instalments, 2 to 100 (the KSeF limit)." }, "firstDate": { "type": "string", "format": "date", "example": "2026-10-21", "description": "Due date of the first instalment, not before the issue date. Defaults to paymentDeadlineDate from the request; on an update, the stored payment deadline of a document to pay; otherwise the issue date + 14 days." }, "every": { "type": "string", "enum": [ "month", "week", "14days" ], "default": "month", "example": "month", "description": "Interval between instalments: month = monthly (counted from the first date: 31 Jan, 28 Feb, 31 Mar), week = every 7 days, 14days = every 14 days. Default: month." } } }, "paymentDeadlineTerm": { "type": "object", "nullable": true, "description": "Due date in words (KSeF TerminOpis), e.g. 14 days from the invoice date. Printed next to the due date.", "required": [ "count", "unit", "event" ], "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9999, "example": 14 }, "unit": { "type": "string", "enum": [ "day", "week", "month" ], "example": "day" }, "event": { "type": "string", "enum": [ "issue", "invoice_delivery", "supply", "acceptance" ], "example": "issue", "description": "What the term counts from: issue the issue of the invoice, invoice_delivery delivery of the invoice, supply the supply of goods or services, acceptance acceptance." } } }, "advanceReceipts": { "type": "array", "maxItems": 31, "description": "Advance invoice documenting several payments (KSeF ZaliczkaCzesciowa): at least two receipts dated no later than the issue date and adding up to advancePaymentAmount, with paymentStatusId=0. In a foreign currency each receipt has its own rate from the business day before it arrived (art. 31a). Each receipt is a separate tax point in VAT reports. Ignored for other document types.", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-10" }, "amount": { "type": "number", "example": 500 }, "exchangeRate": { "type": "number", "nullable": true, "example": 4.4512 }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true, "example": "2026-09-09" } } } }, "bankAccounts": { "type": "array", "description": "Bank accounts to show on the document. The first account goes to bankAccountNumber, the rest to 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 } } } }, "vatAccountNumber": { "type": "string", "description": "VAT account number (split payment / MPP)." }, "vatAccountBank": { "type": "string", "description": "Bank name of the VAT account." }, "vatAccountSwift": { "type": "string", "description": "SWIFT code of the VAT account." }, "vatAccountDescription": { "type": "string", "description": "VAT account description." }, "paymentMethodId": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Payment method ID: 1=Cash, 2=Card, 3=Voucher, 4=Check, 5=Credit, 6=Bank transfer, 7=Mobile payment", "example": 6 }, "paymentStatusId": { "type": "integer", "enum": [ 0, 1 ], "description": "0=Paid (requires additionalPaymentDate or partialPayments), 1=Due (requires paymentDeadlineDate)", "example": 1 }, "partialPayments": { "type": "array", "maxItems": 100, "description": "Partial payments made by the issue date (KSeF ZaplataCzesciowa). With paymentStatusId=1 their sum must be lower than the amount due. With paymentStatusId=0 at least two payments summing to the amount due. A payment date cannot be later than the issue date.", "items": { "type": "object", "required": [ "amount", "date" ], "properties": { "amount": { "type": "number", "example": 500 }, "date": { "type": "string", "format": "date", "example": "2026-09-14" }, "paymentMethodId": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "nullable": true, "description": "Payment form as paymentMethodId; absent = not given", "example": 1 } } } }, "annotations": { "$ref": "#/components/schemas/AnnotationsInput" }, "additionalInfo": { "$ref": "#/components/schemas/AdditionalInfoInput" }, "linkedOrderId": { "type": "string", "description": "Order ID (required for FakturaZaliczka)" }, "advancePaymentAmount": { "type": "number", "minimum": 0.01, "description": "Advance payment amount (required for FakturaZaliczka)" }, "correctedInvoiceId": { "type": "string", "description": "ID of the corrected invoice (required for FakturaKorygujaca, FakturaKorygujacaZaliczkowa and FakturaKorygujacaRozliczeniowa). When you do not send the buyer, receiver, currency or annotations, the correction takes them from this invoice." }, "correctionReason": { "type": "string", "maxLength": 256, "description": "Correction reason: the description printed on the PDF and sent to KSeF (PrzyczynaKorekty). Optional, at most 256 characters (KSeF limit)." }, "correctionCause": { "type": "string", "nullable": true, "enum": [ "after_sale", "mistake", null ], "example": "after_sale", "description": "Cause of the correction: after_sale (an event after the sale: discount, return of goods, complaint, price or quantity changed after the sale) or mistake (an error on the corrected invoice). Sets the TypKorekty sent to KSeF when you leave out correctionType, and the period in which the correction enters the VAT and KPiR reports. Without a cause the correction goes to KSeF with TypKorekty 2, as before. Applies to correcting invoices only; for other types the field is ignored." }, "correctionType": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, null ], "example": 1, "description": "KSeF TypKorekty set by hand: 1 = effect on the date the original invoice was recorded, 2 = on the issue date of the correcting invoice, 3 = on another date. Leave it out and Fakturnia works it out when sending: after_sale or no cause gives 2; mistake gives 1 when the correction raises the amounts, does not change them or takes the whole invoice to zero (wrong buyer, duplicate), 2 when it lowers them, and 3 when it raises one rate and lowers another. Applies to correcting invoices only." }, "correctionEffectDate": { "type": "string", "format": "date", "nullable": true, "description": "Corrections: the day the correction takes effect for VAT when it is neither the date of the corrected invoice nor the date of the correction. For an increase after the sale (after_sale) it is the day the cause arose, e.g. a price rise was agreed (art. 29a ust. 17); in another month than the correction it gives TypKorekty 3. With correctionType=3 set by hand it is the day of the effect. KSeF has no field for it; the VAT report and JPK place the correction on this day." }, "correctionConfirmationDate": { "type": "string", "format": "date", "nullable": true, "description": "Decreasing corrections issued outside KSeF: the day the buyer's confirmation of receipt arrived. Under art. 29a ust. 13a the decrease counts in the period the confirmation arrived in, and the VAT report places it there." }, "linkedAdvanceInvoiceIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of advance invoices to settle (required for FakturaRozliczeniowa)" }, "prepaymentIds": { "type": "array", "items": { "type": "string" } }, "settlementAmount": { "type": "number", "description": "Settlement amount (FakturaRozliczeniowa). Passed through without automatic calculations." }, "isSettlementAmountManual": { "type": "boolean", "description": "Whether settlementAmount was provided manually." }, "signatures": { "type": "object", "description": "Signatures on the PDF (person authorized to issue/receive the document).", "properties": { "issuerSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } }, "receiverSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } } } }, "ksefJst": { "type": "boolean", "description": "Whether the document is for a JST entity (Polish local government unit)" } } }, "PatchDocumentRequestBody": { "type": "object", "description": "Partial update (PATCH): only the keys sent change; an explicit null clears the field.", "properties": { "correctionAdvanceAmountAfter": { "type": "number", "description": "Advance payment amount AFTER the correction (FakturaKorygujacaZaliczkowa)." }, "correctionSettlementAmountAfter": { "type": "number", "description": "Settlement amount AFTER the correction (FakturaKorygujacaRozliczeniowa)." }, "issueDate": { "type": "string", "format": "date", "description": "Issue date (ISO 8601)", "example": "2026-05-07" }, "documentNo": { "type": "integer", "minimum": 1, "description": "Optional document number. If provided, it is used instead of automatic numbering.", "example": 1 }, "numberingFormat": { "type": "string", "enum": [ "/MM/YYYY", "YYYY/MM/", "/YYYY/MM", "MM/YYYY/", "/YYYY", "YYYY/", "-MM-YYYY", "YYYY-MM-", "-YYYY-MM", "MM-YYYY-", "-YYYY", "YYYY-" ], "description": "Numbering format (e.g. \"/MM/YYYY\"). Defaults to the user's settings.", "example": "/MM/YYYY" }, "symbol": { "type": "string", "description": "Document symbol prefix (e.g. \"FV/\"). Defaults to the settings.", "example": "FV/" }, "documentNumber": { "type": "string", "description": "Full document number for exact (1:1) validation. If provided together with documentNo, the two must be consistent.", "example": "FV/1/05/2026" }, "invoiceName": { "type": "string", "description": "Invoice name (e.g. for advance invoices)", "example": "Faktura zaliczkowa" }, "buyerId": { "type": "string", "description": "ID of an existing client. Do not combine with buyer. buyerId or buyer is required (except corrections, which take the buyer from the corrected invoice).", "example": "681a3b2c4d5e6f7a8b9c0d1e" }, "buyer": { "$ref": "#/components/schemas/ClientReference" }, "receiverId": { "type": "string", "description": "ID of an optional receiver (for invoices with multiple parties)." }, "receiver": { "$ref": "#/components/schemas/ClientReference" }, "products": { "type": "array", "description": "Document lines. Corrections: the full list of lines AFTER the correction (document totals are the difference to the corrected invoice). FakturaZaliczka: omit, the lines are the split of the advance over the order's VAT rates.", "items": { "type": "object", "required": [ "name", "unitOfMeasure", "quantity" ], "properties": { "name": { "type": "string", "example": "Usługa programistyczna" }, "gtu": { "type": "string", "nullable": true, "enum": [ "GTU_01", "GTU_02", "GTU_03", "GTU_04", "GTU_05", "GTU_06", "GTU_07", "GTU_08", "GTU_09", "GTU_10", "GTU_11", "GTU_12", "GTU_13", null ], "description": "GTU code (optional)" }, "pkwiu": { "type": "string", "nullable": true }, "unitOfMeasure": { "type": "string", "example": "szt." }, "quantity": { "type": "number", "example": 1 }, "netPrice": { "type": "number", "nullable": true, "description": "Net unit price. When provided, netValue/amountOfVat/grossValue are calculated automatically.", "example": 100 }, "grossPrice": { "type": "number", "nullable": true, "description": "Gross unit price (alternative to netPrice).", "example": 123 }, "netValue": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 100 }, "grossValue": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 123 }, "amountOfVat": { "type": "number", "nullable": true, "description": "Optional, the values may be recalculated automatically.", "example": 23 }, "vatRate": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": 23, "description": "VAT rate from the AppData.VatRates dictionary. Validated by the backend, which also sets taxSymbol. Missing = the account's default rate (settings.defaultTaxRate). \"marza\" = a margin-scheme line (Articles 119 and 120 of the VAT Act): send grossPrice; the invoice shows gross amounts only and KSeF gets the total in P_13_11. Requires annotations.marginProcedure (otherwise 422 MARGIN_LINE_WITHOUT_PROCEDURE)." }, "marginPurchaseValue": { "type": "number", "nullable": true, "minimum": 0, "description": "vatRate \"marza\" only: gross purchase amount of the whole line in PLN (second-hand goods: the purchase price; travel agency: the costs of services bought for the tourist). It never appears on the invoice or in KSeF; it gives the margin and the VAT on the margin in the VAT register and JPK. Missing = to be added later. Left out on a correction: taken from the corrected line with the same name, in proportion to the quantity.", "example": 3000 }, "marginTaxRate": { "type": "number", "nullable": true, "enum": [ 23, 8, 5, 0, null ], "description": "vatRate \"marza\" only: rate of the VAT on the margin (VAT = margin × rate / (100 + rate); a negative margin = VAT 0). Default 23.", "example": 23 }, "discount": { "type": "number", "example": 0 }, "currency": { "type": "string", "example": "PLN" } } } }, "useAccountDefaults": { "type": "boolean", "description": "Defaults to true: missing fields get the account's settings like a new document in the app (comments, signatures, place of issue, automatic annotations MPP/margin with the VAT account, exemption basis for the zw rate, payment method and status, line VAT rate). A field you send always wins. false = no account defaults. A correction still takes the buyer, receiver, currency and annotations from the corrected invoice when you do not send them.", "example": true }, "currency": { "type": "string", "description": "Document currency (ISO 4217)", "example": "PLN" }, "exchangeRate": { "type": "number", "description": "Exchange rate for foreign currencies" }, "issuePlace": { "type": "string", "description": "Place of issue", "example": "Warszawa" }, "comments": { "type": "string", "description": "Document notes" }, "paymentDescription": { "type": "string", "description": "Payment description" }, "showPaymentSection": { "type": "boolean", "description": "Whether to show the payment section on the document/PDF. For Zamowienie documents it can be set to false." }, "paymentDeadlineDate": { "type": "string", "format": "date", "description": "Payment due date (required when paymentStatusId=1). Ignored for the Zapłacono (paid) status." }, "additionalPaymentDate": { "type": "string", "format": "date", "description": "Payment received date (required when paymentStatusId=0). Ignored for the Do zapłaty (to be paid) status." }, "additionalPaymentDateHeaderId": { "type": "number", "description": "Payment date header ID from the paymentDateHeaders dictionary. For paymentStatusId=0 the default is id=2 (\"Data otrzymania zapłaty\").", "example": 2 }, "subDate": { "type": "string", "format": "date", "description": "Sale / service date. For KSeF invoices and Zamowienie documents, issueDate is used by default if not provided." }, "subDateHeaderId": { "type": "number", "description": "Sale date header ID from the additionalDateHeaders dictionary (e.g. 1 => \"Data wykonania usługi\").", "example": 1 }, "subDateTo": { "type": "string", "format": "date", "nullable": true, "description": "End of the sale period (KSeF OkresFa, P_6_Do). With it, subDate is the start of the period, e.g. a service for a whole month. Without it, subDate is a single sale date (P_6). A correction without subDate takes the sale date or period of the corrected invoice." }, "taxPointRule": { "type": "string", "nullable": true, "enum": [ "art19a5p3a", "art19a5p3b", "art19a5p3c", "art19a5p4", null ], "description": "Tax point at the issue of the invoice (art. 19a ust. 5 of the VAT Act): art19a5p3a construction services (at the latest the 30th day after completion), art19a5p3b supply of books and press (60th day), art19a5p3c printing of books and press (90th day), art19a5p4 utilities, telecommunications, rent, lease, leasing, security, ongoing legal and office services (at the latest when the payment is due). Not sent to KSeF; it decides the period in VAT reports and the day of the exchange rate. null = the usual rules (the sale date)." }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true, "description": "Day of the NBP table exchangeRate comes from. Under art. 31a of the VAT Act it is the last business day before the tax point (usually before the sale date), or before the issue date when the invoice comes first. A correction without exchangeRate takes the rate, its day and table from the corrected invoice (art. 31b ust. 1)." }, "exchangeRateTable": { "type": "string", "nullable": true, "maxLength": 32, "example": "190/A/NBP/2026", "description": "NBP table number of exchangeRate, printed on the PDF next to the rate." }, "paymentInstallments": { "type": "array", "maxItems": 100, "description": "Instalments with custom amounts (e.g. a larger first instalment): at least two due dates with amounts (KSeF TerminPlatnosci; the instalment amounts go to DodatkowyOpis). Only with paymentStatusId=1; the instalments must add up to the amount due to the grosz, the dates must be in order and not before the issue date. Without paymentDeadlineDate the first instalment is the document's payment deadline. For equal instalments send paymentInstallmentsSplit instead of computing the amounts (do not combine the two fields).", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-10-20" }, "amount": { "type": "number", "example": 615 } } } }, "paymentInstallmentsSplit": { "type": "object", "nullable": true, "required": [ "count" ], "description": "Equal instalments computed by the API: recommended whenever the instalments should be equal. Send the number of instalments; once the document totals are computed the API splits the amount due to the grosz: every instalment gets the same amount and the rounding remainder goes to the last one (100.00 in 3 instalments = 33.33 + 33.33 + 33.34). The document stores ordinary paymentInstallments (returned in the response and in the preview) and its payment deadline (paymentDeadlineDate) is the date of the first instalment. Only with paymentStatusId=1; on create without paymentStatusId the document becomes unpaid (to pay). Instalments with different amounts (e.g. a larger first instalment) go in paymentInstallments; do not combine the two fields. A PATCH without products splits the amount stored in the document. Errors: 422 PAYMENT_INSTALLMENTS_INVALID. null = no split.", "properties": { "count": { "type": "integer", "minimum": 2, "maximum": 100, "example": 3, "description": "Number of instalments, 2 to 100 (the KSeF limit)." }, "firstDate": { "type": "string", "format": "date", "example": "2026-10-21", "description": "Due date of the first instalment, not before the issue date. Defaults to paymentDeadlineDate from the request; on an update, the stored payment deadline of a document to pay; otherwise the issue date + 14 days." }, "every": { "type": "string", "enum": [ "month", "week", "14days" ], "default": "month", "example": "month", "description": "Interval between instalments: month = monthly (counted from the first date: 31 Jan, 28 Feb, 31 Mar), week = every 7 days, 14days = every 14 days. Default: month." } } }, "paymentDeadlineTerm": { "type": "object", "nullable": true, "description": "Due date in words (KSeF TerminOpis), e.g. 14 days from the invoice date. Printed next to the due date.", "required": [ "count", "unit", "event" ], "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9999, "example": 14 }, "unit": { "type": "string", "enum": [ "day", "week", "month" ], "example": "day" }, "event": { "type": "string", "enum": [ "issue", "invoice_delivery", "supply", "acceptance" ], "example": "issue", "description": "What the term counts from: issue the issue of the invoice, invoice_delivery delivery of the invoice, supply the supply of goods or services, acceptance acceptance." } } }, "advanceReceipts": { "type": "array", "maxItems": 31, "description": "Advance invoice documenting several payments (KSeF ZaliczkaCzesciowa): at least two receipts dated no later than the issue date and adding up to advancePaymentAmount, with paymentStatusId=0. In a foreign currency each receipt has its own rate from the business day before it arrived (art. 31a). Each receipt is a separate tax point in VAT reports. Ignored for other document types.", "items": { "type": "object", "required": [ "date", "amount" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-10" }, "amount": { "type": "number", "example": 500 }, "exchangeRate": { "type": "number", "nullable": true, "example": 4.4512 }, "exchangeRateDate": { "type": "string", "format": "date", "nullable": true, "example": "2026-09-09" } } } }, "bankAccounts": { "type": "array", "description": "Bank accounts to show on the document. The first account goes to bankAccountNumber, the rest to 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 } } } }, "vatAccountNumber": { "type": "string", "description": "VAT account number (split payment / MPP)." }, "vatAccountBank": { "type": "string", "description": "Bank name of the VAT account." }, "vatAccountSwift": { "type": "string", "description": "SWIFT code of the VAT account." }, "vatAccountDescription": { "type": "string", "description": "VAT account description." }, "paymentMethodId": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Payment method ID: 1=Cash, 2=Card, 3=Voucher, 4=Check, 5=Credit, 6=Bank transfer, 7=Mobile payment", "example": 6 }, "paymentStatusId": { "type": "integer", "enum": [ 0, 1 ], "description": "0=Paid (requires additionalPaymentDate or partialPayments), 1=Due (requires paymentDeadlineDate)", "example": 1 }, "partialPayments": { "type": "array", "maxItems": 100, "description": "Partial payments made by the issue date (KSeF ZaplataCzesciowa). With paymentStatusId=1 their sum must be lower than the amount due. With paymentStatusId=0 at least two payments summing to the amount due. A payment date cannot be later than the issue date.", "items": { "type": "object", "required": [ "amount", "date" ], "properties": { "amount": { "type": "number", "example": 500 }, "date": { "type": "string", "format": "date", "example": "2026-09-14" }, "paymentMethodId": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "nullable": true, "description": "Payment form as paymentMethodId; absent = not given", "example": 1 } } } }, "annotations": { "$ref": "#/components/schemas/AnnotationsInput" }, "additionalInfo": { "$ref": "#/components/schemas/AdditionalInfoInput" }, "linkedOrderId": { "type": "string", "description": "Order ID (required for FakturaZaliczka)" }, "advancePaymentAmount": { "type": "number", "minimum": 0.01, "description": "Advance payment amount (required for FakturaZaliczka)" }, "correctedInvoiceId": { "type": "string", "description": "ID of the corrected invoice (required for FakturaKorygujaca, FakturaKorygujacaZaliczkowa and FakturaKorygujacaRozliczeniowa). When you do not send the buyer, receiver, currency or annotations, the correction takes them from this invoice." }, "correctionReason": { "type": "string", "maxLength": 256, "description": "Correction reason: the description printed on the PDF and sent to KSeF (PrzyczynaKorekty). Optional, at most 256 characters (KSeF limit)." }, "correctionCause": { "type": "string", "nullable": true, "enum": [ "after_sale", "mistake", null ], "example": "after_sale", "description": "Cause of the correction: after_sale (an event after the sale: discount, return of goods, complaint, price or quantity changed after the sale) or mistake (an error on the corrected invoice). Sets the TypKorekty sent to KSeF when you leave out correctionType, and the period in which the correction enters the VAT and KPiR reports. Without a cause the correction goes to KSeF with TypKorekty 2, as before. Applies to correcting invoices only; for other types the field is ignored." }, "correctionType": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, null ], "example": 1, "description": "KSeF TypKorekty set by hand: 1 = effect on the date the original invoice was recorded, 2 = on the issue date of the correcting invoice, 3 = on another date. Leave it out and Fakturnia works it out when sending: after_sale or no cause gives 2; mistake gives 1 when the correction raises the amounts, does not change them or takes the whole invoice to zero (wrong buyer, duplicate), 2 when it lowers them, and 3 when it raises one rate and lowers another. Applies to correcting invoices only." }, "correctionEffectDate": { "type": "string", "format": "date", "nullable": true, "description": "Corrections: the day the correction takes effect for VAT when it is neither the date of the corrected invoice nor the date of the correction. For an increase after the sale (after_sale) it is the day the cause arose, e.g. a price rise was agreed (art. 29a ust. 17); in another month than the correction it gives TypKorekty 3. With correctionType=3 set by hand it is the day of the effect. KSeF has no field for it; the VAT report and JPK place the correction on this day." }, "correctionConfirmationDate": { "type": "string", "format": "date", "nullable": true, "description": "Decreasing corrections issued outside KSeF: the day the buyer's confirmation of receipt arrived. Under art. 29a ust. 13a the decrease counts in the period the confirmation arrived in, and the VAT report places it there." }, "linkedAdvanceInvoiceIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of advance invoices to settle (required for FakturaRozliczeniowa)" }, "prepaymentIds": { "type": "array", "items": { "type": "string" } }, "settlementAmount": { "type": "number", "description": "Settlement amount (FakturaRozliczeniowa). Passed through without automatic calculations." }, "isSettlementAmountManual": { "type": "boolean", "description": "Whether settlementAmount was provided manually." }, "signatures": { "type": "object", "description": "Signatures on the PDF (person authorized to issue/receive the document).", "properties": { "issuerSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } }, "receiverSignature": { "type": "object", "properties": { "show": { "type": "boolean" }, "value": { "type": "string" } } } } }, "ksefJst": { "type": "boolean", "description": "Whether the document is for a JST entity (Polish local government unit)" } } } }, "headers": { "X-Request-ID": { "description": "Unique id of this request. Quote it when contacting support about a specific call.", "schema": { "type": "string", "format": "uuid", "example": "3f1c9a2e-7b7d-4c1a-9c1e-2b6f0d8e5a11" } }, "X-RateLimit-Limit": { "description": "Requests allowed in the current window for this endpoint (or the global window).", "schema": { "type": "integer", "example": 100 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "example": 97 } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the current window resets.", "schema": { "type": "integer", "example": 1790000000 } }, "Retry-After": { "description": "Seconds to wait before retrying (sent with 429).", "schema": { "type": "integer", "example": 12 } }, "Idempotent-Replayed": { "description": "Present (true) when the response was replayed from an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://prod.api.fakturnia.pl/v1/oauth/token", "scopes": { "documents:browse": "Wyszukiwanie dokumentów", "documents:read": "Pobieranie dokumentu po ID", "documents:download": "Pobieranie PDF dokumentu", "documents:create": "Tworzenie dokumentów", "documents:delete": "Usuwanie dokumentów", "documents:update": "Edycja dokumentów", "documents:update-payment-status": "Zmiana statusu płatności dokumentu", "documents:update-external-reference": "Powiązanie dokumentu z zamówieniem zewnętrznym", "documents:send-to-ksef": "Wysyłka dokumentów do KSeF", "ksef:read": "Podgląd statusu połączenia KSeF", "ksef:configure": "Konfiguracja połączenia KSeF", "ksef:test": "Test połączenia KSeF", "webhooks:read": "Podgląd webhooków i historii dostaw", "webhooks:create": "Tworzenie webhooków", "webhooks:update": "Edycja webhooków, rotacja sekretu i wysyłka testowa", "webhooks:delete": "Usuwanie webhooków", "email-accounts:browse": "Lista podłączonych kont pocztowych", "email-accounts:read": "Szczegóły konta pocztowego", "settings:read": "Podgląd ustawień", "settings:update": "Edycja ustawień", "gus:company:read": "Pobieranie danych firmy po NIP z GUS", "clients:browse": "Wyszukiwanie klientów", "clients:read": "Pobieranie klienta po ID", "clients:create": "Tworzenie klientów", "clients:update": "Edycja klientów", "clients:delete": "Usuwanie klientów", "products:browse": "Wyszukiwanie produktów", "products:read": "Pobieranie produktu po ID", "products:create": "Tworzenie produktów", "products:update": "Edycja produktów", "products:delete": "Usuwanie produktów", "warehouse:browse": "Lista magazynów", "warehouse:create": "Tworzenie magazynów", "warehouse:update": "Edycja magazynów", "warehouse:delete": "Usuwanie magazynów", "warehouse:stock:read": "Raport stanów magazynowych", "warehouse:adjust": "Korekty stanów (inwentaryzacja)", "warehouse:wz:create": "Wystawianie WZ do faktur", "warehouse:documents:create": "Wystawianie dokumentów magazynowych (WZ, PZ, PW, RW, MM)", "employees:browse": "Lista kont pracowniczych", "employees:create": "Tworzenie kont pracowniczych", "employees:update": "Edycja kont pracowniczych i uprawnień", "employees:delete": "Usuwanie kont pracowniczych", "recurring:browse": "Lista reguł cyklicznych", "recurring:read": "Szczegóły reguły i historia generacji", "recurring:toggle": "Pauza i wznowienie reguły", "activity:read": "Historia aktywności konta (właściciel i pracownicy)" } } } } } }, "paths": { "/documents/": { "get": { "operationId": "browseDocuments", "summary": "Get list of documents", "description": "Paginated list of documents, newest first. Combine `documentType`, the issue-date range, buyer identifiers and `onlyUnlinked` to find what an integration needs.\n\n**Required permission (Scope)**: `documents:browse`\n\n**Rate limit**: 10 / 30 s", "parameters": [ { "name": "searchQuery", "in": "query", "required": false, "description": "Filter documents by document number", "schema": { "type": "string" } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Number of documents per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "currentPage", "in": "query", "required": false, "description": "Current page number (starting from 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "buyerNip", "in": "query", "required": false, "description": "Filter documents by buyer NIP", "schema": { "type": "string" } }, { "name": "buyerVatUE", "in": "query", "required": false, "description": "Filter documents by buyer VAT UE number", "schema": { "type": "string" } }, { "name": "buyerIdentifier", "in": "query", "required": false, "description": "Filter documents by buyer other tax identifier", "schema": { "type": "string" } }, { "name": "excludeIds", "in": "query", "required": false, "description": "Comma-separated list of document IDs to exclude from results", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "description": "List order (newest first): createdAt = creation date (default), issueDate = issue date.", "schema": { "type": "string", "enum": [ "createdAt", "issueDate" ], "default": "createdAt" } }, { "name": "onlyUnlinked", "in": "query", "required": false, "description": "If true, only return documents that have no externalSource (not linked to any external order)", "schema": { "type": "boolean", "default": false } }, { "name": "documentType", "in": "query", "required": false, "description": "Filter by document type. Accepts a single type or a comma-separated list (e.g. FakturaVAT,FakturaKorygujaca)", "schema": { "type": "string", "example": "FakturaVAT" } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Filter by issue date: inclusive lower bound (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Filter by issue date: inclusive upper bound (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2026-01-31" } } ], "responses": { "200": { "description": "List of documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" }, "example": { "success": true, "data": { "documents": [], "currentPage": 1, "totalPages": 5, "totalCount": 50, "itemsPerPage": 10, "searchQuery": "FV/2023/001" }, "executionTime": 50 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:browse" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] }, "post": { "operationId": "createDocument", "summary": "Create a new document", "description": "Creates an invoice or related document. Numbers are auto-generated unless explicitly provided. Seller is taken from user.company. Partial payments (partialPayments) that do not fit the document are rejected with 422 PARTIAL_PAYMENTS_INVALID. Identifiers of a buyer or receiver given as data follow the contractor rules: a missing identifierType is inferred (a VAT UE number given in nip is stored as vatEu in vatUE) and reported in data.warnings; contradictions (e.g. identifierType nip with DE123456789, vatEu with a PL or XI number, a NIP with a wrong check digit, idWew for a buyer) are rejected with 422 PARTY_IDENTIFIER_INVALID naming the field (buyer.nip, receiver.vatUE). Equal instalments: send paymentInstallmentsSplit { count, firstDate?, every? } and the API splits the final amount due to the grosz (the remainder on the last instalment) and stores ordinary paymentInstallments; instalments that cannot be made (or both paymentInstallments and paymentInstallmentsSplit) are rejected with 422 PAYMENT_INSTALLMENTS_INVALID. A document has at most one live correction: a new correction of a document that already has one is rejected with 409 CORRECTED_INVOICE_HAS_CORRECTION, whose message names the latest correction of the chain; the next change corrects that correction (correctedInvoiceId = its id), so its state before includes the earlier changes. In KSeF a correction of a correction names the original invoice (DaneFaKorygowanej).\n\n**Required permission (Scope)**: `documents:create`\n\n**Idempotency-Key**: supported (the response is kept for 24 h; a retry with the same key returns the same result).\n\n**Rate limit**: 30 / 60 s\n\n**Emitted webhooks**:\n- `document.created` (on statuses: 201)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique idempotency key (UUID v4 recommended). Protects against duplicating operations on retry. Stored for 24h.", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequestBody" }, "example": { "documentType": "FakturaVAT", "issueDate": "2026-05-07", "buyer": { "nip": "5261040828", "name": "Acme Corp Sp. z o.o.", "street": "Marszałkowska 1", "postalCode": "00-001", "city": "Warszawa", "country": "Polska", "countryCode": "PL" }, "products": [ { "name": "Usługa programistyczna", "unitOfMeasure": "szt.", "quantity": 1, "netPrice": 100, "netValue": 100, "grossValue": 123, "amountOfVat": 23, "vatRate": 23 } ], "paymentMethodId": 6, "paymentStatusId": 1, "paymentDeadlineDate": "2026-05-14" } } } }, "responses": { "201": { "description": "Document created successfully", "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": "5261040828", "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 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request body (missing required fields, invalid types, ambiguous buyer/receiver)", "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." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (missing or invalid JWT token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "UNAUTHORIZED", "executionTime": 2, "errors": null } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden (no active PRO/MAX plan, document limit exceeded or missing scope). Reasons: \"Subskrypcja nieaktywna. Do wystawiania dokumentów potrzebujesz aktywnego planu PRO lub MAX.\", \"Subskrypcja wygasła. Do wystawiania dokumentów potrzebujesz aktywnego planu PRO lub MAX.\", \"Osiągnięto limit N dokumentów w miesiącu. Wykup wyższą subskrypcję, aby tworzyć więcej dokumentów.\"", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "DOCUMENT_LIMIT_EXCEEDED", "executionTime": 18, "errors": [ "Subskrypcja nieaktywna. Do wystawiania dokumentów potrzebujesz aktywnego planu PRO lub MAX." ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Related resource not found (buyer, corrected invoice, linked order, etc.)", "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." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Document number already exists, or the corrected document already has a correction (CORRECTED_INVOICE_HAS_CORRECTION: correct its latest correction instead)", "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." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Business validation failed (annotation conflicts, missing payment dates, type-specific requirements, PARTIAL_PAYMENTS_INVALID when partialPayments do not fit the document, PARTY_IDENTIFIER_INVALID when buyer or receiver identifiers contradict each other)", "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)." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "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" } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:create" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}": { "get": { "operationId": "getDocument", "summary": "Get document details", "description": "One document by id, with computed totals, payment fields and KSeF state.\n\n**Required permission (Scope)**: `documents:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSuccessResponse" }, "example": { "success": true, "data": { "document": {} }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid document ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:read" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] }, "delete": { "operationId": "deleteDocument", "summary": "Delete a document", "description": "Deletes a document that is not in KSeF. A document confirmed in KSeF (KSEF_CONFIRMED) or awaiting confirmation (KSEF_SENT) cannot be deleted; issue a correction instead. Linked documents are protected like in the app: an invoice that has a correction (409 DOCUMENT_CORRECTED), an advance invoice settled by a settlement invoice (409 ADVANCE_INVOICE_SETTLED) and an order with advance invoices (400 ORDER_HAS_ADVANCE_INVOICES). Deleting a warehouse document (WZ, PZ, PW, RW, MM) reverses its stock movements; deleting the last correction unlocks the corrected invoice.\n\n**Required permission (Scope)**: `documents:delete`\n\n**Emitted webhooks**:\n- `document.deleted` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" }, "example": { "success": true, "data": { "id": "681a3b2c4d5e6f7a8b9c0d1e" }, "message": "Document deleted.", "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request, KSeF blocked (KSEF_CONFIRMED / KSEF_SENT), order with advance invoices (ORDER_HAS_ADVANCE_INVOICES), or missing parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized: missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden: missing documents:delete scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found or not owned by authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:delete" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] }, "put": { "operationId": "updateDocument", "summary": "Full update of an existing document", "description": "Replaces all editable fields of a document. documentType is immutable and cannot be changed. Buyer can be referenced by buyerId or inline buyer object. Seller is always taken from user.company and cannot be overwritten. An order (Zamowienie) that already has advance invoices is locked: the update is rejected with 400 ORDER_HAS_ADVANCE_INVOICES. Partial payments (partialPayments) that do not fit the document are rejected with 422 PARTIAL_PAYMENTS_INVALID. A buyer or receiver given as data follows the contractor identifier rules like on create (inferred identifierType reported in data.warnings, 422 PARTY_IDENTIFIER_INVALID on a contradiction); identifiers equal to the stored ones are not re-checked. paymentInstallmentsSplit splits the amount due of the document as it will be saved (the stored amount when products are not sent) into equal paymentInstallments, the remainder on the last one; 422 PAYMENT_INSTALLMENTS_INVALID when they cannot be made.\n\n**Required permission (Scope)**: `documents:update`\n\n**Emitted webhooks**:\n- `document.updated` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentRequestBody" }, "example": { "issueDate": "2026-09-26", "buyerId": "681a3b2c4d5e6f7a8b9c0d1e", "products": [ { "name": "Usługa programistyczna", "unitOfMeasure": "godz.", "quantity": 10, "netPrice": 150, "vatRate": 23 } ], "paymentMethodId": 6, "paymentStatusId": 1, "paymentDeadlineDate": "2026-10-10", "comments": "Zamówienie #10234" } } } }, "responses": { "200": { "description": "Document updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSuccessResponse" }, "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 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid input, KSeF blocked, or missing parameters. Error codes: KSEF_CONFIRMED / KSEF_SENT (document already in KSeF), ORDER_HAS_ADVANCE_INVOICES (order frozen by issued advance invoices).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized: missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden: missing documents:update scope, or no active PRO/MAX plan (DOCUMENT_LIMIT_EXCEEDED, reason \"Subskrypcja nieaktywna. Do edycji i wysyłki dokumentów potrzebujesz aktywnego planu PRO lub MAX.\" or \"Subskrypcja wygasła. ...\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found or not owned by authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "DOCUMENT_NUMBER_EXISTS: the number sent as documentNo is taken, either in its series (document type group, numbering format and month or year of the issue date) or, when the number changes, as the same full number anywhere on the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error: malformed payload, or PARTIAL_PAYMENTS_INVALID (partialPayments do not fit the document), or PARTY_IDENTIFIER_INVALID (buyer or receiver identifiers contradict each other).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:update" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] }, "patch": { "operationId": "patchDocument", "summary": "Partial update of a document field(s)", "description": "Updates only the provided fields of a document. All fields are optional: send only what needs to change. documentType is immutable and cannot be changed. Seller is always taken from user.company and cannot be overwritten. An order (Zamowienie) that already has advance invoices is locked: the update is rejected with 400 ORDER_HAS_ADVANCE_INVOICES. Partial payments (partialPayments) that do not fit the document are rejected with 422 PARTIAL_PAYMENTS_INVALID. A buyer or receiver given as data follows the contractor identifier rules like on create (inferred identifierType reported in data.warnings, 422 PARTY_IDENTIFIER_INVALID on a contradiction); identifiers equal to the stored ones are not re-checked. paymentInstallmentsSplit splits the amount due of the document as it will be saved (the stored amount when products are not sent) into equal paymentInstallments, the remainder on the last one; 422 PAYMENT_INSTALLMENTS_INVALID when they cannot be made.\n\n**Required permission (Scope)**: `documents:update`\n\n**Emitted webhooks**:\n- `document.updated` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document to partially update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchDocumentRequestBody" }, "example": { "paymentDeadlineDate": "2026-10-24", "comments": "Termin wydłużony na prośbę klienta" } } } }, "responses": { "200": { "description": "Document partially updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSuccessResponse" }, "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 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid input, empty body, or KSeF blocked. Error codes: KSEF_CONFIRMED / KSEF_SENT (document already in KSeF), ORDER_HAS_ADVANCE_INVOICES (order frozen by issued advance invoices).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized: missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden: missing documents:update scope, or no active PRO/MAX plan (DOCUMENT_LIMIT_EXCEEDED, reason \"Subskrypcja nieaktywna. Do edycji i wysyłki dokumentów potrzebujesz aktywnego planu PRO lub MAX.\" or \"Subskrypcja wygasła. ...\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found or not owned by authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "DOCUMENT_NUMBER_EXISTS: the number sent as documentNo is taken, either in its series (document type group, numbering format and month or year of the issue date) or, when the number changes, as the same full number anywhere on the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error: malformed payload, or PARTIAL_PAYMENTS_INVALID (partialPayments do not fit the document), or PARTY_IDENTIFIER_INVALID (buyer or receiver identifiers contradict each other).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:update" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/download": { "get": { "operationId": "downloadDocument", "summary": "Download document", "description": "Renders the PDF of a document. When the rendering queue is full the API answers 429 WAIT_PDF_QUEUE with Retry-After; retry after that many seconds.\n\n**Required permission (Scope)**: `documents:download`\n\n**Rate limit**: 5 / 60 s", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF file (Content-Disposition: attachment)", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "PDF rendering queue is full (WAIT_PDF_QUEUE): retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:download" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/validate": { "post": { "operationId": "validateDocument", "summary": "Dry-run validation of a document payload (no DB writes)", "description": "Runs full validation pipeline and returns a preview (next number, resolved buyer/receiver, totals) without saving. Same scope as create. The preview lists the instalments that will be saved (paymentInstallments), also those computed from paymentInstallmentsSplit. Identifiers of a buyer or receiver given as data follow the contractor rules: a missing identifierType is inferred (a VAT UE number given in nip is stored as vatEu in vatUE) and reported in data.warnings; contradictions (e.g. identifierType nip with DE123456789, vatEu with a PL or XI number, a NIP with a wrong check digit, idWew for a buyer) are rejected with 422 PARTY_IDENTIFIER_INVALID naming the field (buyer.nip, receiver.vatUE).\n\n**Required permission (Scope)**: `documents:create`\n\n**Rate limit**: 30 / 60 s", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique idempotency key. For /validate use a separate keyPrefix than for /create.", "schema": { "type": "string", "example": "660e8400-e29b-41d4-a716-446655440001" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequestBody" }, "example": { "documentType": "FakturaVAT", "issueDate": "2026-05-07", "buyer": { "nip": "5261040828", "name": "Acme Corp Sp. z o.o.", "street": "Marszałkowska 1", "postalCode": "00-001", "city": "Warszawa", "country": "Polska", "countryCode": "PL" }, "products": [ { "name": "Usługa programistyczna", "unitOfMeasure": "szt.", "quantity": 1, "netPrice": 100, "vatRate": 23 } ], "subDateHeaderId": 2, "paymentMethodId": 6, "paymentStatusId": 1, "paymentDeadlineDate": "2026-05-14" } } } }, "responses": { "200": { "description": "Validation succeeded: returns preview (no DB writes)", "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": "5261040828", "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", "warnings": [] }, "valid": true }, "message": "VALIDATION_SUCCESSFUL", "executionTime": 38 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request body", "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." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "UNAUTHORIZED", "executionTime": 2, "errors": null } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden (missing scope)", "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" } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Related resource not found", "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." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Document number already exists", "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." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Business validation failed (also PARTY_IDENTIFIER_INVALID when buyer or receiver identifiers contradict each other)", "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." } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "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" } ] } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:create" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/payment-status": { "patch": { "operationId": "updateDocumentPaymentStatus", "summary": "Update document payment status", "description": "Updates payment receipt state for a document. Supported values: RECEIVED or NOT_RECEIVED. paymentDate (YYYY-MM-DD, optional) is the day the payment arrived, today in Poland when omitted; it cannot be in the future. For the cash method it is the day of the VAT tax point. Allowed only for documents with payment status \"Do zapłaty\" (payment.status=1) or documents imported from KSeF (source=ksef).\n\n**Required permission (Scope)**: `documents:update-payment-status`\n\n**Emitted webhooks**:\n- `document.paymentStatusChanged` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatusInput" }, "example": { "receivedPayment": "RECEIVED" } } } }, "responses": { "200": { "description": "Payment status updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPaymentStatusResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid input or unsupported document payment state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:update-payment-status" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/external-reference": { "patch": { "operationId": "updateDocumentExternalReference", "summary": "Link document with external order reference", "description": "Links a document with an order in an external system (shop, ERP), so it can be found with `GET /documents?onlyUnlinked=false` and recognised in webhooks.\n\n**Required permission (Scope)**: `documents:update-external-reference`\n\n**Emitted webhooks**:\n- `document.updated` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReferenceInput" }, "example": { "externalSource": "woocommerce", "externalOrderId": "10234", "externalOrderNumber": "#10234" } } } }, "responses": { "200": { "description": "External reference updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentExternalReferenceResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:update-external-reference" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] }, "delete": { "operationId": "deleteDocumentExternalReference", "summary": "Remove external order reference from a document", "description": "Removes the external order link from a document.\n\n**Required permission (Scope)**: `documents:update-external-reference`\n\n**Emitted webhooks**:\n- `document.updated` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "responses": { "200": { "description": "External reference removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentExternalReferenceResponse" }, "example": { "success": true, "data": { "id": "681a3b2c4d5e6f7a8b9c0d1e", "externalSource": null, "externalOrderId": null, "externalOrderNumber": null }, "message": "External reference removed.", "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:update-external-reference" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/margin-purchases": { "patch": { "operationId": "updateDocumentMarginPurchases", "summary": "Set purchase amounts of margin-scheme lines", "description": "Sets the purchase amount (`marginPurchaseValue`, gross, PLN) and the rate of the tax on the margin (`marginTaxRate`) of lines with `vatRate: \"marza\"`, by their position in `products`. They are the seller's data for the VAT register and JPK, not invoice content, so they can change also after the document was sent to KSeF or corrected (a travel agency learns its costs later; an invoice downloaded from KSeF never carries them). A key left out keeps the stored value, `null` clears it.\n\n**Required permission (Scope)**: `documents:update`\n\n**Emitted webhooks**:\n- `document.updated` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarginPurchasesInput" }, "example": { "lines": [ { "index": 0, "marginPurchaseValue": 1500, "marginTaxRate": 23 } ] } } } }, "responses": { "200": { "description": "Purchase amounts saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentMarginPurchasesResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "MARGIN_PURCHASES_INVALID or MARGIN_LINE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:update" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/send-to-ksef": { "post": { "operationId": "sendDocumentToKsef", "summary": "Send document to KSeF", "description": "Starts KSeF instant send for an existing document. API waits for immediate KSeF result (best effort). If KSeF is still processing, endpoint returns success payload with processing status and client should poll status endpoint or consume webhook document.sentToKSeF.\n\n**Required permission (Scope)**: `documents:send-to-ksef`\n\n**Idempotency-Key**: supported (the response is kept for 24 h; a retry with the same key returns the same result).\n\n**Rate limit**: 10 / 60 s\n\n**Emitted webhooks**:\n- `document.sentToKSeF` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document to send", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key to safely retry send requests.", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Document sent and processed in KSeF (ksefNumber available).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KsefSendResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request or document cannot be sent to KSeF.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Forbidden: missing documents:send-to-ksef scope, or no active PRO/MAX plan (DOCUMENT_LIMIT_EXCEEDED, reason \"Subskrypcja nieaktywna. Do edycji i wysyłki dokumentów potrzebujesz aktywnego planu PRO lub MAX.\" or \"Subskrypcja wygasła. ...\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Conflict (already sent / already processing / no KSeF connection).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "KSEF_CONNECTION_NOT_AUTHORIZED: the KSeF connection exists but is not authorized. KSEF_VALIDATION_FAILED: the document does not meet the KSeF requirements checked before sending (for example it is sent on a day other than its issue date, or the buyer NIP has a wrong checksum); `errors` lists the reasons.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:send-to-ksef" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/ksef-status": { "get": { "operationId": "getDocumentKsefStatus", "summary": "Get document KSeF send status", "description": "Returns simplified KSeF status state to support polling after send-to-ksef.\n\n**Required permission (Scope)**: `documents:read`\n\n**Rate limit**: 5 / 60 s", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the document", "schema": { "type": "string" } } ], "responses": { "200": { "description": "KSeF status payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KsefStatusResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Too many status checks. Slow down polling (max 5 requests per minute).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:read" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/documents/{id}/history": { "get": { "operationId": "getDocumentHistory", "summary": "Get the history of a document", "description": "Activity journal of one document, newest first: CREATE, UPDATE (with the field diff in `changes`), SENT_BY_EMAIL, DOWNLOAD, KSEF_SENT, KSEF_ERROR, PAYMENT_RECEIVED, PAYMENT_REVERTED, DELETE and links to advance or settlement invoices. Each entry says who acted (owner or employee) and, when recorded, where from (`origin`: external_api, app, import). Page-based.\n\n**Required permission (Scope)**: `documents:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document id", "schema": { "type": "string" } }, { "name": "currentPage", "in": "query", "required": false, "description": "Page number, starting from 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Page size (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Journal page, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentHistoryResponse" }, "example": { "success": true, "data": { "documentId": "681a3b2c4d5e6f7a8b9c0d1e", "documentNumber": "FV/12/09/2026", "entries": [ { "id": "681a3b2c4d5e6f7a8b9c0d2a", "type": "PAYMENT_RECEIVED", "createdAt": "2026-09-26T12:00:00.000Z", "actor": "employee", "employeeId": "681a3b2c4d5e6f7a8b9c0d3b", "employeeName": "Ewa Kowalska", "origin": "external_api", "changes": null, "data": { "origin": "external_api", "receivedPayment": "RECEIVED" } }, { "id": "681a3b2c4d5e6f7a8b9c0d29", "type": "CREATE", "createdAt": "2026-09-26T10:30:00.000Z", "actor": "owner", "employeeId": null, "employeeName": null, "origin": "external_api", "changes": null, "data": { "origin": "external_api", "source": "local" } } ], "currentPage": 1, "itemsPerPage": 20, "totalCount": 2, "totalPages": 1 }, "executionTime": 9 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid pagination parameters (INVALID_PARAMS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Document not found (DOCUMENT_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "documents:read" ] }, { "BearerAuth": [] } ], "tags": [ "documents" ] } }, "/clients/": { "get": { "operationId": "browseClients", "summary": "Get list of clients", "description": "Paginated list of contractors. `searchQuery` matches name, NIP, e-mail, first and last name (case-insensitive).\n\n**Required permission (Scope)**: `clients:browse`\n\n**Rate limit**: 10 / 30 s", "parameters": [ { "name": "searchQuery", "in": "query", "required": false, "description": "Filter clients by name, NIP or email", "schema": { "type": "string" } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Number of clients per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "currentPage", "in": "query", "required": false, "description": "Current page number (starting from 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "List of clients", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientListResponse" }, "example": { "success": true, "data": { "clients": [], "currentPage": 1, "totalPages": 5, "totalCount": 50, "itemsPerPage": 10, "searchQuery": "" }, "executionTime": 50 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "clients:browse" ] }, { "BearerAuth": [] } ], "tags": [ "clients" ] }, "post": { "operationId": "createClient", "summary": "Create a new client", "description": "Adds a contractor. A company needs `name`, a person `firstName` and `lastName`; the identifier named by `identifierType` is required. identifierType: nip (Polish NIP, 10 digits with a check digit), vatEu (EU VAT number with its country prefix in vatUE, e.g. DE123456789; EL for Greece), other (country code and otherTaxIdentifier, e.g. US and 12-3456789), idWew (internal unit NIP-NNNNN), none (consumer). Without identifierType the API infers it (a VAT UE number given in nip is stored as vatEu in vatUE, the country taken from its prefix) and reports it in data.warnings. Contradictions (nip with DE123456789, vatEu with a PL or XI number, a NIP with a wrong length or check digit, other without a country, an unknown identifierType) or a malformed e-mail answer 422 VALIDATION_ERROR naming the field; a NIP already present in the account answers 409.\n\n**Required permission (Scope)**: `clients:create`\n\n**Emitted webhooks**:\n- `client.created` (on statuses: 200)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" }, "example": { "type": "company", "contractorType": "client", "identifierType": "nip", "name": "Acme Sp. z o.o.", "nip": "5261040828", "street": "Marszałkowska 1", "postalCode": "00-001", "city": "Warszawa", "country": "Polska", "countryCode": "PL", "email": "biuro@acme.pl" } } } }, "responses": { "200": { "description": "Client created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" }, "example": { "success": true, "data": { "client": {} }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Client with this NIP already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "clients:create" ] }, { "BearerAuth": [] } ], "tags": [ "clients" ] } }, "/clients/{id}": { "get": { "operationId": "getClient", "summary": "Get client details", "description": "One contractor by id.\n\n**Required permission (Scope)**: `clients:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the client", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" }, "example": { "success": true, "data": { "client": {} }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid client ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "clients:read" ] }, { "BearerAuth": [] } ], "tags": [ "clients" ] }, "put": { "operationId": "updateClient", "summary": "Update an existing client", "description": "Full replacement of a contractor (PUT): omitted optional fields are cleared. Same validation and identifier rules as on create (data.warnings reports an inferred identifierType or a moved number); identifiers and e-mail addresses are checked only when they differ from the stored ones.\n\n**Required permission (Scope)**: `clients:update`\n\n**Emitted webhooks**:\n- `client.updated` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the client to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" }, "example": { "type": "company", "contractorType": "client", "identifierType": "nip", "name": "Acme Sp. z o.o.", "nip": "5261040828", "street": "Marszałkowska 1", "postalCode": "00-001", "city": "Warszawa", "country": "Polska", "countryCode": "PL", "email": "biuro@acme.pl" } } } }, "responses": { "200": { "description": "Client updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" }, "example": { "success": true, "data": { "client": {} }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "NIP conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "clients:update" ] }, { "BearerAuth": [] } ], "tags": [ "clients" ] }, "delete": { "operationId": "deleteClient", "summary": "Delete a client", "description": "Removes a contractor from the address book. Documents already issued keep their own copy of the buyer data.\n\n**Required permission (Scope)**: `clients:delete`\n\n**Emitted webhooks**:\n- `client.deleted` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the client to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" }, "example": { "success": true, "data": { "id": "681a3b2c4d5e6f7a8b9c0d1e" }, "message": "Client deleted.", "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "clients:delete" ] }, { "BearerAuth": [] } ], "tags": [ "clients" ] } }, "/products/": { "get": { "operationId": "browseProducts", "summary": "Get list of products", "description": "Paginated list of products and services. `searchQuery` matches the name.\n\n**Required permission (Scope)**: `products:browse`\n\n**Rate limit**: 10 / 30 s", "parameters": [ { "name": "searchQuery", "in": "query", "required": false, "description": "Filter products by name", "schema": { "type": "string" } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Number of products per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "currentPage", "in": "query", "required": false, "description": "Current page number (starting from 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" }, "example": { "success": true, "data": { "products": [], "currentPage": 1, "totalPages": 5, "totalCount": 50, "itemsPerPage": 10, "searchQuery": "" }, "executionTime": 50 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "products:browse" ] }, { "BearerAuth": [] } ], "tags": [ "products" ] }, "post": { "operationId": "createProduct", "summary": "Create a new product", "description": "Adds a product or service. Send the unit price (`netPrice` or `grossPrice`) and `vatRate`; net value, VAT amount and gross value are computed to the cent.\n\n**Required permission (Scope)**: `products:create`\n\n**Emitted webhooks**:\n- `product.created` (on statuses: 200)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" }, "example": { "name": "Usługa programistyczna", "unitOfMeasure": "szt.", "quantity": 1, "netPrice": 100, "vatRate": 23, "currency": "PLN" } } } }, "responses": { "200": { "description": "Product created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "example": { "success": true, "data": { "product": {} }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "products:create" ] }, { "BearerAuth": [] } ], "tags": [ "products" ] } }, "/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get product details", "description": "One product by id.\n\n**Required permission (Scope)**: `products:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the product", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "example": { "success": true, "data": { "product": {} }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "products:read" ] }, { "BearerAuth": [] } ], "tags": [ "products" ] }, "put": { "operationId": "updateProduct", "summary": "Update an existing product", "description": "Full replacement of a product (PUT). A new `netPrice` (or `vatRate`, `quantity`, `discount`) sent without `netValue`, `amountOfVat` and `grossValue` recomputes them to the cent, with the discount. Values sent explicitly are stored as sent only when they add up (net + VAT = gross), match the VAT rate and the price; otherwise 422 VALIDATION_ERROR names the field. When the price fields do not change, the stored product is not re-checked.\n\n**Required permission (Scope)**: `products:update`\n\n**Emitted webhooks**:\n- `product.updated` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the product to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdateInput" }, "example": { "name": "Usługa programistyczna (senior)", "unitOfMeasure": "godz.", "quantity": 1, "netPrice": 150, "vatRate": 23, "currency": "PLN" } } } }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" }, "example": { "success": true, "data": { "product": {} }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "products:update" ] }, { "BearerAuth": [] } ], "tags": [ "products" ] }, "delete": { "operationId": "deleteProduct", "summary": "Delete a product", "description": "Removes a product from the catalogue. Documents already issued keep their line items.\n\n**Required permission (Scope)**: `products:delete`\n\n**Emitted webhooks**:\n- `product.deleted` (on statuses: 200)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the product to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" }, "example": { "success": true, "data": { "id": "681a3b2c4d5e6f7a8b9c0d1e" }, "message": "Product deleted.", "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "products:delete" ] }, { "BearerAuth": [] } ], "tags": [ "products" ] } }, "/dictionaries/": { "get": { "operationId": "getDictionaries", "summary": "Get static dictionaries (document types, payment methods, etc.)", "description": "Static dictionaries needed to build documents: document types, payment methods and statuses, VAT rates, GTU codes, margin procedures, VAT exemption types, currencies, countries and date headers. Only a valid token is required, no scope.", "responses": { "200": { "description": "Dictionary payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DictionariesResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "data": null, "message": "ERROR_CODE", "executionTime": 42, "errors": null } } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [] }, { "BearerAuth": [] } ], "tags": [ "dictionaries" ] } }, "/ksef/connection": { "get": { "operationId": "getKsefConnection", "summary": "Get KSeF connection status", "description": "State of the KSeF connection of the account: whether a KSeF token or a certificate is configured (`connectionType`, `hasToken`, `hasCertificate`) and authorized, the environment, permissions and the last error. Secrets are never returned.\n\n**Required permission (Scope)**: `ksef:read`", "responses": { "200": { "description": "KSeF connection status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KsefConnectionResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "ksef:read" ] }, { "BearerAuth": [] } ], "tags": [ "ksef" ] }, "post": { "operationId": "upsertKsefConnection", "summary": "Create or update KSeF connection (token or certificate)", "description": "Stores (or replaces) the KSeF connection of the account. Two methods are supported: a KSeF token (`connectionType` TOKEN with `token`) or a KSeF certificate (`connectionType` CERTIFICATE with `certificateContent`, `privateKeyContent` and `privateKeyPassword`). A body with the certificate fields and no `connectionType` is a certificate connection. Saving one method replaces the other. Secrets are encrypted at rest and never returned. Run `POST /ksef/connection/test` afterwards to authorize.\n\n**Required permission (Scope)**: `ksef:configure`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KsefConnectionInput" }, "examples": { "default": { "summary": "KSeF token", "value": { "connectionType": "TOKEN", "token": "20260901-EC-1A2B3C4D5E-6F7A8B9C0D-E1|nip-5261040828|0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "environment": "test" } }, "certificate": { "summary": "KSeF certificate", "value": { "certificateContent": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----", "privateKeyContent": "-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIF...\n-----END ENCRYPTED PRIVATE KEY-----", "privateKeyPassword": "haslo-do-klucza", "environment": "test" } } } } } }, "responses": { "200": { "description": "KSeF connection saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KsefConnectionSavedResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "ksef:configure" ] }, { "BearerAuth": [] } ], "tags": [ "ksef" ] }, "delete": { "operationId": "deleteKsefConnection", "summary": "Deactivate KSeF connection", "description": "Deactivates the KSeF connection and removes the stored credentials (KSeF token, or certificate and private key).\n\n**Required permission (Scope)**: `ksef:configure`", "responses": { "200": { "description": "KSeF connection deactivated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KsefConnectionDeletedResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "ksef:configure" ] }, { "BearerAuth": [] } ], "tags": [ "ksef" ] } }, "/ksef/connection/test": { "post": { "operationId": "testKsefConnection", "summary": "Test KSeF connection authorization and permissions", "description": "Authenticates in KSeF with the stored credentials (KSeF token or certificate) and records the result on the connection. Answers 200 with `isAuthorized` false when KSeF rejects the credentials.\n\n**Required permission (Scope)**: `ksef:test`\n\n**Rate limit**: 5 / 60 s", "responses": { "200": { "description": "KSeF connection test result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KsefConnectionTestResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "ksef:test" ] }, { "BearerAuth": [] } ], "tags": [ "ksef" ] } }, "/webhooks/": { "get": { "operationId": "getWebhooks", "summary": "List webhooks", "description": "All webhooks of the account, newest first, without secrets. With `?endpoint=` the response also says whether a webhook for that URL exists (used by plugins that register themselves with POST /webhooks/initial).\n\n**Required permission (Scope)**: `webhooks:read`", "parameters": [ { "name": "endpoint", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional endpoint URL to check if initial webhook exists." } ], "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or no MAX plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:read" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] }, "post": { "operationId": "createWebhook", "summary": "Create a webhook", "description": "Registers a public HTTPS endpoint for the chosen events. The signing secret is returned once, in this response only; rotate it with POST /webhooks/{id}/rotate-secret when lost. One webhook per endpoint URL.\n\n**Required permission (Scope)**: `webhooks:create`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" }, "example": { "endpoint": "https://erp.example.com/hooks/fakturnia", "events": [ "document.created", "document.sentToKSeF", "document.ksefRejected" ], "description": "ERP" } } } }, "responses": { "201": { "description": "Webhook created; `secret` is shown only here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreatedResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (UNAUTHORIZED, TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope (NO_PERMISSIONS) or no MAX plan (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Webhook not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "A webhook for this endpoint already exists (CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error: unknown event, empty event list, private or non-http(s) endpoint (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:create" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/webhooks/initial": { "post": { "operationId": "createInitialWebhook", "summary": "Create the initial webhook of a plugin (all events)", "description": "Convenience endpoint for plugins: registers the endpoint for every event, idempotently per URL. Calling it again for the same URL returns `created: false`; with `rotateSecret: true` it issues a new secret. For a custom event subscription use POST /webhooks.\n\n**Required permission (Scope)**: `webhooks:create`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialWebhookInput" }, "example": { "endpoint": "https://shop.example.com/wp-json/fakturnia/v1/webhook", "siteName": "Sklep Example", "domain": "shop.example.com", "rotateSecret": false } } } }, "responses": { "200": { "description": "Webhook created or already existing; `secret` present only when created or rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialWebhookResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Missing, non-URL, private or non-http(s) endpoint (BAD_REQUEST)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or no MAX plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:create" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Get a webhook", "description": "Returns one webhook with its delivery counters. The signing secret is never returned.\n\n**Required permission (Scope)**: `webhooks:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (the `id` field of a webhook object)", "schema": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" } } ], "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (UNAUTHORIZED, TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope (NO_PERMISSIONS) or no MAX plan (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Webhook not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:read" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] }, "patch": { "operationId": "updateWebhook", "summary": "Update a webhook", "description": "Partial update: only the keys present in the body change. `events` replaces the whole subscription list. Setting `status` to ACTIVE re-enables a webhook switched off automatically after repeated failures and resets its failure streak.\n\n**Required permission (Scope)**: `webhooks:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (the `id` field of a webhook object)", "schema": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPatchInput" }, "example": { "events": [ "document.created", "document.paymentStatusChanged" ], "status": "ACTIVE" } } } }, "responses": { "200": { "description": "Updated webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (UNAUTHORIZED, TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope (NO_PERMISSIONS) or no MAX plan (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Webhook not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error: empty body, unknown event, status other than ACTIVE/INACTIVE, private endpoint (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:update" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "description": "Removes the webhook; pending deliveries are cancelled and no further events are sent to its endpoint.\n\n**Required permission (Scope)**: `webhooks:delete`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (the `id` field of a webhook object)", "schema": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (UNAUTHORIZED, TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope (NO_PERMISSIONS) or no MAX plan (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Webhook not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:delete" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret of a webhook", "description": "Generates a new secret and returns it once. Deliveries sent after this call are signed with the new secret, so update the receiver first, then rotate.\n\n**Required permission (Scope)**: `webhooks:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (the `id` field of a webhook object)", "schema": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" } } ], "responses": { "200": { "description": "New secret (shown only here)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (UNAUTHORIZED, TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope (NO_PERMISSIONS) or no MAX plan (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Webhook not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:update" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "getWebhookDeliveries", "summary": "List recent deliveries of a webhook", "description": "Newest first, page-based. Use it to debug a receiver: each row shows the event, the attempt count, the next retry and the last error. Delivery records are kept for 30 days.\n\n**Required permission (Scope)**: `webhooks:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (the `id` field of a webhook object)", "schema": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" } }, { "name": "status", "in": "query", "required": false, "description": "Only deliveries in this state", "schema": { "type": "string", "enum": [ "PENDING", "SUCCESS", "FAILED", "CANCELLED" ] } }, { "name": "currentPage", "in": "query", "required": false, "description": "Page number, starting from 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Page size (default 20, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Deliveries, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveriesResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Unknown status filter or bad pagination (INVALID_PARAMS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (UNAUTHORIZED, TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope (NO_PERMISSIONS) or no MAX plan (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Webhook not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:read" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test delivery to a webhook", "description": "Delivers a `webhook.test` event to the endpoint right away, signed like a real delivery, and reports the HTTP outcome. The ping is sent regardless of the subscribed events, is never retried and does not count towards the automatic switch-off.\n\n**Required permission (Scope)**: `webhooks:update`\n\n**Rate limit**: 5 / 60 s", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id (the `id` field of a webhook object)", "schema": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" } } ], "responses": { "200": { "description": "Outcome of the test delivery (`ok` false when the endpoint did not answer 2xx)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized (UNAUTHORIZED, TOKEN_EXPIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope (NO_PERMISSIONS) or no MAX plan (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Webhook not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Too many test deliveries (max 5 per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "webhooks:update" ] }, { "BearerAuth": [] } ], "tags": [ "webhooks" ] } }, "/settings/": { "get": { "operationId": "getSettings", "summary": "Get general and numbering settings", "description": "General settings (date format, newsletter) and numbering settings (numbering type and format, document symbols), with the allowed options.\n\n**Required permission (Scope)**: `settings:read`", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "settings:read" ] }, { "BearerAuth": [] } ], "tags": [ "settings" ] } }, "/settings/general": { "patch": { "operationId": "updateGeneralSettings", "summary": "Update general settings (date format, newsletter)", "description": "Sets the date format printed on documents and the newsletter consent.\n\n**Required permission (Scope)**: `settings:update`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralSettingsInput" }, "example": { "dateFormat": "dd.MM.yyyy", "newsletter": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralSettingsResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error (VALIDATION_ERROR): errors[] names each invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "settings:update" ] }, { "BearerAuth": [] } ], "tags": [ "settings" ] } }, "/settings/numbering": { "patch": { "operationId": "updateNumberingSettings", "summary": "Update numbering settings (type, format, symbols)", "description": "Sets the numbering type (monthly or yearly), the date pattern of document numbers and the symbol prefix per document type.\n\n**Required permission (Scope)**: `settings:update`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSettingsInput" }, "example": { "numberingType": "MONTH", "numberingFormat": "/MM/YYYY", "documentSymbols": { "FakturaVAT": "FV/", "FakturaKorygujaca": "KOR/", "Zamowienie": "ZAM/" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSettingsResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error (VALIDATION_ERROR): errors[] names each invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "settings:update" ] }, { "BearerAuth": [] } ], "tags": [ "settings" ] } }, "/company/nip-lookup": { "get": { "operationId": "lookupCompanyByNip", "summary": "Lookup company data in GUS by NIP", "description": "Looks a Polish company up in the GUS register by NIP and returns its name and address: `company` as registered and `buyer` with client field names, ready to pass as the `buyer` of a document or the body of a new client.\n\n**Required permission (Scope)**: `gus:company:read`\n\n**Rate limit**: 10 / 60 s", "parameters": [ { "in": "query", "name": "nip", "required": true, "schema": { "type": "string", "example": "5261040828" }, "description": "Polish NIP number (10 digits)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLookupResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "NIP is not 10 digits or its check digit is wrong (INVALID_NIP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "GUS has no company with this NIP (COMPANY_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "503": { "description": "The GUS register did not answer (GUS_UNAVAILABLE); retry in a moment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "gus:company:read" ] }, { "BearerAuth": [] } ], "tags": [ "company" ] } }, "/warehouse/": { "get": { "operationId": "browseWarehouses", "summary": "Get list of warehouses", "description": "All warehouses of the account.\n\n**Required permission (Scope)**: `warehouse:browse`", "responses": { "200": { "description": "List of warehouses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseListResponse" }, "example": { "success": true, "data": { "warehouses": [ { "id": "665f...", "name": "Magazyn główny", "symbol": "MAG1", "address": "", "isDefault": true } ] }, "executionTime": 12 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Subscription plan below Pro (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:browse" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] }, "post": { "operationId": "createWarehouse", "summary": "Create a warehouse (requires the MAX plan)", "description": "Adds a warehouse. Requires the MAX plan.\n\n**Required permission (Scope)**: `warehouse:create`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseInput" }, "example": { "name": "Magazyn główny", "symbol": "MAG1", "address": "ul. Prosta 1, 00-001 Warszawa", "isDefault": false } } } }, "responses": { "201": { "description": "Warehouse created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Plan below MAX (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:create" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/warehouse/stock": { "get": { "operationId": "getStockReport", "summary": "Get stock levels report (sum of movements per product/warehouse)", "description": "Stock levels per product and warehouse, as the sum of movements. `asOf` returns the historical level at the end of that day, `warehouseId` narrows to one warehouse, `productId` to one product.\n\n**Required permission (Scope)**: `warehouse:stock:read`", "parameters": [ { "name": "asOf", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Historic stock state at the end of the given day (YYYY-MM-DD)." }, { "name": "warehouseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit the report to a single warehouse." }, { "name": "productId", "in": "query", "required": false, "description": "Only this product", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stock levels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockReportResponse" }, "example": { "success": true, "data": { "levels": [ { "productId": "665f...", "warehouseId": "665e...", "quantity": 12 } ], "asOf": null }, "executionTime": 18 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:stock:read" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/warehouse/movements": { "get": { "operationId": "getWarehouseMovements", "summary": "List stock movements", "description": "The stock ledger, newest first: every receipt and issue with its document, quantity, unit cost and who recorded it. Stock levels are the sum of these lines. Filter by product, warehouse, document, movement type (PZ, WZ, PW, RW, MM_OUT, MM_IN, INW, WYCENA) and a date range. Page-based.\n\n**Required permission (Scope)**: `warehouse:stock:read`", "parameters": [ { "name": "productId", "in": "query", "required": false, "description": "Only movements of this product", "schema": { "type": "string" } }, { "name": "warehouseId", "in": "query", "required": false, "description": "Only movements in this warehouse", "schema": { "type": "string" } }, { "name": "documentId", "in": "query", "required": false, "description": "Only movements of this warehouse document", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Movement type or a comma-separated list", "schema": { "type": "string", "example": "WZ,PZ" } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Movement date from, inclusive (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Movement date to, inclusive (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "currentPage", "in": "query", "required": false, "description": "Page number, starting from 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Page size (default 50, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Movements page, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockMovementsResponse" }, "example": { "success": true, "data": { "movements": [ { "id": "681a3b2c4d5e6f7a8b9c0d1e", "productId": "681a3b2c4d5e6f7a8b9c0d2a", "warehouseId": "681a3b2c4d5e6f7a8b9c0d3b", "quantity": -2, "unitCost": null, "type": "WZ", "documentId": "681a3b2c4d5e6f7a8b9c0d4c", "documentNumber": "WZ/3/09/2026", "date": "2026-09-26", "note": null, "employeeId": null, "employeeName": null, "createdAt": "2026-09-26T10:30:00.000Z" } ], "currentPage": 1, "itemsPerPage": 50, "totalCount": 1, "totalPages": 1 }, "executionTime": 11 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Unknown movement type, bad date or pagination (INVALID_PARAMS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:stock:read" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/warehouse/adjustments": { "post": { "operationId": "createStockAdjustment", "summary": "Create a manual stock adjustment (INW movement)", "description": "Records a manual stock adjustment (inventory count, opening balance) as an INW movement. Positive quantity receives, negative issues. quantity 0 with unitCost is a revaluation (WYCENA movement): a new average cost of the current stock without changing the quantity; quantity 0 without unitCost is rejected (422).\n\n**Required permission (Scope)**: `warehouse:adjust`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockAdjustmentInput" }, "example": { "productId": "681a3b2c4d5e6f7a8b9c0d1e", "warehouseId": "681a3b2c4d5e6f7a8b9c0d1f", "quantity": 25, "unitCost": 12.5, "date": "2026-09-26", "note": "Bilans otwarcia" } } } }, "responses": { "201": { "description": "Adjustment recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockAdjustmentResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Warehouse or product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:adjust" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/warehouse/wz-from-invoice/{id}": { "post": { "operationId": "createWzFromInvoice", "summary": "Create a WZ document from a sales invoice (goods lines only)", "description": "Issues a WZ (goods issue) document for the goods lines of a sales invoice. Service lines and products without a catalogue entry are skipped. One WZ per invoice (409 on a duplicate). The WZ gets the account defaults of a warehouse document (WZ symbol and numbering, place of issue, comments, signatures, two-step release status), the recipient from the invoice, and is linked to the invoice on both sides (the WZ number is printed on the invoice and sent to KSeF). Missing goods are rejected with 422 STOCK_SHORTAGE unless allowNegativeStock=true; an unknown warehouse with 422 WAREHOUSE_INVALID.\n\n**Required permission (Scope)**: `warehouse:wz:create`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sales invoice ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WzFromInvoiceInput" }, "example": { "warehouseId": "681a3b2c4d5e6f7a8b9c0d1f" } } } }, "responses": { "201": { "description": "WZ document created; skipped lists non-goods lines omitted from the WZ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WzFromInvoiceResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "A WZ for this invoice already exists (CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Invoice has no goods lines or is not a sales document (VALIDATION_ERROR), unknown warehouse (WAREHOUSE_INVALID), not enough stock (STOCK_SHORTAGE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:wz:create" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/warehouse/documents/validate": { "post": { "operationId": "validateWarehouseDocument", "summary": "Validate a warehouse document without saving it", "description": "Dry run of POST /warehouse/documents: full validation, the number the document would get, warehouses, lines resolved from the catalogue, stock before and after per line and the shortages that would block an outbound document. Nothing is written (a new contractor given as an object is not created). Requires the MAX plan.\n\n**Required permission (Scope)**: `warehouse:documents:create`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseDocumentRequestBody" }, "example": { "documentType": "PZ", "issueDate": "2026-09-26", "buyerId": "681a3b2c4d5e6f7a8b9c0d2e", "products": [ { "productId": "681a3b2c4d5e6f7a8b9c0d1e", "quantity": 20, "netPrice": 45.5 } ], "comments": "Dostawa do magazynu głównego" } } } }, "responses": { "200": { "description": "Validation succeeded: preview without saving", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseDocumentPreviewResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid body (type, dates, lines)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Product, contractor or source invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Unknown warehouse or MM without a target (WAREHOUSE_INVALID), other business rules (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:documents:create" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/warehouse/documents": { "post": { "operationId": "createWarehouseDocument", "summary": "Issue a warehouse document (WZ, PZ, PW, RW, MM)", "description": "Issues a warehouse document and books its stock movements. Lines reference catalogue products (productId); names, units and prices come from the catalogue unless given (PZ/PW: purchase price, WZ/RW/MM: sale price). WZ/PZ take a contractor in buyerId/buyer (WZ: recipient, PZ: supplier); PW/RW/MM have none. Missing warehouse = the default warehouse (MM: source = default, target required). Account defaults apply like in the app editor: symbol and numbering, place of issue, comments, signatures from the warehouse signature setting, stock status from the two-step release setting (useAccountDefaults=false switches them off). Outbound documents (WZ, RW, MM) that would take stock below zero are rejected with 422 STOCK_SHORTAGE unless allowNegativeStock=true. WZ with sourceInvoiceId is linked to the invoice on both sides (its number is printed on the invoice). Requires the MAX plan.\n\n**Required permission (Scope)**: `warehouse:documents:create`\n\n**Idempotency-Key**: supported (the response is kept for 24 h; a retry with the same key returns the same result).\n\n**Rate limit**: 30 / 60 s\n\n**Emitted webhooks**:\n- `document.created` (on statuses: 201)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique idempotency key (UUID v4 recommended). Protects against duplicating operations on retry. Stored for 24h.", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseDocumentRequestBody" }, "example": { "documentType": "PZ", "issueDate": "2026-09-26", "buyerId": "681a3b2c4d5e6f7a8b9c0d2e", "products": [ { "productId": "681a3b2c4d5e6f7a8b9c0d1e", "quantity": 20, "netPrice": 45.5 } ], "comments": "Dostawa do magazynu głównego" } } } }, "responses": { "201": { "description": "Warehouse document issued, stock movements booked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseDocumentResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid body (type, dates, lines)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Product, contractor or source invoice not found (PRODUCT_NOT_FOUND, CLIENT_NOT_FOUND, DOCUMENT_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Document number already exists (DOCUMENT_NUMBER_EXISTS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Unknown warehouse or MM without a target (WAREHOUSE_INVALID), stock would go below zero (STOCK_SHORTAGE), other business rules (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:documents:create" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/warehouse/{id}": { "put": { "operationId": "updateWarehouse", "summary": "Update a warehouse", "description": "Full replacement of a warehouse (PUT).\n\n**Required permission (Scope)**: `warehouse:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Warehouse ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseInput" }, "example": { "name": "Magazyn główny", "symbol": "MAG1", "address": "ul. Prosta 1, 00-001 Warszawa", "isDefault": false } } } }, "responses": { "200": { "description": "Warehouse updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Warehouse not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:update" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] }, "delete": { "operationId": "deleteWarehouse", "summary": "Delete a warehouse (blocked when it has stock movements)", "description": "Removes a warehouse. Refused (409) when it still has stock movements or is the only warehouse of the account.\n\n**Required permission (Scope)**: `warehouse:delete`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Warehouse ID" } ], "responses": { "200": { "description": "Warehouse deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Warehouse not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Warehouse has stock movements or is the only one (CONFLICT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:delete" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] }, "get": { "operationId": "getWarehouse", "summary": "Get a warehouse", "description": "One warehouse by id.\n\n**Required permission (Scope)**: `warehouse:browse`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Warehouse id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Warehouse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Warehouse not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "warehouse:browse" ] }, { "BearerAuth": [] } ], "tags": [ "warehouse" ] } }, "/employees/permissions": { "get": { "operationId": "getEmployeePermissions", "summary": "Get the registry of available employee permissions", "description": "Registry of employee permissions (key, group, label, description, implied permissions). Only a valid token is required.", "responses": { "200": { "description": "Permission registry (key + Polish label and description)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeePermissionsResponse" }, "example": { "success": true, "data": { "permissions": [ { "key": "documents:read", "label": "Podgląd dokumentów", "description": "Viewing invoices…" } ] }, "executionTime": 4 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [] }, { "BearerAuth": [] } ], "tags": [ "employees" ] } }, "/employees/": { "get": { "operationId": "browseEmployees", "summary": "Get list of employee accounts", "description": "Employee accounts of the owner, without passwords. Requires the MAX plan.\n\n**Required permission (Scope)**: `employees:browse`", "responses": { "200": { "description": "List of employee accounts (never includes passwords)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeListResponse" }, "example": { "success": true, "data": { "employees": [ { "id": "665f...", "firstName": "Jan", "lastName": "Kowalski", "emailAddress": "jan@firma.pl", "permissions": [ "documents:read" ], "isActive": true } ] }, "executionTime": 9 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Plan below MAX (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "employees:browse" ] }, { "BearerAuth": [] } ], "tags": [ "employees" ] }, "post": { "operationId": "createEmployee", "summary": "Create an employee account", "description": "Creates an employee account (max 20 per account). The e-mail must be unique across Fakturnia. Requires the MAX plan.\n\n**Required permission (Scope)**: `employees:create`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeInput" }, "example": { "firstName": "Jan", "lastName": "Kowalski", "emailAddress": "jan@firma.pl", "password": "bardzo-tajne-haslo", "permissions": [ "documents:read", "documents:write" ] } } } }, "responses": { "201": { "description": "Employee account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeCreatedResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Plan below MAX (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Email already taken (EMAIL_TAKEN) or employee limit reached (EMPLOYEE_LIMIT_REACHED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "employees:create" ] }, { "BearerAuth": [] } ], "tags": [ "employees" ] } }, "/employees/{id}": { "put": { "operationId": "updateEmployee", "summary": "Update an employee account (data, permissions, activation, password)", "description": "Updates an employee account: data, password, the full permission list, or `isActive` (false ends the sessions of the employee).\n\n**Required permission (Scope)**: `employees:update`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Employee account ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeUpdateInput" }, "example": { "permissions": [ "documents:read" ], "isActive": true } } } }, "responses": { "200": { "description": "Employee account updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Plan below MAX (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Employee account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Email already taken (EMAIL_TAKEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "employees:update" ] }, { "BearerAuth": [] } ], "tags": [ "employees" ] }, "delete": { "operationId": "deleteEmployee", "summary": "Delete an employee account (soft delete; its email becomes available again)", "description": "Deletes an employee account; its e-mail becomes available again.\n\n**Required permission (Scope)**: `employees:delete`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Employee account ID" } ], "responses": { "200": { "description": "Employee account deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Plan below MAX (SUBSCRIPTION_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Employee account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "employees:delete" ] }, { "BearerAuth": [] } ], "tags": [ "employees" ] }, "get": { "operationId": "getEmployee", "summary": "Get an employee account", "description": "One employee account by id, without the password.\n\n**Required permission (Scope)**: `employees:browse`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee account id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Employee not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "employees:browse" ] }, { "BearerAuth": [] } ], "tags": [ "employees" ] } }, "/employees/{id}/activity": { "get": { "operationId": "getEmployeeActivity", "summary": "Get the activity feed of an employee", "description": "What one employee did, newest first: logins (with device and IP), changes made to the account, document actions and warehouse operations. Cursor pagination: pass `nextBefore` of a page as `before` to get the next one; `scope` narrows to one journal.\n\n**Required permission (Scope)**: `employees:browse`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee account id", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "description": "Which journals to include", "schema": { "type": "string", "enum": [ "all", "auth", "management", "documents", "warehouse" ], "default": "all" } }, { "name": "before", "in": "query", "required": false, "description": "Cursor: only entries older than this ISO date-time (use `nextBefore` from the previous page)", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Entries per page (default 30, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Activity feed page of the employee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeActivityResponse" }, "example": { "success": true, "data": { "employee": { "id": "681a3b2c4d5e6f7a8b9c0d3b", "firstName": "Ewa", "lastName": "Kowalska", "emailAddress": "ewa@firma.pl", "permissions": [ "documents:read" ], "isActive": true, "lastLoginAt": "2026-09-26T07:58:00.000Z", "createdAt": "2026-09-01T10:00:00.000Z" }, "items": [ { "id": "681a3b2c4d5e6f7a8b9c0d1e", "scope": "auth", "type": "LOGIN", "createdAt": "2026-09-26T07:58:00.000Z", "employeeId": "681a3b2c4d5e6f7a8b9c0d3b", "employeeName": "Ewa Kowalska", "entityId": null, "entityName": null, "entityType": null, "entityDeleted": false, "changes": null, "data": { "ip": "203.0.113.5", "device": "web" } } ], "hasMore": false, "nextBefore": null }, "executionTime": 12 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Unknown scope or unparsable date (INVALID_PARAMS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Employee not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "employees:browse" ] }, { "BearerAuth": [] } ], "tags": [ "employees" ] } }, "/recurring-rules/": { "get": { "operationId": "browseRecurringRules", "summary": "Get list of recurring document rules", "description": "Returns all recurring rules with a summary (counts per status, next scheduled generation, monthly recurring gross in PLN). Requires the MAX plan.\n\n**Required permission (Scope)**: `recurring:browse`", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by rule status", "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "FINISHED" ] } }, { "name": "currentPage", "in": "query", "required": false, "description": "Page number, starting from 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Page size (default 50, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "List of recurring rules with a summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringRuleListResponse" }, "example": { "success": true, "data": { "rules": [ { "id": "665f...", "name": "Abonament — Firma Sp. z o.o.", "status": "ACTIVE", "mode": "AUTO", "documentSummary": { "documentType": "FakturaVAT", "buyerName": "Firma Sp. z o.o.", "grossSum": 1230, "currency": "PLN" }, "schedule": { "frequency": "MONTHLY", "dayOfMonth": 1, "startDate": "2026-01-01", "endType": "NEVER" }, "nextRunAt": "2026-08-01", "occurrencesCount": 7, "documentsIssuedCount": 7 } ], "summary": { "total": 3, "active": 2, "paused": 1, "finished": 0, "nextRunAt": "2026-08-01", "monthlyRecurringGross": 2460 } }, "executionTime": 11 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Subscription plan below MAX (SUBSCRIPTION_REQUIRED) or insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "recurring:browse" ] }, { "BearerAuth": [] } ], "tags": [ "recurring-rules" ] } }, "/recurring-rules/{id}/history": { "get": { "operationId": "getRecurringRuleHistory", "summary": "Get generation history of a recurring rule", "description": "Journal of rule occurrences (newest first) with links to generated documents. Statuses: GENERATED, DRAFT, REMINDED, SKIPPED, FAILED, PENDING. Page-based (`currentPage`, `itemsPerPage`).\n\n**Required permission (Scope)**: `recurring:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the recurring rule", "schema": { "type": "string" } }, { "name": "currentPage", "in": "query", "required": false, "description": "Page number, starting from 1", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Page size (default 50, max 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Generation history of the rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringRuleHistoryResponse" }, "example": { "success": true, "data": { "runs": [ { "id": "665f...", "plannedDate": "2026-07-01", "issueDate": "2026-07-01", "documentId": "665a...", "documentNumber": "FV/7/2026", "status": "GENERATED", "emailSent": true, "ksefQueued": false } ], "currentPage": 1, "itemsPerPage": 50, "totalCount": 1, "totalPages": 1 }, "executionTime": 9 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Subscription plan below MAX (SUBSCRIPTION_REQUIRED) or insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Recurring rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "recurring:read" ] }, { "BearerAuth": [] } ], "tags": [ "recurring-rules" ] } }, "/recurring-rules/{id}": { "get": { "operationId": "getRecurringRule", "summary": "Get recurring rule details", "description": "One recurring rule with its schedule, automation and a summary of the generated document.\n\n**Required permission (Scope)**: `recurring:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the recurring rule", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recurring rule details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringRuleResponse" }, "example": { "success": true, "data": { "rule": {} }, "executionTime": 8 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Subscription plan below MAX (SUBSCRIPTION_REQUIRED) or insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Recurring rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "recurring:read" ] }, { "BearerAuth": [] } ], "tags": [ "recurring-rules" ] } }, "/recurring-rules/{id}/toggle": { "patch": { "operationId": "toggleRecurringRule", "summary": "Pause or resume a recurring rule", "description": "Body: { \"active\": boolean }. Pausing clears nextRunAt (null while paused). Resuming recomputes nextRunAt from today: missed occurrences are NOT backfilled and an occurrence already generated today is not repeated. A FINISHED rule cannot be resumed (409).\n\n**Required permission (Scope)**: `recurring:toggle`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the recurring rule", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringRuleToggleInput" }, "example": { "active": false } } } }, "responses": { "200": { "description": "Updated rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringRuleResponse" }, "example": { "success": true, "data": { "rule": { "id": "665f...", "status": "PAUSED" } }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Subscription plan below MAX (SUBSCRIPTION_REQUIRED) or insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Recurring rule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "409": { "description": "Rule is FINISHED and cannot be resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "recurring:toggle" ] }, { "BearerAuth": [] } ], "tags": [ "recurring-rules" ] } }, "/email-accounts/": { "get": { "operationId": "browseEmailAccounts", "summary": "List connected email accounts", "description": "Mailboxes connected in the app (SMTP, Gmail, Outlook) that documents are e-mailed from, default mailbox first. Read-only: connecting, verifying and editing a mailbox happens in the app. Secrets are never returned.\n\n**Required permission (Scope)**: `email-accounts:browse`", "responses": { "200": { "description": "Connected email accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAccountListResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or no MAX plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "email-accounts:browse" ] }, { "BearerAuth": [] } ], "tags": [ "email-accounts" ] } }, "/email-accounts/{id}": { "get": { "operationId": "getEmailAccount", "summary": "Get a connected email account", "description": "One mailbox by id, with its verification state. Secrets are never returned.\n\n**Required permission (Scope)**: `email-accounts:read`", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Email account id", "schema": { "type": "string", "example": "681a3b2c4d5e6f7a8b9c0d1e" } } ], "responses": { "200": { "description": "Email account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAccountResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Missing scope or no MAX plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "404": { "description": "Email account not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "email-accounts:read" ] }, { "BearerAuth": [] } ], "tags": [ "email-accounts" ] } }, "/activity/": { "get": { "operationId": "getAccountActivity", "summary": "Get the account activity feed", "description": "Everything that happened on the account, newest first: document actions (created, updated, sent, paid, deleted), employee logins and account management, warehouse operations. Merges the journals of the owner and every employee. Cursor pagination: pass `nextBefore` of a page as `before` to get the next one. Filter by `scope`, `employeeId` (an id, or `main` for the owner alone), a `from`/`to` window and free text `q` (employee name or document number).\n\n**Required permission (Scope)**: `activity:read`", "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "Which journals to include", "schema": { "type": "string", "enum": [ "all", "auth", "management", "documents", "warehouse" ], "default": "all" } }, { "name": "before", "in": "query", "required": false, "description": "Cursor: only entries older than this ISO date-time (use `nextBefore` from the previous page)", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Entries per page (default 30, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "employeeId", "in": "query", "required": false, "description": "Only one employee (id) or only the owner account (`main`)", "schema": { "type": "string", "example": "main" } }, { "name": "from", "in": "query", "required": false, "description": "Only entries at or after this ISO date-time", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only entries at or before this ISO date-time", "schema": { "type": "string", "format": "date-time" } }, { "name": "q", "in": "query", "required": false, "description": "Free text: employee name or document number", "schema": { "type": "string", "example": "FV/12" } } ], "responses": { "200": { "description": "Activity feed page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityFeedResponse" }, "example": { "success": true, "data": { "items": [ { "id": "681a3b2c4d5e6f7a8b9c0d1e", "scope": "document", "type": "CREATE", "createdAt": "2026-09-26T10:30:00.000Z", "employeeId": null, "employeeName": null, "entityId": "681a3b2c4d5e6f7a8b9c0d1f", "entityName": "FV/12/09/2026", "entityType": "DOCUMENT", "entityDeleted": false, "changes": null, "data": { "origin": "external_api", "source": "local" } } ], "hasMore": true, "nextBefore": "2026-09-26T10:30:00.000Z" }, "executionTime": 14 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Unknown scope or unparsable date (INVALID_PARAMS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, invalid or expired token (UNAUTHORIZED, TOKEN_EXPIRED), or API account revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Unexpected server error (INTERNAL_SERVER_ERROR); safe to retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [ "activity:read" ] }, { "BearerAuth": [] } ], "tags": [ "activity" ] } }, "/auth/me": { "get": { "operationId": "getMe", "summary": "Get information about the current account", "description": "Identity and granted scopes behind the current token. Use it after deployment to confirm the token works and carries the right scopes.", "responses": { "200": { "description": "Account data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMeResponse" }, "example": { "success": true, "data": { "clientId": "507f1f77bcf86cd799439011", "name": "Integracja z e-Sklepem", "scopes": [ "documents:read", "clients:browse" ], "userId": "507f1f77bcf86cd799439012" }, "executionTime": 10 } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "403": { "description": "Token lacks the scope (NO_PERMISSIONS), owner below the MAX plan (SUBSCRIPTION_REQUIRED) or IP outside the account allowlist (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED); wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } } }, "security": [ { "OAuth2": [] }, { "BearerAuth": [] } ], "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", "webhooks:update", "webhooks:delete", "email-accounts:browse", "email-accounts:read", "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", "warehouse:browse", "warehouse:create", "warehouse:update", "warehouse:delete", "warehouse:stock:read", "warehouse:adjust", "warehouse:wz:create", "warehouse:documents:create", "employees:browse", "employees:create", "employees:update", "employees:delete", "recurring:browse", "recurring:read", "recurring:toggle", "activity:read" ] } ], "tags": [] }