Invoice OCR Approval
Use this when someone asks in Lark to turn invoice files into a Lark payment approval
(for example, ::invoice-ocr-approval-payload-builder with PDFs/images attached, plus
department or review notes).
You (the agent) run the WHOLE flow yourself with your own tools, then SUBMIT the Lark approval.
Do NOT refuse, do NOT just describe, do NOT claim "the skill only formats" — drive the flow. If a
required config (approval_code / scope) is missing, FALL BACK to posting the approval summary card
to the chat — never fail the run. Never ask the user for tokens — your NyxID-brokered tools broker
all credentials.
How to run it
Resolve inputs from the current Lark invocation: invoice PDF/image attachments, sender
identity (applicant open id), optional submitter email, department, payment entity, related
approval serial/UUID, amount/vendor corrections, per-invoice descriptions, and remark. The
payment approval_code defaults to F640097D-0A68-47C1-A7BC-86659BC4B06F; supply your own only
if the approval definition differs. If invoice files or required business fields are missing,
reply in the chat asking for exactly those.
Collect files and sender data from Lark via Lark tools or nyxid_proxy {slug:"api-lark-bot", path:"/open-apis/...", method:...}:
- files:
GET /open-apis/im/v1/messages/{message_id}/resources/{file_key}?type=file
- images:
GET /open-apis/im/v1/images/{image_key}
Keep filename, MIME type, bytes, and any sender email/open_id from the interaction.
OCR the invoices with your own model. Extract one JSON object per invoice — vendor,
amount, currency, date, invoice_number, description, bank_name, bank_account,
swift_code. Currency rules: S$ / Singapore vendor-address / Pte Ltd imply SGD; explicit
US$/USD imply USD; RM/MYR imply MYR; RMB/CNY or mainland China imply CNY; bare
$ from a Singapore issuer is SGD.
Upload invoice attachments for the approval form via nyxid_proxy {slug:"api-lark-bot", path:"/open-apis/approval/v4/files/upload", method:"POST"} with form fields name=<filename>,
type=attachment, content=<file bytes>. Collect file tokens from data.urls_detail[].code,
data.code, or data.file_token.
Collect related approval context via nyxid_proxy {slug:"api-lark-bot", ...}:
- list recent invoice approvals:
GET /open-apis/approval/v4/instances?approval_code=F640097D-0A68-47C1-A7BC-86659BC4B06F&start_time={now-365d}&end_time={now}&page_size=100
- fetch each detail:
GET /open-apis/approval/v4/instances/{instance_code}
Spot duplicate invoice numbers / same-vendor history. If the user gave a related approval serial,
resolve it to a UUID-style instance_code and pass it as relatedApprovalId.
Resolve Lark applicant and department approver via nyxid_proxy {slug:"api-lark-bot", ...}:
- applicant by email:
POST /open-apis/contact/v3/users/batch_get_id?user_id_type=user_id
- mapped department leader by email (same endpoint):
devops -> kaiwei.lim@aelf.io; finance / human resources / hr / executive support /
president's office / ai application / portkey -> ada.niu@aelf.io;
ai framework -> shining.wang@aelf.io; aetherlink & aefinder / aetherlink /
aefinder -> jason.wang@aelf.io
- direct leader fallback:
GET /open-apis/contact/v3/users/{applicantOpenId}?user_id_type={open_id|user_id}&department_id_type=open_department_id
Use the applicant id as the final fallback department head id.
Build the exact approval body by running the bundled builder. Call
scripts/build_invoice_approval_payload.js via code_execute with language: "javascript" (NO
stdin — inline the data): const {buildPayload}=require('./scripts/build_invoice_approval_payload.js'); console.log(JSON.stringify(buildPayload({mode:"build_approval", invoices, review, attachments, applicantOpenId, department, deptHeadId, deptHeadSource, relatedApprovalId, remark}))). Use the
returned lark.body. If you genuinely cannot execute code, build the body by following
references/invoice-approval-contract.md field-for-field.
Terminal — submit the Lark approval instance via nyxid_proxy {slug:"api-lark-bot", path:"/open-apis/approval/v4/instances?user_id_type=user_id", method:"POST", body:<lark.body from step 7>}. Verify code === 0, capture data.instance_code, then query
GET /open-apis/approval/v4/instances/{instance_code}. If no approval_code / scope OR the
submit fails → FALL BACK to reply_with_interaction (approve/reject card) or a plain summary
requesting manual approval — never fail the run.
Report back to the current Lark chat with lark_messages_reply, lark_messages_send, or
reply_with_interaction: one line with invoice count, applicant, approval instance code or serial
(or "card fallback"), and status.
Payload builder reference
scripts/build_invoice_approval_payload.js exports buildPayload(data). The only mode is
build_approval (default): it builds one Lark approval instance body from normalized invoices,
review fields, Lark user ids, optional approval file tokens, and an optional resolved
relatedApprovalId. Review fields may sit under review / reviewRaw / review_raw /
reviewFields / review_fields or the root. Required after normalization: invoices,
applicantOpenId, department, and each invoice row's amount / date / vendor (unless an
accepted alias/fallback provides them). Output carries summary, invoice_count, form,
approval_body, and a lark.body ready for POST /open-apis/approval/v4/instances?user_id_type=user_id.
Exact aliases, widget ids, option ids, and examples are in references/invoice-approval-contract.md.
Approval status tracking (typed tools)
After a successful submit, capture the returned instance_code and include it in your report.
For anything status-related, prefer the typed approval tools over raw nyxid_proxy:
lark_approvals_get {instance_code} (read-only, auto-approved): returns normalized status
(approved / rejected / withdrawn / terminated / running / none) plus is_terminal and
should_continue_waiting, with the task list and form data. Use it when the user asks how the
approval is going, before any resubmit (avoid duplicate instances), and to report the final
decision. Optional: locale (zh-CN/en-US/ja-JP), user_id_type (open_id/user_id/union_id).
lark_approvals_list {topic} (read-only): list approval tasks visible to the bot identity when
the instance_code is lost — topics todo/pending, done/completed, initiated, cc_unread,
cc_read.
lark_approvals_act {action, instance_code, task_id}: approve / reject / transfer a pending
task — ONLY when the user explicitly asks the bot to act on it; this one is not read-only, so a
human-approval card may appear before it executes.
Check once and report; do not busy-poll inside a chat turn. Offer to re-check on demand or via a
scheduled_agent_creator reminder instead.
Guardrails
- Use real returned data for invoice fields, file tokens, Lark user ids, related approval ids,
instance codes, serial numbers, and statuses; never invent records.
- Prefer running the bundled script; it is the deterministic source of truth for the approval form.
- Use your NyxID-brokered Lark tools for credentials and API calls; never handle raw secrets or ask
the user for tokens.
1---2name: invoice-ocr-approval-payload-builder3version: "2.3"4description: Runs the invoice OCR approval flow end to end yourself — collect invoice files and review fields, OCR them, upload attachments, resolve Lark contacts and related approvals, then SUBMIT the Lark approval instance.5metadata:6 source: https://skillmd.com/skills/chronoaiproject/invoice-ocr-approval-payload-builder7 category: plain8 tag:9 - aevatar10 - s-capability11 - invoice-approval12 - lark-approval13 - payload-builder14 clawdbot:15 emoji: "receipt"16 files:17 - "references/*"18 - "scripts/*"19---2021# Invoice OCR Approval2223Use this when someone asks in Lark to turn invoice files into a Lark payment approval24(for example, `::invoice-ocr-approval-payload-builder` with PDFs/images attached, plus25department or review notes).2627**You (the agent) run the WHOLE flow yourself with your own tools, then SUBMIT the Lark approval.**28Do NOT refuse, do NOT just describe, do NOT claim "the skill only formats" — drive the flow. If a29required config (`approval_code` / scope) is missing, FALL BACK to posting the approval summary card30to the chat — never fail the run. Never ask the user for tokens — your NyxID-brokered tools broker31all credentials.3233## How to run it34351. **Resolve inputs** from the current Lark invocation: invoice PDF/image attachments, sender36 identity (applicant open id), optional submitter email, `department`, payment entity, related37 approval serial/UUID, amount/vendor corrections, per-invoice descriptions, and remark. The38 payment `approval_code` defaults to `F640097D-0A68-47C1-A7BC-86659BC4B06F`; supply your own only39 if the approval definition differs. If invoice files or required business fields are missing,40 reply in the chat asking for exactly those.41422. **Collect files and sender data from Lark** via Lark tools or `nyxid_proxy` `{slug:"api-lark-bot",43 path:"/open-apis/...", method:...}`:44 - files: `GET /open-apis/im/v1/messages/{message_id}/resources/{file_key}?type=file`45 - images: `GET /open-apis/im/v1/images/{image_key}`46 Keep filename, MIME type, bytes, and any sender email/open_id from the interaction.47483. **OCR the invoices with your own model.** Extract one JSON object per invoice — `vendor`,49 `amount`, `currency`, `date`, `invoice_number`, `description`, `bank_name`, `bank_account`,50 `swift_code`. Currency rules: `S$` / Singapore vendor-address / `Pte Ltd` imply `SGD`; explicit51 `US$`/`USD` imply `USD`; `RM`/`MYR` imply `MYR`; `RMB`/`CNY` or mainland China imply `CNY`; bare52 `$` from a Singapore issuer is `SGD`.53544. **Upload invoice attachments for the approval form** via `nyxid_proxy` `{slug:"api-lark-bot",55 path:"/open-apis/approval/v4/files/upload", method:"POST"}` with form fields `name=<filename>`,56 `type=attachment`, `content=<file bytes>`. Collect file tokens from `data.urls_detail[].code`,57 `data.code`, or `data.file_token`.58595. **Collect related approval context** via `nyxid_proxy` `{slug:"api-lark-bot", ...}`:60 - list recent invoice approvals: `GET /open-apis/approval/v4/instances?approval_code=F640097D-0A68-47C1-A7BC-86659BC4B06F&start_time={now-365d}&end_time={now}&page_size=100`61 - fetch each detail: `GET /open-apis/approval/v4/instances/{instance_code}`62 Spot duplicate invoice numbers / same-vendor history. If the user gave a related approval serial,63 resolve it to a UUID-style `instance_code` and pass it as `relatedApprovalId`.64656. **Resolve Lark applicant and department approver** via `nyxid_proxy` `{slug:"api-lark-bot", ...}`:66 - applicant by email: `POST /open-apis/contact/v3/users/batch_get_id?user_id_type=user_id`67 - mapped department leader by email (same endpoint):68 `devops -> kaiwei.lim@aelf.io`; `finance` / `human resources` / `hr` / `executive support` /69 `president's office` / `ai application` / `portkey -> ada.niu@aelf.io`;70 `ai framework -> shining.wang@aelf.io`; `aetherlink & aefinder` / `aetherlink` /71 `aefinder -> jason.wang@aelf.io`72 - direct leader fallback: `GET /open-apis/contact/v3/users/{applicantOpenId}?user_id_type={open_id|user_id}&department_id_type=open_department_id`73 Use the applicant id as the final fallback department head id.74757. **Build the exact approval body by running the bundled builder.** Call76 `scripts/build_invoice_approval_payload.js` via `code_execute` with `language: "javascript"` (NO77 stdin — inline the data): `const {buildPayload}=require('./scripts/build_invoice_approval_payload.js');78 console.log(JSON.stringify(buildPayload({mode:"build_approval", invoices, review, attachments,79 applicantOpenId, department, deptHeadId, deptHeadSource, relatedApprovalId, remark})))`. Use the80 returned `lark.body`. If you genuinely cannot execute code, build the body by following81 `references/invoice-approval-contract.md` field-for-field.82838. **Terminal — submit the Lark approval instance** via `nyxid_proxy` `{slug:"api-lark-bot",84 path:"/open-apis/approval/v4/instances?user_id_type=user_id", method:"POST", body:<lark.body from85 step 7>}`. Verify `code === 0`, capture `data.instance_code`, then query86 `GET /open-apis/approval/v4/instances/{instance_code}`. **If no `approval_code` / scope OR the87 submit fails → FALL BACK** to `reply_with_interaction` (approve/reject card) or a plain summary88 requesting manual approval — never fail the run.89909. **Report** back to the current Lark chat with `lark_messages_reply`, `lark_messages_send`, or91 `reply_with_interaction`: one line with invoice count, applicant, approval instance code or serial92 (or "card fallback"), and status.9394## Payload builder reference9596`scripts/build_invoice_approval_payload.js` exports `buildPayload(data)`. The only mode is97`build_approval` (default): it builds one Lark approval instance body from normalized invoices,98review fields, Lark user ids, optional approval file tokens, and an optional resolved99`relatedApprovalId`. Review fields may sit under `review` / `reviewRaw` / `review_raw` /100`reviewFields` / `review_fields` or the root. Required after normalization: `invoices`,101`applicantOpenId`, `department`, and each invoice row's `amount` / `date` / `vendor` (unless an102accepted alias/fallback provides them). Output carries `summary`, `invoice_count`, `form`,103`approval_body`, and a `lark.body` ready for `POST /open-apis/approval/v4/instances?user_id_type=user_id`.104Exact aliases, widget ids, option ids, and examples are in `references/invoice-approval-contract.md`.105106## Approval status tracking (typed tools)107108After a successful submit, capture the returned `instance_code` and include it in your report.109For anything status-related, prefer the typed approval tools over raw `nyxid_proxy`:110111- `lark_approvals_get` `{instance_code}` (read-only, auto-approved): returns normalized `status`112 (`approved` / `rejected` / `withdrawn` / `terminated` / `running` / `none`) plus `is_terminal` and113 `should_continue_waiting`, with the task list and form data. Use it when the user asks how the114 approval is going, before any resubmit (avoid duplicate instances), and to report the final115 decision. Optional: `locale` (`zh-CN`/`en-US`/`ja-JP`), `user_id_type` (`open_id`/`user_id`/`union_id`).116- `lark_approvals_list` `{topic}` (read-only): list approval tasks visible to the bot identity when117 the instance_code is lost — topics `todo`/`pending`, `done`/`completed`, `initiated`, `cc_unread`,118 `cc_read`.119- `lark_approvals_act` `{action, instance_code, task_id}`: approve / reject / transfer a pending120 task — ONLY when the user explicitly asks the bot to act on it; this one is not read-only, so a121 human-approval card may appear before it executes.122123Check once and report; do not busy-poll inside a chat turn. Offer to re-check on demand or via a124`scheduled_agent_creator` reminder instead.125126## Guardrails127128- Use real returned data for invoice fields, file tokens, Lark user ids, related approval ids,129 instance codes, serial numbers, and statuses; never invent records.130- Prefer running the bundled script; it is the deterministic source of truth for the approval form.131- Use your NyxID-brokered Lark tools for credentials and API calls; never handle raw secrets or ask132 the user for tokens.