elnora-merit-aktiva

Do your Merit Aktiva accounting from the command line — or let Claude Code do it for you.

Merit Aktiva is Estonia's cloud accounting platform. This repo gives you two ways to drive its API:

• elnora-merit — a CLI that covers the entire Merit Aktiva API (invoices, payments, VAT/KMD, ledger, reports, and more) plus Merit Palk payroll. JSON in, JSON out.
• A Claude Code plugin that wraps the CLI in skills, agents, and slash commands, so you can ask in plain English ("book this purchase invoice", "file my KMD") and Claude runs the right commands the right way.

Everything is universal — nothing about any one company is hardcoded. Point it at your own Merit credentials and it works.

Requires a Merit Aktiva Pro or Premium license — the API is not available on lower tiers.

Install

As a CLI

npm install -g @elnora-ai/merit-aktiva

This puts the elnora-merit command on your PATH. Node.js ≥ 20 required.

As a Claude Code plugin

Paste these two slash commands into Claude Code one at a time — wait for the first to finish before the second:

/plugin marketplace add Elnora-AI/elnora-merit-aktiva

/plugin install merit-aktiva-workspace@elnora-merit-aktiva

The plugin uses the elnora-merit CLI under the hood, so install that first.

Authenticate

Generate an API ID and API Key in Merit Aktiva:
Settings → Company data → API settings → "Koosta võti" (Generate key).

The CLI reads them from environment variables. On first run it also prompts and saves them to ~/.config/elnora-merit/.env (mode 0600):

export MERIT_API_ID=your-api-id
export MERIT_API_KEY=your-api-key

Or copy .env.template to .env and fill it in (.env is gitignored — never commit it).

Company profile (optional)

Snapshot your account's own chart of accounts, banks, VAT codes, and financial years so
an agent (or you) can look up the real codes without transcribing them by hand:

elnora-merit profile sync                  # → company-profile.json (in MERIT_REFERENCES_DIR)
elnora-merit profile show --section taxes  # the VAT TaxId guids, etc.

company-profile.json holds no secrets but is company-specific, so it is gitignored.
Re-run profile sync whenever the chart of accounts changes.

Quickstart

elnora-merit accounts list                              # chart of accounts
elnora-merit banks list                                 # bank accounts
elnora-merit taxes list                                 # VAT rates
elnora-merit customers list --name "Acme"               # find a customer
elnora-merit sales-invoices list --period-start 2026-01-01 --period-end 2026-03-31
elnora-merit reports income-statement --end-date 20260331 --per-count 3

# Output controls (work on any command)
elnora-merit accounts list --output table --fields Code,Name
elnora-merit accounts list --pretty                     # pretty JSON

Creating documents. Create/send commands take the Merit JSON body via --data (inline) or --file (path). Each command's --help lists the required fields:

elnora-merit sales-invoices create --file invoice.json

See the official Merit reference manual for field details.

What you can do

Full coverage of the Merit Aktiva REST API — 22 resource groups — plus two local helpers: profile (snapshot your account's codes) and reconcile (book Stripe payouts). Run elnora-merit <group> --help for per-command options and payload schemas.

Payroll (Merit Palk)

palk is Merit's separate payroll product. It uses its own credentials (MERIT_PALK_API_ID / MERIT_PALK_API_KEY) and needs a Merit Palk PRO license.

elnora-merit palk employees list
elnora-merit palk base-salary list --start-month 202601 --end-month 202612
elnora-merit palk gl get --month 202606                   # GL batch for a month
elnora-merit palk salary-report --start-date 2026-06-01 --end-date 2026-06-30

Palk dates are YYYY-MM-DD and months are YYYYMM. See the Palk reference manual.

Reconcile Stripe payouts

Book Stripe card sales, fees, and refunds into Merit, one payout at a time (a payout = one bank deposit). Works for any Stripe account → any Merit company.

elnora-merit reconcile init                 # write a config template to ~/.config/elnora-merit/stripe-map.json
# ...edit that file: account codes + VAT (see stripe-map.example.json)

export STRIPE_API_KEY=sk_live_...           # a read-only restricted key is enough

elnora-merit reconcile preview --output table   # read-only: shows exactly what would be booked
elnora-merit reconcile run --yes                # book it (idempotent — never books a payout twice)
elnora-merit reconcile status                   # booked vs outstanding

Each payout becomes one balanced summary GL batch: card sales debit a clearing account, revenue is credited net of VAT (the VAT posts implicitly from the revenue line's tax tag, which auto-populates the KMD), and fees are booked as a separate expense. Your real bank-import row then clears the payout net in Merit — no double posting. The connector refuses to book a payout whose figures don't balance. See docs/stripe-reconciliation-spec.md for the full design.

What's in this repo

elnora-merit-aktiva/
├── src/                    # the elnora-merit CLI (TypeScript)
├── skills/                 # Claude Code how-to skills (the right Merit procedure for each task)
├── agents/                 # plugin agents
├── commands/               # plugin slash commands
├── docs/                   # Stripe reconciliation spec and design notes
├── .claude-plugin/         # plugin + marketplace manifest
├── AGENTS.md               # agent usage conventions
└── INSTALL_FOR_AGENTS.md   # step-by-step agent setup walkthrough

The plugin ships how-to skills for both products so Claude follows the correct Merit procedure, not just the raw API:

• Accounting — merit-aktiva-workspace (router), merit-sales-invoices, merit-purchase-invoices, merit-payments-bank, merit-vat-kmd, merit-reports, merit-reverse-charge, merit-stripe.
• Payroll — merit-palk-workspace (router), merit-palk-employees, merit-palk-payroll, merit-palk-reports, merit-palk-settings.

Design

• Universal & open — no account-specific values baked in. Configure with env vars; works for any Merit company.
• Correct by construction — HMAC-SHA256 request signing, verified against Merit's published test vector.
• Agent-friendly — JSON by default, machine-readable error envelopes with dedicated exit codes, --data/--file for complex payloads.
• Safe — destructive operations require an explicit --yes; credentials and signatures are redacted from all output.

Output & errors

• Formats: --output json (default, compact), table, or csv. --pretty for indented JSON. --fields a,b to pick columns.
• Errors are JSON on stderr with a message, a suggestion, and structured data.
• Exit codes: 0 success · 1 general · 2 validation · 3 auth · 5 rate limited · 6 API error.

Notes & gotchas

• Merit endpoints are POST with a JSON body, even read/query operations.
• Dates: query fields use YYYYMMDD (the CLI also accepts YYYY-MM-DD and normalizes). Some payload fields use YYYYMMDDHHMMSS — see each command's help.
• Period limits: invoice list queries span at most 3 months.
• Batch limit: at most 500 rows per document.
• Sales invoices cannot be updated — delete and re-create. Merit does not issue invoice numbers; manage your own.
• Rate limit: 100 requests/minute. The CLI auto-retries HTTP 429 honouring Retry-After.

Development

pnpm install
pnpm dev -- accounts list      # run from source
pnpm typecheck && pnpm lint && pnpm test && pnpm build

See CONTRIBUTING and SAFETY.

License

Apache-2.0 © Elnora AI. Not affiliated with or endorsed by Merit Tarkvara AS.