Invoice Scan
⚠️ Privacy Notice
CLI mode sends base64-encoded invoice images to Anthropic's API (api.anthropic.com). Invoice data (supplier/buyer names, addresses, IBANs, bank details, amounts) will be transmitted to a third-party service. Confirm this is acceptable under your privacy and compliance requirements before use. Consider dedicated API credentials with usage limits.
Agent-native mode does NOT send data externally — the agent uses its own built-in vision. Only formatOutput() is called locally for CSV/Excel export.
Setup
Install dependencies (required before first use):
cd {SKILL_DIR}/scripts && npm install --production
Dependencies: sharp (image processing), xlsx (Excel export). Review scripts/package.json before installing.
CLI mode requires: ANTHROPIC_API_KEY environment variable.
Agent-native mode requires: nothing — uses agent's built-in vision capability.
Two Modes
Mode 1: Agent-Native (No API Key, No External Calls)
Use your built-in vision to look at the invoice image directly. Do NOT call scanInvoice() — that function requires an API key and sends data externally. Instead:
- Look at the image with your vision capability
- Extract all fields into a JSON object matching the canonical schema in
references/canonical-schema.md - Classify document type: invoice, credit-note, receipt, purchase-order, delivery-note, confirmation, statement, other-financial, not-financial
- Validate arithmetic and business rules per
references/validation-rules.md - Present results (see Output Format below)
- For CSV/Excel export, construct the canonical JSON object and pass it to
formatOutput()only:
const { formatOutput } = require('{SKILL_DIR}/scripts');
// invoiceData = the JSON object YOU built from your vision extraction
// IMPORTANT: include ALL fields from canonical-schema.md, including charges[]
// e.g. invoiceData.charges = [{ type: 'shipping', label: 'P&P', amount: 5.99, vatRate: 20, vatAmount: 1.20 }]
const csv = formatOutput(invoiceData, 'csv'); // string — local only
const xlsx = formatOutput(invoiceData, 'excel'); // Buffer — local only
Key: formatOutput() is purely local — no network calls, no API key needed. It just formats your extracted data into CSV or Excel.
Mode 2: CLI Standalone (Needs API Key)
For automation or pipelines. Requires ANTHROPIC_API_KEY env var.
ANTHROPIC_API_KEY=<key> node {SKILL_DIR}/scripts/cli.js scan <file> [--format json|csv|excel] [--output result.json]
Options: --provider claude, --accept strict|relaxed|any, --no-preprocess, --model <model>
Agent-Native Extraction Checklist
Extract ALL of:
Header: invoiceNumber, invoiceDate (YYYY-MM-DD), dueDate, currency (ISO 4217), supplierName, supplierAddress, supplierVatNumber, buyerName, buyerAddress, buyerVatNumber, paymentTerms, paymentReference, bankDetails (iban, bic, accountNumber, sortCode)
Line items: description, quantity, unitOfMeasure, unitPrice, lineTotal, vatRate, sku, discount
References: PO, contract, GRN, timesheet, project, proforma, invoice (original invoice if this is a credit/debit memo), credit-note, debit-note refs. For credit/debit memos, ALWAYS include the original invoice reference.
Totals: netTotal, vatBreakdown (rate + amount + type per band — type is the tax regime label e.g. "CGST", "SGST", "USt", "НДС", "IVA"), vatTotal, grossTotal, amountPaid, amountDue, discount (invoice-level discount amount), discountRate (percentage)
Metadata: paidDate (YYYY-MM-DD — date from PAID stamp), vatInclusive (true if line totals include VAT, false if net, null if unknown)
Charges: Surcharges/fees outside line items — shipping, postage, P&P, delivery, freight, carriage, dispatch, handling, insurance, eco-levy, surcharges. Each: type (shipping|handling|insurance|surcharge|discount|other), label (original text from document), amount, vatRate, vatAmount. Do NOT duplicate items already captured as line items.
Document type: documentType (invoice, credit-note, debit-note, receipt, purchase-order, delivery-note, confirmation, statement, other-financial, not-financial)
Additional: handwritten notes, stamps/seals (type + text), remarks/comments, document language (ISO 639-1)
Arithmetic Validation
- qty × unitPrice = lineTotal (per line)
- Sum of lineTotals = netTotal
- netTotal + vatTotal = grossTotal (Tolerance: ±0.02 for rounding)
Locale Numbers
Parse regional formats automatically: US/UK (1,234.56), European (1.234,56), French (1 234,56), Indian (1,23,456.78). Use currency/country context when ambiguous.
Quality Score
Count present from: invoiceNumber, invoiceDate, currency, supplierName, buyerName, supplierVatNumber, netTotal, vatTotal, grossTotal. Score = present / 9. good ≥ 0.8, partial ≥ 0.5, poor < 0.5.
Output Format
📄 Invoice #{number} | {date}
Supplier: {name} → Buyer: {name}
Net: {currency}{net} | VAT: {currency}{vat} | Gross: {currency}{gross}
[if charges exist] 📦 Charges: {label} {currency}{amount} [per charge]
[if amountDue is not null] Amount Due: {currency}{amountDue} [if amountPaid] (Paid: {currency}{amountPaid})
Items: {count} | Arithmetic: ✅/❌ | Quality: {rating} ({score}/9)
List warnings/flags, then offer: "Want JSON, CSV, or Excel?"
File Delivery
- Output directory:
{WORKSPACE}/invoice-scan/output/(create if needed) - Naming:
{supplierName}_{invoiceNumber}_{invoiceDate}.{ext}(replace spaces/slashes with hyphens) - Always save JSON automatically, offer CSV/Excel on request
- Send file as chat attachment + confirm path
References
- Full schema:
references/canonical-schema.md - Validation rules:
references/validation-rules.md