CLI a SDK

Balík efaktura na npm obsahuje typovaný Node/TS klient Agent API a príkazový riadok efaktura — pokrývajú celé Agent API (faktúry, Peppol, výdavky, banka, sklad, vozový park, zmluvy). Výstup je JSON, takže rovnaké príkazy poslúžia človeku, skriptu v CI aj AI agentovi. Používa rovnaké API kľúče, scopes, limity a audit ako REST volania.

Inštalácia a prihlásenie

npm i -g efaktura
efaktura login --api-key efk_test_…     # kľúč z Nastavenia → Integrácie → API kľúče
efaktura whoami

Kľúč sa ukladá iba do vášho profilu (~/.config/efaktura/config.json, práva 0600). V CI použite premenné EFAKTURA_API_KEY a EFAKTURA_ORG_ID; parametre --api-key / --org majú prednosť pred oboma.

Testovacie kľúče (efk_test_…) posielajú do siete Peppol TEST a nikdy sa neúčtujú — začnite nimi.

Príkazy

Príkaz	Čo robí
efaktura login --api-key <efk_…> [--org <uuid>]	Overí kľúč a uloží ho do ~/.config/efaktura/config.json (práva 0600)
efaktura whoami	Zdroj kľúča, režim (test/live) a firmy, ku ktorým má prístup
efaktura invoices list\|get\|create\|update\|status\|remind	Faktúry: zoznam s filtrami a stránkovaním, detail, vystavenie z JSON (Idempotency-Key automaticky), úprava obsahu, zmena stavu, upomienka
efaktura invoices pdf\|xml <id> [--out súbor\|-]	Stiahne PDF alebo UBL XML faktúry (predvolene názov súboru z API)
efaktura invoices attachments\|attach\|detach	Prílohy faktúry: zoznam, pridanie súboru (PDF/JPG/PNG), odstránenie
efaktura peppol send <id> [--confirm] \| send-batch <id…> --confirm	Bez --confirm iba náhľad (exit 2); s --confirm zaradí do fronty Peppol (nevratné)
efaktura peppol status\|evidence\|recipient\|preflight\|submission\|events	Stav doručenia, dôkaz o doručení, overenie príjemcu, validácia XML pred odoslaním, stav podania, denník udalostí
efaktura peppol received list\|get\|evidence\|ack\|attachments\|pdf\|xml	Prijaté Peppol doklady vrátane PDF/XML a potvrdenia prevzatia
efaktura customers list\|get\|create	Zákazníci (create s --file, idempotentné)
efaktura vendors list\|get\|create	Dodávatelia
efaktura expenses list\|get\|create\|upload\|update\|approve\|reject\|mark-paid\|ocr\|bulk\|scan-qr\|qr\|stats	Výdavky a prijaté doklady: nahratie súboru s OCR, schvaľovanie, úhrady, hromadné akcie, platobný QR, štatistiky
efaktura projects list\|get\|create\|update	Zákazky (projekty)
efaktura dashboard [--period YYYY-MM]	Mesačný prehľad
efaktura bank accounts \| movements <accountId> --from --to	Bankové účty a pohyby (cursor stránkovanie)
efaktura inventory warehouses\|stock\|stock-get\|docs\|doc-get\|doc-create\|doc-confirm	Sklady, stav zásob a skladové doklady
efaktura vehicles list\|get\|by-plate	Vozidlá zákazníkov (fakturácia podľa ŠPZ)
efaktura autopark vehicles\|register\|documents\|fines\|insurances\|deadlines\|installments…	Vozový park: vozidlá, register podľa ŠPZ/VIN, doklady, pokuty, poistky, termíny, predaje na splátky (+ *-create)
efaktura contracts list\|get\|payments\|stats\|create\|update\|generate-payments	Zmluvy a opakované platby
efaktura company <ico> \| company search <názov>	Register firiem
efaktura webhooks listen [--port] [--secret]	Lokálny prijímač webhookov s overením podpisu

Úplný zoznam s parametrami vypíše efaktura help. Príkazy s --file prijímajú - pre stdin; sťahovanie s --out - posiela bajty na stdout.

Každý príkaz prijíma --org <uuid> (firma, za ktorú kľúč koná). Chyby idú na stderr ako API chyba <status> (<kód>): <správa> s exit kódom 1; kódy sú rovnaké ako v chybových kódoch API.

Príklad: vystavenie a odoslanie cez Peppol

cat > faktura.json <<'JSON'
{
  "customer": { "name": "Novák s. r. o.", "ico": "36631124" },
  "items": [{ "description": "Konzultácie 09/2026", "quantity": 12, "unit": "hod", "unit_price": 60, "vat_rate": 23 }],
  "due_days": 14
}
JSON
efaktura invoices create --file faktura.json --idempotency-key order-1001 > vystavena.json
ID=$(jq -r .id vystavena.json)
efaktura peppol send "$ID"            # náhľad, nič sa neposiela
efaktura peppol send "$ID" --confirm  # odoslanie
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" });

Zdroje: organizations, invoices (+ attachments), customers, vendors, expenses, projects, peppol (+ received), dashboard, bank, inventory, vehicles, autopark, contracts, companyLookup — 1:1 s modulmi Agent API. Chyby vyhadzujú EfakturaApiError so status, code a details. Klient pre PHP je v tom istom repozitári (php/).

Webhooky lokálne

efaktura webhooks listen --port 4242 --secret whsec_…
# nasmerujte zaregistrovaný endpoint cez tunel (napr. cloudflared) na http://localhost:4242

Prijímač overí hlavičku X-Webhook-Signature (HMAC-SHA256) a vypíše každú udalosť — lokálny náprotivok trvalého doručovania a replayu v portáli.