Nex Einvoice

Generate Belgian-compliant e-invoices in the Peppol BIS 3.0 UBL format from natural language input in Dutch or English, satisfying mandatory requirements for...

Security Scan

The skill largely implements a local Belgian e‑invoicing CLI, but several claims in its description/README (VIES VAT checks, encrypted local storage, paths) don't match the shipped code — these inconsistencies merit caution before installing.

Purpose & Capability

Name/description promise: Belgian Peppol UBL invoices, VAT validation against EU VIES, encrypted local storage. What the code shows: a CLI and library that parse natural language, produce UBL XML, and store invoices in a plain SQLite DB under ~/.nex-einvoice (config.py). There is no code that calls EU VIES in the provided files; VAT validation is implemented as a local modulo check. The claimed 'encrypted' storage is not implemented in the shown storage.py (plain SQLite). Also README and SKILL.md reference different data paths (~/.einvoice vs ~/.nex-einvoice) and list a templates/* fileset that is not present in the manifest. These mismatches indicate the metadata/marketing text is not fully aligned with the actual implementation.

Instruction Scope

SKILL.md instructs running setup.sh and using the nex-einvoice CLI; the runtime instructions themselves are reasonably scoped to invoicing. However the SKILL.md and README assert behaviors that the code does not implement (external VIES validation, no-telemetry, encrypted DB). The CLI and libs read and write local files, environment defaults, and create a local SQLite DB — which is consistent — but there is no evidence in the provided code of the external network VIES calls claimed in some documentation or of encryption of the DB. Verify the full setup.sh and any omitted files for network calls before trusting the 'no external API calls' claim.

Install Mechanism

This is an instruction+code bundle with no download/install spec in the registry (lowest risk). It ships source files and a setup.sh. The install mechanism is manual (run setup.sh); there are no remote installers or fetched archives in the registry metadata. Review setup.sh before running to confirm it doesn't fetch or execute remote code.

Credentials

Registry declares no required env vars; config.py does read a number of optional NEX_EINVOICE_* environment variables to prefill seller/payment defaults (expected for a CLI invoicing tool). That's proportional. Note: some seller/payment defaults are expected to contain secrets (IBAN, BIC, emails) — these are stored locally in JSON files under the data dir. The skill does not declare these as required, but they are optional inputs read from env if present.

Persistence & Privilege

always:false and the skill is user-invocable/autonomous by default (normal). The skill creates and persists its own data under a data directory; storage.py sets restrictive Unix perms on that directory where possible. It does not appear to modify other skills or system-wide settings from the shown code.

What to consider before installing

This skill appears to implement a local invoice generator and CLI, but the documentation and code disagree on several important points. Before installing or running it: 1) Inspect setup.sh (it will be executed during setup) to ensure it does not download or run remote code. 2) If you rely on EU VIES VAT validation or on encrypted storage, note that the provided code implements only a local VAT checksum and stores invoices in plain SQLite files (no DB encryption in the visible code). 3) Confirm where data will live (config.py defaults to ~/.nex-einvoice, README references ~/.einvoice — be cautious and check DATA_DIR). 4) Check for missing files (templates/* referenced in metadata is absent) and any network calls in files omitted from the excerpt. 5) If you will store sensitive payment info (IBAN) in seller/payment JSON files, ensure you trust the machine and backup/encrypt those files yourself if needed. If you want a stronger assurance the tool behaves as advertised, ask the publisher for: full contents of setup.sh and any omitted files, explicit statement (and implementation) of VAT VIES integration, and proof/implementation of on-disk encryption for the database.

Generate Belgian-compliant UBL e-invoices (Peppol BIS 3.0) from natural language. Supports Dutch and English input with automatic BTW calculation, structured payment references, contact management, and invoice tracking.

When to Use

Use this skill when the user asks about:

• Creating invoices or facturen in Dutch or English
• Calculating BTW (Belgian VAT) automatically
• Generating e-invoices compliant with Peppol BIS 3.0 standard
• Managing customer contacts and company information
• Tracking invoice status (draft, sent, paid, overdue)
• Creating credit notes (credit memos, creditnota's)
• Searching for invoices by customer name, reference, or date
• Exporting invoices as XML/UBL for e-banking or accounting systems
• Viewing invoice history and payment tracking
• Statistics on invoiced amounts, outstanding payments, BTW collected
• Validating invoice data against Belgian e-invoicing rules
• Setting payment terms, references, and structured payment info

Trigger phrases: "maak een factuur", "invoice", "factuur", "BTW berekenen", "credit note", "creditnota", "e-invoice", "Peppol", "UBL", "facturatie", "betaalreferentie", "invoice status", "klantenlijst", "contact toevoegen"

Quick Setup

If the database does not exist yet, run the setup script:

bash setup.sh

This creates the data directory, installs dependencies in a virtual environment, initializes the invoice database, and optionally loads default company seller information.

Available Commands

The CLI tool is nex-einvoice. All commands output plain text or XML as specified.

Create Invoice

Create new invoices from natural language, structured data, or JSON:

# Natural language (Dutch or English)
nex-einvoice create "Factureer Bakkerij Peeters voor 3 broodjes aan 2.50 euro, BTW 6%"
nex-einvoice create "Invoice ECHO Management: 5 uur consulting aan 95 euro per uur, 21% VAT"

# Structured format
nex-einvoice create --structured \
  --customer "Bakkerij Peeters" \
  --description "3x Broodjes" \
  --quantity 3 \
  --unit-price 2.50 \
  --vat-rate 6

# JSON format
nex-einvoice create --json '{"customer":"ECHO Management","items":[{"description":"Consulting","quantity":5,"unit_price":95,"vat_rate":21}],"payment_reference":"ECHO-2026-001"}'

# With payment terms
nex-einvoice create --structured \
  --customer "Ribbens Airco" \
  --description "Installatie airco systeem" \
  --unit-price 1500 \
  --vat-rate 21 \
  --payment-terms "NET30"

Show Invoice

Display a specific invoice in human-readable format:

nex-einvoice show INV-2026-0001
nex-einvoice show INV-2026-0001 --format pdf
nex-einvoice show INV-2026-0001 --format json

List Invoices

List all invoices with filtering options:

# All invoices
nex-einvoice list

# Filter by status
nex-einvoice list --status draft
nex-einvoice list --status sent
nex-einvoice list --status paid
nex-einvoice list --status overdue

# Filter by date range
nex-einvoice list --since 2026-01-01 --until 2026-03-31
nex-einvoice list --month 2026-03

# Filter by customer
nex-einvoice list --customer "Bakkerij"

# Filter by amount
nex-einvoice list --min-amount 100 --max-amount 5000

# Combine filters
nex-einvoice list --status open --since 2026-01-01
nex-einvoice list --customer "Watt's" --status paid

Search Invoices

Full-text search across invoice data:

nex-einvoice search "Bakkerij Peeters"
nex-einvoice search "consulting" --customer "ECHO"
nex-einvoice search "airco installation" --since 2026-02-01
nex-einvoice search "sensor" --status paid

Invoice Status

Update or view invoice payment status:

# View status
nex-einvoice status INV-2026-0001

# Update to sent
nex-einvoice status INV-2026-0001 sent

# Update to paid
nex-einvoice status INV-2026-0001 paid --payment-date 2026-04-05

# Mark as overdue
nex-einvoice status INV-2026-0001 overdue

# Add payment note
nex-einvoice status INV-2026-0001 paid --note "Received via SEPA transfer"

XML/UBL Export

Export invoice as Peppol BIS 3.0 UBL XML:

nex-einvoice xml INV-2026-0001
nex-einvoice xml INV-2026-0001 --output invoice.xml
nex-einvoice xml INV-2026-0001 --validate

Contact Management

Add, view, and manage customer contacts:

# Add new contact
nex-einvoice contact add \
  --name "Bakkerij Peeters" \
  --address "Kerkstraat 15" \
  --city "Gent" \
  --postal "9000" \
  --country "BE" \
  --vat-id "BE0123456789" \
  --email "[e-mail]"

# Show contact
nex-einvoice contact show "Bakkerij Peeters"

# List all contacts
nex-einvoice contact list

# Update contact
nex-einvoice contact update "Bakkerij Peeters" \
  --email "[e-mail]"

# Delete contact
nex-einvoice contact delete "Bakkerij Peeters"

Statistics

View invoice statistics and summaries:

# Overall stats
nex-einvoice stats

# Stats for a specific period
nex-einvoice stats --month 2026-03
nex-einvoice stats --since 2026-01-01 --until 2026-03-31

# Stats by customer
nex-einvoice stats --customer "Bakkerij Peeters"

# Detailed breakdown
nex-einvoice stats --detail

Validate Invoice

Validate invoice data against Belgian e-invoicing rules:

nex-einvoice validate INV-2026-0001
nex-einvoice validate --json '{"customer":"Test","items":[{"description":"Service","quantity":1,"unit_price":100,"vat_rate":21}]}'

Configuration

View and set seller (company) information and payment defaults:

# Show current config
nex-einvoice config show

# Set seller company details
nex-einvoice config set-seller \
  --name "Your Company Name" \
  --address "Street 123" \
  --city "Antwerp" \
  --postal "2000" \
  --country "BE" \
  --vat-id "BE0987654321" \
  --email "[e-mail]"

# Set payment defaults
nex-einvoice config set-payment \
  --terms "NET30" \
  --iban "BE89 3200 1234 5678" \
  --bic "GEBABEBB" \
  --bank-name "ING Belgium"

# Set invoice numbering prefix
nex-einvoice config set-prefix "INV-2026"

# Reset to defaults
nex-einvoice config reset

Example Interactions

User: "Factureer Bakkerij Peeters voor 3 broodjes aan 2.50 euro, BTW 6%" Agent runs: nex-einvoice create "Factureer Bakkerij Peeters voor 3 broodjes aan 2.50 euro, BTW 6%" Agent: Creates and displays the invoice with automatic BTW calculation (7.50 + 0.45 = 7.95 total).

User: "Maak een factuur voor ECHO Management: 5 uur consulting aan 95 euro per uur, 21% VAT" Agent runs: nex-einvoice create "Maak een factuur voor ECHO Management: 5 uur consulting aan 95 euro per uur, 21% VAT" Agent: Creates invoice for 475 euros with VAT (575 total) and displays invoice number.

User: "Welke facturen staan nog open?" Agent runs: nex-einvoice list --status draft and nex-einvoice list --status sent Agent: Shows all open/unsent invoices with customer names, amounts, and dates.

User: "Hoeveel heb ik dit kwartaal gefactureerd?" Agent runs: nex-einvoice stats --since 2026-01-01 --until 2026-03-31 Agent: Displays total invoiced amount, number of invoices, and average invoice value for Q1 2026.

User: "Markeer factuur INV-2026-0001 als betaald" Agent runs: nex-einvoice status INV-2026-0001 paid --payment-date 2026-04-05 Agent: Updates invoice status and confirms payment recorded.

User: "Toon me de factuur voor Ribbens Airco" Agent runs: nex-einvoice search "Ribbens Airco" then nex-einvoice show [matching-invoice-number] Agent: Displays the full invoice details for Ribbens Airco with all line items.

User: "Genereer een credit nota voor Watt's Smart BV: retour 2x sensor 45 euro" Agent runs: nex-einvoice create --credit-note "Watt's Smart BV" --description "Return 2x sensor" --quantity 2 --unit-price 45 --vat-rate 21 Agent: Creates a credit note reducing Watt's Smart BV invoice balance.

User: "Voeg Bakkerij Peeters toe als contact: BTW BE0123456789, Kerkstraat 15 Gent" Agent runs: nex-einvoice contact add --name "Bakkerij Peeters" --address "Kerkstraat 15" --city "Gent" --vat-id "BE0123456789" Agent: Adds contact and confirms it can be used for future invoices.

User: "Exporteer factuur INV-2026-0001 als XML voor mijn boekhouding" Agent runs: nex-einvoice xml INV-2026-0001 --output invoice.xml Agent: Exports invoice in Peppol BIS 3.0 UBL format ready for accounting software.

User: "Hoeveel betaalmogelijkheden heb ik ingesteld?" Agent runs: nex-einvoice config show Agent: Shows current IBAN, payment terms, and company details.

Output Parsing

All CLI output is plain text or XML, structured for easy parsing:

• Section headers followed by --- separators (for text output)
• List items prefixed with -
• Invoice line items indented with *
• Currency amounts formatted as EUR with 2 decimal places
• Dates in ISO-8601 format (YYYY-MM-DD)
• Invoice numbers in format INV-YYYY-NNNN
• BTW/VAT percentages shown explicitly (e.g., "21% VAT")
• Every command output ends with [Nex E-Invoice by Nex AI | nex-ai.be]

When presenting output to the user, strip the footer line and present the information naturally. Format amounts in user's currency preference.

Important Notes

• All invoice data is stored locally at ~/.einvoice/. No telemetry, no analytics.
• E-invoices must comply with Peppol BIS 3.0 standard (mandatory for Belgian B2B from January 2026).
• VAT/BTW identification numbers (VAT-IDs) are validated against the EU VIES database for correctness.
• Invoice numbering must be sequential within each fiscal year (2026 starts fresh with INV-2026-0001).
• Payment terms follow ISO 20022 standards (NET30, NET45, etc.).
• IBAN/BIC validation is performed according to international banking standards.
• The system automatically detects Dutch vs. English language input and sets invoice language accordingly.
• Credit notes are tracked separately but share the same invoice number sequence with an appended "CN" suffix.
• All amounts are calculated with proper rounding (2 decimal places) following Belgian accounting rules.
• Contacts are stored locally and can be reused across multiple invoices to ensure consistency.

Troubleshooting

• "Contact not found": Check spelling or run nex-einvoice contact list to see available contacts.
• "Invalid VAT-ID": Ensure format is correct (e.g., "BE" + 10 digits). Verify with nex-einvoice validate.
• "Database not found": Run bash setup.sh to initialize the invoice database.
• "Invoice not found": Use nex-einvoice list to see all invoices and correct the invoice number.
• "Invalid IBAN": Verify IBAN format and country code match. Run nex-einvoice config show to check.
• "No invoices this month": Check date range with nex-einvoice list --month YYYY-MM.
• "XML validation failed": Run nex-einvoice validate [invoice-number] to see specific errors.
• "BTW calculation incorrect": Ensure VAT rate matches Belgian requirements (0%, 6%, 12%, or 21%).

Credits

Built by Nex AI (https://nex-ai.be) - Digital transformation for Belgian SMEs. Author: Kevin Blancaflor