n8n-nodes-quick

A QUiCK (helloquick.riport.app) számlázó- és könyvelőrendszer Public API-ja dual-purpose npm csomagként:

1. n8n community node + trigger node — n8n-workflow-ba dropolható integráció
2. QuickClient API kliens — framework-mentes, type-safe TypeScript kliens bárhol, ahol Node.js 20+ vagy modern JS runtime fut

Szerző: E. Martin Maho

Highlight features:

• ⚡ Párhuzamos pagináció (count-alapú, ~5x gyorsabb listázás)
• 🔁 Auto-retry 429 / 5xx-re exponenciális backoff-fal, Retry-After fejléccel
• 📦 Auto-batch chunking bulk akciókra (100/req) és create-re (5/req)
• 🤖 usableAsTool: true — AI Agent node automatikusan használhatja
• 🌳 Két output ág (Output / Error) continueOnFail esetén
• 🔍 Resource Locator + loadOptions dropdown ID mezőkre
• 📄 Binary input bridge számlakép és audit XML feltöltéshez
• 📚 Workflow templates a templates/ mappában

QuickClient API (npm import)

import { QuickClient, QuickApiError } from 'n8n-nodes-quick';

const quick = new QuickClient({ apiToken: process.env.QUICK_TOKEN! });

// Egyszeri lekérés
const expenses = await quick.expenses.list({ is_paid: false });

// Async iterátor — automatikus pagináció minden oldalon
for await (const expense of quick.expenses.iterate({ from_date: '2026-01-01' })) {
  console.log(expense.partner_name, expense.gross_amount);
}

// Részletek
const detail = await quick.expenses.get(42);

// Bulk akció — 100-as batch méretben automatikusan chunkolva
await quick.expenses.approve([1, 2, 3 /* …akár több ezer ID */]);

// Hibakezelés
try {
  await quick.expenses.get(999);
} catch (err) {
  if (err instanceof QuickApiError) {
    if (err.isNotFound) console.log('nincs ilyen kiadás');
    if (err.isAuthError) console.log('rossz token');
    if (err.isTransient) console.log('átmeneti hiba — később próbálkozz');
  }
}

Resource namespace-ek: expenses, incomes, partners, accounts, payments, pulse, documents, documentTypes, taxes, taxCodes, salaries, ledgerNumbers, vatCategories, company, artifacts, auditXml (16 darab — minden non-OAuth végpont).

Egyedi transport (proxy / custom auth / Workers env):

import { QuickClient, createFetchTransport } from 'n8n-nodes-quick';

const transport = createFetchTransport({
  apiToken: process.env.QUICK_TOKEN!,
  fetch: customFetch,            // pl. proxy-zolt fetch
  maxRetries: 5,
  defaultHeaders: { 'X-App': 'my-app' },
});
const quick = new QuickClient(transport);

Telepítés

n8n-en belül Settings → Community Nodes → Install és add meg a csomag nevét: n8n-nodes-quick.

Helyi fejlesztéshez:

npm install
npm run build
# az n8n custom mappájába linkelés
mkdir -p ~/.n8n/custom
ln -s "$(pwd)" ~/.n8n/custom/n8n-nodes-quick

Indítsd újra az n8n-t, ezután a QUiCK node megjelenik a node listában.

Hitelesítés

A node Token típusú authentikációt használ: Authorization: Token <api_key>. A QUiCK admin felületén kérhető API kulcs.

A credential űrlap mezői:

A credential teszt a /2/company-info/ végponttal validál.

Resource-ok és műveletek

Lapozás

A Get Many műveletek a paginált végpontokon a Return All kapcsolóval automatikusan végiglapoznak (page=1..N), egyébként a megadott Limit értékkel egy oldalt kérnek le.

ID listás mezők

A vesszővel elválasztott ID mezőket (ids, with_tag_ids, simple_tag_ids, …) a node automatikusan parsolja számtömbbé a request body / query előtt.

Példa: utolsó 30 nap kiadásai

1. Resource: Expense
2. Operation: Get Many
3. Return All: true
4. Filters:
   • date_field: fulfilled_at
   • from_date: ={{ $today.minus({days:30}).toFormat('yyyy-MM-dd') }}
   • to_date: ={{ $today.toFormat('yyyy-MM-dd') }}

Fejlesztés

npm install
npm run dev    # tsc --watch
npm run lint
npm run build  # tsc + ikon másolás dist/-be

Tesztek

Háromrétegű tesztpiramis, jest + ts-jest alatt. 263 teszt, 100% statement / line / function coverage, 97% branch coverage (a maradék 3% defenzív kód, pl. ?? String(error) ami csak nem-Error throw esetén futna le — n8n-ben sosem). Threshold-ként rögzítve — a npm run test:coverage bármilyen regresszió esetén hibát dob. npm run lint zero error, npm run build zero error.

npm test                # egyszeri futtatás (jest)
npm run test:watch      # watch mód, fejlesztés közben
npm run test:coverage   # lcov + html report a coverage/ mappába

A három teszt-réteg:

tests/
├── credentials/                              # 1. statikus contract tesztek
│   └── QuickApi.credentials.test.ts
├── helpers/
│   └── mockExecuteFunctions.ts               # IExecuteFunctions factory
├── nodes/Quick/
│   ├── GenericFunctions.test.ts              # 2.a unit tesztek
│   ├── Quick.description.test.ts             # 2.b description integritás
│   ├── Quick.description.snapshot.test.ts    # 2.c sort-order + snapshot
│   ├── Quick.handlers.test.ts                # 2.d resource × operation lefedés
│   ├── Quick.node.test.ts                    # 2.e execute() core happy paths
│   └── Quick.execute.errors.test.ts          # 2.f hibaágak
└── integration/
    └── Quick.integration.test.ts             # 3. nock-os HTTP wire teszt

Licenc

MIT