Cn Invoice To Xlsx

Runtime entrypoint

Run the bundled script from this skill directory:

python3 scripts/invoice_to_xlsx.py \
  --input-dir "$RUN_DIR" \
  --ledger-root /path/to/invoice-ledger \
  --recursive

If the repository root is the current directory, this also works:

python3 skills/cn-invoice-to-xlsx/scripts/invoice_to_xlsx.py \
  --input-dir "$RUN_DIR" \
  --ledger-root /path/to/invoice-ledger \
  --recursive

Inputs

• Supported file types in this version: .xml, .pdf
• XML is parsed first and used as the primary data source
• PDF is matched to XML by filename stem first, then used as a fallback source when XML is missing
• .ofd is not imported in this version

Output

The script creates one folder per issue month:

<ledger-root>/
  2026-03/
    invoices_2026-03.xlsx
    source/
      xml/
      pdf/
    manifest/
      rows.csv
      import-log.csv

• invoices_YYYY-MM.xlsx: monthly ledger workbook
• source/xml, source/pdf: archived originals
• manifest/rows.csv: canonical monthly row store used to rebuild the workbook
• manifest/import-log.csv: import audit trail

Columns are defined in references/xlsx_schema.md.

Deduplication

Invoices are deduplicated by:

• invoice_number
• issue_date
• amount_incl_tax
• buyer_tax_id

Behavior:

• duplicate XML-backed invoices are skipped
• a new XML import upgrades an existing pdf_fallback row for the same invoice

Dependencies

• Python 3.9+
• pdftotext (Poppler) for PDF fallback parsing

Required run report block

After every import run, include this block in the user-facing summary:

• Staging root: absolute path
• Run folder: absolute path
• Copied files: count and filenames with original names unchanged
• Ledger root: absolute path
• Import summary: imported / duplicate_skipped / upgraded_from_pdf / parse_error / archive_error
• Cleanup choice: ask whether to delete or keep the staged batch