{"_id":"@app4you/n8n-nodes-ksef","_rev":"3-57f9647f9b35de10d0d41d65dec09397","name":"@app4you/n8n-nodes-ksef","dist-tags":{"latest":"1.1.0"},"versions":{"0.2.0":{"name":"@app4you/n8n-nodes-ksef","version":"0.2.0","keywords":["n8n-community-node-package","ksef","e-invoicing","poland","faktura","fa-3"],"author":{"name":"Dawid Wiewiórski","email":"biuro@app4you.dev"},"license":"MIT","_id":"@app4you/n8n-nodes-ksef@0.2.0","maintainers":[{"name":"dawidw5219","email":"wiewiorskidawid@gmail.com"}],"homepage":"https://github.com/Dawidw5219/n8n-nodes-ksef","bugs":{"url":"https://github.com/Dawidw5219/n8n-nodes-ksef/issues"},"n8n":{"nodes":["dist/Ksef.node.js"],"strict":false,"credentials":["dist/KsefApi.credentials.js"],"n8nNodesApiVersion":1},"dist":{"shasum":"4b3ad1238bfaec2b7a0bfaa631a7c33b6f88e09b","tarball":"https://registry.npmjs.org/@app4you/n8n-nodes-ksef/-/n8n-nodes-ksef-0.2.0.tgz","fileCount":9,"integrity":"sha512-qGNEp1xUTQ5yHFzWq0dBZ+OreafcuW+q23rE81ExEIpddJBdHLYXjWMmt5/v5sRKuXIDSYgac67xBFFbkgOacA==","signatures":[{"sig":"MEYCIQCeGL47j4GAg3VlMsgXkJabw1VuvJ5QpYbsAfU9E1GK9wIhAP737+l7Idi3s9oaNhWAeDiTMYQZMFSllX7oUeHhOg6z","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9456940},"gitHead":"1f23ad27f9fa0a18ea0fe6548386641e95d9f722","scripts":{"dev":"concurrently --names 'builder,n8n' --kill-others-on-fail --prefix-colors blue,green 'pnpm run dev:builder' 'pnpm run dev:n8n'","lint":"n8n-node lint","test":"vitest run","build":"tsup && cp src/icon.svg src/icon.dark.svg dist/ && node scripts/check-bundle-boundaries.mjs","deploy":"pnpm typecheck && pnpm test && pnpm build && ghdeploy --npm","dev:n8n":"N8N_USER_FOLDER=$HOME/.n8n-node-cli N8N_DEV_RELOAD=true DB_SQLITE_POOL_SIZE=10 npx -y --prefer-online n8n@2.18.4","release":"n8n-node release","lint:fix":"n8n-node lint --fix","typecheck":"tsc --noEmit","test:watch":"vitest","build:watch":"tsup --watch","dev:builder":"n8n-node dev --external-n8n","check:schemas":"pnpm generate:schemas && git diff --exit-code -- src/schemas/fa3.xsd src/generated/fa3.ts","schema:bundle":"xsd2zod bundle 'docs/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd' --outFile src/schemas/fa3.xsd --silent","prepublishOnly":"pnpm typecheck && pnpm test && pnpm build","generate:schemas":"pnpm schema:bundle && xsd2zod src/schemas/fa3.xsd --outDir src/generated/ --silent"},"_npmUser":{"name":"dawidw5219","email":"wiewiorskidawid@gmail.com"},"repository":{"url":"git+https://github.com/Dawidw5219/n8n-nodes-ksef.git","type":"git"},"_npmVersion":"10.9.8","description":"n8n community node for the official Polish KSeF API with FA(3) validation","directories":{},"_nodeVersion":"22.23.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@9.15.4","devDependencies":{"tsx":"^4.21.0","zod":"^4.4.3","tsup":"^8.5.1","big.js":"^7.0.1","eslint":"9.39.4","vitest":"^4.1.4","prettier":"3.8.3","release-it":"20.0.0","typescript":"5.9.3","concurrently":"^9.2.1","@n8n/node-cli":"*","@types/big.js":"^6.2.2","ksef-client-ts":"^0.10.0","@app4you/xsd2zod":"^1.0.2"},"peerDependencies":{"n8n-workflow":"*"},"_npmOperationalInternal":{"tmp":"tmp/n8n-nodes-ksef_0.2.0_1784801200025_0.0010627870955606245","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@app4you/n8n-nodes-ksef","version":"1.1.0","description":"n8n community node for the official Polish KSeF API with FA(3) validation","license":"MIT","homepage":"https://github.com/Dawidw5219/n8n-nodes-ksef","keywords":["n8n-community-node-package","ksef","e-invoicing","poland","faktura","fa-3"],"author":{"name":"Dawid Wiewiórski","email":"biuro@app4you.dev"},"repository":{"type":"git","url":"git+https://github.com/Dawidw5219/n8n-nodes-ksef.git"},"packageManager":"pnpm@9.15.4","publishConfig":{"access":"public"},"scripts":{"build":"tsup && cp src/icon.svg src/icon.dark.svg dist/ && node scripts/check-bundle-boundaries.mjs","build:watch":"tsup --watch","dev":"concurrently --names 'builder,n8n' --kill-others-on-fail --prefix-colors blue,green 'pnpm run dev:builder' 'pnpm run dev:n8n'","dev:builder":"n8n-node dev --external-n8n","dev:n8n":"N8N_USER_FOLDER=$HOME/.n8n-node-cli N8N_DEV_RELOAD=true DB_SQLITE_POOL_SIZE=10 npx -y --prefer-online n8n@2.18.4","deploy":"pnpm typecheck && pnpm test && pnpm build && ghdeploy --npm","lint":"n8n-node lint","lint:fix":"n8n-node lint --fix","release":"n8n-node release","prepublishOnly":"pnpm typecheck && pnpm test && pnpm build","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","schema:bundle":"xsd2zod bundle 'docs/faktury/schemy/FA/schemat_FA(3)_v1-0E.xsd' --outFile src/schemas/fa3.xsd --silent","generate:schemas":"pnpm schema:bundle && xsd2zod src/schemas/fa3.xsd --outDir src/generated/ --silent","check:schemas":"pnpm generate:schemas && git diff --exit-code -- src/schemas/fa3.xsd src/generated/fa3.ts"},"n8n":{"n8nNodesApiVersion":1,"strict":false,"credentials":["dist/KsefApi.credentials.js"],"nodes":["dist/Ksef.node.js"]},"devDependencies":{"@n8n/node-cli":"*","@types/big.js":"^6.2.2","big.js":"^7.0.1","concurrently":"^9.2.1","eslint":"9.39.4","ksef-client-ts":"^0.10.0","prettier":"3.8.3","release-it":"20.0.0","tsup":"^8.5.1","tsx":"^4.21.0","typescript":"5.9.3","vitest":"^4.1.4","@app4you/xsd2zod":"^1.0.2","zod":"^4.4.3"},"peerDependencies":{"n8n-workflow":"*"},"gitHead":"b02386676cd80cf88e619044c2bbb28ee9792e01","_id":"@app4you/n8n-nodes-ksef@1.1.0","bugs":{"url":"https://github.com/Dawidw5219/n8n-nodes-ksef/issues"},"_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-k+V+Qocss+ZZKS+KbEh1zt7uzPPnhPNQnf7fEDhKhKDf/Vl9RhW/xT+vuxZWwLUTlld2HrCPcppEicXamib+ug==","shasum":"dbcf49d65fd6f845bacba4d6909e3446d51fea2f","tarball":"https://registry.npmjs.org/@app4you/n8n-nodes-ksef/-/n8n-nodes-ksef-1.1.0.tgz","fileCount":9,"unpackedSize":9457253,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCmE+5or+/RAkLUR4//Pabpi2oot0PHTvKDcyDdCq2nIAIhAOfz0TI0SoIwMJK2KkM4BdX7loszH29tncz7/CwFwVkM"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c6ddc0c0-580e-40d2-be98-24946ad028f2"}},"directories":{},"maintainers":[{"name":"dawidw5219","email":"wiewiorskidawid@gmail.com"},{"name":"wiktorslominski","email":"wiktor.slominski@app4you.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/n8n-nodes-ksef_1.1.0_1784813589630_0.9346139442166876"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-23T10:06:39.881Z","modified":"2026-07-23T13:33:09.996Z","0.2.0":"2026-07-23T10:06:40.216Z","1.1.0":"2026-07-23T13:33:09.827Z"},"bugs":{"url":"https://github.com/Dawidw5219/n8n-nodes-ksef/issues"},"author":{"name":"Dawid Wiewiórski","email":"biuro@app4you.dev"},"license":"MIT","homepage":"https://github.com/Dawidw5219/n8n-nodes-ksef","keywords":["n8n-community-node-package","ksef","e-invoicing","poland","faktura","fa-3"],"repository":{"type":"git","url":"git+https://github.com/Dawidw5219/n8n-nodes-ksef.git"},"description":"n8n community node for the official Polish KSeF API with FA(3) validation","maintainers":[{"name":"dawidw5219","email":"wiewiorskidawid@gmail.com"},{"name":"wiktorslominski","email":"wiktor.slominski@app4you.dev"}],"readme":"# n8n-nodes-ksef \n\n[![npm version](https://img.shields.io/npm/v/%40app4you%2Fn8n-nodes-ksef.svg)](https://www.npmjs.com/package/@app4you/n8n-nodes-ksef)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nn8n community node for **KSeF** — Krajowy System e-Faktur, the Polish national e-invoicing system. Safely ingest incoming invoices, fetch, search, and parse FA-3 invoices directly from your n8n workflows.\n\nBuilt on top of [`ksef-client-ts`](https://github.com/Flopsstuff/ksef-client-ts). Outgoing FA-3 invoices are validated before sending, while incoming invoices are downloaded in the buyer role and their SHA-256 hash is verified before any Drive/PDF artifacts are produced.\n\n> **Read-only by default.** The credential setting that permits invoice issuing is disabled by default, and the node opens on **Get Incoming**. Enable issuing only in a dedicated credential after reviewing the workflow.\n\n[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.\n\n---\n\n## Table of contents\n\n- [Installation](#installation)\n- [Credentials](#credentials)\n- [Operations](#operations)\n- [How validation works](#how-validation-works)\n- [Compatibility](#compatibility)\n- [Limitations & roadmap](#limitations--roadmap)\n- [Development](#development)\n- [License](#license)\n\n---\n\n## Installation\n\n1. Open your n8n instance.\n2. Go to **Settings → Community Nodes**.\n3. Click **Install**, paste `@app4you/n8n-nodes-ksef`, and confirm.\n\nOr via npm if you self-host:\n\n```bash\nnpm install @app4you/n8n-nodes-ksef\n```\n\nSee the official [community node installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) for details.\n\n---\n\n## Credentials\n\nThe node uses one credential type — **KSeF API** — supporting three authentication methods. You always need a NIP and an environment.\n\n| Field | Required | Description |\n| --- | --- | --- |\n| **NIP** | yes | NIP of the entity (10 digits, with checksum). Whitespace and dashes are stripped automatically. |\n| **Environment** | yes | `Test` (`api-test.ksef.mf.gov.pl`), `Demo` (`api-demo.ksef.mf.gov.pl`), or `Production` (`api.ksef.mf.gov.pl`). |\n| **Auth method** | yes | `KSeF Token`, `Certyfikat .p12 (Base64)`, or `Certyfikat PEM (Cert + Klucz)`. |\n| **Timeout (ms)** | optional | `0` = SDK default (~30s). |\n\n### Auth method: KSeF Token\n\nLong-lived token generated in the official KSeF portal. Easiest for personal / single-NIP setups.\n\n| Field | Description |\n| --- | --- |\n| **KSeF Token** | Token string from the MF portal. |\n\n### Auth method: Certyfikat .p12 (Base64)\n\nPKCS#12 bundle (cert + private key). Useful if you have a qualified signature.\n\n| Field | Description |\n| --- | --- |\n| **Plik .p12 (Base64)** | Base64-encoded `.p12` bundle. On macOS: `base64 cert.p12 \\| pbcopy`. |\n| **Hasło .p12** | Password protecting the bundle. |\n\n### Auth method: Certyfikat PEM (Cert + Klucz)\n\nSeparate certificate and private key in PEM format.\n\n| Field | Description |\n| --- | --- |\n| **Certyfikat PEM** | Full PEM cert (`-----BEGIN CERTIFICATE-----...`). |\n| **Klucz Prywatny PEM** | Private key PEM (`-----BEGIN PRIVATE KEY-----` or `-----BEGIN ENCRYPTED PRIVATE KEY-----`). |\n| **Hasło Klucza** | Required only if the key is encrypted. |\n\n> **Note:** credential fields are validated locally (including NIP checksum and token/base64/PEM shape), but remote KSeF authentication is verified only by the first real operation.\n\n---\n\n## Operations\n\nOne resource — **Invoice** — with five operations.\n\n### Get Incoming\n\nSafely ingest incoming purchase invoices for reconciliation and archiving. This operation hard-codes the two safety-critical KSeF filters so a workflow cannot accidentally switch them:\n\n- subject type is always `Subject2` (the company is the buyer),\n- date type is always `PermanentStorage`, which is suitable for incremental polling.\n\nFor each result the node downloads the source XML, verifies its SHA-256 hash against KSeF metadata, and returns one n8n item containing:\n\n- the complete KSeF metadata and source XML,\n- a deterministic KSeF-number idempotency key,\n- safe Drive file names for the PDF and XML,\n- the target `YYYY-MM` folder,\n- escaped, print-ready HTML with parties, invoice identifiers, line items, and totals,\n- Unicode-safe plain text for a credential-free Google Docs → PDF export path.\n\nKSeF does not return a PDF. Use either the HTML with an HTML-to-PDF node or the plain-text representation with Google Docs export. The XML remains the source document in both cases.\n\n### Create\n\nIssue a new FA-3 invoice in KSeF and return the UPO (urzędowe poświadczenie odbioru).\n\nTwo input modes:\n\n| Source | Description |\n| --- | --- |\n| **Interaktywny formularz** | Structured form auto-generated from the FA-3 XSD schema. Required-by-schema fields are marked, dropdowns come from official enumerations (currency codes, country codes, VAT rates, document types). Sums (P_13_*, P_14_*, P_15) are computed for you from line items. Validated against FA-3 Zod schema before XML build. |\n| **Gotowy XML** | Paste your own XML. Advanced bypass — the node still runs SDK schema validation before sending. |\n\nReturns: parsed UPO (KSeF reference number, timestamps, signed acknowledgement).\n\n### Get\n\nFetch a single invoice by KSeF number.\n\n| Field | Description |\n| --- | --- |\n| **KSeF Number** | Format: `NIP-YYYYMMDD-XXXXXXXXXXXX` (12 hex chars). Validated client-side via the SDK. |\n\nReturns: `xml` (raw FA-3 XML), `hash` (SHA-256), `fields` (extracted business fields when the XML matches FA-2/FA-3).\n\n### Get Many\n\nSearch invoices by date range and subject type. Two modes:\n\n| Mode | Use case |\n| --- | --- |\n| **Metadata (zalecane)** | Lightweight metadata page-walk. Hard cap of 10 000 results. Returns `invoices[]`, `totalReturned`, `hasMore`, `isTruncated`. |\n| **Download (XMLs)** | Full export package with invoice XMLs (extracted from the KSeS ZIP, base64-encoded per file). Suitable for bulk archives. |\n\nFilters: `subjectType` (Subject1=sales, Subject2=purchases, Subject3, SubjectAuthorized), `dateType` (Issue / Invoicing / PermanentStorage), `dateFrom`, `dateTo`. Validated client-side: `dateFrom <= dateTo`, ISO 8601 with offset.\n\n### Parse\n\nValidate and extract fields from a raw FA-3 XML you already have. No KSeF call.\n\n| Field | Description |\n| --- | --- |\n| **XML** | FA-3 invoice XML to validate and parse. |\n| **Skip Char Validity** | Skip the Level 1a char-validity pre-parse (XML processing instructions and discouraged Unicode). |\n\nReturns: `isValid`, `schemaType`, `errors[]`, `fields` (when extractable).\n\n---\n\n## How validation works\n\nThis node validates **before** any KSeF call, in three layers:\n\n1. **Compile-time (TypeScript).** The form spec is a mapped type over the `Faktura` Zod schema generated from the FA-3 XSD. Adding a field that doesn't exist in FA-3 is a TS error. Operation enums (`SubjectType`, `DateType`, `SortOrder`) are `as const satisfies` against the SDK's literal types — if the SDK adds a new value, TS forces us to extend. Incoming ingestion additionally hard-codes buyer/permanent-storage filters and verifies downloaded XML hashes.\n2. **Startup (coverage check).** When the node loads, the `zod2n8n` walker asserts that every required-by-Zod field is either present in the spec, omitted explicitly, or filled by `compute`. Spec drift is caught at boot, not at execute.\n3. **Runtime (per execution).** Every operation pre-flights its input through Zod (`Filters.safeParse` for `Get Many`, `fakturaForm.parse` for `Create`, `isValidKsefNumber` for `Get`, SDK `validate()` for `Parse`). KSeF only ever sees data that already passed local validation.\n\n```\nsrc/schemas/fa3.xsd       (official FA-3 XSD, committed)\n        │\n        └─► xsd2zod   ──►  src/generated/fa3.ts   (Zod schema with .meta() value-docs)\n                                  │\n                                  └─►  zod2n8n walker\n                                       │\n                                       ├──► n8n form properties (auto-generated)\n                                       └──► fakturaForm.parse() (pre-flight validator)\n                                                  │\n                                                  └──► ksef-client-ts → KSeF API\n```\n\nRegenerate the schema from the XSD:\n\n```bash\npnpm run generate:schemas\n```\n\nWhen MF publishes a new FA version, the form, dropdowns, and validators all update from one regen.\n\n---\n\n## Compatibility\n\n- **n8n:** `>=2.0.0` (tested against n8n 2.31.x).\n- **Node.js:** `>=18.10` (n8n requirement).\n- **KSeF API:** v2.6.x. FA-3 invoices.\n- **TypeScript (for development):** 5.9+.\n\n---\n\n## Limitations & roadmap\n\n**Currently supported:**\n- Safe incoming-invoice ingestion with hash verification and PDF-ready HTML/plain text.\n- Issue, fetch, search, parse FA-3 invoices.\n- 3 auth methods (token, .p12, PEM).\n- Test / Demo / Production environments.\n\n**Not yet supported (planned):**\n- Cancel session / cancel queued invoice (`KSEF.cancel`).\n- Re-fetch UPO by KSeF number after the original `Create` output is lost.\n- Send-without-close (multiple invoices in one online session).\n- Cross-validation: warn when seller NIP in the invoice ≠ session NIP from credentials.\n- Telemetry hooks.\n\nOpen an issue on [GitHub](https://github.com/Dawidw5219/n8n-nodes-ksef/issues) for feature requests.\n\n---\n\n## Development\n\n```bash\npnpm install\npnpm dev          # starts n8n with the node hot-reloaded\npnpm build        # tsc + copy icon to dist\npnpm lint         # n8n-node lint\npnpm typecheck    # tsc --noEmit\n```\n\nThe node lives in `src/Ksef.node.ts`, credentials in `src/KsefApi.credentials.ts`. Per-operation code in `src/resources/invoice/actions/`. The form auto-generator (`zod2n8n`) is in `src/utils/zod2n8n/` and is intended to ship as a standalone npm package later.\n\nSee [`AUDIT.md`](AUDIT.md) for the archived pre-publication audit from 2026-05-08. Its original findings are retained for history and do not describe the current release state.\n\n---\n\n## License\n\n[MIT](LICENSE) © 2026 Dawid Wiewiórski\n","readmeFilename":"README.md"}