invoice dedup

use this skill to enter invoice info into the system for duplicate checking, or query existing dedup records. catches duplicate invoice submissions before they hit your books.

intent

this skill prevents duplicate invoice entry by checking new invoices against your historical record, and lets you audit what's been checked. run it when onboarding invoices from multiple sources, reconciling batches, or validating that an invoice hasn't already been recorded. two modes: enter mode submits a new invoice for checking; query mode retrieves past dedup records by date range.

inputs

external connection: Zhongxing Tongyi tax API

• platform: https://skill.quandianfapiao.com/
• auth method: apiKey (request via platform account)
• env var name: ZXT_API_KEY
• edge cases: windows shell may not inherit user-level env vars; macOS/Linux typically do. see procedure step 1 for platform-specific checks.

enter mode (new invoice check)

• invoiceNumber (required): invoice code, e.g. "26117000000698099579"
• invoiceDate (required): date in YYYY-MM-DD format
• invoiceCode (optional): issuer code
• jshj (optional): total tax-inclusive amount

query mode (historical records)

• startDate (optional): collection date range start, YYYY-MM-DD
• endDate (optional): collection date range end, YYYY-MM-DD
• startKprqDate (optional): issue date range start, YYYY-MM-DD
• endKprqDate (optional): issue date range end, YYYY-MM-DD
• pageNo (optional): page number, defaults to 1
• pageSize (optional): records per page, defaults to 10

procedure

1. check api key availability (highest priority)

   • input: system environment
   • windows: run powershell -Command "[System.Environment]::GetEnvironmentVariable('ZXT_API_KEY', 'User')" to fetch user-level env var; also check shell var $ZXT_API_KEY
   • macOS/Linux: check $ZXT_API_KEY only
   • if both checks return empty, stop immediately and output the setup prompt (see decision points). do not proceed further.
   • output: either apiKey value (string) or "not found" signal

2. write apiKey to environment (if provided by user)

   • input: apiKey string from user
   • windows: execute setx ZXT_API_KEY <apiKey> to write user-level env var, then export ZXT_API_KEY=<apiKey> to activate in current session
   • macOS/Linux: append export ZXT_API_KEY=<apiKey> to ~/.bashrc or ~/.zshrc (detect active shell), then execute same export command in current session
   • output: env var active in current session

3. validate required parameters

   • input: user-supplied parameters for chosen mode (enter or query)
   • for enter mode: check invoiceNumber and invoiceDate are present and non-empty; halt if missing
   • for query mode: no hard requirements, but at least one date filter is recommended
   • output: pass/fail signal; if fail, output which param is missing

4. call remote api via python

   • input: apiKey, mode (enter or query), all parameters
   • command template: python3 .claude/skills/invoice-dedup/invoice_dedup.py --api-key "<apiKey>" <mode> [options]
   • windows: use python instead of python3
   • the script must prioritize --api-key parameter over env var ZXT_API_KEY
   • output: raw json response from api (status, message, data fields)

5. check response status

   • input: json response from api
   • if status != 200: stop, display error message and status code to user. do not retry, do not ignore.
   • if status == 200: proceed to step 6
   • output: either error halt or pass signal

6. parse and format results

   • input: response data field (json object or list)
   • for enter mode: display invoiceNumber, invoiceDate, invoiceCode, jshj, repeatType (0=not duplicate, 1=duplicate), repeatTypeName, collectTime
   • for query mode: display paginated list with same fields plus pageNo, pageSize, total count
   • output: human-readable formatted output (table, list, or summary text)

decision points

if apiKey is not set in environment:

• output this setup prompt and stop. do not attempt any file reads, api calls, scripts, or parameter parsing:

you need to complete three steps to auto-configure and run the skill:

1. create account visit Zhongxing Tongyi tax skill platform: https://skill.quandianfapiao.com/ and register.

2. request apiKey log in, go to "skill center", copy your apiKey.

3. provide apiKey to me send me the apiKey and i'll configure it and run the skill immediately.

if required parameter (invoiceNumber or invoiceDate for enter mode) is missing:

• stop execution. output which param is missing and request user to provide it. do not skip or use empty value.

if api response status is not 200:

• stop execution. display the error message and status code from the response. do not retry automatically. user may retry after fixing input or checking account status (e.g. quota exhaustion).

if repeatType == 0 (enter mode):

• invoice is not a duplicate. safe to record.

if repeatType == 1 (enter mode):

• invoice is a duplicate match. alert user to manual review before recording.

if query mode returns empty list:

• no records found in the date range. this is normal if filters are too restrictive.

output contract

enter mode success response (status 200):

• json with fields: invoiceNumber, invoiceCode, invoiceDate, jshj, repeatType (0 or 1), repeatTypeName (string: "不重复" or "重复"), collectTime (timestamp)
• example: {"invoiceNumber": "26117000000698099579", "repeatType": "0", "repeatTypeName": "不重复", "collectTime": "2026-05-18 08:58:28"}
• human-readable output: single record summary with duplicate status highlighted

query mode success response (status 200):

• json with pagination: pageNo, pageSize, total, list (array of records with same fields as enter mode output)
• example: {"pageNo": "1", "pageSize": "10", "total": "123", "list": [...]}
• human-readable output: table or list showing all records, with page info and total count

error responses (any status other than 200):

• json with status code, message field (string describing error)
• common codes: 400 (bad params), 300 (empty or malformed param), 305 (access denied), 307 (quota exhausted), 308 (rate limit), 500 (server error)
• output to user: error code and message only

file location: no files written; results displayed in stdout only

outcome signal

• enter mode success: skill outputs "不重复" (not duplicate) or "重复" (duplicate) in repeatTypeName field, with collectTime timestamp confirming the check ran. user can proceed to record or reject the invoice.
• query mode success: skill outputs a table/list of past records with date ranges and duplicate statuses. user can audit dedup history.
• any failure: skill outputs error code and message. user knows to check apiKey setup, params, or account quota.
• user sees the invoice invoice has been checked or the historical records retrieved. no ambiguity.

credits: original skill designed for Zhongxing Tongyi tax platform (clawhub source). enriched for implexa standards.