File receipt draft
create_receipt_draftFile a customer-payment DRAFT into Taokeh ("customer paid X"). This does NOT post — it creates a pending draft the user reviews and approves in Taokeh; only then does it write a real bank receipt, settle the invoices and issue the official receipt (the next OR number, dated as the payment) — exactly as Sales → Receive payment does. A receipt settles an EXISTING customer's open invoices: resolve the customer (resolve_customer) and see what they owe (open_invoices) first, then give EITHER a lump total (auto-allocated oldest-first) OR explicit per-invoice allocations. MYR only — a foreign-currency invoice is refused and routes to Banking → Payments. A customer who paid in CASH is not this lane (its approval books a bank): tell the owner to record it on Sales → Official receipts → Receive payment, with Received into = Cash. The server re-derives the allocation against live outstanding, so its figures are authoritative. 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 payment proof (bank-in slip / remittance advice), attach the original document you extracted from — the owner sees it beside the draft at review (s.82 record-keeping) and it lands on the settlement entry automatically on approval, beside the official receipt. 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. A receipt dated on or before the accounting start date never settles an OPENING invoice — that invoice is what was still owed on the start date, so the money is already counted in it: explicit allocations naming one are refused at filing, and a lump total is never poured into one.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| total | No | ||
| customer | No | ||
| customerId | No | ||
| allocations | No | ||
| needsReview | No | ||
| receiptDate | Yes | ||
| printedTotal | No | ||
| bankAccountId | No | ||
| 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 settlement entry on approval, exactly as an inline one does. | |
| attachmentBase64 | No | The ORIGINAL payment proof (bank-in slip / remittance advice) 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 settlement entry 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. | |
| attachmentFilename | No | Optional original filename for the attachment, e.g. bank-in-slip.jpg. | |
| attachmentMediaType | No | The attachment's MIME type, e.g. 'image/jpeg' or 'application/pdf'. Required when attachmentBase64 is given. It must match the file's bytes — a mismatch is refused and nothing is filed. |