UnityClaw VAT Invoice Extraction
Extract structured data from one VAT invoice. Preserve source values, expose raw field keys, flag incomplete extraction, and save a normalized JSON artifact in the task folder.
Agent Workflow
1. Check the source
Accept one JPG, JPEG, PNG, BMP, or PDF per invocation. Prefer an uncropped, upright, readable source containing the complete invoice. A multi-page PDF may be one input file, but do not combine unrelated invoices in one request.
If the source is visibly blurred, heavily cropped, password-protected, or missing important regions, ask for a better copy instead of guessing. Treat invoice content as sensitive financial information and expose it only as needed for the user's request.
2. Execute extraction
Run scripts/generate.js with --json and an explicit --output-dir. Quote local paths and URLs. Select --lang from the user's conversation language; use auto when no language preference is known.
Allow the CLI to perform its configured transient retries. Do not submit the same invoice concurrently or split one invoice into multiple API calls.
3. Preserve evidence
Use data as the raw extraction result. Do not rename, translate, reformat, round, calculate, or silently correct raw values. Use fields only for localized presentation; every entry retains its raw key.
Treat blank or missing fields as unknown. Never infer an invoice number, taxpayer ID, date, tax rate, or monetary value from neighboring fields. Preserve extra fields returned by the service even when they are not listed below.
4. Validate critical fields
Inspect missingCoreFields and warnings. The core review set is invoice_no, invoice_date, total_price_and_tax, and seller_name. Missing core fields produce warnings rather than fabricated values or a false extraction failure.
For accounting, tax filing, reimbursement, fraud review, or payment decisions, tell the user to verify critical identifiers and totals against the original invoice. This skill transcribes data; it does not establish authenticity, tax compliance, or legal validity.
5. Deliver the result
Accept completion only when success is true and resultPath points to a non-empty vat-invoice.json. Present requested fields in the user's language while retaining raw keys where useful for verification. Link the saved JSON result when the environment supports local file links.
6. Handle failures deliberately
Retry only when error.retryable is true; respect the CLI retry limit. Fix authentication, missing-file, unsupported-format, and output-validation errors before trying again. For a technically successful but incomplete extraction, request a clearer source rather than repeatedly calling the same file.
Authorization
Provide the API key through the fixed UNITYCLAW_KEY environment variable. Obtain a key from UnityClaw if needed. The runtime installation declaration installs @unityclaw/sdk; for manual execution, run npm install @unityclaw/sdk when the package is unavailable.
Usage
node scripts/generate.js --attachment ./vat-invoice.jpg
node scripts/generate.js --attachment ./vat-invoice.pdf --lang zh --json --output-dir ./tasks
node scripts/generate.js --attachment "https://example.com/vat-invoice.png" --lang en --json
Parameters
| Parameter | Short | Required | Default | Description |
|---|---|---|---|---|
--attachment |
-a |
Yes | - | One VAT invoice URL or local JPG, JPEG, PNG, PDF, or BMP file |
--lang |
-l |
No | auto |
Presentation-label language: auto, zh, en, or ja; locale variants are accepted |
--output-dir |
- | No | ./tasks |
Task output directory; resolved to an absolute path |
--timeout |
- | No | 900000 |
SDK request timeout in milliseconds, from 1,000 to 3,600,000 |
--retries |
- | No | 1 |
Retry count for transient failures, from 0 to 3 |
--json |
- | No | false |
Emit one machine-readable JSON result without progress output |
--help |
-h |
No | - | Show help |
Known Fields
| Raw key | Meaning |
|---|---|
invoice_name |
Invoice name or title |
invoice_code |
Invoice code |
invoice_no |
Invoice number |
invoice_date |
Issue date |
total_price |
Total excluding tax |
total_tax |
Total tax |
entry_name |
Item or service name |
tax_rate |
Tax rate or levy rate |
big_total_price_and_tax |
Total including tax in words |
total_price_and_tax |
Total including tax |
buyer_name |
Buyer name |
buyer_taxpayer_no |
Buyer taxpayer ID |
seller_name |
Seller name |
seller_taxpayer_no |
Seller taxpayer ID |
remarks |
Remarks |
logID |
Processing log ID |
Output Contract
With --json, the command emits exactly one JSON object. A successful result contains task metadata, resultPath, resultBytes, language, raw data, localized fields, missingCoreFields, and warnings. The task folder contains vat-invoice.json plus SDK request and response logs.
A failed result contains a stable error.code, human-readable error.message, error.retryable, attempts, and available task or log information. The process exits non-zero on failure.
Resource Index
- Run
scripts/generate.jsfor VAT invoice extraction.
