CLI & SDK

The efaktura npm package ships a typed Node/TS client for the Agent API and the efaktura command line — both cover the whole Agent API (invoices, Peppol, expenses, bank, inventory, fleet, contracts). Output is JSON, so the same commands serve a person, a CI script and an AI agent. It uses the same API keys, scopes, limits and audit log as REST calls.

Install and sign in

npm i -g efaktura
efaktura login --api-key efk_test_…     # key from Settings → Integrations → API keys
efaktura whoami

The key is stored in your profile only (~/.config/efaktura/config.json, mode 0600). In CI use EFAKTURA_API_KEY and EFAKTURA_ORG_ID; --api-key / --org override both.

Test keys (efk_test_…) send to the Peppol TEST network and are never billed — start with them.

Commands

Command	What it does
efaktura login --api-key <efk_…> [--org <uuid>]	Verifies the key and stores it in ~/.config/efaktura/config.json (mode 0600)
efaktura whoami	Key source, mode (test/live) and the organisations it can act for
efaktura invoices list\|get\|create\|update\|status\|remind	Invoices: filtered, paginated list, detail, issue from JSON (Idempotency-Key generated), content edit, status change, reminder
efaktura invoices pdf\|xml <id> [--out file\|-]	Downloads the invoice PDF or UBL XML (file name from the API by default)
efaktura invoices attachments\|attach\|detach	Invoice attachments: list, add a file (PDF/JPG/PNG), remove
efaktura peppol send <id> [--confirm] \| send-batch <id…> --confirm	Without --confirm a preview only (exit 2); with --confirm queues the Peppol send (irreversible)
efaktura peppol status\|evidence\|recipient\|preflight\|submission\|events	Delivery status, delivery evidence, recipient lookup, XML validation before sending, submission status, event log
efaktura peppol received list\|get\|evidence\|ack\|attachments\|pdf\|xml	Received Peppol documents including PDF/XML and acknowledgement
efaktura customers list\|get\|create	Customers (create with --file, idempotent)
efaktura vendors list\|get\|create	Vendors
efaktura expenses list\|get\|create\|upload\|update\|approve\|reject\|mark-paid\|ocr\|bulk\|scan-qr\|qr\|stats	Expenses and received documents: file upload with OCR, approval, payments, bulk actions, payment QR, statistics
efaktura projects list\|get\|create\|update	Projects
efaktura dashboard [--period YYYY-MM]	Monthly summary
efaktura bank accounts \| movements <accountId> --from --to	Bank accounts and movements (cursor pagination)
efaktura inventory warehouses\|stock\|stock-get\|docs\|doc-get\|doc-create\|doc-confirm	Warehouses, stock levels and stock documents
efaktura vehicles list\|get\|by-plate	Customer vehicles (invoicing by plate)
efaktura autopark vehicles\|register\|documents\|fines\|insurances\|deadlines\|installments…	Fleet: vehicles, register by plate/VIN, documents, fines, insurance, deadlines, installment sales (+ *-create)
efaktura contracts list\|get\|payments\|stats\|create\|update\|generate-payments	Contracts and recurring payments
efaktura company <ico> \| company search <name>	Company register
efaktura webhooks listen [--port] [--secret]	Local webhook receiver with signature verification

efaktura help prints the full list with parameters. Commands taking --file accept - for stdin; downloads with --out - stream the bytes to stdout.

Every command accepts --org <uuid> (the organisation the key acts for). Errors go to stderr as API chyba <status> (<code>): <message> with exit code 1; the codes match the API error codes.

Example: issue and send through Peppol

cat > invoice.json <<'JSON'
{
  "customer": { "name": "Novák s. r. o.", "ico": "36631124" },
  "items": [{ "description": "Consulting 09/2026", "quantity": 12, "unit": "hod", "unit_price": 60, "vat_rate": 23 }],
  "due_days": 14
}
JSON
efaktura invoices create --file invoice.json --idempotency-key order-1001 > issued.json
ID=$(jq -r .id issued.json)
efaktura peppol send "$ID"            # preview, nothing is sent
efaktura peppol send "$ID" --confirm  # send
efaktura peppol status "$ID"

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);
const accounts = await efaktura.bank.accounts();
await efaktura.expenses.upload({ base64_data, mime_type: "application/pdf", process_ocr: "background" });

Resources: organizations, invoices (+ attachments), customers, vendors, expenses, projects, peppol (+ received), dashboard, bank, inventory, vehicles, autopark, contracts, companyLookup — 1:1 with the Agent API modules. Errors throw EfakturaApiError with status, code and details. A PHP client lives in the same repository (php/).

Webhooks locally

efaktura webhooks listen --port 4242 --secret whsec_…
# point a registered endpoint at http://localhost:4242 through a tunnel (e.g. cloudflared)

The receiver verifies X-Webhook-Signature (HMAC-SHA256) and prints every event — the local counterpart to durable delivery and replay in the portal.