n8n-nodes-pokash-archive

Custom n8n node integrating with the POKASH document archive API (https://archive.pokash.cloud).

Operations

| Operation | What it does | |---|---| | Register MinIO File | Triggers AI classification on a PDF/XML/image already stored in MinIO. The file is not copied — only metadata flows into the archive. Optional polling waits for classification to finish and returns the full Document object in the next step. | | Get Request Status | Polls the status of a previously registered request by request_id. | | Get Document | Fetches a classified document by UUID or by archive number (e.g. PKSH/2026/05/42). Includes a presigned MinIO download URL. |

Build

cd n8n-node
npm install
npm run build
# Output goes to ./dist

Install in self-hosted n8n (Docker)

Mount dist/ into the n8n custom-extensions directory:

docker run -d \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  -v $(pwd)/dist:/home/node/.n8n/custom/n8n-nodes-pokash-archive \
  -e N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom \
  n8nio/n8n

Or via npm-link in n8n's custom directory:

mkdir -p ~/.n8n/custom && cd ~/.n8n/custom
npm link n8n-nodes-pokash-archive

Restart n8n. The node appears as POKASH Archive in the node palette.

Configure credentials

1. n8n → Credentials → New → search POKASH Archive API
2. Fields:
   • API URL — https://archive.pokash.cloud
   • API Key — long-lived key issued via POST /api-keys (format: ark_<tenant>_<random>)
   • Tenant Code (optional, cosmetic) — np. PKSH, ułatwia rozpoznanie credentialu w UI

API key NIE wygasa do momentu rewokacji. Tenant jest powiązany z kluczem po stronie API — nie trzeba podawać go ręcznie w żądaniach.

Generowanie API key

Pełny przewodnik (Swagger UI + curl, listowanie, rewokacja, best practices): docs/API_KEYS.md

TL;DR (curl):

API="https://archive.pokash.cloud"; TENANT="PKSH"
BOOT=$(curl -s -X POST "$API/auth/bootstrap-token" -H 'Content-Type: application/json' -d '{}' | jq -r .access_token)
JWT=$(curl -s -X POST "$API/auth/token" -H "Authorization: Bearer $BOOT" -H 'Content-Type: application/json' -d "{\"tenant_code\":\"$TENANT\",\"ttl_seconds\":3600}" | jq -r .access_token)
curl -s -X POST "$API/api-keys" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"name":"n8n production"}' | jq -r .key

Output to plaintext API key — wklej go natychmiast do n8n credentials (pole API Key). Pokazywany jest tylko raz.

Example workflow

[MinIO Webhook]  →  [POKASH Archive: Register MinIO File]  →  [Slack: notify]
                       bucket: ={{$json.Records[0].s3.bucket.name}}
                       objectKey: ={{$json.Records[0].s3.object.key}}
                       source: ksef
                       waitForClassification: true

When waitForClassification is enabled, the node returns the full Document object once classification finishes (status classified). Useful fields in the output:

{
  "id": "...",
  "archive_number": "PKSH/2026/05/42",
  "document_type": "invoice",
  "document_date": "2026-05-13",
  "document_number": "PL6773048",
  "sender_name": "OVH SP z.o.o.",
  "sender_tax_id": "8992520556",
  "amount_net": 58.99,
  "amount_gross": 72.56,
  "currency": "PLN",
  "summary": "...",
  "download_url": "https://s3.pokash.cloud/...presigned..."
}

License

MIT