Invoice Scan

AI-powered invoice OCR, scanning, and data extraction. Use when: (1) user needs OCR or text extraction from invoice images, scanned documents, or PDFs, (2) s...

⚠️ 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:

1. Look at the image with your vision capability
2. Extract all fields into a JSON object matching the canonical schema in references/canonical-schema.md
3. Classify document type: invoice, credit-note, receipt, purchase-order, delivery-note, confirmation, statement, other-financial, not-financial
4. Validate arithmetic and business rules per references/validation-rules.md
5. Present results (see Output Format below)
6. 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

1. qty × unitPrice = lineTotal (per line)
2. Sum of lineTotals = netTotal
3. 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