efaktura — SDK + CLI for the eFaktúra Agent API

Typed Node/TS SDK and the efaktura command-line tool for the eFaktúra Agent API (https://api.efaktura.sk): invoices (incl. PDF/UBL XML and attachments), Peppol e-invoicing (send, batch, status, delivery evidence, received documents, preflight validation, event log), customers, vendors, expenses (upload with OCR, approve/reject, payments, bulk actions, Pay by Square QR), projects, dashboard, bank accounts and movements, inventory (warehouses, stock levels, stock documents), customer vehicles and the fleet module (Autopark: vehicles, documents, insurance, fines, deadlines, installment sales, vehicle register), contracts and the company register. A PHP client lives in php/.

Auth = an API key (X-API-Key, created in eFaktúra → Nastavenia → Integrácie → API kľúče) plus the organisation it acts for (X-Organization-Id). Test keys (efk_test_…, efk_pk_test_…) hit the Peppol testbed and are never billed.

Prefer talking instead of typing? The same capabilities are exposed to Claude, ChatGPT, Claude Code and Cursor through the eFaktúra MCP server (https://api.efaktura.sk/mcp, OAuth 2.1): https://developers.efaktura.sk/docs/mcp

CLI

npm i -g efaktura            # or: npx efaktura …

efaktura login --api-key efk_test_…        # verifies the key, stores it in ~/.config/efaktura/config.json (0600)
efaktura whoami                            # key source, mode, organisations

# Invoices
efaktura invoices list --status overdue --per-page 50
efaktura invoices get <id>
efaktura invoices create --file faktura.json          # Idempotency-Key is generated unless --idempotency-key is given
efaktura invoices update <id> --file zmeny.json       # items, dates, notes; pass "version" for issued invoices
efaktura invoices status <id> paid
efaktura invoices pdf <id> --out faktura.pdf          # --out - streams to stdout
efaktura invoices xml <id>                            # Peppol BIS 3.0 UBL
efaktura invoices attach <id> --file priloha.pdf

# Peppol
efaktura peppol send <invoiceId>           # preview only (exit 2) …
efaktura peppol send <invoiceId> --confirm # … sends: irreversible, uses Peppol credit
efaktura peppol send-batch <id1> <id2> --confirm
efaktura peppol status <invoiceId>
efaktura peppol evidence <invoiceId>
efaktura peppol recipient 0245:2020123456
efaktura peppol preflight --file faktura.xml --receiver 0245:2020123456
efaktura peppol events --from 2026-09-01 --to 2026-09-30
efaktura peppol received list --acknowledged false
efaktura peppol received pdf <id> --out prijata.pdf
efaktura peppol received ack <id>

# Contacts, expenses, projects
efaktura customers list --search "Novák"
efaktura vendors get <id>
efaktura expenses list --status approved --from 2026-09-01
efaktura expenses upload --file blocek.jpg --ocr background
efaktura expenses approve <id> | efaktura expenses reject <id> --reason "duplicita"
efaktura expenses mark-paid <id> --amount 120.50 --date 2026-09-09
efaktura expenses bulk --file akcia.json           # {"ids":[…],"action":"add_labels","data":{"labels":["Q3"]}}
efaktura expenses qr <id>                          # Pay by Square QR (base64 image)
efaktura projects list --status active

# Bank, inventory, vehicles, contracts
efaktura bank accounts
efaktura bank movements <accountId> --from 2026-09-01 --to 2026-09-30
efaktura inventory stock --sku ABC-1
efaktura inventory doc-create --file prijemka.json && efaktura inventory doc-confirm <id>
efaktura vehicles by-plate BA123XY
efaktura autopark deadlines --days 30
efaktura autopark register --ecv BA123XY
efaktura contracts list --status active
efaktura contracts payments <id>

efaktura dashboard --period 2026-09
efaktura company 36631124 | efaktura company search "Slovnaft"
efaktura webhooks listen --port 4242 --secret whsec_…
efaktura help                                      # the full command list

Output is JSON on stdout, errors on stderr with exit code 1 (API chyba <status> (<code>): <message>). Every command accepts --org <uuid>, --api-key, --base-url; the environment variables EFAKTURA_API_KEY, EFAKTURA_ORG_ID, EFAKTURA_BASE_URL override the config file, flags override both. Commands that take --file accept - for stdin.

webhooks listen runs a local HTTP receiver, verifies the X-Webhook-Signature (t=…,v1=…, HMAC-SHA256) against --secret and pretty-prints each event.

Node / TypeScript

import { EfakturaClient } from "efaktura";

const efaktura = new EfakturaClient({
  apiKey: process.env.EFAKTURA_API_KEY!,
  organizationId: process.env.EFAKTURA_ORG_ID,
});

const overdue = await efaktura.invoices.list({ status: "overdue", per_page: 50 });
const created = await efaktura.invoices.create(payload, { idempotencyKey: "order-1001" });
await efaktura.peppol.send(created.id);
const { bytes } = await efaktura.invoices.pdf(created.id); // Uint8Array
const evidence = await efaktura.peppol.sentEvidence(created.id);
const accounts = await efaktura.bank.accounts();
const movements = await efaktura.bank.movements(accounts[0].id, {
  from: "2026-09-01",
  to: "2026-09-30",
});
await efaktura.expenses.upload({
  base64_data,
  mime_type: "application/pdf",
  process_ocr: "background",
});
const company = await efaktura.companyLookup.byIco("36631124");

Resources: organizations, invoices (+ attachments), customers, vendors, expenses, projects, peppol (+ received), dashboard, bank, inventory (warehouses, stockLevels, stockDocuments), vehicles, autopark (vehicles, register, documents, fines, insurances, deadlines, installments), contracts, companyLookup. Request bodies are passed through untyped (see the OpenAPI spec at https://api.efaktura.sk/v1/agent/openapi.yaml); client.request(method, path, opts) and client.download(path) cover anything new.

Errors throw EfakturaApiError with .status, .code and the raw .details.

PHP

use Efaktura\Sdk\EfakturaClient;

$efaktura = new EfakturaClient($apiKey, $organizationId);
$invoices = $efaktura->listInvoices(['status' => 'sent']);

See php/ (composer.json, PSR-4 Efaktura\Sdk\).

Docs: https://developers.efaktura.sk/docs/cli · MCP server: https://developers.efaktura.sk/docs/mcp · API reference: https://developers.efaktura.sk/reference