File bill draft
create_bill_draftFile a supplier-bill DRAFT into Taokeh from a bill you've read. INVENTORY-ONLY — every line must be a product you stock; for services / non-stock / mixed bills use the manual bill form, or create_expense_draft if already paid. This does NOT post to the books — it creates a pending draft the user reviews and approves in Taokeh; only then does it post (receive stock, blend moving-average cost, book input SST as a non-recoverable cost). Shape the fields with intake_contract(doc_type:'bill') + resolve_vendor + resolve_product first. The server re-computes every line quantity from the tally and the grand total — so present your working, but the server's figures are authoritative. READ THE PAYMENT TERM OFF THE BILL and send it as term — a supplier's credit period is what decides when this money actually leaves, so it drives the payables aging buckets, the OVERDUE badge and the 8-week cash forecast; for one of the five preset terms Taokeh fills the due date on the draft itself and shows it on the approval screen. Set needsReview and add a SHORT reviewer note in notes (one or two sentences naming what to double-check — not lengthy reasoning) for any doubt. If you have the ORIGINAL bill image/PDF, attach it — it rides the draft and lands on the posted bill automatically on approval, so the user never has to re-upload it. Small files: attachmentBase64 + attachmentMediaType inline. Send attachmentBytes (the original file’s decoded size) with it so a truncated base64 is rejected instead of filed. Anything bigger: request_attachment_upload → PUT the bytes → pass the returned attachmentToken — unless your shell cannot reach taokeh.my (a sandboxed client behind a network allowlist), in which case inline it anyway, with attachmentBytes; never both. ⛔ LINE KEYS ARE STRICT (2026-09-09): a key this schema does not list is REFUSED BY NAME — with the key it probably meant — and NOTHING is filed. Unknown keys used to be dropped in silence, which let a line through with its price or its tax code missing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | The SUPPLIER's payment term, exactly as the bill prints it ('Due on Receipt', 'Net 7', 'Net 14', 'Net 30', 'Net 60', or whatever this supplier actually stated — 'COD 7 days', 'Net 45', '30 days EOM'). It is stored as written, so do NOT round a real term to the nearest familiar one. Leave it out when the bill states no term: an unstated term is not 'Due on Receipt', and the bill then simply falls due on its own date. | |
| lines | Yes | ||
| notes | No | A SHORT reviewer note: one or two plain sentences, written in the reviewer's language, flagging what the human should double-check before approving — a smudged or ambiguous total, a vendor/customer you weren't sure of, a judgment call you made. The reviewer reads this on a small approval card, so keep it brief and human. This is NOT a place to dump lengthy reasoning, your working, or boilerplate — just the one thing to check. Leave it empty when there is nothing to flag. | |
| vendor | No | ||
| dueDate | No | The due date, YYYY-MM-DD, when the bill states one outright. You usually do not need it: for one of the five preset terms above, Taokeh fills the due date on the draft itself (bill date + 0/7/14/30/60 days) and shows it on the approval screen for the owner to check. State dueDate only to override that, or when the paper gives a due date that does not follow the term. A term Taokeh does not recognise fills NOTHING — if that bill has a due date, say it here, because otherwise the bill falls due on its own date and shows up in the payables aging and the cash forecast a whole credit period early. | |
| vendorId | No | ||
| reference | No | ||
| needsReview | No | ||
| printedTotal | No | ||
| purchaseDate | Yes | ||
| paymentMethod | Yes | ||
| shoeboxItemId | No | The id of a SHOEBOX photo (from shoebox_items) that this draft was read from — the paper someone in the business snapped and sent in. Taokeh attaches ITS OWN stored copy of that photo to the draft, so DO NOT also send the image: no re-upload, no base64, nothing to truncate. Mutually exclusive with attachmentBase64 and attachmentToken. The item must still be waiting: one already booked, set aside, or already carrying a pending draft is refused with the reason. Approving the draft closes that shoebox item against the document it became. | |
| attachmentBytes | No | The decoded byte size of the ORIGINAL file on disk — send it alongside attachmentBase64 and the server rejects a truncated paste instead of filing a corrupt file. | |
| attachmentToken | No | The token from request_attachment_upload, AFTER you have PUT the file bytes to its uploadUrl. Use this instead of attachmentBase64 for any real photo/PDF — it carries the file out-of-band (no base64 in this call). Mutually exclusive with attachmentBase64. The uploaded file rides the draft and lands on the posted bill on approval, exactly as an inline one does. | |
| attachmentBase64 | No | The ORIGINAL bill as base64 — SMALL files only (a few KB). For a real photo or multi-page PDF use request_attachment_upload instead (attachmentToken). Rides the draft and lands on the posted bill on approval — no re-upload. A bad type/oversize file is rejected and NOTHING is filed. | |
| attachmentSha256 | No | The SHA-256 of the ORIGINAL file as 64 hex chars — optional second check alongside attachmentBase64, so corrupted bytes are rejected instead of filed. | |
| confirmNewVendor | No | Set to true ONLY after the user has EXPLICITLY confirmed this vendor is genuinely new. It skips the near-miss guard (which rejects a name that looks like shorthand for an existing vendor). Never set it to push a near-miss through — ask the user first. | |
| attachmentFilename | No | Optional original filename for the attachment, e.g. bill.pdf. | |
| attachmentMediaType | No | The attachment's MIME type, e.g. 'image/jpeg' or 'application/pdf'. Required when attachmentBase64 is given. |