Checking Xero supplier statements with n8n and deterministic TypeScript

The open-source Xero Supplier Statement Checker uses the orchestration tool n8n and the programming language TypeScript for precise checking. This article explores three key decisions behind its design: distinguishing different amount meanings, retrieving complete data, and preserving evidence for operator review. The project is still a preview, with synthetic tests and local n8n runs passing, but live Xero and n8n Cloud verification remains pending. All examples used are fictional.

First, the checker separates references from amounts. When selecting a supplier from the configured Xero organization's contacts, it only considers bills in that supplier and currency. To establish a match, it normalizes references using Unicode NFC, outer-whitespace trimming, and ASCII case changes, while preserving punctuation, internal spaces, and leading zeros.

Amounts, dates, or fuzzy similarity are not used for matching. Xero's purchase-bill InvoiceNumber is the primary reference, while the separate Reference field serves as supporting evidence. Multiple candidate references are kept visible for review. The checker can only compare tax-inclusive original totals after one eligible reference candidate exists.

The fixture includes two cases: matching original totals and requiring review when only an outstanding balance is present. Both cases demonstrate the importance of explicit amount meanings.

Second, the checker retrieves complete data. It parses Xero JSON losslessly before converting numeric values to integer minor units based on a checked-in currency table. Credits, partial payments, duplicate statement references, and unsafe bill statuses also require review. The workflow records requested pages, returned IDs, counts, and retrieval intervals.

If any issue arises, such as a "Not found" message, insufficient pages, or malformed responses, the check stops, and the evidence validates the retrieval instead of trusting a caller's success flag. The interrupted-retrieval fixture fails on page two with a 401, resulting in zero matches, amount differences, and not-found conclusions.

Available statement rows remain review-required, and no follow-up draft is produced. This ensures no hidden or outdated bills are overlooked.

Finally, the checker relies on human operators for AI extraction. Unlike AI-driven tools, this checker allows operators to map columns and explicitly identify original totals and outstanding balances. The operator maps invoice references as strings, including leading zeros, and retains quoted multiline fields with their source record numbers.

For optional text-PDF extraction, n8n extracts pages separately, assigning page numbers and verifying page coverage. OpenAI receives page-labelled text with a strict output schema and receives no tools, ensuring the operator retains control over the process. The review form shows extracted rows, source references, and warnings, while operators correct a canonical CSV representation and confirm supplier, currency, amount meanings, and statement coverage.

AI never chooses a supplier or decides a match, emphasizing the importance of human oversight. While AI extraction carries some risk, fully scanned, encrypted, or partly unreadable PDFs are rejected, and the operator must verify the original document for omitted rows. The checker supports statement review without reconciling supplier balances, converting currencies, posting accounting entries, or sending email.

The synthetic example provided demonstrates the checker's capabilities, producing two matched rows, one amount difference, one not found, and six requiring review without needing any credentials. The repository includes a synthetic form workflow and documentation on limits, which stop processing at 10 MiB, 50 PDF pages, or 1,000 rows.

The MIT-licensed project provides source code, fixtures, tests, and verification status, with a Bjorvand AI Disclosure noting the free workflow and paid installation/customization services.