{ "item": [ { "name": "Reference", "description": "One request per OpenAPI operation.", "item": [ { "id": "29e7ff30-17c1-00c7-4e7a-227b1061fc65", "name": "Invoices", "description": { "content": "Invoices and corrections from paid orders and refunds.", "type": "text/plain" }, "item": [ { "id": "aa6aaeef-0888-459b-7a23-874778266bb2", "name": "Create an invoice from a paid order", "request": { "name": "Create an invoice from a paid order", "description": { "content": "Send either `order` (platform-neutral format, gross prices) or `woocommerce_order` (a WooCommerce REST API v3\norder, used by the WooCommerce plugin). The buyer must have a valid Polish NIP and the order must be paid.\nReturns `201` for a new invoice, `200` when an invoice for this `external_id` already exists.\n", "type": "text/plain" }, "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "26cd7cdf-825d-4bf3-55b9-dd85cbcd64cb", "name": "An invoice for this external_id already exists (or Idempotency-Key replay).", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"inv_4fJ2kP9xQwErTy7uI0oPaSdF\",\n \"object\": \"invoice\",\n \"livemode\": false,\n \"status\": \"accepted\",\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\"\n },\n \"number\": \"FV/2026/10/1\",\n \"ksef_number\": \"4235405606-20261019-0E7570400000-57\",\n \"ksef_environment\": \"test\",\n \"issue_date\": \"2026-10-19\",\n \"currency\": \"PLN\",\n \"total_gross\": \"163.99\",\n \"buyer_nip\": \"5260250274\",\n \"pdf_url\": \"https://app.ksefshop.pl/pdf/cmgxa1b2c0000/Qk9tZ2FsX3ZhbGlkX3Rva2VuX2V4YW1w\",\n \"last_error\": null,\n \"created\": 1760865185,\n \"updated\": 1760865214,\n \"corrections\": []\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f2162a57-d9bb-aada-d90b-e1e53815f1d5", "name": "Invoice created (status pending).", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "disabled": false, "description": "Unique id of this request.", "key": "Request-Id", "value": "req_8Kq2Lm4Np6Rs8Tu0Vw2X" }, { "disabled": false, "key": "RateLimit-Limit", "value": "100", "description": "" }, { "disabled": false, "key": "RateLimit-Remaining", "value": "99", "description": "" }, { "disabled": false, "description": "Seconds until the window resets.", "key": "RateLimit-Reset", "value": "60" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"inv_4fJ2kP9xQwErTy7uI0oPaSdF\",\n \"object\": \"invoice\",\n \"livemode\": false,\n \"status\": \"pending\",\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": null\n },\n \"number\": null,\n \"ksef_number\": null,\n \"ksef_environment\": \"test\",\n \"issue_date\": null,\n \"currency\": null,\n \"total_gross\": null,\n \"buyer_nip\": null,\n \"pdf_url\": null,\n \"last_error\": null,\n \"created\": 1760865185,\n \"updated\": 1760865185,\n \"corrections\": []\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9f59cf1e-e918-9df9-14e4-4864360a004e", "name": "Invalid request.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"buyer_nip_invalid\",\n \"message\": \"buyer.nip is not a valid Polish NIP (checksum).\",\n \"param\": \"order.buyer.nip\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#buyer_nip_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cfa0f29f-bad1-2b99-55a2-1cf037ac0d61", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "515a2ca8-a65a-89fb-93a0-dfe4245e768f", "name": "Not allowed (live mode not enabled).", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"permission_error\",\n \"code\": \"live_mode_disabled\",\n \"message\": \"Live mode is not enabled for this account yet.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#live_mode_disabled\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1bcfa8fc-285e-6b12-a367-46a0d2eb47b2", "name": "Idempotency-Key reused with another request, or the PDF is not ready yet.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"idempotency_error\",\n \"code\": \"idempotency_key_reused\",\n \"message\": \"Idempotency-Key \\\"k-1002\\\" was already used with a different request.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#idempotency_key_reused\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d2bea782-667d-95d5-9179-a361b1486813", "name": "Invalid request.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Request Entity Too Large", "code": 413, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"buyer_nip_invalid\",\n \"message\": \"buyer.nip is not a valid Polish NIP (checksum).\",\n \"param\": \"order.buyer.nip\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#buyer_nip_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "af3b6368-3adb-e1d9-dae4-812ae0f32056", "name": "The order cannot become an invoice (e.g. negative fee, amount-only refund).", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"order_unprocessable\",\n \"message\": \"Order 728: negative fee \\\"Rabat\\\" is not supported yet (use a coupon instead)\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#order_unprocessable\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1081bebe-4503-c8a3-e39d-6cd7af8ab1b4", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "key": "Retry-After", "value": "30", "description": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"rate_limit_error\",\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests; wait for Retry-After seconds.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#rate_limited\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e2e7770a-8949-b061-42cb-d3b66c2e4c80", "name": "Our error; retry with the same Idempotency-Key.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"api_error\",\n \"code\": \"internal_error\",\n \"message\": \"Something went wrong on our side (request req_8Kq2Lm4Np6Rs8Tu0Vw2X). Retry with the same Idempotency-Key.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#internal_error\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "4ffd3628-b654-3b3e-59ce-d9cb2e1ff2a0", "name": "List invoices", "request": { "name": "List invoices", "description": {}, "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "limit", "value": "10" }, { "disabled": false, "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF", "description": "Id of the last object of the previous page." }, { "disabled": false, "key": "external_id", "value": "SO-1001", "description": "Only the invoice of this order." } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "a0a81874-0f17-88c4-972c-ff1d29f8910c", "name": "A page of invoices, newest first. Corrections are nested in each invoice.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "external_id", "value": "SO-1001" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "Unique id of this request.", "key": "Request-Id", "value": "req_8Kq2Lm4Np6Rs8Tu0Vw2X" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"object\": \"list\",\n \"url\": \"/v1/invoices\",\n \"has_more\": false,\n \"data\": []\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bab33b21-a790-3ec8-0580-1492f169e59b", "name": "Invalid request.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "external_id", "value": "SO-1001" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"buyer_nip_invalid\",\n \"message\": \"buyer.nip is not a valid Polish NIP (checksum).\",\n \"param\": \"order.buyer.nip\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#buyer_nip_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "93ec46a8-d36e-1a5f-b5b8-0aaa9d1adc6e", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "external_id", "value": "SO-1001" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c860a610-b671-41b3-a9ec-49991248780f", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "external_id", "value": "SO-1001" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "12495570-a281-26d8-ff36-7007607dae86", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "v1", "invoices" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "external_id", "value": "SO-1001" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "key": "Retry-After", "value": "30", "description": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"rate_limit_error\",\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests; wait for Retry-After seconds.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#rate_limited\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "6d1f63b9-2b60-50bd-2f51-bf7feade2b4a", "name": "Retrieve an invoice or a correction", "request": { "name": "Retrieve an invoice or a correction", "description": {}, "url": { "path": [ "v1", "invoices", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "f24ffe0e-fc60-b107-8346-87cf8e29bc94", "name": "The invoice (inv_..., with its corrections) or the correction (cor_...).", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"inv_4fJ2kP9xQwErTy7uI0oPaSdF\",\n \"object\": \"invoice\",\n \"livemode\": false,\n \"status\": \"accepted\",\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\"\n },\n \"number\": \"FV/2026/10/1\",\n \"ksef_number\": \"4235405606-20261019-0E7570400000-57\",\n \"ksef_environment\": \"test\",\n \"issue_date\": \"2026-10-19\",\n \"currency\": \"PLN\",\n \"total_gross\": \"163.99\",\n \"buyer_nip\": \"5260250274\",\n \"pdf_url\": \"https://app.ksefshop.pl/pdf/cmgxa1b2c0000/Qk9tZ2FsX3ZhbGlkX3Rva2VuX2V4YW1w\",\n \"last_error\": null,\n \"created\": 1760865185,\n \"updated\": 1760865214,\n \"corrections\": []\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e03951f1-9e12-af96-3b28-becdbfb699e3", "name": "Invalid request.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"buyer_nip_invalid\",\n \"message\": \"buyer.nip is not a valid Polish NIP (checksum).\",\n \"param\": \"order.buyer.nip\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#buyer_nip_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "89a653d9-69fe-9634-79f8-058ff3140453", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c4aba3cf-59a0-e439-7307-790e5cd74b07", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c64fcaa0-5beb-4d13-5e1e-b3c5863ae1fe", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "key": "Retry-After", "value": "30", "description": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"rate_limit_error\",\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests; wait for Retry-After seconds.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#rate_limited\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3effd5ed-7213-91e7-8a0c-d1c015ae474a", "name": "Download the PDF", "request": { "name": "Download the PDF", "description": { "content": "The PDF with the KSeF number and the KOD I QR code. `409 pdf_not_ready` until it is rendered.", "type": "text/plain" }, "url": { "path": [ "v1", "invoices", ":id", "pdf" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/pdf" } ], "method": "GET", "auth": null }, "response": [ { "id": "d5a78d48-b718-1b38-f5f1-dda8cfef15ae", "name": "PDF file.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "pdf" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/pdf" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/pdf" } ], "body": "string", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "1cc0d0d4-84f9-36e0-5613-f6dd1bc4437f", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "pdf" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "77bb69bd-381d-f9a6-2ef6-285acab5e757", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "pdf" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0244eedc-5429-5a08-5c2e-7dc2e32230d0", "name": "Idempotency-Key reused with another request, or the PDF is not ready yet.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "pdf" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"idempotency_error\",\n \"code\": \"idempotency_key_reused\",\n \"message\": \"Idempotency-Key \\\"k-1002\\\" was already used with a different request.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#idempotency_key_reused\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "71f77b87-05ee-c37e-ca55-863b6b8f3da5", "name": "Create a correction (refund) for an invoice", "request": { "name": "Create a correction (refund) for an invoice", "description": { "content": "A refund becomes a correction invoice (KOR, TypKorekty 2) with difference lines (negative quantities)\nreferring to the invoice's KSeF number. The queue waits until the invoice is accepted in KSeF.\nSend `refund` (neutral format) or `woocommerce_order` + `woocommerce_refund`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "71fc68e2-58f3-d32e-bfa6-fc4795b06819", "name": "A correction for this refund external_id already exists.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cor_8hG3jK2lMnBvCxZ1aS4dF6gH\",\n \"object\": \"correction\",\n \"livemode\": false,\n \"status\": \"pending\",\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": null\n },\n \"number\": null,\n \"ksef_number\": null,\n \"ksef_environment\": \"test\",\n \"issue_date\": null,\n \"currency\": null,\n \"total_gross\": null,\n \"buyer_nip\": null,\n \"pdf_url\": null,\n \"last_error\": null,\n \"created\": 1760951000,\n \"updated\": 1760951000,\n \"invoice\": \"inv_4fJ2kP9xQwErTy7uI0oPaSdF\",\n \"refund\": {\n \"external_id\": \"RF-1\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bb728cea-58b9-2066-9d8e-f1c2d0bdb617", "name": "Correction created (status pending).", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cor_8hG3jK2lMnBvCxZ1aS4dF6gH\",\n \"object\": \"correction\",\n \"livemode\": false,\n \"status\": \"pending\",\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": null\n },\n \"number\": null,\n \"ksef_number\": null,\n \"ksef_environment\": \"test\",\n \"issue_date\": null,\n \"currency\": null,\n \"total_gross\": null,\n \"buyer_nip\": null,\n \"pdf_url\": null,\n \"last_error\": null,\n \"created\": 1760951000,\n \"updated\": 1760951000,\n \"invoice\": \"inv_4fJ2kP9xQwErTy7uI0oPaSdF\",\n \"refund\": {\n \"external_id\": \"RF-1\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dcb0bb83-5962-38c2-60ca-39bcccbca57b", "name": "Invalid request.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"buyer_nip_invalid\",\n \"message\": \"buyer.nip is not a valid Polish NIP (checksum).\",\n \"param\": \"order.buyer.nip\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#buyer_nip_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ff169b48-3887-67e2-fda8-bb4bba2cf892", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e1165c4b-6214-645d-ecbe-af8a0994502a", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "77529c4f-c259-a027-c0a4-bde59bb25082", "name": "Idempotency-Key reused with another request, or the PDF is not ready yet.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"idempotency_error\",\n \"code\": \"idempotency_key_reused\",\n \"message\": \"Idempotency-Key \\\"k-1002\\\" was already used with a different request.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#idempotency_key_reused\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b92bf5c0-06e3-91e7-1283-5ee26a9def12", "name": "The order cannot become an invoice (e.g. negative fee, amount-only refund).", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"order_unprocessable\",\n \"message\": \"Order 728: negative fee \\\"Rabat\\\" is not supported yet (use a coupon instead)\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#order_unprocessable\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0af63f45-6717-9f3a-35a1-bfaf5f398699", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "v1", "invoices", ":id", "corrections" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{invoice_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "key": "Retry-After", "value": "30", "description": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"rate_limit_error\",\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests; wait for Retry-After seconds.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#rate_limited\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "6c9179bd-d791-bfba-05d0-cdef354261af", "name": "Account", "description": { "content": "", "type": "text/plain" }, "item": [ { "id": "fc2190bf-ee00-fff8-3090-927970505b67", "name": "Retrieve the account of the key's mode", "request": { "name": "Retrieve the account of the key's mode", "description": { "content": "Seller data, KSeF connection and plan usage. The WooCommerce plugin's \"Test connection\" calls this.", "type": "text/plain" }, "url": { "path": [ "v1", "account" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "dc048ade-7504-f0ab-7d09-d128a69edde2", "name": "Account.", "originalRequest": { "url": { "path": [ "v1", "account" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"acct_Xy7Qw2Er4Ty6Ui8Op0As2Df4\",\n \"object\": \"account\",\n \"livemode\": false,\n \"email\": \"sklep@example.com\",\n \"platform\": \"woocommerce\",\n \"ksef_environment\": \"test\",\n \"seller\": {\n \"nip\": \"4235405606\",\n \"name\": \"Sklep Woo sp. z o.o.\",\n \"address_line1\": \"ul. Testowa 1\",\n \"address_line2\": \"00-001 Warszawa\"\n },\n \"seller_configured\": true,\n \"ksef_connected\": true,\n \"ksef_check_error\": null,\n \"plan\": {\n \"name\": \"Unlimited\",\n \"monthly_limit\": null,\n \"used_this_month\": 12\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2c2adc39-d48a-b3f2-20de-fc4d289e96e5", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "account" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ef1060d6-aa15-f137-51ac-648b055475b2", "name": "Not allowed (live mode not enabled).", "originalRequest": { "url": { "path": [ "v1", "account" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"permission_error\",\n \"code\": \"live_mode_disabled\",\n \"message\": \"Live mode is not enabled for this account yet.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#live_mode_disabled\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8ca11ed5-0d3e-727b-73a1-4a438d8e8ef5", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "v1", "account" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "key": "Retry-After", "value": "30", "description": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"rate_limit_error\",\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests; wait for Retry-After seconds.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#rate_limited\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "05f6e3cc-2189-e736-19d6-ef481c15ae23", "name": "Webhooks", "description": { "content": "", "type": "text/plain" }, "item": [ { "id": "cd81889f-2737-de52-3124-fe7f0f6d41e8", "name": "Create a webhook endpoint", "request": { "name": "Create a webhook endpoint", "description": { "content": "The `secret` (whsec_...) is returned only in this response.", "type": "text/plain" }, "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "e52c3813-37a5-f3f5-7895-57af12842d89", "name": "Endpoint with its signing secret.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"we_Ab3Cd5Ef7Gh9Ij1Kl3Mn5Op7\",\n \"object\": \"webhook_endpoint\",\n \"livemode\": false,\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\",\n \"status\": \"enabled\",\n \"created\": 1760865185,\n \"secret\": \"whsec_shownOnlyOnceExampleValue0000\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7ba6f3fb-939d-864b-0c5b-00a72427742f", "name": "Invalid request.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"buyer_nip_invalid\",\n \"message\": \"buyer.nip is not a valid Polish NIP (checksum).\",\n \"param\": \"order.buyer.nip\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#buyer_nip_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7073e340-7040-b253-2133-3093779f068c", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "63598567-ef50-c15c-c4f4-19a47f7d8738", "name": "Idempotency-Key reused with another request, or the PDF is not ready yet.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"idempotency_error\",\n \"code\": \"idempotency_key_reused\",\n \"message\": \"Idempotency-Key \\\"k-1002\\\" was already used with a different request.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#idempotency_key_reused\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c27e7d5c-f369-d5dd-eee3-ec8c0549963e", "name": "Rate limit exceeded.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "Makes the POST safe to retry for 24 hours.", "key": "Idempotency-Key", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "key": "Retry-After", "value": "30", "description": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"rate_limit_error\",\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests; wait for Retry-After seconds.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#rate_limited\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "9f425f63-475d-caea-ce02-16986ac50507", "name": "List webhook endpoints", "request": { "name": "List webhook endpoints", "description": {}, "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "8bf6040c-ae4c-3672-cbef-a5947f6f1ddb", "name": "Endpoints of the key's mode.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"object\": \"list\",\n \"url\": \"/v1/webhook_endpoints\",\n \"has_more\": false,\n \"data\": []\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a9f5661b-577f-5081-0b93-e0d43b5d49d1", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "39c695e7-b7c1-9dda-7e60-c090dbe7d30e", "name": "Retrieve a webhook endpoint", "request": { "name": "Retrieve a webhook endpoint", "description": {}, "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "03cbf56b-24a9-bfe8-99f7-38286b1e1b07", "name": "Endpoint.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"we_Ab3Cd5Ef7Gh9Ij1Kl3Mn5Op7\",\n \"object\": \"webhook_endpoint\",\n \"livemode\": false,\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\",\n \"status\": \"enabled\",\n \"created\": 1760865185\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a2d9d074-2ea8-91cc-4fe2-d4b798cc630e", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "73ba0ec3-93c5-e309-d008-150c153a7a88", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "615772d3-430f-80ed-c0b4-3e683890cc8b", "name": "Delete a webhook endpoint", "request": { "name": "Delete a webhook endpoint", "description": {}, "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "auth": null }, "response": [ { "id": "c76d89eb-fc4f-c8bc-6c19-d1124e238c69", "name": "Deleted.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"we_Ab3Cd5Ef7Gh9Ij1Kl3Mn5Op7\",\n \"object\": \"webhook_endpoint\",\n \"deleted\": true\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6cfb6ab6-756c-a5eb-354d-08ea09650c68", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c403b9a5-da36-31bb-9781-5ee1d4572b0a", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "webhook_endpoints", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{webhook_endpoint_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "24e8c032-ed17-7b65-b488-2b865478f790", "name": "Events", "description": { "content": "", "type": "text/plain" }, "item": [ { "id": "20431082-cae3-3d90-2ba8-11705460da85", "name": "List events", "request": { "name": "List events", "description": {}, "url": { "path": [ "v1", "events" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "limit", "value": "10" }, { "disabled": false, "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF", "description": "Id of the last object of the previous page." }, { "disabled": false, "key": "type", "value": "invoice.accepted" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "0cf2e1c2-c292-8985-8259-28e0bdc24873", "name": "Events, newest first.", "originalRequest": { "url": { "path": [ "v1", "events" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "type", "value": "invoice.accepted" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"object\": \"list\",\n \"url\": \"/v1/events\",\n \"has_more\": false,\n \"data\": []\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8903ddc2-8c03-1409-5729-8db60f616da1", "name": "Invalid request.", "originalRequest": { "url": { "path": [ "v1", "events" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "type", "value": "invoice.accepted" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"buyer_nip_invalid\",\n \"message\": \"buyer.nip is not a valid Polish NIP (checksum).\",\n \"param\": \"order.buyer.nip\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#buyer_nip_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "22fc6a4c-2a81-300b-b192-71bd69fb4f62", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "events" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "type", "value": "invoice.accepted" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cb6b3487-5a63-ca9d-062a-02b0f7e19127", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "events" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "10" }, { "key": "starting_after", "value": "inv_4fJ2kP9xQwErTy7uI0oPaSdF" }, { "key": "type", "value": "invoice.accepted" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0442760b-b4f9-4c89-e5e5-1f063fae1715", "name": "Retrieve an event", "request": { "name": "Retrieve an event", "description": {}, "url": { "path": [ "v1", "events", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{event_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "27268148-2491-95a9-4d54-068f530496b9", "name": "Event.", "originalRequest": { "url": { "path": [ "v1", "events", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{event_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8\",\n \"object\": \"event\",\n \"type\": \"invoice.accepted\",\n \"livemode\": false,\n \"created\": 1760865214,\n \"data\": {\n \"object\": {\n \"id\": \"inv_4fJ2kP9xQwErTy7uI0oPaSdF\",\n \"object\": \"invoice\",\n \"livemode\": false,\n \"status\": \"accepted\",\n \"order\": {\n \"external_id\": \"SO-1001\",\n \"number\": \"1001\"\n },\n \"number\": \"FV/2026/10/1\",\n \"ksef_number\": \"4235405606-20261019-0E7570400000-57\",\n \"ksef_environment\": \"test\",\n \"issue_date\": \"2026-10-19\",\n \"currency\": \"PLN\",\n \"total_gross\": \"163.99\",\n \"buyer_nip\": \"5260250274\",\n \"pdf_url\": \"https://app.ksefshop.pl/pdf/cmgxa1b2c0000/Qk9tZ2FsX3ZhbGlkX3Rva2VuX2V4YW1w\",\n \"last_error\": null,\n \"created\": 1760865185,\n \"updated\": 1760865214,\n \"corrections\": []\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7e32dbd8-41cb-d2c1-3c49-0baba816cd32", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "events", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{event_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"api_key_invalid\",\n \"message\": \"The API key is wrong, revoked, or the account is disabled.\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#api_key_invalid\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ca4ddf8c-70bb-ebc2-a9d0-5218085e2cff", "name": "No such object (or it belongs to another account or mode).", "originalRequest": { "url": { "path": [ "v1", "events", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "{{event_id}}", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"type\": \"not_found_error\",\n \"code\": \"resource_missing\",\n \"message\": \"No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'\",\n \"doc_url\": \"https://ksefshop.pl/api/errors#resource_missing\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] } ] }, { "name": "Scenarios", "description": "Runnable end-to-end flows in order. Set the environment, then run the folder (Collection Runner). Each run uses fresh external ids ({{run}}).", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "if (!pm.collectionVariables.get(\"run\")) pm.collectionVariables.set(\"run\", String(Date.now()));" ] } } ], "item": [ { "name": "0. Check the account (Test connection)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v1/account", "host": [ "{{baseUrl}}" ], "path": [ "v1", "account" ] } } }, { "name": "1. First invoice (PLN)", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const b = pm.response.json();", "if (b.id) pm.collectionVariables.set(\"invoice_id\", b.id);", "pm.test(\"status 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices" ] }, "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1001-{{run}}\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "2. Retrieve the invoice (poll until accepted)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v1/invoices/{{invoice_id}}", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices", "{{invoice_id}}" ] } } }, { "name": "3. Foreign currency (EUR)", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const b = pm.response.json();", "if (b.id) pm.collectionVariables.set(\"invoice_eur_id\", b.id);", "pm.test(\"status 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices" ] }, "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1002-{{run}}\",\n \"paid_at\": \"2026-10-20T07:15:00Z\",\n \"currency\": \"EUR\",\n \"payment_method\": \"transfer\",\n \"buyer\": {\n \"nip\": \"7740001454\",\n \"name\": \"Przykład S.A.\",\n \"address_line1\": \"ul. Długa 5\",\n \"address_line2\": \"80-831 Gdańsk\"\n },\n \"lines\": [\n {\n \"name\": \"Lampka biurkowa LED\",\n \"quantity\": 1,\n \"unit_price\": \"123.00\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "4. WooCommerce order", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices" ] }, "body": { "mode": "raw", "raw": "{\n \"woocommerce_order\": {\n \"id\": 727,\n \"number\": \"727\",\n \"status\": \"processing\",\n \"currency\": \"PLN\",\n \"date_created_gmt\": \"2026-10-19T09:12:40\",\n \"date_paid_gmt\": \"2026-10-19T09:13:05\",\n \"billing\": {\n \"first_name\": \"Jan\",\n \"last_name\": \"Kowalski\",\n \"company\": \"Testowa Firma sp. z o.o.\",\n \"address_1\": \"ul. Prosta 20\",\n \"city\": \"Warszawa\",\n \"postcode\": \"00-850\",\n \"country\": \"PL\",\n \"email\": \"jan@example.com\"\n },\n \"payment_method\": \"cod\",\n \"meta_data\": [\n {\n \"key\": \"_ksef_buyer_nip\",\n \"value\": \"5260250274\"\n }\n ],\n \"line_items\": [\n {\n \"id\": 41,\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"quantity\": 2,\n \"subtotal\": \"79.67\",\n \"subtotal_tax\": \"18.33\",\n \"total\": \"79.67\",\n \"total_tax\": \"18.33\",\n \"taxes\": [\n {\n \"id\": 1,\n \"total\": \"18.33\"\n }\n ]\n }\n ],\n \"tax_lines\": [\n {\n \"id\": 51,\n \"rate_id\": 1,\n \"rate_percent\": 23\n }\n ],\n \"shipping_lines\": []\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "5. Wrong NIP -> 400 buyer_nip_invalid", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"error buyer_nip_invalid\", () => pm.expect(pm.response.json().error.code).to.eql(\"buyer_nip_invalid\"));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices" ] }, "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-1003-{{run}}\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"buyer\": {\n \"nip\": \"5260250275\",\n \"name\": \"Literówka sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 1\"\n },\n \"lines\": [\n {\n \"name\": \"Notes A5\",\n \"quantity\": 3,\n \"unit_price\": \"19.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "6a. Idempotent retry - first call", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "pm.collectionVariables.set(\"idem_key\", \"retry-\" + pm.collectionVariables.get(\"run\"));" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const b = pm.response.json();", "if (b.id) pm.collectionVariables.set(\"idem_invoice_id\", b.id);", "pm.test(\"status 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{idem_key}}" } ], "url": { "raw": "{{baseUrl}}/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices" ] }, "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-IDEM-{{run}}\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "6b. Idempotent retry - same key, same body -> replayed", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"replayed\", () => pm.expect(pm.response.headers.get(\"Idempotent-Replayed\")).to.eql(\"true\"));", "pm.test(\"same id\", () => pm.expect(pm.response.json().id).to.eql(pm.collectionVariables.get(\"idem_invoice_id\")));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{idem_key}}" } ], "url": { "raw": "{{baseUrl}}/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices" ] }, "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-IDEM-{{run}}\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "6c. Same key, different body -> 409", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"error idempotency_key_reused\", () => pm.expect(pm.response.json().error.code).to.eql(\"idempotency_key_reused\"));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{idem_key}}" } ], "url": { "raw": "{{baseUrl}}/v1/invoices", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices" ] }, "body": { "mode": "raw", "raw": "{\n \"order\": {\n \"external_id\": \"SO-OTHER-{{run}}\",\n \"number\": \"1001\",\n \"paid_at\": \"2026-10-19T09:13:05Z\",\n \"currency\": \"PLN\",\n \"payment_method\": \"card\",\n \"buyer\": {\n \"nip\": \"5260250274\",\n \"name\": \"Testowa Firma sp. z o.o.\",\n \"address_line1\": \"ul. Prosta 20\",\n \"address_line2\": \"00-850 Warszawa\",\n \"email\": \"jan@example.com\"\n },\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 2,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n },\n {\n \"name\": \"Książka: Podstawy księgowości\",\n \"sku\": \"KS-001\",\n \"quantity\": 1,\n \"unit_price\": \"59.90\",\n \"discount\": \"9.90\",\n \"vat_rate\": \"5\"\n }\n ],\n \"shipping\": [\n {\n \"name\": \"Kurier InPost\",\n \"price\": \"15.99\",\n \"vat_rate\": \"23\"\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "7. Correction (refund) for the first invoice", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const b = pm.response.json();", "if (b.id) pm.collectionVariables.set(\"correction_id\", b.id);", "pm.test(\"status 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/invoices/{{invoice_id}}/corrections", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices", "{{invoice_id}}", "corrections" ] }, "body": { "mode": "raw", "raw": "{\n \"refund\": {\n \"external_id\": \"RF-1-{{run}}\",\n \"reason\": \"Zwrot towaru\",\n \"lines\": [\n {\n \"name\": \"Kubek ceramiczny 350 ml\",\n \"sku\": \"KUB-350\",\n \"quantity\": 1,\n \"unit_price\": \"49.00\",\n \"vat_rate\": \"23\"\n }\n ],\n \"shipping\": {\n \"price\": \"15.99\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "8. Download the PDF (409 until rendered)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v1/invoices/{{invoice_id}}/pdf", "host": [ "{{baseUrl}}" ], "path": [ "v1", "invoices", "{{invoice_id}}", "pdf" ] } } }, { "name": "9. Register a webhook endpoint", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const b = pm.response.json();", "pm.collectionVariables.set(\"webhook_endpoint_id\", b.id);", "if (b.secret) pm.collectionVariables.set(\"webhook_secret\", b.secret);" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/webhook_endpoints", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhook_endpoints" ] }, "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/ksef/webhook\",\n \"enabled_events\": [\n \"*\"\n ],\n \"description\": \"Shop backend\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "10. Verify a webhook signature (offline example)", "description": "Shows how a receiver checks KSeF-Signature: v1 = HMAC-SHA256(secret, t + '.' + raw_body). Runs locally in the test script against /v1/events data; no request to your server.", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const secret = pm.collectionVariables.get(\"webhook_secret\") || \"whsec_example\";", "const body = JSON.stringify({ id: \"evt_example\", object: \"event\", type: \"invoice.accepted\" });", "const t = Math.floor(Date.now() / 1000);", "const header = \"t=\" + t + \",v1=\" + CryptoJS.HmacSHA256(t + \".\" + body, secret).toString(CryptoJS.enc.Hex);", "const parts = Object.fromEntries(header.split(\",\").map(p => p.split(\"=\")));", "const expected = CryptoJS.HmacSHA256(parts.t + \".\" + body, secret).toString(CryptoJS.enc.Hex);", "pm.test(\"signature verifies\", () => pm.expect(parts.v1).to.eql(expected));", "pm.test(\"timestamp within 5 minutes\", () => pm.expect(Math.abs(Date.now() / 1000 - Number(parts.t))).to.be.below(300));" ] } } ], "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v1/events?limit=1", "host": [ "{{baseUrl}}" ], "path": [ "v1", "events?limit=1" ] } } }, { "name": "11. List events", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v1/events", "host": [ "{{baseUrl}}" ], "path": [ "v1", "events" ] } } }, { "name": "12. Delete the webhook endpoint", "request": { "method": "DELETE", "url": { "raw": "{{baseUrl}}/v1/webhook_endpoints/{{webhook_endpoint_id}}", "host": [ "{{baseUrl}}" ], "path": [ "v1", "webhook_endpoints", "{{webhook_endpoint_id}}" ] } } } ] } ], "event": [], "variable": [ { "key": "baseUrl", "value": "https://app.ksefshop.pl" }, { "key": "invoice_id", "value": "" }, { "key": "invoice_eur_id", "value": "" }, { "key": "correction_id", "value": "" }, { "key": "webhook_endpoint_id", "value": "" }, { "key": "webhook_secret", "value": "" }, { "key": "idem_key", "value": "" }, { "key": "idem_invoice_id", "value": "" }, { "key": "event_id", "value": "" }, { "key": "run", "value": "" } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] }, "info": { "_postman_id": "13b4ae75-4224-69dc-c01b-b2b8555b10ae", "name": "KSeF Faktury API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": "Structured VAT invoices (FA(3)) in the Polish KSeF from paid orders.\n\nGenerated from docs/api/openapi.yaml (version 2026-10-19) by docs/api/tools/generate-postman.mjs. Do not edit by hand." } }