# Vendor Invoice Intake

Extract vendor name, amount, and payment terms from incoming invoice files and stage a draft bill for human approval before anything is recorded or paid.

## When to use

- A vendor invoice arrives as a text or CSV attachment (or export) and needs to be logged as a draft bill.
- You need to reconcile invoice line items against an accounting system before approval.
- A batch of invoice files needs to be triaged and summarized for an accounts payable (AP) reviewer.
- An invoice references a format you cannot parse yet (for example, a PDF) and needs human handling.

## Tools

- `read-file` — open invoice text or CSV files from the local filesystem to extract raw content.
- `shell-execute` — run local commands to list invoice files, filter directories, or run lightweight text parsing (for example, grep or csv splitting) when extraction logic exceeds simple reading.
- `http-post` — create draft bill or draft transaction records in the accounting system's REST API once vendor, amount, and terms are extracted.

## Playbook

1. Use `read-file` to open the invoice file (text or CSV) from the intake location and load its raw contents.
2. If the file is a PDF or other unsupported format, stop immediately and use `create-task` titled "APPROVAL: Manual invoice parse needed" describing the file and route it to a human — do not guess at contents.
3. Use `shell-execute` to run any lightweight parsing needed to isolate fields (for example, splitting CSV columns or grepping for "Total", "Due Date", "Vendor") when the raw text is not already structured.
4. Extract the vendor name, invoice amount, currency, invoice date, and payment terms (for example, "Net 30") from the parsed content.
5. Call the accounting system's REST API with `http-post` to create a draft bill record (e.g. POST https://api.accounting-example.com/v1/bills) with status set to "draft" or "pending_approval" — never "posted" or "paid". Auth is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. On 401/403 or missing Integration, stop and message a human via `send-message` naming the service and required scopes.
6. If the draft bill creation implies any fund movement, payment scheduling, or ledger posting, do not execute it — instead use `create-task` titled "APPROVAL: Vendor bill ready for review — [vendor name, amount]" with the extracted fields attached, and assign it to the AP approver.
7. If the invoice amount or terms are ambiguous or the file is malformed, use `create-task` titled "APPROVAL: Ambiguous invoice needs review" rather than guessing values.
8. Confirm the draft bill record was created successfully by checking the API response, and note the resulting draft bill ID in the approval task.

## Failure modes

- Invoice is a PDF or scanned image: no parse-document tool exists yet — stop and hand off via `create-task` rather than attempting to read binary content.
- Extracted amount or vendor name is missing, zero, or clearly malformed: do not create a draft bill with placeholder values — route to human review instead.
- `http-post` call to the accounting API fails with 401/403 or no Integration is configured for that host: stop, do not retry with alternate credentials, and message a human via `send-message`.
- CSV or text file uses an unexpected column layout or encoding: flag for human review rather than silently mis-mapping fields.

## Done when

- A draft bill (never a posted or paid bill) has been created in the accounting system with vendor, amount, and terms populated, or
- A human approval task has been created describing the invoice and blocking issue, and
- No payment, refund, or journal entry has been executed autonomously at any point.