Import bank statement into the review queue (nothing posts)
import_bank_statementImport a bank statement into Taokeh for reconciliation, from a statement you've read (PDF/CSV/image). This does NOT post to the books — every row lands in Banking → Review for the user to categorize and post line by line. FOREIGN-CURRENCY ACCOUNTS: a statement for an account whose currency is not ringgit still imports, but Taokeh books in ringgit and refuses to post or match that account's lines for now (intake_contract(doc_type:'statement') lists each account's currency) — say so instead of telling the user to post them. A statement is the bank's own list of transactions for ONE account over a period: use intake_contract(doc_type:'statement') first to see the tenant's bank accounts + the arithmetic law. Give the account id, the printed opening + closing balances, the printed statement date (statementDate) and beginning-balance date (beginningBalanceDate) when the statement shows them, and every transaction row (signed amount: + money in, − money out). The server checks opening + the rows tie to the closing balance and rejects with the exact delta if they don't — never invent or omit rows to force it to balance. CREDIT CARDS: a card statement can be filed here too, but ONLY with signConvention declared, because a card prints the opposite convention (a purchase INCREASES what you owe). Pass 'PRINTED_CARD' when the figures are exactly as the card statement prints them (the usual case) or 'STORED' if you deliberately converted them to Taokeh's convention (− = a spend). Never guess: declaring the wrong one books the whole month backwards and the arithmetic check cannot catch it, because negating every figure still ties out — the server runs a separate directional check and refuses a declaration that reads as a card which never owed anything. signConvention is refused on a bank account. Each card line is then expensed on its OWN statement date against the card, and the "payment received" line that settles the card bill is excluded automatically (the bank statement's lump owns that movement). Single receipts, invoices or bills go through their own draft doors, not here. ARCHIVING THE ORIGINAL: this import archives the statement file WHEN you send one — call request_attachment_upload FIRST, PUT the statement's raw bytes to its uploadUrl, then pass the returned attachmentToken here; the original is then kept on the statement (s.82 record-keeping) and the user can download it from the statement page, exactly as the web upload at Banking → Import does. Without a token nothing is archived and the books carry rows with no source document behind them. Already filed one bare? Call this tool AGAIN with the IDENTICAL account, balances and rows plus attachmentToken — the identical reading matches the same statement, so the file is ADOPTED onto it and no rows are staged twice. Filed one before without statementDate / beginningBalanceDate? The same identical call with the two dates added records them on that statement, again staging nothing twice.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | ||
| bankAccountId | Yes | ||
| statementDate | No | The statement date printed on the statement (the ENDING BALANCE date), YYYY-MM-DD — it is the end of the period the statement covers, even when the last transaction is earlier. Omit it only if the statement prints none. | |
| closingBalance | Yes | ||
| confirmOverlap | No | Set to true ONLY after the user has confirmed this is a genuinely new, separate statement whose period overlaps one already imported. It bypasses the overlap guard that stops the same transactions being counted twice. Never set it to push an overlap through — ask the user first. | |
| openingBalance | Yes | ||
| signConvention | No | REQUIRED when bankAccountId is a CREDIT CARD, and refused on a bank account. Which convention you signed the rows AND the opening/closing balances in. 'PRINTED_CARD' = exactly as the card statement prints them: a purchase is POSITIVE (what you owe goes up), a payment or refund is NEGATIVE, and the balances are the printed balances owed — this is the right choice when you read the card's own statement. 'STORED' = already converted to Taokeh's stored convention: a spend is NEGATIVE, a payment or refund POSITIVE, and the balances negative while money is owed. Do not guess between them: the wrong declaration books the entire month backwards, and the arithmetic check cannot catch it because negating every figure still ties out. Ask the user if unsure. | |
| 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 statement bytes to its uploadUrl. This is the normal way to archive a statement PDF — it carries the file out-of-band (no base64 in this call). Mutually exclusive with attachmentBase64. The file is archived on the statement and the user downloads it from the statement page in Taokeh. | |
| attachmentBase64 | No | The ORIGINAL statement as base64 — SMALL files only (a few KB). A real bank statement PDF is never that small, so in practice use request_attachment_upload + attachmentToken instead. Mutually exclusive with attachmentToken. A bad type/oversize file is rejected and NOTHING is imported. | |
| 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 | The original filename, for the user browsing their statements. | |
| attachmentMediaType | No | The attachment's MIME type, e.g. 'application/pdf'. Required when attachmentBase64 is given. It must match the file's bytes — a mismatch is refused and nothing is filed. | |
| beginningBalanceDate | No | The date on the BEGINNING (opening) BALANCE line, YYYY-MM-DD — the start of the period. Every row must fall between it and statementDate. Omit it only if the statement prints none. | |
| confirmSignConvention | No | Set true ONLY after the user confirms that the card genuinely sat in CREDIT for the whole period. It bypasses the directional check that refuses a statement reading as a card which never owed anything — the usual cause of which is a printed statement declared 'STORED' (or the reverse). Never set it to push a refusal through: ask the user first. |